fix: use DEP code as slug for deprecation headings (#752)

Author: avivkeller

src/generators/legacy-html/constants.mjs

@@ -0,0 +1,5 @@
+'use strict';
+
+// Matches deprecation headings (e.g., "DEP0001: some title") and captures
+// the deprecation code (e.g., "DEP0001") as the first group
+export const DEPRECATION_HEADING_REGEX = /^(DEP\d+):/;

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

@@ -36,4 +36,28 @@ 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 a deprecation heading', () => {
+      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'
+      );
+    });
+  });
 });

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

@@ -1,16 +1,28 @@
 'use strict';
 
+import { DEPRECATION_HEADING_REGEX } from '../constants.mjs';
+
 /**
  * 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.
  *
+ * Headings matching the `DEP####:` pattern return 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 = DEPRECATION_HEADING_REGEX.exec(text);
+
+    if (depMatch) {
+      return depMatch[1];
+    }
+
     const id = `${apiStem}_${text}`
       .toLowerCase()
       .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '')