chore(remark-lint): migrate to @doc-kit/core

@node-core/doc-kit 2 moved its internals to @doc-kit/core, and removed
the two helpers invalid-type-reference was built on:
`transformTypeToReferenceLink` and `QUERIES.normalizeTypes`.

- duplicate-stability-nodes and validate-links import the same modules
  from @doc-kit/core.
- invalid-type-reference keeps its type pattern locally and resolves
  each `|` member with doc-kit's `resolveTypeReference`, so it accepts
  exactly what the generator can link. Types never reach it with `<>`
  in them, so the old generic handling is gone.
- The old resolver accepted anything containing a `.`, which hid HTML
  comments and tags being read as `<type>` references. The html branch
  now only matches bare `<name>` nodes.
- doc-kit 2 no longer turns `_` into `-` in slugs, matching the site's
  rehype-slug and the Node.js API anchors (`#child_process`).

Over Node.js's doc/api with its type-map.json, the rule reports nothing
new: it drops the HTML false positives (7103 -> 283 messages) and now
resolves {object}, {QuotaExceededError}, {WorkerGlobalScope} and
{DedicatedWorkerGlobalScope}. The site's markdown lint stays clean.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: ovflowd

.changeset/quiet-rules-migrate.md

@@ -0,0 +1,5 @@
+---
+'@node-core/remark-lint': patch
+---
+
+Use `@doc-kit/core` instead of `@node-core/doc-kit` 1.x. Heading anchors now follow doc-kit 2's slugs (`child_process` links as `#child_process`), and `invalid-type-reference` no longer treats HTML comments and tags as type references.

packages/remark-lint/package.json

@@ -21,7 +21,7 @@
     "test:unit": "cross-env NODE_NO_WARNINGS=1 node --experimental-test-coverage --test \"**/*.test.mjs\""
   },
   "dependencies": {
-    "@node-core/doc-kit": "^1.2.0",
+    "@doc-kit/core": "^1.3.1",
     "mdast-util-to-string": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-lint-blockquote-indentation": "^4.0.1",

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

@@ -38,6 +38,28 @@ const value = {invalid};
 <div>{invalid}</div>`,
     expected: [],
   },
+  {
+    name: 'ignores HTML comments and tags',
+    input: `<!--introduced_in=v0.10.0-->
+
+<a id="module_builtins" href="module.html#builtins"></a>`,
+    expected: [],
+  },
+  {
+    name: 'array reference',
+    input: 'Takes a {string[]}.',
+    expected: [],
+  },
+  {
+    name: 'module-qualified reference',
+    input: 'Returns a {vm.Module}.',
+    expected: [],
+  },
+  {
+    name: 'union with one resolvable member',
+    input: 'This is a {Unknown|number}.',
+    expected: [],
+  },
   {
     name: 'multiple references',
     input: 'Psst, are you a {string | boolean}',

packages/remark-lint/src/rules/__tests__/validate-links.test.mjs

@@ -111,7 +111,7 @@ describe('validate-links', () => {
         '# Existing heading',
         '[Existing](#existing%2Dheading)',
         '# child_process',
-        '[Node.js-style slug](#child-process)',
+        '[Node.js-style slug](#child_process)',
       ].join('\n\n')
     );
     const invalid = await processMarkdown(

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

@@ -1,4 +1,4 @@
-import { QUERIES } from '@node-core/doc-kit/src/utils/queries/index.mjs';
+import { QUERIES } from '@doc-kit/core/src/utils/queries/index.mjs';
 import { lintRule } from 'unified-lint-rule';
 import { visit } from 'unist-util-visit';
 

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

@@ -1,30 +1,51 @@
-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 { resolveTypeReference } from '@doc-kit/core/src/generators/metadata/utils/transformers.mjs';
 import { lintRule } from 'unified-lint-rule';
 import { visit } from 'unist-util-visit';
 
+const TYPE_RE = /(\{|<)(?! )[^<({})>]+(?! )(\}|>)/g;
+// Excludes HTML comments, closing tags and tags with attributes
+const HTML_TYPE_RE = /^<[^\s!/=]+>$/;
 const MATCH_RE = /\s\||\| /g;
 const REPLACE_RE = /\s*\| */g;
 
 const isTypeNode = node => {
   if (node.type === 'text') {
-    return QUERIES.normalizeTypes.test(node.value);
+    return TYPE_RE.test(node.value);
   }
 
   if (node.type === 'html') {
-    return node.value.match(QUERIES.normalizeTypes)?.includes(node.value);
+    return (
+      HTML_TYPE_RE.test(node.value) &&
+      node.value.match(TYPE_RE)?.includes(node.value)
+    );
   }
 
   return false;
 };
 
+/**
+ * Whether at least one member of a `{type}` reference links somewhere
+ * @param {string} type
+ * @param {Record<string, string>} typeMap
+ * @returns {boolean}
+ */
+const isResolvable = (type, typeMap) =>
+  type
+    .slice(1, -1)
+    .split('|')
+    .some(piece => {
+      const name = piece.trim().replace(/\[\]$/, '');
+
+      return name.length > 0 && resolveTypeReference(name, typeMap) !== '';
+    });
+
 /**
  * Ensures that all type references are valid
  * @type {import('unified-lint-rule').Rule<, import('../api.mjs').Options>}
  */
 const invalidTypeReference = (tree, vfile, { typeMap = {} }) => {
   visit(tree, isTypeNode, node => {
-    const types = node.value.match(QUERIES.normalizeTypes);
+    const types = node.value.match(TYPE_RE);
 
     types.forEach(type => {
       // Ensure wrapped in {}
@@ -50,7 +71,7 @@ const invalidTypeReference = (tree, vfile, { typeMap = {} }) => {
         node.value = node.value.replace(type, normalized);
       }
 
-      if (transformTypeToReferenceLink(type, typeMap) === type) {
+      if (!isResolvable(type, typeMap)) {
         vfile.message(`Invalid type reference: ${type}`, node);
       }
     });

packages/remark-lint/src/rules/validate-links.mjs

@@ -2,7 +2,7 @@ import { readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import createNodeSlugger from '@node-core/doc-kit/src/generators/metadata/utils/slugger.mjs';
+import createNodeSlugger from '@doc-kit/core/src/generators/metadata/utils/slugger.mjs';
 import { toString } from 'mdast-util-to-string';
 import { lintRule } from 'unified-lint-rule';
 import { visit } from 'unist-util-visit';