docbridge 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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
@@ -568,7 +577,8 @@ 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.14.0...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

package/dist/bin/darwin-arm64/SHA256SUMS

@@ -1,4 +1,4 @@
-2db42ddea8060f988cea4933696e73d652ae5b807a8e8ff00249375faf2b0be4  docbridge-swift-scanner
-f3da86ea5a0c1c92fa1e1f077251bec490e294d257b09cd03a46c8ce382aad19  docbridge_dart_scanner
+e07fdf1803763dd68bdbb274d2ffe439a5e9bdf19cb1d450d2fb163e0e387752  docbridge-swift-scanner
+eddd64885f3c9071db22459cbcb1665f717c22bf9bd682ab3943b28338023f38  docbridge_dart_scanner
 7fc3e6842b3e1bf425b8fd63e241eee7e64875f16be7ba8d1ae4a25baa7f2338  docbridge-rust-scanner
-1646b06856b0420acdcb82d1692b7afea83fe2b7666adeb6412c99782dfc8cae  docbridge-go-scanner
+03b0a4dc30dd5e6a4958aa8d4ee1a6731c6efa7f6a90782c131641f0e02d084c  docbridge-go-scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -1,4 +1,4 @@
-0c023cfacede26a217a62420f9da1206b93c228122a3685469685a3db89f7735  docbridge-swift-scanner
+8b37cbbfd3afbad16d9b2f1a1a63c6f6db50e63573cdb7c0166ab2a7ea4d5f9a  docbridge-swift-scanner
 b75b14006ca792ed3ca8faf7ceee9e4d33c895f27dd416b640818cf8a4bdd9c8  docbridge_dart_scanner
 e0da7b8cc6ee23704f5fe8514cc309f0bb60380c77b55e3bc5ed113abd1f3478  docbridge-rust-scanner
-5b8aee5b85a38679875c473b2dc32f021f022cba242785bb0fd94ee6fda0a6bf  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: 0c023cfacede26a217a62420f9da1206b93c228122a3685469685a3db89f7735
+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.14.0",
+  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 = {

package/package.json

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