docbridge 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-12
+
+### Added
+
+- `doc_anchor_not_found` suggests the closest anchor in the same Markdown file
+  with `Did you mean`, for both `@doc` annotations and link manifest entries.
+  Anchors in other doc files are not suggested, and no suggestion is added when
+  no anchor is close enough.
+
+## [0.14.0] - 2026-10-08
+
+### Changed
+
+- A heading anchor keeps `_`, as GitHub's heading slugs do. Before, `_` became
+  `-`, so `### title_definitions` gave `#title-definitions`; it now gives
+  `#title_definitions`. A link written with the old `-` form now produces
+  `doc_anchor_not_found`; change it to match the heading, such as
+  `#title_definitions`.
+
 ## [0.13.1] - 2026-10-06
 
 ### Fixed
@@ -558,7 +577,9 @@ Initial release of the SpecLink CLI.
 - `speclink check` command with `--root`, `--json`, and `--audit` options.
 - `speclink --version` (alias `-v`) and `speclink --help` (alias `-h`).
 
-[Unreleased]: https://github.com/salan70/docbridge/compare/v0.13.1...HEAD
+[Unreleased]: https://github.com/salan70/docbridge/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/salan70/docbridge/releases/tag/v0.15.0
+[0.14.0]: https://github.com/salan70/docbridge/releases/tag/v0.14.0
 [0.13.1]: https://github.com/salan70/docbridge/releases/tag/v0.13.1
 [0.13.0]: https://github.com/salan70/docbridge/releases/tag/v0.13.0
 [0.12.0]: https://github.com/salan70/docbridge/releases/tag/v0.12.0

package/dist/bin/darwin-arm64/SHA256SUMS

@@ -1,4 +1,4 @@
-41027ff70b494c96a27c0a4e373a070b47222323d0fb8941f4e694eeaa2f2ad9  docbridge-swift-scanner
-42e6858926db804a07efc8b370b0744e9b23c691b8a363461e5286115c7950ef  docbridge_dart_scanner
+e07fdf1803763dd68bdbb274d2ffe439a5e9bdf19cb1d450d2fb163e0e387752  docbridge-swift-scanner
+eddd64885f3c9071db22459cbcb1665f717c22bf9bd682ab3943b28338023f38  docbridge_dart_scanner
 7fc3e6842b3e1bf425b8fd63e241eee7e64875f16be7ba8d1ae4a25baa7f2338  docbridge-rust-scanner
-720b5a88fda4a2ffd10660bae19dd5070989fbe5c9463421a180f17bb50b7915  docbridge-go-scanner
+03b0a4dc30dd5e6a4958aa8d4ee1a6731c6efa7f6a90782c131641f0e02d084c  docbridge-go-scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -1,4 +1,4 @@
-3f2005f4df20fcf6001111724eac5a9ece412edb5457e3450bd67420e85ba8e3  docbridge-swift-scanner
+8b37cbbfd3afbad16d9b2f1a1a63c6f6db50e63573cdb7c0166ab2a7ea4d5f9a  docbridge-swift-scanner
 b75b14006ca792ed3ca8faf7ceee9e4d33c895f27dd416b640818cf8a4bdd9c8  docbridge_dart_scanner
 e0da7b8cc6ee23704f5fe8514cc309f0bb60380c77b55e3bc5ed113abd1f3478  docbridge-rust-scanner
-2b8820630246507cdaca9de288dc8a0eb5d870db36287cf8ffd6ec31ce13b328  docbridge-go-scanner
+77fbcc7637f0719cc2628e8bcbaf29d0f84651a578a6b324ea6458c9c717b328  docbridge-go-scanner

package/dist/bin/linux-x64/docbridge-swift-scanner

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/bin/linux-x64/docbridge-swift-scanner
 size: 40932352 bytes
-sha256: 3f2005f4df20fcf6001111724eac5a9ece412edb5457e3450bd67420e85ba8e3
+sha256: 8b37cbbfd3afbad16d9b2f1a1a63c6f6db50e63573cdb7c0166ab2a7ea4d5f9a

package/dist/index.js

@@ -175581,7 +175581,7 @@ import { join as join15, resolve as resolve5 } from "node:path";
 // package.json
 var package_default = {
   name: "docbridge",
-  version: "0.13.1",
+  version: "0.15.0",
   description: "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   keywords: [
     "bun",
@@ -177171,6 +177171,51 @@ function pluralize(word, count) {
   return count === 1 ? word : `${word}s`;
 }
 
+// src/shared/suggest.ts
+function nearestMatch(input, candidates) {
+  const ranked = candidates.map((candidate, index) => ({
+    candidate,
+    distance: editDistance(input, candidate),
+    index
+  })).toSorted((left, right) => left.distance - right.distance || left.index - right.index);
+  const abbreviation = ranked.find(({ candidate }) => isOrderedAbbreviation(input, candidate));
+  if (abbreviation !== undefined) {
+    return abbreviation.candidate;
+  }
+  const best = ranked[0];
+  if (best === undefined) {
+    return;
+  }
+  const closeEnough = best.distance <= Math.max(1, Math.floor(best.candidate.length / 2));
+  return closeEnough ? best.candidate : undefined;
+}
+function isOrderedAbbreviation(input, candidate) {
+  if (input.length < 3 || input.length >= candidate.length) {
+    return false;
+  }
+  let candidateIndex = 0;
+  for (const character of input) {
+    const matchIndex = candidate.indexOf(character, candidateIndex);
+    if (matchIndex === -1) {
+      return false;
+    }
+    candidateIndex = matchIndex + 1;
+  }
+  return true;
+}
+function editDistance(left, right) {
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let leftIndex = 1;leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    for (let rightIndex = 1;rightIndex <= right.length; rightIndex += 1) {
+      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      current[rightIndex] = Math.min((current[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + 1, (previous[rightIndex] ?? Number.POSITIVE_INFINITY) + 1, (previous[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + substitutionCost);
+    }
+    previous = current;
+  }
+  return previous[right.length] ?? 0;
+}
+
 // src/link/resolver.ts
 function resolveLinks(input) {
   const diagnostics = [];
@@ -177178,10 +177223,12 @@ function resolveLinks(input) {
   const docFilePaths = new Set(input.docFiles.map((file) => file.filePath));
   const codeFilePaths = new Set(input.codeFiles.map((file) => file.filePath));
   const docAnchorEndpoints = new Set;
+  const docAnchorsByFile = new Map;
   for (const file of input.docFiles) {
     for (const anchor of file.anchors) {
       docAnchorEndpoints.add(anchor.endpoint);
     }
+    docAnchorsByFile.set(file.filePath, file.anchors.map((anchor) => anchor.anchor));
   }
   const docToCodePairs = new Set;
   for (const file of input.docFiles) {
@@ -177216,7 +177263,7 @@ function resolveLinks(input) {
         continue;
       }
       if (!docAnchorEndpoints.has(docEndpoint)) {
-        diagnostics.push(relationshipDiagnostic("doc_anchor_not_found", link.source, docEndpoint, `Doc anchor ${docEndpoint} referenced by ${link.source} does not exist.`, link));
+        diagnostics.push(relationshipDiagnostic("doc_anchor_not_found", link.source, docEndpoint, withAnchorSuggestion(`Doc anchor ${docEndpoint} referenced by ${link.source} does not exist.`, docEndpoint, docAnchorsByFile), link));
         continue;
       }
       if (!docToCodePairs.has(pairKey(docEndpoint, link.source))) {
@@ -177330,6 +177377,11 @@ function unlinkedDocSectionDiagnostic(node, anchor) {
   }
   return diagnostic;
 }
+function withAnchorSuggestion(message, docEndpoint, docAnchorsByFile) {
+  const docFilePath = filePathOf(docEndpoint);
+  const suggestion = nearestMatch(fragmentOf(docEndpoint), docAnchorsByFile.get(docFilePath) ?? []);
+  return suggestion === undefined ? message : `${message} Did you mean \`${docFilePath}#${suggestion}\`?`;
+}
 function pairKey(source, target) {
   return `${source}->${target}`;
 }
@@ -177348,51 +177400,6 @@ function relationshipDiagnostic(code, source, target, message, link) {
   return diagnostic;
 }
 
-// src/shared/suggest.ts
-function nearestMatch(input, candidates) {
-  const ranked = candidates.map((candidate, index) => ({
-    candidate,
-    distance: editDistance(input, candidate),
-    index
-  })).toSorted((left, right) => left.distance - right.distance || left.index - right.index);
-  const abbreviation = ranked.find(({ candidate }) => isOrderedAbbreviation(input, candidate));
-  if (abbreviation !== undefined) {
-    return abbreviation.candidate;
-  }
-  const best = ranked[0];
-  if (best === undefined) {
-    return;
-  }
-  const closeEnough = best.distance <= Math.max(1, Math.floor(best.candidate.length / 2));
-  return closeEnough ? best.candidate : undefined;
-}
-function isOrderedAbbreviation(input, candidate) {
-  if (input.length < 3 || input.length >= candidate.length) {
-    return false;
-  }
-  let candidateIndex = 0;
-  for (const character of input) {
-    const matchIndex = candidate.indexOf(character, candidateIndex);
-    if (matchIndex === -1) {
-      return false;
-    }
-    candidateIndex = matchIndex + 1;
-  }
-  return true;
-}
-function editDistance(left, right) {
-  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
-  for (let leftIndex = 1;leftIndex <= left.length; leftIndex += 1) {
-    const current = [leftIndex];
-    for (let rightIndex = 1;rightIndex <= right.length; rightIndex += 1) {
-      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
-      current[rightIndex] = Math.min((current[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + 1, (previous[rightIndex] ?? Number.POSITIVE_INFINITY) + 1, (previous[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + substitutionCost);
-    }
-    previous = current;
-  }
-  return previous[right.length] ?? 0;
-}
-
 // src/link/manifest-apply.ts
 function applyLinkManifest(input) {
   if (input.manifest.entries.length === 0) {
@@ -177476,7 +177483,7 @@ class ApplyState {
       return false;
     }
     if (!state.anchors.has(entry.docEndpoint)) {
-      this.report("doc_anchor_not_found", entry.docEndpoint, `Doc anchor ${entry.docEndpoint} declared in the link manifest does not exist.`, entry, "doc");
+      this.report("doc_anchor_not_found", entry.docEndpoint, this.docAnchorNotFoundMessage(entry, state), entry, "doc");
       return false;
     }
     this.markAnnotated(state, entry.docEndpoint);
@@ -177546,6 +177553,12 @@ class ApplyState {
     const suggestion = nearestMatch(entry.code.fragment, candidates);
     return suggestion === undefined ? base : `${base} Did you mean \`${suggestion}\`?`;
   }
+  docAnchorNotFoundMessage(entry, state) {
+    const base = `Doc anchor ${entry.docEndpoint} declared in the link manifest does not exist.`;
+    const candidates = state.file.anchors.map((anchor) => anchor.anchor);
+    const suggestion = nearestMatch(entry.doc.fragment, candidates);
+    return suggestion === undefined ? base : `${base} Did you mean \`${entry.doc.filePath}#${suggestion}\`?`;
+  }
   report(code, target, message, entry, side, language) {
     const range = side === "code" ? entry.codeRange : entry.docRange;
     const diagnostic = {
@@ -177597,24 +177610,13 @@ function manifestLink(source, target, entry, side) {
 }
 
 // src/shared/cancelable.ts
-function deferred() {
-  let settle;
-  const promise = new Promise((resolve2, reject) => {
-    settle = { resolve: resolve2, reject };
-  });
-  return {
-    promise,
-    resolve: (value) => settle?.resolve(value),
-    reject: (error) => settle?.reject(error)
-  };
-}
 function settledCancelable(value) {
   return { promise: Promise.resolve(value), cancel: () => {
     return;
   } };
 }
 function mapCancelable(task, map) {
-  const mapped = deferred();
+  const mapped = Promise.withResolvers();
   let cancelled = false;
   task.promise.then((value) => {
     if (cancelled) {
@@ -177640,7 +177642,7 @@ function isAbortError(error) {
   return error instanceof Error && error.name === "AbortError";
 }
 function cancelableSequence(body) {
-  const outcome = deferred();
+  const outcome = Promise.withResolvers();
   let cancelled = false;
   let running;
   const step = async (next) => {
@@ -178539,7 +178541,7 @@ function workerTimeoutMs(fileCount) {
   return 30000 + 1000 * fileCount;
 }
 function runScannerWorkerProcess(input) {
-  const run = deferred();
+  const run = Promise.withResolvers();
   let settled = false;
   let timer;
   let grace;
@@ -179495,7 +179497,7 @@ function stripClosingHashes(text) {
 }
 function toAnchor(headingText) {
   const lowered = headingText.toLowerCase();
-  const replaced = lowered.replace(/[^\p{L}\p{N}]+/gu, "-");
+  const replaced = lowered.replace(/[^\p{L}\p{N}_]+/gu, "-");
   return replaced.replace(/^-+/, "").replace(/-+$/, "");
 }
 function matchCodeComment(line, filePath, lineNumber) {

package/docs/user/linking.md

@@ -255,8 +255,9 @@ Use the scanner-produced canonical symbol ID exactly.
 ## Heading anchors and reciprocity
 
 DocBridge creates anchors from ATX headings only. It lowercases the heading,
-collapses runs of whitespace and punctuation to `-`, preserves Unicode letters
-and numbers, and removes leading and trailing hyphens. `## Login Spec (v2)` is
+collapses runs of whitespace and punctuation other than `_` to `-`, keeps `_`
+as GitHub's heading slugs do, preserves Unicode letters and numbers, and removes
+leading and trailing hyphens. `## Login Spec (v2)` is
 `#login-spec-v2`.
 
 Empty headings have no anchor; a `@code` annotation attached to an empty

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docbridge",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   "keywords": [
     "bun",