docbridge 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-10-12
+
+### Added
+
+- A language entry under `include.code` accepts an optional `exclude` array.
+  Matched files that an `exclude` pattern selects are not managed, such as
+  Flutter's `*.g.dart` and `*.freezed.dart` files.
+
+## [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 +585,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.14.0...HEAD
+[Unreleased]: https://github.com/salan70/docbridge/compare/v0.16.0...HEAD
+[0.16.0]: https://github.com/salan70/docbridge/releases/tag/v0.16.0
+[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
+fbe811d3c84850751dca02c4b9ed6c71404d1b6e6666f4e0955054b12f4448e2  docbridge-swift-scanner
+a49fb9474445a3d7d35ab332a1660c3ddd50dbe4ed11adb81c19d99568abb9fa  docbridge_dart_scanner
 7fc3e6842b3e1bf425b8fd63e241eee7e64875f16be7ba8d1ae4a25baa7f2338  docbridge-rust-scanner
-1646b06856b0420acdcb82d1692b7afea83fe2b7666adeb6412c99782dfc8cae  docbridge-go-scanner
+81a1f97936f7b503131a1380dbcdbe610c5662ffa86284af754c7e6dfd792f21  docbridge-go-scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -1,4 +1,4 @@
-0c023cfacede26a217a62420f9da1206b93c228122a3685469685a3db89f7735  docbridge-swift-scanner
+86af421dafc4dbff3498893c7600e44e6bdb230177ae63a0639267ebba78ed94  docbridge-swift-scanner
 b75b14006ca792ed3ca8faf7ceee9e4d33c895f27dd416b640818cf8a4bdd9c8  docbridge_dart_scanner
 e0da7b8cc6ee23704f5fe8514cc309f0bb60380c77b55e3bc5ed113abd1f3478  docbridge-rust-scanner
-5b8aee5b85a38679875c473b2dc32f021f022cba242785bb0fd94ee6fda0a6bf  docbridge-go-scanner
+c89df71f1762fa25da26de1ffbd511c9ebc967e088d9653115b944c7a9b02c00  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: 86af421dafc4dbff3498893c7600e44e6bdb230177ae63a0639267ebba78ed94

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.16.0",
   description: "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   keywords: [
     "bun",
@@ -175829,7 +175829,7 @@ function collectCodeFiles(projectRoot, codeInclude) {
     if (entry === undefined) {
       continue;
     }
-    for (const relPath of collectLanguageFiles(projectRoot, language, entry.patterns)) {
+    for (const relPath of collectLanguageFiles(projectRoot, language, entry)) {
       if (seen.has(relPath)) {
         continue;
       }
@@ -175847,7 +175847,7 @@ function codeFileOwners(projectRoot, codeInclude) {
     if (entry === undefined) {
       continue;
     }
-    for (const relPath of collectLanguageFiles(projectRoot, language, entry.patterns)) {
+    for (const relPath of collectLanguageFiles(projectRoot, language, entry)) {
       const existing = owners.get(relPath);
       if (existing === undefined) {
         owners.set(relPath, [language]);
@@ -175858,8 +175858,9 @@ function codeFileOwners(projectRoot, codeInclude) {
   }
   return owners;
 }
-function collectLanguageFiles(projectRoot, language, patterns) {
-  return collectFiles(projectRoot, patterns).filter((relPath) => !hasExcludedSuffix(language, relPath));
+function collectLanguageFiles(projectRoot, language, entry) {
+  const excluded = entry.exclude ?? [];
+  return collectFiles(projectRoot, entry.patterns).filter((relPath) => !hasExcludedSuffix(language, relPath) && !excluded.some((pattern) => matchGlob(pattern, relPath)));
 }
 
 // src/config/scanner-runtimes.ts
@@ -175918,7 +175919,7 @@ var EMPTY_CONFIG = {
 };
 var KNOWN_TOP_LEVEL_KEYS = new Set(["$schema", "include", "scanners"]);
 var KNOWN_INCLUDE_KEYS = new Set(["code", "docs"]);
-var KNOWN_CODE_ENTRY_KEYS = new Set(["patterns", "visibility"]);
+var KNOWN_CODE_ENTRY_KEYS = new Set(["patterns", "exclude", "visibility"]);
 var LANGUAGE_VISIBILITY = {
   typescript: ["public", "protected", "private"],
   swift: ["public", "open", "internal"],
@@ -176047,6 +176048,9 @@ function validateCodeEntry(language, value, diagnostics) {
   }
   const before = diagnostics.length;
   validatePatternArray(value.patterns, `code.${language}.patterns`, LANGUAGE_SUFFIXES[language], EXCLUDED_SUFFIXES[language], diagnostics);
+  if ("exclude" in value) {
+    validateExcludePatterns(language, value.exclude, diagnostics);
+  }
   if ("visibility" in value) {
     if (!isStringArray(value.visibility)) {
       diagnostics.push(configDiagnostic2("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` must be an array of strings.`));
@@ -176058,6 +176062,9 @@ function validateCodeEntry(language, value, diagnostics) {
     return;
   }
   const entry = { patterns: value.patterns };
+  if (isStringArray(value.exclude)) {
+    entry.exclude = value.exclude;
+  }
   if (isStringArray(value.visibility)) {
     entry.visibility = value.visibility;
   }
@@ -176071,6 +176078,14 @@ function validateVisibilityOptions(language, values, target, diagnostics) {
     }
   }
 }
+function validateExcludePatterns(language, value, diagnostics) {
+  const target = `include.code.${language}.exclude`;
+  if (!Array.isArray(value)) {
+    diagnostics.push(configDiagnostic2("config_invalid_value", target, `\`${target}\` must be an array of strings.`));
+    return;
+  }
+  validatePatternStrings(value, `code.${language}.exclude`, LANGUAGE_SUFFIXES[language], EXCLUDED_SUFFIXES[language], diagnostics);
+}
 function validatePatternArray(value, field, suffixes, excludedSuffixes, diagnostics) {
   const target = `include.${field}`;
   if (!Array.isArray(value)) {
@@ -176081,6 +176096,10 @@ function validatePatternArray(value, field, suffixes, excludedSuffixes, diagnost
     diagnostics.push(configDiagnostic2("config_invalid_value", target, `\`${target}\` must contain at least one pattern.`));
     return;
   }
+  validatePatternStrings(value, field, suffixes, excludedSuffixes, diagnostics);
+}
+function validatePatternStrings(value, field, suffixes, excludedSuffixes, diagnostics) {
+  const target = `include.${field}`;
   for (const pattern of value) {
     if (typeof pattern !== "string") {
       diagnostics.push(configDiagnostic2("config_invalid_value", target, `\`${target}\` patterns must be strings.`));
@@ -177171,6 +177190,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 +177242,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 +177282,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 +177396,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 +177419,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 +177502,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 +177572,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 = {
@@ -179805,7 +179837,7 @@ class Project {
         if (hasExcludedSuffix(language, relPath)) {
           continue;
         }
-        if (entry.patterns.some((pattern) => matchGlob(pattern, relPath))) {
+        if (entry.patterns.some((pattern) => matchGlob(pattern, relPath)) && !(entry.exclude ?? []).some((pattern) => matchGlob(pattern, relPath))) {
           seen.add(relPath);
           all.push({ language, relPath });
         }

package/docs/user/configuration.md

@@ -69,7 +69,9 @@ source file may match only one language.
 | `ruby`       | `.rb`                                                | `public`, `protected`, `private`            | `public`              | CRuby 3.3 or later        |
 | `java`       | `.java`                                              | `public`, `protected`, `package`, `private` | `public`              | JDK 17 or later           |
 
-Patterns must end with one of the language's extensions. The npm package
+Patterns must end with one of the language's extensions. Each language also
+accepts an optional `exclude` array that removes matched files, such as generated
+code; see [Excluded files](#excluded-files). The npm package
 bundles the Swift, Dart, Rust, and Go scanners for `darwin-arm64` and
 `linux-x64`; TypeScript, JavaScript, and Markdown need no scanner binary.
 Python, Ruby, and Java are scanned by workers in the package that run on the
@@ -136,9 +138,29 @@ DocBridge there.
 
 ## Excluded files
 
-The configuration has no `exclude` property and no glob negation. Narrow the
-positive include patterns when tests, fixtures, generated files, or general
-documentation should stay outside the graph:
+Use `exclude` in a language entry to remove matched files that should not be
+managed, such as generated code. Flutter's `build_runner` outputs `*.g.dart` and
+`*.freezed.dart` are the usual case:
+
+```json
+{
+  "include": {
+    "code": {
+      "dart": {
+        "patterns": ["lib/**/*.dart"],
+        "exclude": ["lib/**/*.g.dart", "lib/**/*.freezed.dart"]
+      }
+    },
+    "docs": ["docs/**/*.md"]
+  }
+}
+```
+
+Each `exclude` pattern follows the `patterns` rules and must end with the
+language's extension. The configuration has no glob negation, so `exclude` is the
+only way to remove files that `patterns` matches. Narrow the positive include
+patterns when tests, fixtures, or general documentation should stay outside the
+graph:
 
 ```json
 {

package/package.json

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

package/schemas/docbridge.schema.json

@@ -78,6 +78,13 @@
             "pattern": "^(?!.*\\.d\\.[cm]?ts$).*\\.(ts|tsx|mts|cts)$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*\\.d\\.[cm]?ts$).*\\.(ts|tsx|mts|cts)$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {
@@ -100,6 +107,13 @@
             "pattern": "\\.swift$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "\\.swift$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {
@@ -122,6 +136,13 @@
             "pattern": "\\.dart$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "\\.dart$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {
@@ -144,6 +165,13 @@
             "pattern": "\\.rs$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "\\.rs$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {
@@ -166,6 +194,13 @@
             "pattern": "\\.go$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "\\.go$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {
@@ -188,6 +223,13 @@
             "pattern": "\\.(js|jsx|mjs|cjs)$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "\\.(js|jsx|mjs|cjs)$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {
@@ -210,6 +252,13 @@
             "pattern": "\\.py$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "\\.py$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {
@@ -232,6 +281,13 @@
             "pattern": "\\.rb$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "\\.rb$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {
@@ -254,6 +310,13 @@
             "pattern": "\\.java$"
           }
         },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "\\.java$"
+          }
+        },
         "visibility": {
           "type": "array",
           "items": {