fix: use DEP code as slug for deprecation headings

Headings in deprecations.md use the form 'DEP0001: some description'.
The old tooling generated the DEP code (e.g., 'DEP0001') as the anchor
ID for these headings, producing stable links like #DEP0190. The new
tooling was generating long slugs from the full heading text, breaking
existing external links.

When processing the 'deprecations' API doc, detect headings that match
the DEP#### pattern and use just the code as the slug rather than the
full text-derived slug.

Fixes: #750

Author: cursoragent

src/generators/metadata/constants.mjs

@@ -59,5 +59,9 @@ export const DOC_API_HEADING_TYPES = [
 // This regex is used to match basic TypeScript generic types (e.g., Promise<string>)
 export const TYPE_GENERIC_REGEX = /^([^<]+)<([^>]+)>$/;
 
+// This regex matches headings in the deprecations API doc (e.g., "DEP0001: some title")
+// and captures the deprecation code (e.g., "DEP0001") as the first group
+export const DEPRECATION_HEADING_REGEX = /^(DEP\d+):/;
+
 // This is the base URL of the Man7 documentation
 export const DOC_MAN_BASE_URL = 'http://man7.org/linux/man-pages/man';

src/generators/metadata/utils/__tests__/parse.test.mjs

@@ -222,6 +222,43 @@ describe('parseApiDoc', () => {
     });
   });
 
+  describe('deprecation heading slugs', () => {
+    it('uses the DEP code as slug for headings in the deprecations doc', () => {
+      const tree = u('root', [
+        h('DEP0001: `http.OutgoingMessage.prototype.flush`', 3),
+      ]);
+      const [entry] = parseApiDoc({ path: '/deprecations', tree }, typeMap);
+
+      assert.strictEqual(entry.heading.data.slug, 'DEP0001');
+    });
+
+    it('uses the DEP code as slug regardless of the heading text that follows', () => {
+      const tree = u('root', [
+        h(
+          'DEP0190: spawning .bat and .cmd files with child_process.spawn() with shell option',
+          3
+        ),
+      ]);
+      const [entry] = parseApiDoc({ path: '/deprecations', tree }, typeMap);
+
+      assert.strictEqual(entry.heading.data.slug, 'DEP0190');
+    });
+
+    it('does not use the DEP code shortcut for non-deprecations docs', () => {
+      const tree = u('root', [h('DEP0190: some section heading', 3)]);
+      const [entry] = parseApiDoc({ path, tree }, typeMap);
+
+      assert.notStrictEqual(entry.heading.data.slug, 'DEP0190');
+    });
+
+    it('uses normal slug for non-DEP headings in the deprecations doc', () => {
+      const tree = u('root', [h('List of deprecated APIs', 2)]);
+      const [entry] = parseApiDoc({ path: '/deprecations', tree }, typeMap);
+
+      assert.strictEqual(entry.heading.data.slug, 'list-of-deprecated-apis');
+    });
+  });
+
   describe('document without headings', () => {
     it('produces one entry for content with no headings', () => {
       const tree = u('root', [

src/generators/metadata/utils/parse.mjs

@@ -22,7 +22,10 @@ import {
 import { UNIST } from '../../../utils/queries/index.mjs';
 import { getRemark as remark } from '../../../utils/remark.mjs';
 import { relative } from '../../../utils/url.mjs';
-import { IGNORE_STABILITY_STEMS } from '../constants.mjs';
+import {
+  DEPRECATION_HEADING_REGEX,
+  IGNORE_STABILITY_STEMS,
+} from '../constants.mjs';
 
 /**
  * This generator generates a flattened list of metadata entries from a API doc
@@ -87,8 +90,16 @@ export const parseApiDoc = ({ path, tree }, typeMap) => {
       heading: headingNode,
     });
 
-    // Generate slug and update heading data
-    metadata.heading.data.slug = nodeSlugger.slug(metadata.heading.data.text);
+    // Generate slug and update heading data.
+    // For the deprecations API doc, headings like "DEP0001: some title" use
+    // just the deprecation code (e.g., "DEP0001") as the anchor to preserve
+    // compatibility with existing external links.
+    const depMatch =
+      api === 'deprecations' &&
+      DEPRECATION_HEADING_REGEX.exec(metadata.heading.data.text);
+    metadata.heading.data.slug = depMatch
+      ? depMatch[1]
+      : nodeSlugger.slug(metadata.heading.data.text);
 
     // Find the next heading to determine section boundaries
     const nextHeadingNode =