From e35d78c2505bb6aa29994953934514415720cde1 Mon Sep 17 00:00:00 2001
From: Fadhlan <fadhlanzap@gmail.com>
Date: Sat, 18 Jul 2026 14:49:14 +0700
Subject: [PATCH 1/2] fix: preserve deprecation codes in table of contents

Signed-off-by: Fadhlan <fadhlanzap@gmail.com>
---
 .changeset/tidy-deprecations-smile.md         |  5 +++++
 .../utils/__tests__/buildBarProps.test.mjs    | 22 +++++++++++++++++++
 .../jsx-ast/utils/buildBarProps.mjs           |  7 ++++++
 3 files changed, 34 insertions(+)
 create mode 100644 .changeset/tidy-deprecations-smile.md

diff --git a/.changeset/tidy-deprecations-smile.md b/.changeset/tidy-deprecations-smile.md
new file mode 100644
index 00000000..d9e7c7bb
--- /dev/null
+++ b/.changeset/tidy-deprecations-smile.md
@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': patch
+---
+
+Preserve deprecation codes in generated table-of-contents labels.
diff --git a/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs b/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs
index 38ea8d55..bd5fe6d8 100644
--- a/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs
+++ b/src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs
@@ -116,6 +116,28 @@ describe('extractHeadings', () => {
     assert.equal(result[1].value, 'new Buffer');
   });
 
+  it('preserves deprecation codes in heading labels', () => {
+    const entries = [
+      {
+        heading: {
+          depth: 2,
+          data: {
+            text: 'DEP0001: `http.OutgoingMessage.prototype.flush`',
+            name: 'http.OutgoingMessage.prototype.flush',
+            slug: 'DEP0001',
+          },
+        },
+      },
+    ];
+
+    const result = extractHeadings(entries);
+
+    assert.equal(
+      result[0].value,
+      'DEP0001: http.OutgoingMessage.prototype.flush'
+    );
+  });
+
   it('drops overload headings and links to the first signature', () => {
     const entries = [
       {
diff --git a/src/generators/jsx-ast/utils/buildBarProps.mjs b/src/generators/jsx-ast/utils/buildBarProps.mjs
index cdad9536..351965db 100644
--- a/src/generators/jsx-ast/utils/buildBarProps.mjs
+++ b/src/generators/jsx-ast/utils/buildBarProps.mjs
@@ -9,6 +9,9 @@ import { TOC_MAX_HEADING_DEPTH } from '../constants.mjs';
 // rather than the full signature.
 const FUNCTION_HEADING_TYPES = new Set(['method', 'ctor', 'classMethod']);
 
+// Deprecation codes are part of the heading label, not a generic type prefix.
+const DEPRECATION_HEADING_REGEX = /^DEP\d+:/;
+
 /**
  * Generate a combined plain text string from all MDAST entries for estimating reading time.
  *
@@ -56,6 +59,10 @@ const headingLabel = data => {
     return cliFlagOrEnv.at(-1)[1];
   }
 
+  if (DEPRECATION_HEADING_REGEX.test(data.text)) {
+    return data.text.replace(/`/g, '').trim();
+  }
+
   return (
     data.text
       // Remove any containing code blocks

From 60bd582348c7b793e97699cf05fbbfbb5b8b1b59 Mon Sep 17 00:00:00 2001
From: Fadhlan <fadhlanzap@gmail.com>
Date: Sun, 19 Jul 2026 07:59:45 +0700
Subject: [PATCH 2/2] refactor: preserve DEP prefix in prefix regex

---
 src/generators/jsx-ast/utils/buildBarProps.mjs | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/src/generators/jsx-ast/utils/buildBarProps.mjs b/src/generators/jsx-ast/utils/buildBarProps.mjs
index 351965db..d535c30a 100644
--- a/src/generators/jsx-ast/utils/buildBarProps.mjs
+++ b/src/generators/jsx-ast/utils/buildBarProps.mjs
@@ -9,9 +9,6 @@ import { TOC_MAX_HEADING_DEPTH } from '../constants.mjs';
 // rather than the full signature.
 const FUNCTION_HEADING_TYPES = new Set(['method', 'ctor', 'classMethod']);
 
-// Deprecation codes are part of the heading label, not a generic type prefix.
-const DEPRECATION_HEADING_REGEX = /^DEP\d+:/;
-
 /**
  * Generate a combined plain text string from all MDAST entries for estimating reading time.
  *
@@ -59,16 +56,13 @@ const headingLabel = data => {
     return cliFlagOrEnv.at(-1)[1];
   }
 
-  if (DEPRECATION_HEADING_REGEX.test(data.text)) {
-    return data.text.replace(/`/g, '').trim();
-  }
-
   return (
     data.text
       // Remove any containing code blocks
       .replace(/`/g, '')
-      // Remove any prefixes (i.e. 'Class:')
-      .replace(/^[^:]+:/, '')
+      // Remove any prefixes (i.e. 'Class:'), except deprecation codes
+      // (i.e. 'DEP0001:') which are part of the label
+      .replace(/^(?!DEP\d+:)[^:]+:/, '')
       // Trim the remaining whitespace
       .trim()
   );