[WIP] feature-complete linting

Author: avivkeller

.changeset/remark-lint-rewrite.md

@@ -0,0 +1,5 @@
+---
+'@node-core/remark-lint': major
+---
+
+Rewrite `@node-core/remark-lint` with new lint rules

apps/site/.remarkrc.json

@@ -1,12 +1,13 @@
 {
   "plugins": [
     "remark-frontmatter",
-    "@node-core/remark-lint",
     [
-      "@node-core/remark-lint/rules/validate-links",
+      "@node-core/remark-lint",
       {
-        "ignoreFiles": ["pages/!(en)/**/*.{md,mdx}"],
-        "ignoreLinks": ["/learn", "/learn/**/*", "/static/**/*", "/feed/*"]
+        "link-targets": {
+          "ignoreFiles": ["pages/!(en)/**/*.{md,mdx}"],
+          "ignoreLinks": ["/learn", "/learn/**/*", "/static/**/*", "/feed/*"]
+        }
       }
     ]
   ]

packages/remark-lint/README.md

@@ -2,10 +2,14 @@
   "name": "@node-core/remark-lint",
   "type": "module",
   "version": "1.4.1",
+  "description": "remark-lint presets and rules enforcing the Node.js documentation standards and the doc-kit Markdown specification",
   "exports": {
     ".": "./src/index.mjs",
     "./api": "./src/api.mjs",
-    "./rules/*": "./src/rules/*.mjs"
+    "./rules": "./src/rules/index.mjs",
+    "./rules/*": "./src/rules/*.mjs",
+    "./presets/*": "./src/presets/*.mjs",
+    "./package.json": "./package.json"
   },
   "repository": {
     "type": "git",
@@ -21,46 +25,37 @@
     "test:unit": "cross-env NODE_NO_WARNINGS=1 node --experimental-test-coverage --test \"**/*.test.mjs\""
   },
   "dependencies": {
-    "@node-core/doc-kit": "^1.2.0",
-    "mdast-util-to-string": "^4.0.0",
+    "@doc-kit/core": "^1.1.0",
+    "github-slugger": "^2.0.0",
     "remark-gfm": "^4.0.1",
-    "remark-lint-blockquote-indentation": "^4.0.1",
-    "remark-lint-checkbox-character-style": "^5.0.1",
-    "remark-lint-checkbox-content-indent": "^5.0.1",
-    "remark-lint-code-block-style": "^4.0.1",
     "remark-lint-definition-spacing": "^4.0.1",
     "remark-lint-fenced-code-flag": "^4.2.0",
-    "remark-lint-fenced-code-marker": "^4.0.1",
+    "remark-lint-file-extension": "^3.0.1",
     "remark-lint-final-definition": "^4.0.2",
-    "remark-lint-heading-style": "^4.0.1",
+    "remark-lint-first-heading-level": "^4.0.1",
     "remark-lint-maximum-line-length": "^4.1.1",
-    "remark-lint-no-consecutive-blank-lines": "^5.0.1",
+    "remark-lint-no-duplicate-definitions": "^4.0.1",
+    "remark-lint-no-file-name-articles": "^3.0.1",
     "remark-lint-no-file-name-consecutive-dashes": "^3.0.1",
     "remark-lint-no-file-name-outer-dashes": "^3.0.1",
-    "remark-lint-no-heading-indent": "^5.0.1",
-    "remark-lint-no-literal-urls": "^4.0.1",
     "remark-lint-no-multiple-toplevel-headings": "^4.0.1",
     "remark-lint-no-shell-dollars": "^4.0.1",
-    "remark-lint-no-table-indentation": "^5.0.1",
-    "remark-lint-no-tabs": "^4.0.1",
-    "remark-lint-no-trailing-spaces": "^5.0.0",
+    "remark-lint-no-shortcut-reference-image": "^4.0.1",
+    "remark-lint-no-shortcut-reference-link": "^4.0.1",
+    "remark-lint-no-undefined-references": "^5.0.2",
     "remark-lint-no-unused-definitions": "^4.0.2",
     "remark-lint-prohibited-strings": "^5.0.0",
-    "remark-lint-rule-style": "^4.0.1",
-    "remark-lint-strong-marker": "^4.0.1",
-    "remark-lint-table-cell-padding": "^5.1.1",
-    "remark-lint-table-pipes": "^5.0.1",
-    "remark-lint-unordered-list-marker-style": "^4.0.1",
-    "remark-preset-lint-recommended": "^7.0.1",
-    "semver": "^7.8.1",
+    "remark-message-control": "^8.0.0",
+    "remark-parse": "^11.0.0",
+    "semver": "^7.8.5",
+    "unified": "^11.0.5",
     "unified-lint-rule": "^3.0.1",
-    "unist-util-visit": "^5.1.0",
-    "yaml": "^2.8.4"
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "cross-env": "catalog:",
     "dedent": "^1.7.2",
-    "remark-parse": "^11.0.0",
-    "unified": "^11.0.5"
+    "remark-stringify": "^11.0.0",
+    "vfile": "^6.0.3"
   }
 }

packages/remark-lint/package.json

@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import dedent from 'dedent';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { VFile } from 'vfile';
+
+import { getContext } from '../context.mjs';
+import remarkTypeAnnotations from '../syntax.mjs';
+
+const parse = markdown => {
+  const file = new VFile({ path: 'doc/api/fs.md', value: markdown });
+  const tree = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkTypeAnnotations)
+    .parse(file);
+
+  return getContext(tree, file);
+};
+
+describe('context', () => {
+  it('splits the document into entries, like doc-kit', () => {
+    const context = parse(dedent`
+      Preamble.
+
+      # File system
+
+      Intro.
+
+      ## Class: \`fs.Dir\`
+
+      ### \`dir.close()\`
+
+      Text.
+
+      ## \`fs.readFile(path)\`
+
+      ### Event: \`'close'\`
+    `);
+
+    const [preamble, title, klass, method, fn, event] = context.entries;
+
+    assert.equal(preamble.heading, null);
+    assert.equal(preamble.nodes.length, 1);
+    assert.equal(title.data.text, 'File system');
+    assert.equal(title.data.slug, 'file-system');
+    assert.equal(klass.data.type, 'class');
+    assert.equal(klass.data.name, 'fs.Dir');
+    assert.equal(klass.parent, title);
+    assert.equal(method.data.type, 'method');
+    assert.equal(method.parent, klass);
+    assert.equal(method.nodes.length, 1);
+    assert.equal(fn.parent, title);
+    assert.deepEqual(klass.children, [method]);
+    assert.equal(event.data.type, 'event');
+    assert.equal(event.data.slug, 'event-close');
+  });
+
+  it('classifies comments', () => {
+    const context = parse(dedent`
+      # T
+
+      <!--introduced_in=v1.0.0-->
+
+      <!-- type=misc -->
+
+      <!-- YAML
+      added: v1.0.0
+      changes:
+        - version: v2.0.0
+      -->
+
+      <!-- legacy -->
+
+      <!--YAML
+      added: [
+      -->
+
+      <div>not a comment</div>
+    `);
+
+    const [directive, padded, yaml, tag, broken, html] = context.comments;
+
+    assert.equal(directive.kind, 'directive');
+    assert.equal(directive.key, 'introduced_in');
+    assert.equal(directive.value, 'v1.0.0');
+    assert.equal(directive.padded, false);
+    assert.equal(padded.kind, 'directive');
+    assert.equal(padded.symmetric, true);
+    assert.equal(padded.padded, true);
+    assert.equal(yaml.kind, 'yaml');
+    assert.equal(yaml.padded, 1);
+    assert.deepEqual(yaml.yaml, {
+      added: 'v1.0.0',
+      changes: [{ version: 'v2.0.0' }],
+    });
+    assert.equal(tag.kind, 'tag');
+    assert.equal(tag.inner, ' legacy ');
+    assert.equal(broken.kind, 'yaml');
+    assert.equal(broken.padded, 0);
+    assert.equal(broken.yaml, undefined);
+    assert.equal(broken.yamlErrors.length, 1);
+    assert.equal(html.kind, 'html');
+    assert.equal(context.commentsOf('directive').length, 2);
+  });
+
+  it('recognizes stability indicators and typed lists', () => {
+    const context = parse(dedent`
+      # T
+
+      > Stability: 1.2 - Release candidate. Text.
+
+      > stability: broken
+
+      > Not stability.
+
+      * \`path\` {string} The path.
+      * Returns: {Promise}
+
+      <!-- separator -->
+
+      * Plain list.
+    `);
+
+    assert.equal(context.stability.length, 2);
+    assert.equal(context.stability[0].valid, true);
+    assert.equal(context.stability[0].index, '1.2');
+    assert.equal(context.stability[0].description, 'Release candidate. Text.');
+    assert.equal(context.stability[1].valid, false);
+    assert.deepEqual(
+      context.lists.map(({ typed }) => typed),
+      [true, false]
+    );
+    assert.equal(context.typeAnnotations.length, 2);
+    assert.equal(context.typeAnnotations[0].node.value, 'string');
+    assert.equal(context.typeAnnotations[0].node.raw, '{string}');
+  });
+
+  it('is computed once per tree', () => {
+    const file = new VFile({ value: '# T\n' });
+    const tree = unified().use(remarkParse).parse(file);
+
+    assert.equal(getContext(tree, file), getContext(tree, file));
+  });
+});