docbridge 0.6.1 → 0.7.0

package/docs/user/agent-integration.md

@@ -0,0 +1,70 @@
+---
+description: Wire DocBridge into coding agents, Git hooks, and CI.
+---
+
+# Agent Integration
+
+DocBridge gives coding agents deterministic link data instead of asking them
+to infer documentation relationships from filenames.
+
+<!-- @code src/cli/init.ts#runInitWithAgent -->
+
+## Install agent skills
+
+`docbridge init` can install the distributable skills while creating project
+configuration. To let an agent decide the scope, run:
+
+```sh
+docbridge init-with-agent --agent-target codex
+```
+
+Use `claude` or `both` for other supported targets. The command installs the
+adoption skill and prints the next command or prompt; it does not launch an
+agent process.
+
+## Editing workflow
+
+Before changing a linked file, provide its counterpart content:
+
+```sh
+docbridge context path/to/changed-file
+```
+
+After editing, inspect the change set:
+
+```sh
+git diff --name-only | docbridge related --stdin --gate
+```
+
+For every reported counterpart, update it when behavior diverged or record why
+no documentation or code change is necessary.
+
+## Hooks
+
+Put the automation in Git hooks rather than in one agent's configuration, so
+it covers every contributor and every tool. A `pre-commit` hook can run
+`docbridge check` as a hard gate, then report `related --gate` over the staged
+files:
+
+```sh
+git diff --cached --name-only | docbridge related --stdin --gate
+```
+
+When an agent runs `git commit` through a shell, the hook's output lands in the
+tool result and therefore in the agent's context, so the counterpart findings
+reach it without any agent-specific wiring. Attach the counterparts' content
+with `docbridge context --stdin` to make the finding actionable in place.
+
+Keep the gate stage non-blocking while the link graph is still sparse: a
+blocking gate on a staged subset mostly trains `--no-verify`. Hooks must not
+silently rewrite files or replace the repository's mandatory checks.
+
+Git hooks cannot signal before an edit, and they are skipped by `--no-verify`
+and by some GUI clients, so the pull request stays the enforcement point.
+
+## CI
+
+Run `docbridge check` over the whole project as the hard link-validity gate. A
+pull-request workflow can additionally pass the base-to-head changed file list
+to `related --stdin --gate` and attach `context` output for reviewers. Ensure
+the checkout includes both commits needed for the diff.

package/docs/user/annotations.md

@@ -0,0 +1,52 @@
+---
+description: Write @doc and @code annotations and valid link targets.
+---
+
+# Annotations
+
+DocBridge links supported code declarations to Markdown headings. A complete
+pair has `@doc` on the declaration and `@code` immediately before the heading.
+
+## Code to documentation
+
+Use a documentation path and heading anchor in a declaration's documentation
+comment:
+
+```ts
+/**
+ * @doc docs/auth.md#login-flow
+ */
+export function login(): void {}
+```
+
+Swift, Dart, and Rust use their normal documentation comment syntax with the same
+target format. Paths are relative to the configured project root.
+
+<!-- @code src/core/markdown.ts#scanMarkdown -->
+
+## Documentation to code
+
+Place an HTML comment immediately before the linked heading:
+
+```md
+<!-- @code src/auth.ts#login -->
+
+## Login Flow
+```
+
+The code fragment is the canonical symbol ID emitted by the language scanner.
+Top-level functions and types normally use their declaration name. Members use
+their type-qualified identity. TypeScript member IDs omit parameter signatures,
+Swift member IDs include argument labels, Dart member IDs omit parameter
+signatures, and Rust member IDs use `::` path qualification.
+
+## Anchors and reciprocity
+
+Markdown anchors use the normalized heading text, such as `# Login Flow`
+becoming `#login-flow`. Duplicate headings receive the same numeric suffixes
+used by GitHub-style Markdown anchors.
+
+Each direction is validated independently. A target can resolve while still
+reporting a missing reciprocal annotation. Run `docbridge check` to validate
+targets and pair completeness, and `docbridge graph --json` when you need the
+resolved endpoints and edges.

package/docs/user/commands.md

@@ -0,0 +1,56 @@
+---
+description: Choose between check, related, context, and graph.
+---
+
+# Commands
+
+Use the narrowest command for the question you need to answer.
+
+<!-- @code src/cli/index.ts#run -->
+
+## Command dispatch
+
+The first argument selects a command. Global `--help` and `--version` are
+handled before project scanning, while each command validates its own options.
+
+### `check`: validate the project
+
+Run `docbridge check` before committing and in CI. It validates configuration,
+annotations, targets, and reciprocal links. Add `--audit` to include warnings
+for undocumented code declarations and unlinked Markdown sections. Add
+`--json` for machine-readable diagnostics.
+
+### `related`: find counterpart files
+
+Pass changed paths to learn which linked files may also need attention:
+
+```sh
+git diff --name-only | docbridge related --stdin
+```
+
+`--gate` exits `1` when a linked counterpart is absent from the supplied change
+set. It identifies review obligations; it does not decide whether the
+counterpart actually needs an edit.
+
+### `context`: read counterpart content
+
+Use `context` when a human or agent needs the linked sections themselves:
+
+```sh
+docbridge context src/auth.ts
+```
+
+The default Markdown output is suitable for an agent prompt. `--json` returns
+structured contexts, diagnostics, and a summary.
+
+### `graph`: inspect link structure
+
+Use `graph` for endpoints, edges, reciprocal pairs, and unresolved links across
+the project. Passing file paths scopes the result to those files and their
+direct counterparts. `--include-content` is available only with `--json`.
+
+## Common options
+
+The project commands accept `--root <path>` when invoked outside the project
+root. Run `docbridge <command> --help` for the exact options and exit behavior
+of a command.

package/docs/user/configuration.md

@@ -0,0 +1,68 @@
+---
+description: "Configure docbridge.config.json: roots, includes, excludes, languages."
+---
+
+# Configuration
+
+DocBridge loads `docbridge.config.json` from the project root supplied by
+`--root`, or from the current directory by default. Paths and glob patterns are
+interpreted relative to that root.
+
+<!-- @code src/core/config.ts#loadConfig -->
+
+## Loading configuration
+
+The configuration loader requires the file, validates its schema, and rejects
+source files claimed by more than one configured language.
+
+## Minimal configuration
+
+Declare documentation patterns and at least one supported code language:
+
+```json
+{
+  "$schema": "./node_modules/docbridge/schemas/docbridge.schema.json",
+  "include": {
+    "code": {
+      "typescript": {
+        "patterns": ["src/**/*.ts"]
+      }
+    },
+    "docs": ["docs/**/*.md"]
+  }
+}
+```
+
+Supported language keys are `typescript`, `swift`, `dart`, and `rust`. A project can
+enable more than one language, each with its own patterns.
+
+## Excluded files
+
+The configuration has no `exclude` property. Narrow the include patterns when
+tests, fixtures, generated files, or general documentation should stay outside
+the graph:
+
+```json
+{
+  "include": {
+    "code": {
+      "typescript": {
+        "patterns": ["src/domain/**/*.ts", "src/services/**/*.ts"]
+      }
+    },
+    "docs": ["docs/specs/**/*.md"]
+  }
+}
+```
+
+DocBridge always ignores dependency directories, Git metadata, dot-prefixed
+path segments, symbolic links, and TypeScript declaration files (`.d.ts`).
+Keep patterns narrow enough that `docbridge check --audit` reports useful
+coverage gaps rather than every implementation detail or general prose file.
+
+## Validate changes
+
+Run `docbridge check` after editing configuration. A missing, malformed, or
+schema-invalid configuration produces `config_file_invalid`. Use
+`docbridge init --dry-run` to inspect a safe generated starting point without
+overwriting an existing file.

package/docs/user/getting-started.md

@@ -0,0 +1,71 @@
+---
+description: Set up DocBridge in an existing TypeScript, Swift, Dart, or Rust project.
+---
+
+# Getting Started
+
+DocBridge checks that Markdown documentation and supported code declarations
+link to each other. It scans only the files selected by
+`docbridge.config.json`; it does not send source or documentation anywhere.
+
+## Install
+
+Add DocBridge to a project with the package manager used by that project:
+
+```sh
+npm install --save-dev docbridge
+```
+
+The CLI supports Node.js 22 or later and Bun 1.1.31 or later.
+
+<!-- @code src/cli/init.ts#runInit -->
+
+## Set up a project
+
+Preview the files DocBridge would create:
+
+```sh
+npx docbridge init --dry-run
+```
+
+Then run `npx docbridge init` interactively, or use `--yes` when the detected
+scope is unambiguous. The command can create `docbridge.config.json` and install
+the distributable DocBridge skills for Codex, Claude Code, or both. It never
+overwrites an existing configuration.
+
+If a coding agent should choose the documentation and code scope, use:
+
+```sh
+npx docbridge init-with-agent
+```
+
+## Add the first reciprocal link
+
+Add `@doc` to a supported declaration and `@code` before the matching Markdown
+heading. Both targets are relative to the project root:
+
+```ts
+/** @doc docs/auth.md#login-flow */
+export function login(): void {}
+```
+
+```md
+<!-- @code src/auth.ts#login -->
+
+## Login Flow
+```
+
+Run the quality gate:
+
+```sh
+npx docbridge check
+```
+
+A clean graph exits `0`. Broken links and invalid configuration exit `1`.
+
+## Next steps
+
+- Read `docbridge docs show configuration` before narrowing scan scope.
+- Read `docbridge docs show annotations` for link target rules.
+- Read `docbridge docs show commands` to choose an inspection command.
+- Add `docbridge check` to CI after the local graph passes.

package/docs/user/troubleshooting.md

@@ -0,0 +1,53 @@
+---
+description: Diagnose configuration, scanner, parsing, and broken-link errors.
+---
+
+# Troubleshooting
+
+Start with the first error line, then follow any recovery guidance printed on
+stderr. Use `docbridge <command> --help` for invocation errors and
+`docbridge check --json` when a tool needs stable diagnostic fields.
+
+## Configuration errors
+
+`config_file_invalid` means `docbridge.config.json` is missing, malformed, or
+does not match the schema. Run `docbridge init --dry-run` when the file is
+missing. When it exists, repair or remove it before running `check` again.
+
+Confirm that include patterns match real files relative to the selected
+`--root`, language keys are supported, and excludes do not remove an intended
+link target.
+
+## Scanner errors
+
+Swift, Dart, and Rust use packaged scanner workers. A `scanner_unavailable` diagnostic
+usually means the installed package lacks a binary for the current platform or
+the binary cannot execute. Reinstall the package first. If the platform is not
+supported, run DocBridge in a supported environment or build the scanner from
+the repository.
+
+`scanner_failed` diagnostics contain the worker failure rather than converting
+it into a broken link. Check that the source parses with the project's own
+toolchain, then reproduce with the smallest configured file set.
+
+## Parsing and target errors
+
+- A missing documentation file or anchor means the `@doc` path or normalized
+  heading anchor does not resolve.
+- A missing code file or symbol means the `@code` path or canonical symbol ID
+  does not resolve.
+- A missing backlink means one direction resolves but the counterpart lacks
+  the reciprocal annotation.
+- A malformed annotation means the comment syntax or target shape is invalid.
+
+Use `docbridge graph --json` to inspect resolved and one-way edges. Use
+`docbridge context <file>` to confirm which counterpart content DocBridge can
+currently resolve.
+
+<!-- @code src/cli/errors.ts#formatCliError -->
+
+## CLI invocation errors
+
+Unknown commands, unknown options, missing values, invalid roots, and missing
+required inputs exit `1`, write to stderr, and leave stdout empty. These are not
+included in diagnostic JSON because the project scan did not run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docbridge",
-  "version": "0.6.1",
+  "version": "0.7.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"]
           }
         }
       }