feat(remark-lint): improve validation

packages/remark-lint/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@node-core/remark-lint",
   "type": "module",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "exports": {
     ".": "./src/index.mjs",
     "./api": "./src/api.mjs"
@@ -20,7 +20,7 @@
     "test:unit": "cross-env NODE_NO_WARNINGS=1 node --experimental-test-coverage --test \"**/*.test.mjs\""
   },
   "dependencies": {
-    "@node-core/doc-kit": "^1.0.0",
+    "@node-core/doc-kit": "^1.0.2",
     "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 invalidDeprecations from './rules/invalid-deprecations.mjs';
 import invalidTypeReference from './rules/invalid-type-reference.mjs';
 import orderedReferences from './rules/ordered-references.mjs';
 import requiredMetadata from './rules/required-metadata.mjs';
@@ -37,6 +38,7 @@ export default (options = {}) => ({
       orderedReferences,
       requiredMetadata,
       invalidTypeReference,
+      invalidDeprecations,
     ].map(plugin => [plugin, options]),
 
     // External Rules

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

@@ -0,0 +1,107 @@
+import { describe, it } from 'node:test';
+
+import dedent from 'dedent';
+
+import { testRule } from './utils.mjs';
+import invalidDeprecations from '../invalid-deprecations.mjs';
+
+const TYPE = 'Type: [...]';
+const CHANGES = dedent`
+  <!-- YAML
+  changes:
+  -->
+  `;
+const BODY = TYPE + '\n' + CHANGES;
+
+const testCases = [
+  {
+    name: 'in order deprecations',
+    input: dedent`
+      ## DEP0001:
+      ${BODY}
+      ## DEP0002:
+      ${BODY}
+    `,
+    expected: [],
+  },
+  {
+    name: 'out of order deprecations',
+    input: dedent`
+      ## DEP0001:
+      ${BODY}
+      ## DEP0003:
+      ${BODY}
+    `,
+    expected: [
+      'Deprecation codes are out of order. Expected DEP0002, saw "DEP0003"',
+    ],
+  },
+  {
+    name: 'skipped deprecations',
+    input: dedent`
+      ## DEP0001:
+      ${BODY}
+      <!-- md-lint skip-deprecation DEP0002 -->
+      ## DEP0003:
+      ${BODY}
+    `,
+    expected: [],
+  },
+  {
+    name: 'out of order skipped deprecations',
+    input: dedent`
+      ## DEP0001:
+      ${BODY}
+      <!-- md-lint skip-deprecation DEP0004 -->
+      ## DEP0003:
+      ${BODY}
+    `,
+    expected: [
+      'Deprecation codes are out of order. Expected DEP0002, saw "DEP0004"',
+    ],
+  },
+  {
+    name: 'not enough skipped deprecations',
+    input: dedent`
+      ## DEP0001:
+      ${BODY}
+      <!-- md-lint skip-deprecation DEP0002 -->
+      ## DEP0004:
+      ${BODY}
+    `,
+    expected: [
+      'Deprecation codes are out of order. Expected DEP0003, saw "DEP0004"',
+    ],
+  },
+  {
+    name: 'no type',
+    input: dedent`
+      ## DEP0001:
+      some text
+      ${CHANGES}
+    `,
+    expected: ['Deprecation "DEP0001" is missing a "Type"'],
+  },
+  {
+    name: 'no changes',
+    input: dedent`
+      ## DEP0001:
+      ${TYPE}
+    `,
+    expected: ['Deprecation "DEP0001" is missing changes'],
+  },
+];
+
+describe('invalid-deprecations', () => {
+  for (const { name, input, expected, options } of testCases) {
+    it(name, () =>
+      testRule(
+        invalidDeprecations,
+        input,
+        expected,
+        { stem: 'deprecations' },
+        options
+      )
+    );
+  }
+});

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

@@ -19,6 +19,11 @@ const testCases = [
     input: 'First a {string}, then a \\<number>.',
     expected: ['Type reference must be wrapped in "{}"; saw "<number>"'],
   },
+  {
+    name: 'miswrapped reference inside link',
+    input: '[<number>]()',
+    expected: ['Type reference must be wrapped in "{}"; saw "<number>"'],
+  },
   {
     name: 'multiple references',
     input: 'Psst, are you a {string | boolean}',

packages/remark-lint/src/rules/invalid-deprecations.mjs

@@ -0,0 +1,65 @@
+import { lintRule } from 'unified-lint-rule';
+import { visit } from 'unist-util-visit';
+
+const DEPRECATION_COMMENT = /^<!-- md-lint skip-deprecation (DEP\d{4}) -->$/;
+const DEPRECATION_HEADING = /^(DEP\d{4}):/;
+const DEPRECATION_YAML = /^<!-- YAML\r?\nchanges:\r?\n/;
+
+const generateDeprecation = code => `DEP${code.toString().padStart(4, '0')}`;
+
+/**
+ * Ensures all needed metadata exists
+ * @type {import('unified-lint-rule').Rule}
+ */
+const invalidDeprecations = (tree, vfile) => {
+  if (vfile.stem !== 'deprecations') {
+    // Skip non-deprecation files
+    return;
+  }
+
+  let expectedDeprecationCode = 1;
+
+  visit(tree, ['heading', 'html'], (node, idx, parent) => {
+    let currentDeprecationCode;
+
+    // Get the current deprecation
+    if (node.type === 'html') {
+      currentDeprecationCode = node.value.match(DEPRECATION_COMMENT)?.[1];
+    } else {
+      currentDeprecationCode =
+        node.children[0].value.match(DEPRECATION_HEADING)?.[1];
+
+      if (!parent.children[idx + 1]?.children[0]?.value?.startsWith('Type:')) {
+        vfile.message(
+          `Deprecation "${currentDeprecationCode}" is missing a "Type"`,
+          node
+        );
+      }
+
+      if (!DEPRECATION_YAML.test(parent.children[idx + 2]?.value)) {
+        vfile.message(
+          `Deprecation "${currentDeprecationCode}" is missing changes`,
+          node
+        );
+      }
+    }
+
+    // If not found, skip
+    if (!currentDeprecationCode) {
+      return;
+    }
+
+    if (
+      currentDeprecationCode !== generateDeprecation(expectedDeprecationCode)
+    ) {
+      vfile.message(
+        `Deprecation codes are out of order. Expected ${generateDeprecation(expectedDeprecationCode)}, saw "${currentDeprecationCode}"`,
+        node
+      );
+    }
+
+    expectedDeprecationCode++;
+  });
+};
+
+export default lintRule('node-core:invalid-deprecations', invalidDeprecations);

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

@@ -1,5 +1,5 @@
-import { transformTypeToReferenceLink } from '@node-core/doc-kit/src/utils/parser/index.mjs';
-import createQueries from '@node-core/doc-kit/src/utils/queries/index.mjs';
+import { transformTypeToReferenceLink } from '@node-core/doc-kit/src/generators/metadata/utils/transformers.mjs';
+import { QUERIES } from '@node-core/doc-kit/src/utils/queries/index.mjs';
 import { lintRule } from 'unified-lint-rule';
 import { visit } from 'unist-util-visit';
 
@@ -11,36 +11,42 @@ const REPLACE_RE = /\s*\| */g;
  * @type {import('unified-lint-rule').Rule<, import('../api.mjs').Options>}
  */
 const invalidTypeReference = (tree, vfile, { typeMap = {} }) => {
-  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, typeMap) === type) {
-        vfile.message(`Invalid type reference: ${type}`, node);
-      }
-    });
-  });
+  visit(
+    tree,
+    ({ value }) => QUERIES.normalizeTypes.test(value),
+    node => {
+      const types = node.value.match(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
+          );
+
+          const newType = `{${type.slice(1, -1)}}`;
+          node.value = node.value.replace(type, newType);
+          type = newType;
+        }
+
+        // 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, typeMap) === type) {
+          vfile.message(`Invalid type reference: ${type}`, node);
+        }
+      });
+    }
+  );
 };
 
 export default lintRule(