为 remark-cli 配置 remark-lint-no-undefined-references 插件/规则“允许”选项？

Question

Original Question

How do I correctly " configure " the ( unified , remark , remark-lint ) remark-lint-no-undefined-references plugin/rule "allow" option for use with the remark-cli ?

My goal is to configure the rule to ignore the Azure DevOps Wiki's non-standard table of contents tag, [[_TOC_]] . My simplified setup entails:

1. All packages globally installed . Probably not relevant.
2. A parent folder in which I have:
   • A package.json file.
   • A Test folder containing just the one Test.md file whose only content is this one line [[_TOC_]] .
3. From a command prompt whose working folder is the aforementioned parent folder, I execute:
   • remark Test

Default Operation

The default operation, ie just the plugin/rule specified in the package.json file, returns the expected warning. This is, presumably , due to the non-standard tag, [[_TOC_]] . This is the warning I wish to turn off.

package.json (default)

{
    "remarkConfig": {
        "plugins": [
            "remark-lint-no-undefined-references"
    ]
    }
}

Execution and Expected Warning (default)

C:\..>remark Test
test\Test.md
  1:1-1:10  warning  Found reference to undefined definition  no-undefined-references  remark-lint
   1:2-1:9  warning  Found reference to undefined definition  no-undefined-references  remark-lint

‼ 2 warnings

What I've tried

I've tried to adapt remark-lint-no-undefined-references API example and Configuration, 'rules can be configured in one standard way' to my package.json file. After much trial and error, I've ended up with this seemingly valid json:

package.json

{
    "remarkConfig": {
        "plugins": [
            "remark-lint-no-undefined-references", [1, {
                "allow": ["[[_TOC_]]"]
            }]
        ]
    }
}

The Online JSON Viewer and JSONLint indicate it's valid JSON. However, remark-cli yields this error. Other variations yielded different errors. I am stumped.

C:\..>
Test\Test.md
  1:1  error  Error: Cannot parse file `package.json`
Expected preset, not `1`
    at Error (file:///C:/Users/scott.welker/AppData/Roaming/npm/node_modules/remark-cli/node_modules/fault/index.js:39:12)
    at file:///C:/Users/scott.welker/AppData/Roaming/npm/node_modules/remark-cli/node_modules/unified-engine/lib/find-up.js:190:15
    at done (file:///C:/Users/scott.welker/AppData/Roaming/npm/node_modules/remark-cli/node_modules/trough/index.js:145:7)

× 1 error

---

Update 03/14/2022

I've made some progress thanks to a bit of help on GitHub Issue (#210) . However, that was not the right avenue and it is closed. My issue remains.

A Few Things are Apparent

1. My initially inferred JSON, package.json , is incorrect. See Hacked my JSON below.
2. I failed to appreciate how the non-standard Azure DevOps Wiki table of contents tag, [[_TOC_]] , is interpreted. See Tag Interpretation (console-log) following.
3. My inferred package.json seemingly remains incorrect. See My JSON Must Still be Wrong below.

Hacked my JSON

To overcome ...Error: Cannot parse file 'package.json', Expected preset, not '1' I hacked my file so that I now have the following. This change overcomes the error and enables me to continue but it is still seemingly incorrect. See My JSON Must Still be Wrong .

package.json file

{
    "remarkConfig": {
        "plugins": [
            "remark-lint-no-undefined-references", {
                "allow": ["_TOC_", "[_TOC_]"]
            }
        ]
    }
}

Tag Interpretation (console.log)

After hacking my JSON, I added a recommended console.log ( ..\npm\node_modules\remark-lint-no-undefined-references\index.js ) of id . This reveals that the linting interprets the table of contents tag as two separate bits of concerning markdown, _TOC_ and [_TOC_] . I did not appreciate this. However, the findings below suggest this may not be a problem. See My JSON Must Still be Wrong .

remark-cli

C:\..>remark Test
Id:  _TOC_
Id:  [_TOC_]
Test\Test.md
  1:1-1:10  warning  Found reference to undefined definition  no-undefined-references  remark-lint
   1:2-1:9  warning  Found reference to undefined definition  no-undefined-references  remark-lint

‼ 2 warnings

My JSON Must Still be Wrong

Referring to another location in the source here (line 126) , when I replace that const allow definition with this hard-coded declaration, const allow = new Set(["_TOC_", "[_TOC_]"]) , I get the desired behavior. Eg:

remark-cli

C:\...>remark Test
Test\Test.md: no issues found

Next Steps:

1. See whether I can forgo the package.json and instead use pure javascript . Either my JSON is incorrect or it isn't being interpreted correctly.
2. Continue to futz with the JSON. What I've inferred may well be wrong.
   • The following guess also fails to suppress the unwanted warnings:

package.json

{
    "remarkConfig": {
        "plugins": [
            "remark-lint-no-undefined-references", [{
                "allow": ["_TOC_", "[_TOC_]"]
            }]
        ]
    }
}

---

Update 03/28/2022

CAUTION!
While the setup in this update is valid, the Test.js example code is flawed. See 03/30/2022 Update below.

Following up on " Next Step, see whether I can forgo the package.json and instead use pure javascript . "

I seem to have made it work except it suppresses all warnings, not just the few (two) that I am targeting. More development and testing is needed.

New Setup

1. A new parent Node.js application folder in which I have:
   • Opted to re-install all packages, and some new ones, but not globally (this time):
     • npm install to-vfile
     • npm install vfile-reporter
     • npm install remark
     • npm install remark-lint
     • npm install remark-lint-no-undefined-references
   • The node_modules folder. Created and populated by npm installs (dependencies).
   • A package.json file. Created and populated by npm installs.
   • A package-lock.json file. Created and populated by npm installs.
   • A copy of the same Test folder containing just the one Test.md file whose only content is this one line [[_TOC_]] .
2. From a command prompt whose working folder is the aforementioned parent folder, I execute my new node/ javascript code:
   • node Test.js See following. Code comments illustrate the unexpected suppression of all warnings, even those not targeted.

Test.js

WARNING! This code is incorrect. See the 03/30/2022 Update below.

import {reporter} from 'vfile-reporter'
import {remark} from 'remark'
import remarkLint from 'remark-lint'
import remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references'
import {read} from 'to-vfile'

main()

async function main() {
  const file = await remark()
    .use(remarkLint)
    // This useage results in the expected warnings, '...Found reference to undefined definition...'
    .use(remarkLintNoUndefinedReferences)
    
    // This usage suppresses the warnings, as desired. However, note the next usage.
    //.use(remarkLintNoUndefinedReferences[ { allow: [ '_TOC_', '[_TOC_]' ] }])

    // This usage also suppresses the warning but it shoud not have done so.
    //.use(remarkLintNoUndefinedReferences[ { allow: [ '...', '…' ] }])

    // This usage (and related tests) seem to illustrate that anything in the allowed array suppresses all warnings. 
    //.use(remarkLintNoUndefinedReferences[ { allow: [ '' ] }])
    .process(await read('.\\Test\\Test.md'))

  console.error(reporter(file))
}

---

Update 03/30/2022

Here is a corrected Test.js file where my invalid usages are commented out, marked WRONG , and the two correct usages are marked GOOD . The final usage corrects mistakes made in my 03/28/2022 update. I now have a working javascript version. I just need to adapt this known working version to the remark-cli's package.json file. Getting very close.

I arrived at this CORRECT , working usage through trial and error. My trial and error was aided by adding console.log() statements to the ..\remark-lint-no-undefined-references\index.js source and tweaking my javascript code as guided by repeated re-reading of the remark-lint Configure section.

Test.js

import {reporter} from 'vfile-reporter'
import {remark} from 'remark'
import remarkLint from 'remark-lint'
import remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references'
import {read} from 'to-vfile'

main()

async function main() {
  const file = await remark()
    .use(remarkLint)
  
    // WRONG: This usage seems to suppress the warnings, as desired. However, note the next usage.
    //.use(remarkLintNoUndefinedReferences[ { allow: [ '_TOC_', '[_TOC_]' ] }])

    // WRONG: This usage also seems to supresses the warnings but, it shoud not have done so.
    //.use(remarkLintNoUndefinedReferences[ { allow: [ '...', '…' ] }])

    // WRONG: This usage (and related tests) seem to illustrate that anything in the allowed array suppresses all warnings. 
    //.use(remarkLintNoUndefinedReferences[ { allow: [ '' ] }])

    // GOOD: This usage results in the expected warnings, '...Found reference to undefined definition...'
    //.use(remarkLintNoUndefinedReferences)

    // GOOD: This usage seems to be correct!!
    .use(remarkLintNoUndefinedReferences, [1, { allow: [ '_TOC_', '[_TOC_]' ] }])
    .process(await read('.\\Test\\Test.md'))

  console.error(reporter(file))
}

Execution and Output

C:\..>node Test.js
DEBUG remarkTest: allow contains 2 items.

DEBUG remarkTest Id: '_TOC_'
DEBUG remarkTest Id: '[_TOC_]'
.\Test\Test.md: no issues found

Answer 1

The package.json below correctly " configures " the remark-lint-no-undefined-references plugin/rule "allow" option for use with remark-cli .

• Note: I also transitioned away from globally installed packages out of an unsubstantiated concern that they might have contributed to my problem. See Multiple globally installed presets and plugins don't work #165 . This transition accounts for the added package.json " dependencies ". See following.

package.json

I arrived at this by working from my 03/30/2022 update and futzing with varying syntax illustrated in the Unified Engine, Configuration, Schema section.

Again, my goal is to configure the rule to ignore the Azure DevOps Wiki's non-standard table of contents tag, [[_TOC_]] .

{
    "remarkConfig": {
        "plugins": {
            "remark-lint-no-undefined-references": { "allow":[ "_TOC_", "[_TOC_]" ] }
        }
    },
    "dependencies": {
        "remark": "^14.0.2",
        "remark-lint": "^9.1.1",
        "remark-lint-no-undefined-references": "^4.1.1"
    }
}

Execution and Output

Note: my debug console.log(...) remains in place.

C:\..>remark Test
DEBUG remarkCLITest: allow contains 2 items.

Test\Test.md: no issues found