fix(metadata): keep hyphens in heading slugs like the old doc tooling

#610 replaced the `--+` collapse with `/^(?!-)(?!-+$).*?(--+)/`, which
also swallows everything before the first run of hyphens, so headings
lost their prefix: `-c`, `--check` became `#-check` and
`DEP0062: node --debug` became `#-debug`. nodejs.org/api serves those
anchors today.

The old tooling (getId in tools/doc/html.mjs) never collapsed or
trimmed hyphens: it lowercased, dropped punctuation and turned spaces
into hyphens, which is what github-slugger already does. Dropping the
three hyphen rules matches its anchors for all 5809 headings in
doc/api, where the current rules differ on 18 of them. That's the same
drift #757 reported for `--` flags, which #810 fixed for that one case.

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

Author: ovflowd

.changeset/legacy-hyphen-anchors.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/core': patch
+---
+
+Keep leading, trailing and repeated hyphens in heading slugs, so anchors match the old Node.js doc tooling again (`#-c---check` instead of `#-check`).

packages/core/src/generators/metadata/constants.mjs

@@ -7,9 +7,6 @@ export const DOC_API_SLUGS_REPLACEMENTS = [
   { from: /node.js/i, to: 'nodejs' }, // Replace Node.js
   { from: /&/, to: '-and-' }, // Replace &
   { from: /[/,:;\\ ]/g, to: '-' }, // Replace /,:;\. and whitespace
-  { from: /^-(?!-|$)/g, to: '' }, // Remove a single leading hyphen
-  { from: /(?<!^-*)-+$/g, to: '' }, // Remove any trailing hyphens
-  { from: /^(?!-)(?!-+$).*?(--+)/g, to: '-' }, // Replace multiple hyphens
 ];
 
 // Matches Node.js deprecation headings such as "DEP0001: Description".

packages/core/src/generators/metadata/utils/__tests__/slugger.test.mjs

@@ -46,41 +46,36 @@ describe('slug', () => {
     });
   });
 
-  describe('leading hyphen removal', () => {
-    it('removes a single leading hyphen', () => {
-      assert.strictEqual(slug('-foo', identity), 'foo');
-    });
-
-    it('preserves multiple leading hyphens', () => {
+  describe('hyphens', () => {
+    it('preserves leading hyphens', () => {
+      assert.strictEqual(slug('-foo', identity), '-foo');
       assert.strictEqual(slug('--permission', identity), '--permission');
     });
 
-    it('preserves an all-hyphen string', () => {
-      assert.strictEqual(slug('---', identity), '---');
-    });
-  });
-
-  describe('trailing hyphen removal', () => {
-    it('removes a single trailing hyphen', () => {
-      assert.strictEqual(slug('foo-', identity), 'foo');
-    });
-
-    it('removes multiple trailing hyphens', () => {
-      assert.strictEqual(slug('foo--', identity), 'foo');
+    it('preserves trailing hyphens', () => {
+      assert.strictEqual(slug('foo--', identity), 'foo--');
     });
-  });
 
-  describe('consecutive hyphen replacement', () => {
-    it('replaces from start of string up to and including double-hyphen with a single hyphen', () => {
-      assert.strictEqual(slug('foo--bar', identity), '-bar');
+    it('preserves consecutive hyphens', () => {
+      assert.strictEqual(slug('foo--bar', identity), 'foo--bar');
     });
 
-    it('does not fire on an all-hyphen string', () => {
+    it('preserves an all-hyphen string', () => {
       assert.strictEqual(slug('---', identity), '---');
     });
+  });
 
-    it('does not collapse leading double hyphen flags', () => {
-      assert.strictEqual(slug('--allow-fs-read', identity), '--allow-fs-read');
+  describe('legacy Node.js anchors', () => {
+    it('matches the anchors of the old doc tooling', () => {
+      assert.strictEqual(slug('`-c`, `--check`'), '-c---check');
+      assert.strictEqual(
+        slug('DEP0147: `fs.rmdir(path, { recursive: true })`'),
+        'dep0147-fsrmdirpath--recursive-true-'
+      );
+      assert.strictEqual(
+        slug('Stability & Deprecation'),
+        'stability--deprecation'
+      );
     });
   });