docbridge 0.6.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docbridge",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   "keywords": [
     "bun",
@@ -25,6 +25,7 @@
   },
   "files": [
     "dist",
+    "docs/user",
     "schemas",
     "templates/skills",
     "README.md",
@@ -37,10 +38,11 @@
     "check": "bun run src/cli/index.ts check",
     "check:example": "bun run src/cli/index.ts check --root examples/typescript",
     "test": "bun test",
-    "build": "bun build src/cli/index.ts --outdir dist --target bun"
+    "build": "bun build src/cli/index.ts --outdir dist --target node"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
+    "ajv": "^8.20.0",
     "oxfmt": "0.57.0",
     "oxlint": "1.73.0",
     "typescript": "^5.9.0"

package/schemas/common-output.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "common-output.schema.json",
+  "title": "DocBridge Common Output Definitions",
+  "$defs": {
+    "location": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["filePath", "line", "column"],
+      "properties": {
+        "filePath": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "column": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "position": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["line", "column"],
+      "properties": {
+        "line": { "type": "integer", "minimum": 1 },
+        "column": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "range": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["start", "end"],
+      "properties": {
+        "start": { "$ref": "#/$defs/position" },
+        "end": { "$ref": "#/$defs/position" }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["severity", "code", "target", "message"],
+      "properties": {
+        "severity": {
+          "type": "string",
+          "enum": ["error", "warning"]
+        },
+        "code": { "type": "string" },
+        "target": { "type": "string" },
+        "language": {
+          "type": "string",
+          "enum": ["typescript", "swift", "dart", "rust"]
+        },
+        "source": { "type": "string" },
+        "message": { "type": "string" },
+        "location": { "$ref": "#/$defs/location" },
+        "range": { "$ref": "#/$defs/range" }
+      }
+    }
+  }
+}

package/schemas/context-output.schema.json

@@ -35,7 +35,7 @@
           },
           "language": {
             "type": "string",
-            "enum": ["typescript", "swift", "dart"],
+            "enum": ["typescript", "swift", "dart", "rust"],
             "description": "Code language for code context blocks."
           },
           "startLine": {
@@ -66,37 +66,7 @@
     "diagnostics": {
       "type": "array",
       "description": "Check diagnostics located in the input files, in check order.",
-      "items": {
-        "type": "object",
-        "required": ["severity", "code", "target", "message"],
-        "properties": {
-          "severity": {
-            "type": "string",
-            "enum": ["error", "warning"]
-          },
-          "code": {
-            "type": "string"
-          },
-          "target": {
-            "type": "string"
-          },
-          "source": {
-            "type": "string"
-          },
-          "message": {
-            "type": "string"
-          },
-          "location": {
-            "type": "object",
-            "required": ["filePath", "line", "column"],
-            "properties": {
-              "filePath": { "type": "string" },
-              "line": { "type": "integer", "minimum": 1 },
-              "column": { "type": "integer", "minimum": 1 }
-            }
-          }
-        }
-      }
+      "items": { "$ref": "common-output.schema.json#/$defs/diagnostic" }
     },
     "summary": {
       "type": "object",

package/schemas/docbridge.schema.json

@@ -18,23 +18,25 @@
           "additionalProperties": false,
           "minProperties": 1,
           "properties": {
-            "typescript": { "$ref": "#/$defs/codeLanguageEntry" },
-            "swift": { "$ref": "#/$defs/codeLanguageEntry" },
-            "dart": { "$ref": "#/$defs/codeLanguageEntry" }
+            "typescript": { "$ref": "#/$defs/typescriptEntry" },
+            "swift": { "$ref": "#/$defs/swiftEntry" },
+            "dart": { "$ref": "#/$defs/dartEntry" },
+            "rust": { "$ref": "#/$defs/rustEntry" }
           }
         },
         "docs": {
           "type": "array",
           "minItems": 1,
           "items": {
-            "type": "string"
+            "type": "string",
+            "pattern": "\\.md$"
           }
         }
       }
     }
   },
   "$defs": {
-    "codeLanguageEntry": {
+    "typescriptEntry": {
       "type": "object",
       "additionalProperties": false,
       "required": ["patterns"],
@@ -43,13 +45,81 @@
           "type": "array",
           "minItems": 1,
           "items": {
-            "type": "string"
+            "type": "string",
+            "pattern": "^(?!.*\\.d\\.ts$).*\\.ts$"
           }
         },
         "visibility": {
           "type": "array",
           "items": {
-            "type": "string"
+            "type": "string",
+            "enum": ["public", "protected", "private"]
+          }
+        }
+      }
+    },
+    "swiftEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\.swift$"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["public", "open", "internal"]
+          }
+        }
+      }
+    },
+    "dartEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\.dart$"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["public"]
+          }
+        }
+      }
+    },
+    "rustEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\.rs$"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["pub", "private"]
           }
         }
       }

package/schemas/graph-output.schema.json

@@ -31,11 +31,11 @@
           },
           "language": {
             "type": "string",
-            "enum": ["typescript", "swift", "dart"],
+            "enum": ["typescript", "swift", "dart", "rust"],
             "description": "Code language for code nodes."
           },
-          "location": { "$ref": "#/$defs/location" },
-          "range": { "$ref": "#/$defs/range" },
+          "location": { "$ref": "common-output.schema.json#/$defs/location" },
+          "range": { "$ref": "common-output.schema.json#/$defs/range" },
           "content": {
             "oneOf": [
               {
@@ -85,8 +85,8 @@
             "type": "string",
             "description": "Resolved target endpoint of the annotation edge."
           },
-          "location": { "$ref": "#/$defs/location" },
-          "range": { "$ref": "#/$defs/range" }
+          "location": { "$ref": "common-output.schema.json#/$defs/location" },
+          "range": { "$ref": "common-output.schema.json#/$defs/range" }
         }
       }
     },
@@ -112,7 +112,7 @@
     },
     "diagnostics": {
       "type": "array",
-      "items": { "$ref": "#/$defs/diagnostic" }
+      "items": { "$ref": "common-output.schema.json#/$defs/diagnostic" }
     },
     "summary": {
       "type": "object",
@@ -136,51 +136,5 @@
         "diagnostics": { "type": "integer", "minimum": 0 }
       }
     }
-  },
-  "$defs": {
-    "location": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["filePath", "line", "column"],
-      "properties": {
-        "filePath": { "type": "string" },
-        "line": { "type": "integer", "minimum": 1 },
-        "column": { "type": "integer", "minimum": 1 }
-      }
-    },
-    "position": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["line", "column"],
-      "properties": {
-        "line": { "type": "integer", "minimum": 1 },
-        "column": { "type": "integer", "minimum": 1 }
-      }
-    },
-    "range": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["start", "end"],
-      "properties": {
-        "start": { "$ref": "#/$defs/position" },
-        "end": { "$ref": "#/$defs/position" }
-      }
-    },
-    "diagnostic": {
-      "type": "object",
-      "required": ["severity", "code", "target", "message"],
-      "properties": {
-        "severity": {
-          "type": "string",
-          "enum": ["error", "warning"]
-        },
-        "code": { "type": "string" },
-        "target": { "type": "string" },
-        "source": { "type": "string" },
-        "message": { "type": "string" },
-        "location": { "$ref": "#/$defs/location" },
-        "range": { "$ref": "#/$defs/range" }
-      }
-    }
   }
 }

package/schemas/scanner-worker.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "scanner-worker.schema.json",
+  "title": "DocBridge Scanner Worker Protocol",
+  "description": "Request and response payloads exchanged with scanner workers.",
+  "oneOf": [{ "$ref": "#/$defs/request" }, { "$ref": "#/$defs/response" }],
+  "$defs": {
+    "language": {
+      "type": "string",
+      "enum": ["typescript", "swift", "dart", "rust"]
+    },
+    "codeSymbol": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "language",
+        "filePath",
+        "symbolName",
+        "canonicalId",
+        "endpoint",
+        "location"
+      ],
+      "properties": {
+        "kind": { "const": "code" },
+        "language": { "$ref": "#/$defs/language" },
+        "filePath": { "type": "string" },
+        "symbolName": { "type": "string" },
+        "canonicalId": { "type": "string" },
+        "endpoint": { "type": "string" },
+        "location": { "$ref": "common-output.schema.json#/$defs/location" },
+        "nameRange": { "$ref": "common-output.schema.json#/$defs/range" },
+        "declarationRange": { "$ref": "common-output.schema.json#/$defs/range" },
+        "signatureRange": { "$ref": "common-output.schema.json#/$defs/range" }
+      }
+    },
+    "link": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "target", "location"],
+      "properties": {
+        "source": { "type": "string" },
+        "target": { "type": "string" },
+        "location": { "$ref": "common-output.schema.json#/$defs/location" },
+        "targetRange": { "$ref": "common-output.schema.json#/$defs/range" }
+      }
+    },
+    "requestFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["filePath", "content"],
+      "properties": {
+        "filePath": { "type": "string" },
+        "content": { "type": "string" }
+      }
+    },
+    "options": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "visibility": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "requestId", "language", "projectRoot", "files", "options"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "requestId": { "type": "string" },
+        "language": { "$ref": "#/$defs/language" },
+        "projectRoot": { "type": "string" },
+        "files": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/requestFile" }
+        },
+        "options": { "$ref": "#/$defs/options" }
+      }
+    },
+    "responseFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["filePath", "symbols", "undocumentedSymbols", "links", "diagnostics"],
+      "properties": {
+        "filePath": { "type": "string" },
+        "symbols": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/codeSymbol" }
+        },
+        "undocumentedSymbols": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/codeSymbol" }
+        },
+        "links": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/link" }
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": { "$ref": "common-output.schema.json#/$defs/diagnostic" }
+        }
+      }
+    },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "requestId", "language", "files"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "requestId": { "type": "string" },
+        "language": { "$ref": "#/$defs/language" },
+        "files": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/responseFile" }
+        }
+      }
+    }
+  }
+}

package/templates/skills/README.md

@@ -1,35 +1,27 @@
 # DocBridge skill templates
 
-Distributable agent skills for projects that use DocBridge. Prefer
+Distributable agent skill for projects that use DocBridge. Prefer
 `docbridge init` for CLI-driven setup or `docbridge init-with-agent` for
-agent-guided adoption. `init-with-agent` installs `docbridge-adopt` first;
-`docbridge-adopt` installs the companion skills after scope is confirmed.
-Manual copy-based installation remains available: copy a
-skill directory into your repository's skill location (`.claude/skills/` for
-Claude Code or `.agents/skills/` for Codex-style project skills) and adjust
-nothing unless your DocBridge invocation differs from the examples inside.
+agent-guided adoption. Both commands install the same `docbridge` skill.
+Manual copy-based installation remains available: copy the skill directory
+into your repository's skill location (`.claude/skills/` for Claude Code or
+`.agents/skills/` for Codex-style project skills).
 
-- [`docbridge-annotate`](docbridge-annotate/SKILL.md) — create correct
-  `@doc`/`@code` link pairs and verify them with `docbridge check`.
-- [`docbridge-sync`](docbridge-sync/SKILL.md) — triage `related --gate`
-  findings: fetch the flagged counterpart content with `docbridge context`,
-  then update the counterpart or justify leaving it unchanged.
-- [`docbridge-adopt`](docbridge-adopt/SKILL.md) — adopt DocBridge in an existing
-  TypeScript, Swift, or Dart project by confirming docs/code scope, creating
-  or improving config, installing companion skills, and handling simple CI/hook
-  setup.
-- [`docbridge-link`](docbridge-link/SKILL.md) — link existing docs sections to
-  existing supported code declarations through docs-first candidate discovery
-  and section-level confirmation.
-- [`docbridge-review`](docbridge-review/SKILL.md) — review the whole DocBridge
-  graph for semantic validity using `docbridge graph --json --include-content`.
+- [`docbridge`](docbridge/SKILL.md) — route adopt, discover-and-link, annotate,
+  review, and sync work. Facts about the binary live in
+  `docbridge docs show`, not in this file.
 
-This repository dogfoods the distributable DocBridge skills from both
+This repository dogfoods the distributable DocBridge skill from both
 `.claude/skills/` and `.agents/skills/` as skill-level symlinks to this
 directory. The template is the source of truth; do not edit the symlinked
 copies in place. In-repository dogfood links require symlink-capable checkouts;
 external projects should use the copy-based installation above.
 
-The hook-side integration that complements these skills lives in
-[`examples/hooks/`](../../examples/hooks/) with recipes under
-[`docs/integrations/`](../../docs/integrations/).
+Existing installs may still have the five legacy skill directories
+(`docbridge-adopt`, `docbridge-annotate`, `docbridge-link`,
+`docbridge-review`, `docbridge-sync`). `docbridge init --force` removes those
+copied directories after you review local edits. Symlinked skill directories
+are reported and left untouched.
+
+The Git-hook and CI integration that complements this skill is described
+under [`docs/integrations/`](../../docs/integrations/).

package/templates/skills/docbridge/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: docbridge
+description: Adopt or introduce DocBridge, choose docs and code scope, create or improve docbridge.config.json, add @doc and @code annotations, fix link diagnostics, triage related --gate findings, and review existing links for stale docs or semantic validity.
+---
+
+# docbridge
+
+Route DocBridge work, then apply the matching judgment. Facts about the binary
+— annotation syntax, supported declarations, the anchor algorithm, diagnostic
+codes — live in packaged docs, not in this skill. Read them with
+`docbridge docs show`. Invocation is documented in
+`docbridge docs show agent-integration`.
+
+An agent with no DocBridge skill can still finish the job from
+`docbridge --help` plus `docbridge docs list` / `docbridge docs show`.
+
+## Task router
+
+Pick **one** job before editing. The first matching question wins:
+
+| Job               | Ask this                                                                       | Not this                                      |
+| ----------------- | ------------------------------------------------------------------------------ | --------------------------------------------- |
+| Adopt             | Introduce DocBridge, choose docs/code scope, or write `docbridge.config.json`? | Linking existing files                        |
+| Discover and link | Choose what to link in existing docs, docs-first?                              | A known pair already confirmed                |
+| Annotate          | Add or fix a `@doc` / `@code` pair, or clear link diagnostics?                 | Deciding _whether_ a section should be linked |
+| Review            | Check whether the docs still match the code, with no change set?               | Gate findings on a diff                       |
+| Sync              | A Git hook, CI comment, or `related --gate` flagged unchanged counterparts?    | Auditing the whole graph                      |
+
+**Review versus sync.** Whole graph, no change set → **review**. A change set's
+flagged counterparts → **sync**. "Check whether the docs still match the code"
+is review. "These counterparts were not updated in this diff" is sync.
+
+## Adopt
+
+Survey the repo: existing config, likely specification directories, public API
+locations, existing annotations, scripts, CI, and Git hooks.
+
+Recommend docs scope, code scope, and whether to wire simple CI or hooks now.
+Show the tradeoff, then wait for confirmation. Create or improve
+`docbridge.config.json` only after that. Use the language-keyed `include.code`
+object, never the old array form. Never replace a user-authored config blindly.
+
+Handle CI and Git hooks conservatively: implement a simple confirmed setup;
+otherwise provide a patch plan. Prefer a non-blocking gate early in adoption.
+
+Verify with `docbridge check`. A clean zero-link result is acceptable. Then
+continue into discover-and-link.
+
+Read `docbridge docs show getting-started` and `configuration`.
+
+## Discover and link
+
+Work docs-first. Confirm docs scope, then follow
+`docbridge docs show linking-workflow`: prioritize unlinked specification
+sections, propose at most three symbols per section with why/uncertain, present
+5–10 sections per round, collect adopt/exclude/hold, and classify no-matches
+instead of forcing a link.
+
+Add annotations only after section-level confirmation. Then follow Annotate.
+
+## Annotate
+
+Create both sides of a pair, or add the missing backlink. Read
+`docbridge docs show annotations` for syntax, supported declarations, anchors,
+and target grammar. Read `docbridge docs show troubleshooting` for diagnostic
+codes and fixes.
+
+Procedure: identify the declaration and the heading; add `@doc` on the
+declaration (create a minimal doc comment if missing); add `@code` directly
+above the heading; verify with `docbridge check`. The pair is correct only when
+no diagnostic mentions either endpoint.
+
+Do not split or rename headings in this job. Preserve existing annotations
+unless the user asked to fix a wrong link.
+
+## Sync
+
+A `related --gate` violation means nobody has decided yet, not that the
+counterpart must change. Read `docbridge docs show agent-integration` for the
+three-way judgment.
+
+1. Collect violations from the hook, CI comment, or
+   `git diff --name-only HEAD | docbridge related --stdin --gate`.
+2. Fetch counterpart content with `docbridge context` over the changed files.
+3. Per counterpart: update it when the documented contract diverged; leave it
+   unchanged with a written justification that cites the counterpart content;
+   or fix the annotation pair when the link itself is wrong.
+4. Re-run the gate. Report every decision.
+
+Never detach a link to silence the gate. Do not rubber-stamp: unread
+counterpart content is not a judgment. When a code change contradicts an
+explicit documented promise, surface that instead of quietly rewriting the
+promise.
+
+## Review
+
+Audit meaning across the whole graph, not a diff. Follow
+`docbridge docs show link-review`.
+
+Requires `docbridge graph --json --include-content`. Read `diagnostics` first.
+Batch by docs file. Read both sides. Classify High / Medium / Low. Report
+severity, endpoints, evidence, and a recommended fix. Do not edit annotations
+automatically.
+
+`check` proves mechanics; this job reviews meaning. Do not rubber-stamp a
+resolving link. Prefer fewer, clearer links. Do not delete annotations to
+silence uncertainty.
+
+## Shared guardrails
+
+- Confirm scope and section-level decisions with the user before writing links.
+- Do not decide branch or pull-request policy.
+- Prefer public API declarations as link targets.
+- After edits, re-run `docbridge check` (and `related --gate` for sync).
+
+## Read more
+
+- `docbridge docs list` — the full menu
+- `docbridge docs show agent-integration` — invocation, gate judgment, hooks, CI
+- `docbridge docs show annotations` — `@doc` / `@code` rules
+- `docbridge docs show linking-workflow` — docs-first candidate discovery
+- `docbridge docs show link-review` — semantic audit
+- `docbridge docs show troubleshooting` — diagnostic codes and fixes
+- `docbridge docs show getting-started` — first-time setup
+- `docbridge docs show configuration` — `docbridge.config.json`
+- `docbridge docs show commands` — check, related, context, graph