fix: use DEP code as anchor for deprecation headings in legacy-html

When generating legacy slugs for the deprecations API doc, headings in
the form 'DEP0001: some description' now return just the DEP code (e.g.
DEP0001) as the anchor ID. This matches the behavior of the old tooling
and preserves existing external links like deprecations.html#DEP0190.

The fix lives in createLegacySlugger so it stays within the legacy
generator, as the legacy anchor is the one exposed on the old-format
HTML page.

Fixes: #750

Author: cursoragent

src/generators/legacy-html/utils/__tests__/slugger.test.mjs

@@ -36,4 +36,36 @@ describe('createLegacySlugger', () => {
     assert.strictEqual(getLegacySlug('Hello', 'fs'), 'fs_hello_2');
     assert.strictEqual(getLegacySlug('World', 'fs'), 'fs_world');
   });
+
+  describe('deprecation headings', () => {
+    it('returns the DEP code for deprecation headings in the deprecations doc', () => {
+      const getLegacySlug = createLegacySlugger();
+      assert.strictEqual(
+        getLegacySlug(
+          'DEP0001: `http.OutgoingMessage.prototype.flush`',
+          'deprecations'
+        ),
+        'DEP0001'
+      );
+    });
+
+    it('returns the DEP code regardless of the description text', () => {
+      const getLegacySlug = createLegacySlugger();
+      assert.strictEqual(
+        getLegacySlug(
+          'DEP0190: spawning .bat and .cmd files with child_process.spawn() with shell option',
+          'deprecations'
+        ),
+        'DEP0190'
+      );
+    });
+
+    it('does not apply deprecation special-casing outside the deprecations doc', () => {
+      const getLegacySlug = createLegacySlugger();
+      assert.notStrictEqual(
+        getLegacySlug('DEP0190: some heading', 'child_process'),
+        'DEP0190'
+      );
+    });
+  });
 });

src/generators/legacy-html/utils/slugger.mjs

@@ -1,16 +1,31 @@
 'use strict';
 
+// Matches headings in the deprecations API doc (e.g., "DEP0001: some title")
+// and captures the deprecation code (e.g., "DEP0001") as the first group
+const DEPRECATION_HEADING_REGEX = /^(DEP\d+):/;
+
 /**
  * Creates a stateful slugger for legacy anchor links.
  *
  * Generates underscore-separated slugs in the form `{apiStem}_{text}`,
  * appending `_{n}` for duplicates to preserve historical anchor compatibility.
  *
+ * For the deprecations API doc, headings matching the `DEP####:` pattern use
+ * just the deprecation code (e.g., `DEP0001`) as the anchor, matching the
+ * behavior of the old tooling and preserving existing external links.
+ *
  * @returns {(text: string, apiStem: string) => string}
  */
 export const createLegacySlugger =
   (counters = {}) =>
   (text, apiStem) => {
+    const depMatch =
+      apiStem === 'deprecations' && DEPRECATION_HEADING_REGEX.exec(text);
+
+    if (depMatch) {
+      return depMatch[1];
+    }
+
     const id = `${apiStem}_${text}`
       .toLowerCase()
       .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '')

src/generators/metadata/constants.mjs

@@ -59,9 +59,5 @@ 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,43 +222,6 @@ 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,10 +22,7 @@ import {
 import { UNIST } from '../../../utils/queries/index.mjs';
 import { getRemark as remark } from '../../../utils/remark.mjs';
 import { relative } from '../../../utils/url.mjs';
-import {
-  DEPRECATION_HEADING_REGEX,
-  IGNORE_STABILITY_STEMS,
-} from '../constants.mjs';
+import { IGNORE_STABILITY_STEMS } from '../constants.mjs';
 
 /**
  * This generator generates a flattened list of metadata entries from a API doc
@@ -90,16 +87,8 @@ export const parseApiDoc = ({ path, tree }, typeMap) => {
       heading: headingNode,
     });
 
-    // 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);
+    // Generate slug and update heading data
+    metadata.heading.data.slug = nodeSlugger.slug(metadata.heading.data.text);
 
     // Find the next heading to determine section boundaries
     const nextHeadingNode =