feat(remark-lint): add strict rules

packages/remark-lint/README.md

@@ -106,6 +106,22 @@ Metadata can be provided in comments:
 <!-- llm_description= Utilities for working with file paths -->
 ```
 
+### `node-core:invalid-type-reference`
+
+Ensures that all `{type}` references are valid types and formatted correctly.
+
+**Allowed:**
+
+```markdown
+This is usually a {boolean}, but it could also be a {string|number}.
+```
+
+**Not allowed:**
+
+```markdown
+This is an {invalid} type, and so is {string | number} because there should **not** be whitespace around the `|`.
+```
+
 ### `node-core:yaml-comments`
 
 Enforces structure and content of YAML comment blocks:

packages/remark-lint/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@node-core/remark-lint",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "exports": {
     ".": "./src/index.mjs",
     "./api": "./src/api.mjs"
@@ -20,6 +20,7 @@
     "test:unit": "cross-env NODE_NO_WARNINGS=1 node --experimental-test-coverage --test \"**/*.test.mjs\""
   },
   "dependencies": {
+    "@nodejs/doc-kit": "github:nodejs/doc-kit",
     "remark-gfm": "^4.0.1",
     "remark-lint-blockquote-indentation": "^4.0.1",
     "remark-lint-checkbox-character-style": "^5.0.1",

packages/remark-lint/src/api.mjs

@@ -7,6 +7,7 @@ import remarkLintUnorderedListMarkerStyle from 'remark-lint-unordered-list-marke
 import basePreset from './index.mjs';
 import duplicateStabilityNodes from './rules/duplicate-stability-nodes.mjs';
 import hashedSelfReference from './rules/hashed-self-reference.mjs';
+import invalidTypeReference from './rules/invalid-type-reference.mjs';
 import orderedReferences from './rules/ordered-references.mjs';
 import requiredMetadata from './rules/required-metadata.mjs';
 import yamlComments from './rules/yaml/index.mjs';
@@ -34,6 +35,7 @@ export default (options = {}) => ({
       hashedSelfReference,
       orderedReferences,
       requiredMetadata,
+      invalidTypeReference,
     ].map(plugin => [plugin, options]),
 
     // External Rules
@@ -61,6 +63,7 @@ export default (options = {}) => ({
         { yes: 'Unix' },
         { yes: 'Valgrind' },
         { yes: 'V8' },
+        { yes: 'npm' },
       ],
     ],
   ],

packages/remark-lint/src/rules/__tests__/invalid-type-reference.test.mjs

@@ -0,0 +1,40 @@
+import { describe, it } from 'node:test';
+
+import { testRule } from './utils.mjs';
+import invalidTypeReference from '../invalid-type-reference.mjs';
+
+const testCases = [
+  {
+    name: 'no references',
+    input: 'Just some text.',
+    expected: [],
+  },
+  {
+    name: 'single reference',
+    input: 'Just a {number}.',
+    expected: [],
+  },
+  {
+    name: 'miswrapped reference',
+    input: 'First a {string}, then a \\<number>.',
+    expected: ['Type reference must be wrapped in "{}"; saw "<number>"'],
+  },
+  {
+    name: 'multiple references',
+    input: 'Psst, are you a {string | boolean}',
+    expected: [
+      'Type reference should be separated by "|", without spaces; saw "{string | boolean}"',
+    ],
+  },
+  {
+    name: 'invalid references',
+    input: 'This is {invalid}.',
+    expected: ['Invalid type reference: {invalid}'],
+  },
+];
+
+describe('invalid-type-reference', () => {
+  for (const { name, input, expected } of testCases) {
+    it(name, () => testRule(invalidTypeReference, input, expected));
+  }
+});

packages/remark-lint/src/rules/duplicate-stability-nodes.mjs

@@ -1,53 +1,43 @@
+import createQueries from '@nodejs/doc-kit/src/utils/queries/index.mjs';
 import { lintRule } from 'unified-lint-rule';
 import { visit } from 'unist-util-visit';
 
-// TODO(@avivkeller): This is re-used from doc-kit
-// Regex to match "Stability: <number>" in blockquotes
-const STABILITY = /Stability: ([0-5](?:\.[0-3])?)/;
-
 /**
  * Finds and reports duplicate stability nodes
  * @type {import('unified-lint-rule').Rule}
  */
 const duplicateStabilityNodes = (tree, vfile) => {
-  let currentDepth = 0;
-  let currentStability = -1;
-  let currentHeaderDepth = 0;
+  // Map depth → stability string recorded at that depth
+  const stabilityByDepth = new Map();
+  let currentHeadingDepth = 0; // Current heading depth (0 for "no heading")
 
-  visit(tree, node => {
-    // Update the current heading depth whenever a heading node is encountered
+  visit(tree, ['heading', 'blockquote'], node => {
     if (node.type === 'heading') {
-      currentHeaderDepth = node.depth;
+      // Update heading depth and clear deeper recorded stabilities
+      currentHeadingDepth = node.depth;
+      for (const depth of stabilityByDepth.keys()) {
+        if (depth >= currentHeadingDepth) stabilityByDepth.delete(depth);
+      }
+      return;
     }
 
-    // Look for blockquotes which may contain stability indicators
-    if (node.type === 'blockquote') {
-      // Assume the first child is a paragraph
-      const paragraph = node.children?.[0];
-      // And the first child of that paragraph is text
-      const text = paragraph?.children?.[0];
+    // Handle blockquotes: extract text from paragraph > text structure
+    const text = node.children?.[0]?.children?.[0]?.value;
+    if (!text) return;
 
-      // Ensure structure is paragraph > text
-      if (paragraph?.type === 'paragraph' && text?.type === 'text') {
-        // Try to match "Stability: X"
-        const match = text.value.match(STABILITY);
-        if (match) {
-          const stability = parseFloat(match[1]);
-          // If the heading got deeper, and stability is valid and matches previous, report a duplicate
-          if (
-            currentHeaderDepth > currentDepth &&
-            stability >= 0 &&
-            stability === currentStability
-          ) {
-            vfile.message('Duplicate stability node', node);
-          } else {
-            // Otherwise, record this stability and heading depth
-            currentDepth = currentHeaderDepth;
-            currentStability = stability;
-          }
-        }
+    const match = createQueries.QUERIES.stabilityIndexPrefix.exec(text); // Match "Stability: X"
+    if (!match) return;
+
+    const stability = match[1];
+    // Report if a duplicate stability exists in a parent heading depth
+    for (const [depth, prevStability] of stabilityByDepth) {
+      if (depth < currentHeadingDepth && prevStability === stability) {
+        vfile.message('Duplicate stability node', node);
+        break;
       }
     }
+
+    stabilityByDepth.set(currentHeadingDepth, stability);
   });
 };
 

packages/remark-lint/src/rules/hashed-self-reference.mjs

@@ -33,6 +33,7 @@ const hashedSelfReference = (tree, vfile) => {
 
     if (targetURL.pathname === currentFileURL.pathname) {
       const expected = url.includes('#') ? url.slice(url.indexOf('#')) : '#';
+      node.url = expected;
 
       vfile.message(
         `Self-reference must start with hash (expected "${expected}", got "${url}")`,

packages/remark-lint/src/rules/invalid-type-reference.mjs

@@ -0,0 +1,49 @@
+import { transformTypeToReferenceLink } from '@nodejs/doc-kit/src/utils/parser/index.mjs';
+import createQueries from '@nodejs/doc-kit/src/utils/queries/index.mjs';
+import { lintRule } from 'unified-lint-rule';
+import { visit } from 'unist-util-visit';
+
+const MATCH_RE = /\s\||\|\s/g;
+const REPLACE_RE = /\s*\|\s*/g;
+
+/**
+ * Ensures that all type references are valid
+ * @type {import('unified-lint-rule').Rule}
+ */
+const invalidTypeReference = (tree, vfile) => {
+  visit(tree, createQueries.UNIST.isTextWithType, node => {
+    const types = node.value.match(createQueries.QUERIES.normalizeTypes);
+
+    types.forEach(type => {
+      // Ensure wrapped in {}
+      if (type[0] !== '{' || type[type.length - 1] !== '}') {
+        vfile.message(
+          `Type reference must be wrapped in "{}"; saw "${type}"`,
+          node
+        );
+
+        node.value = node.value.replace(type, `{${type.slice(1, -1)}}`);
+      }
+
+      // Fix spaces around |
+      if (MATCH_RE.test(type)) {
+        vfile.message(
+          `Type reference should be separated by "|", without spaces; saw "${type}"`,
+          node
+        );
+
+        const normalized = type.replace(REPLACE_RE, '|');
+        node.value = node.value.replace(type, normalized);
+      }
+
+      if (transformTypeToReferenceLink(type) === type) {
+        vfile.message(`Invalid type reference: ${type}`, node);
+      }
+    });
+  });
+};
+
+export default lintRule(
+  'node-core:invalid-type-reference',
+  invalidTypeReference
+);