docbridge 0.6.0 → 0.7.0

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

@@ -15,9 +15,9 @@ nothing unless your DocBridge invocation differs from the examples inside.
   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.
+  TypeScript, Swift, Dart, or Rust project by confirming docs/code scope, creating
+  or improving config, installing companion skills, and handling simple CI or
+  Git-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.
@@ -30,6 +30,5 @@ 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/).
+The Git-hook and CI integration that complements these skills is described
+under [`docs/integrations/`](../../docs/integrations/).

package/templates/skills/docbridge-adopt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docbridge-adopt
-description: Adopt DocBridge in an existing TypeScript, Swift, or Dart project. Use when asked to introduce DocBridge into a repository, choose docs/code scope, create or improve docbridge.config.json, and optionally wire simple CI or agent hooks.
+description: Adopt DocBridge in an existing TypeScript, Swift, Dart, or Rust project. Use when asked to introduce DocBridge into a repository, choose docs/code scope, create or improve docbridge.config.json, and optionally wire simple CI or Git hooks.
 ---
 
 # docbridge-adopt
@@ -22,17 +22,17 @@ repo recipe such as `just check`, or
 1. **Survey the repository.** Inspect:
    - existing `docbridge.config.json`
    - Markdown docs structure and likely specification directories
-   - TypeScript, Swift, or Dart source structure and public API locations
+   - TypeScript, Swift, Dart, or Rust source structure and public API locations
    - existing `@doc` / `@code` annotations
-   - package scripts, CI files, git hooks, and agent hooks
+   - package scripts, CI files, and Git hooks
 
 2. **Recommend scope, then ask for confirmation.** Present concise options and
    your recommendation for:
    - docs scope: directories/files whose sections are likely specifications,
      contracts, behavior, constraints, or design decisions
-   - code scope: language-keyed TypeScript, Swift, or Dart directories/files
+   - code scope: language-keyed TypeScript, Swift, Dart, or Rust directories/files
      whose supported declarations should be linkable
-   - CI/hook mode: if any integration should be added now
+   - CI/Git-hook mode: if any integration should be added now
 
    Do not ask the user to rediscover obvious facts from the repository. Show
    your recommendation and the tradeoff, then wait for confirmation.
@@ -42,8 +42,8 @@ repo recipe such as `just check`, or
      `include.code` and `include.docs` globs.
    - Use the language-keyed `include.code` object. Do not write the old
      array form; for example, use `{ "typescript": { "patterns": [...] } }`,
-     `{ "swift": { "patterns": [...] } }`, or
-     `{ "dart": { "patterns": [...] } }`.
+     `{ "swift": { "patterns": [...] } }`, `{ "dart": { "patterns": [...] } }`,
+     or `{ "rust": { "patterns": [...] } }`.
    - If config exists, read it, explain the current scope, propose any
      improvement, and edit only after confirmation.
    - Never replace a user-authored config blindly.
@@ -52,11 +52,11 @@ repo recipe such as `just check`, or
    - After scope is confirmed and `docbridge.config.json` exists or has been
      intentionally left unchanged, install the rest of the distributable
      DocBridge skills for the same agent target.
-   - Prefer the project-native DocBridge invocation. For example, run
-     `docbridge init --yes --agent-target codex`, `docbridge init --yes
-     --agent-target claude`, or `docbridge init --yes --agent-target both`
-     from the project root. Use the target that matches the existing
-     `.agents/` and/or `.claude/` setup.
+   - Prefer the project-native DocBridge invocation. From the project root, run
+     `docbridge init --yes --agent-target codex` for Codex,
+     `docbridge init --yes --agent-target claude` for Claude Code, or
+     `docbridge init --yes --agent-target both` for both. Use the target that
+     matches the existing `.agents/` and/or `.claude/` setup.
    - This command should leave an existing `docbridge.config.json` unchanged
      and copy any missing `docbridge-annotate`, `docbridge-link`,
      `docbridge-review`, and `docbridge-sync` skill directories. Do not use
@@ -65,7 +65,7 @@ repo recipe such as `just check`, or
      copy target paths from `templates/skills/docbridge-*` instead of silently
      skipping this step.
 
-5. **Handle CI/hooks conservatively.**
+5. **Handle CI and Git hooks conservatively.**
    - If the existing setup is simple and the user confirmed the mode, implement
      it.
    - If the setup is complex or ambiguous, provide a concrete patch plan or
@@ -90,7 +90,7 @@ repo recipe such as `just check`, or
   notes as exclusions by default unless the user identifies specific sections
   as specifications.
 - Prefer supported public API declarations as link targets. TypeScript starts
-  with top-level exported declarations; Swift and Dart also support member
+  with top-level exported declarations; Swift, Dart, and Rust also support member
   endpoints with scanner-produced canonical IDs.
 - Do not decide project workflow policy such as branch or PR strategy. Mention
   only what affects DocBridge adoption.

package/templates/skills/docbridge-annotate/SKILL.md

@@ -37,6 +37,7 @@ section:
 
 ```md
 <!-- @code src/auth/login.ts#login -->
+
 ## Login Spec
 ```
 
@@ -88,11 +89,11 @@ required. Optional text after the target is allowed and ignored
 
 ## Diagnosing check failures
 
-| Diagnostic | Meaning | Usual fix |
-| --- | --- | --- |
-| `doc_file_not_found` / `code_file_not_found` | target file not in the managed set | fix the path, or extend `docbridge.config.json` globs |
-| `doc_anchor_not_found` | file found, anchor wrong | regenerate the anchor from the exact heading text |
-| `doc_backlink_not_found` / `code_backlink_not_found` | one direction missing | add the missing `@code` or `@doc` side |
-| `unsupported_declaration` | `@doc` on an unsupported declaration | move the tag to a supported declaration |
-| `dangling_code_annotation` | text between `@code` and the heading | move the comment directly above the heading |
-| `invalid_link_target` | malformed `file#fragment` | rewrite the target per the rules above |
+| Diagnostic                                           | Meaning                              | Usual fix                                             |
+| ---------------------------------------------------- | ------------------------------------ | ----------------------------------------------------- |
+| `doc_file_not_found` / `code_file_not_found`         | target file not in the managed set   | fix the path, or extend `docbridge.config.json` globs |
+| `doc_anchor_not_found`                               | file found, anchor wrong             | regenerate the anchor from the exact heading text     |
+| `doc_backlink_not_found` / `code_backlink_not_found` | one direction missing                | add the missing `@code` or `@doc` side                |
+| `unsupported_declaration`                            | `@doc` on an unsupported declaration | move the tag to a supported declaration               |
+| `dangling_code_annotation`                           | text between `@code` and the heading | move the comment directly above the heading           |
+| `invalid_link_target`                                | malformed `file#fragment`            | rewrite the target per the rules above                |

package/templates/skills/docbridge-link/SKILL.md

@@ -7,7 +7,7 @@ description: Link existing Markdown specification sections to existing supported
 
 Create DocBridge annotations for existing docs and code. Work docs-first: choose
 Markdown sections that look like specifications, then propose supported
-TypeScript, Swift, or Dart declarations that implement or represent each
+TypeScript, Swift, Dart, or Rust declarations that implement or represent each
 section.
 
 Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a

package/templates/skills/docbridge-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docbridge-sync
-description: Triage DocBridge related-gate findings — linked counterparts of changed files that were not themselves updated. Use when a Stop-hook message, CI comment, or docbridge related --gate run flags unchanged counterparts, to judge divergence with docbridge context and then update or justify each one.
+description: Triage DocBridge related-gate findings — linked counterparts of changed files that were not themselves updated. Use when a Git hook, CI comment, or docbridge related --gate run flags unchanged counterparts, to judge divergence with docbridge context and then update or justify each one.
 ---
 
 # docbridge-sync
@@ -16,8 +16,8 @@ repo recipe such as `just related-gate`, or
 
 ## Procedure
 
-1. **Collect the violations.** Use the gate report you were given (Stop-hook
-   message, CI comment), or produce one over the change set:
+1. **Collect the violations.** Use the gate report you were given (a Git
+   hook's output, a CI comment), or produce one over the change set:
 
    ```sh
    git diff --name-only HEAD | docbridge related --stdin --gate
@@ -62,7 +62,7 @@ repo recipe such as `just related-gate`, or
   the link; that defeats the graph the gate protects.
 - Do not rubber-stamp: if the counterpart content was not read, the judgment
   has no basis.
-- Updating a spec section to match changed code is a *decision about the
-  contract*, not bookkeeping — when the change contradicts an explicit
+- Updating a spec section to match changed code is a _decision about the
+  contract_, not bookkeeping — when the change contradicts an explicit
   documented promise, surface it to the user instead of quietly rewriting the
   promise.