docbridge 0.6.1 → 0.8.0

package/docs/user/agent-integration.md

@@ -0,0 +1,96 @@
+---
+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. An agent can do the whole
+job from `docbridge --help` plus `docbridge docs list` / `docbridge docs show`.
+A project skill is an accelerator, not a prerequisite.
+
+<!-- @code src/cli/init.ts#runInitWithAgent -->
+
+## Invoking DocBridge
+
+Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
+repo recipe such as `just check`, or
+`bun run /path/to/docbridge/src/cli/index.ts`.
+
+`docbridge init` can create `docbridge.config.json` and copy the distributable
+`docbridge` skill for Codex, Claude Code, or both. 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
+skill and prints the next command or prompt; it does not launch an agent
+process.
+
+<!-- @code src/core/context.ts#context -->
+<!-- @code src/core/related.ts#related -->
+
+## 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, choose one of three judgments:
+
+- Update the counterpart when behavior, contract, format, or constraint
+  diverged.
+- Leave it unchanged, with a written justification that cites the counterpart
+  content, when the change is internal and every documented statement still
+  holds.
+- Fix the link itself when the annotation pair points at the wrong section or
+  symbol.
+
+Do not detach a link only to silence the gate.
+
+## 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.
+
+## Read more
+
+Run `docbridge docs list` for the full menu of packaged guides, then
+`docbridge docs show <name>` for a page. Start with `getting-started`,
+`annotations`, `linking-workflow`, `link-review`, `troubleshooting`, and
+`commands`.

package/docs/user/annotations.md

@@ -0,0 +1,173 @@
+---
+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 src/core/links.ts#parseLinkTarget -->
+
+## Target grammar
+
+Both `@doc` and `@code` take a `file#fragment` target:
+
+- The file path is project-root-relative and uses `/` separators.
+- `./`, `../`, and absolute paths are invalid.
+- The fragment is required. File-only, fragment-only, and same-file targets
+  are invalid.
+- Optional text after the target is allowed and ignored
+  (`@doc docs/auth.md#login-spec human note`).
+
+One declaration may carry multiple `@doc` tags, and one heading may carry
+multiple `@code` comments. Each pair is an independent link. Duplicate
+annotations from the same source to the same target produce `duplicate_link`.
+
+## 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
+/// @doc docs/auth.md#login-flow
+public func login(email: String, password: String) {}
+```
+
+```dart
+/// @doc docs/auth.md#login-flow
+void login(String email, String password) {}
+```
+
+```rust
+/// @doc docs/auth.md#login-flow
+pub fn login(email: &str, password: &str) {}
+```
+
+Swift, Dart, and Rust use their normal documentation comment syntax. Paths are
+relative to the configured project root.
+
+An `@doc` on an unsupported declaration produces `unsupported_declaration`. The
+same declaration without `@doc` is ignored.
+
+### TypeScript
+
+Supported top-level exported forms: `function`, `class`, `abstract class`,
+`interface`, `type`, `enum`, `const enum`, `const` with a single declarator,
+named default `function`/`class`, and their `declare` forms in `.ts` files.
+Type members are also supported: class methods, properties, getters, setters,
+constructors, and static members; interface property and method signatures;
+and property and method signatures of a type alias written as an object type
+literal.
+
+By default, `public` and `protected` members are included; `private` members
+are included only when `include.code.typescript.visibility` lists `private`.
+TypeScript `visibility` applies only to type members. Top-level declarations
+are scoped by `export`. Members excluded by visibility are not endpoints; an
+`@doc` on one is `unsupported_declaration`.
+
+Unsupported examples include anonymous default exports, multi-declarator
+`const`, namespaces, re-exports, non-exported declarations, members whose name
+is not a plain identifier, enum members, index signatures, call and construct
+signatures, and constructor parameter properties.
+
+Canonical IDs omit parameter signatures (`AuthService.login`,
+`AuthService.constructor`).
+
+### Swift
+
+Supported forms include top-level and member `class`, `struct`, `enum`,
+`protocol`, and `actor`; top-level and member `func`, `var`, `let`, and
+`init`; and members declared in extensions, canonicalized as members of the
+extended type.
+
+By default only `public` and `open` declarations are included. `internal`
+declarations are included when `include.code.swift.visibility` lists
+`internal`. An `@doc` on a visibility-excluded declaration is
+`unsupported_declaration`.
+
+Member IDs are type-qualified and include argument labels, for example
+`AuthService.login(email:password:)`, `AuthService.refresh(_:)`, and
+`AuthService.init(email:password:)`.
+
+### Dart
+
+Supported forms include top-level functions, getters, setters, and variables;
+`class`, `enum`, `mixin`, and their members; and members declared in
+extensions, canonicalized as members of the extended type.
+
+Only public declarations are scanned. Dart marks library-private names with a
+leading `_`, so an endpoint is excluded when any segment of its canonical ID
+starts with `_`, including a public member of a `_Private` type.
+`include.code.dart.visibility` accepts only `public`. An `@doc` on a
+visibility-excluded declaration is `unsupported_declaration`.
+
+Member IDs omit parameter signatures (`AuthService.login`). Setters carry a
+trailing `=` (`AuthService.token=`). The unnamed constructor is
+`AuthService.new`; named constructors keep their name (`AuthService.guest`).
+
+### Rust
+
+Supported forms are `mod` (including nested modules), `struct`, `enum`, free
+`fn`, and inherent `impl` methods. Trait definitions, trait-impl methods,
+macros, const/static items, unions, and extern blocks are unsupported.
+
+By default only unrestricted `pub` declarations are included. A plain `fn` or
+`struct` without `pub` is not an endpoint. Non-`pub` items are included when
+`include.code.rust.visibility` lists `private`. An `@doc` on a
+visibility-excluded declaration is `unsupported_declaration`.
+
+Canonical IDs use `::` path qualification, for example `normalize`,
+`TypingEngine`, `TypingEngine::advance`, and `domain::typing`.
+
+<!-- @code src/core/markdown.ts#scanMarkdown -->
+
+## Documentation to code
+
+Place a standalone HTML comment immediately before the linked heading. The
+comment may be indented by 0 to 3 spaces; 4 or more spaces are ignored. The
+trimmed comment body must start with `@code`. Blank lines between the comment
+and the heading are allowed. Any other text in between produces
+`dangling_code_annotation`.
+
+```md
+<!-- @code src/auth.ts#login -->
+
+## Login Flow
+```
+
+The code fragment is the canonical symbol ID emitted by the language scanner.
+Use that ID exactly in the `@code` target.
+
+## Anchors and reciprocity
+
+Anchors come from ATX headings (`#` through `######`) only. Setext headings
+have no anchors. Empty headings do not create linkable anchors; a `@code`
+attached to an empty heading is `dangling_code_annotation`.
+
+The algorithm:
+
+1. Take the heading text after the `#` markers.
+2. Lowercase with JavaScript `toLowerCase()`.
+3. Collapse runs of whitespace and punctuation to `-`. Unicode letters and
+   numbers are preserved.
+4. Strip leading and trailing `-`.
+
+Example: `## Login Spec (v2)` becomes `#login-spec-v2`. `# Login Flow`
+becomes `#login-flow`.
+
+Duplicate non-empty anchors in the same Markdown file produce
+`duplicate_doc_anchor`. The same anchor in different files is allowed.
+DocBridge does not add GitHub-style numeric suffixes.
+
+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,64 @@
+---
+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.
+
+<!-- @code src/core/resolver.ts#check -->
+
+### `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.
+
+<!-- @code src/core/related.ts#related -->
+
+### `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.
+
+<!-- @code src/core/context.ts#context -->
+
+### `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.
+
+<!-- @code src/core/graph-output.ts#graph -->
+
+### `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,77 @@
+---
+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.
+
+Each language accepts an optional `visibility` array. Omitting it uses the
+scanner default: TypeScript `public` and `protected` members, Swift `public`
+and `open`, Dart `public` only, Rust unrestricted `pub`. A declaration
+excluded by visibility is not an endpoint; an `@doc` on one is
+`unsupported_declaration`. See `docbridge docs show annotations` for the
+per-language rules, including Dart's leading-underscore privacy.
+
+<!-- @code src/core/glob.ts#collectFiles -->
+
+## 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,75 @@
+---
+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` skill 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 linking-workflow` to choose sections and propose
+  candidates.
+- Read `docbridge docs show link-review` to audit existing links for meaning.
+- Read `docbridge docs show commands` to choose an inspection command.
+- Read `docbridge docs show troubleshooting` when `check` reports a diagnostic.
+- Add `docbridge check` to CI after the local graph passes.

package/docs/user/link-review.md

@@ -0,0 +1,53 @@
+---
+description: Audit existing links for semantic correctness, not just resolution.
+---
+
+# Link Review
+
+Audit the semantic validity of the entire DocBridge graph. This is not a
+change-set or pull-request review, and it is not `related --gate` triage. It
+checks whether valid links actually connect a docs section to the code symbol
+that implements or represents that specification.
+
+`docbridge check` proves link mechanics. This review judges meaning. Do not
+rubber-stamp a link because the target resolves.
+
+## Procedure
+
+1. Build the graph:
+
+   ```sh
+   docbridge graph --json --include-content
+   ```
+
+   Read `diagnostics` first. Mechanical failures from `docbridge check`
+   should be fixed or acknowledged before relying on semantic findings.
+
+2. Batch by docs file. Review all links, but process them in batches:
+   - the docs file is the default batch boundary
+   - split a batch further when it contains too many sections or links
+   - keep notes so repeated patterns are applied consistently across batches
+
+3. Read both sides.
+   - For docs nodes, use the graph range to read the full Markdown section.
+   - For code nodes, start with graph content: documentation comment plus
+     signature. Read the implementation only when necessary to judge the
+     relationship.
+   - Compare behavior, contract, input/output, constraints, and design
+     intent.
+
+4. Classify findings.
+   - High: clearly wrong link, stale docs fixed in place by a link, or a
+     link to a section that is not a specification.
+   - Medium: partial overlap, unclear representative symbol, overly broad
+     section, or multiple linked symbols with ambiguous roles.
+   - Low: cleanup opportunity, duplicate docs, excessive links, or missing
+     explanation of why multiple links are needed.
+
+5. Report findings. For each finding include severity, the doc endpoint, the
+   code endpoint, evidence from both sides, and a recommended fix.
+
+Do not edit annotations automatically. Prefer fewer, clearer links over
+broad many-to-many links without explicit roles. Do not delete annotations
+merely to silence uncertainty; explain the uncertainty and ask for a
+decision.

package/docs/user/linking-workflow.md

@@ -0,0 +1,70 @@
+---
+description: Choose what to link and propose candidates docs-first.
+---
+
+# Linking Workflow
+
+Choose Markdown sections that look like specifications, then propose supported
+code declarations that implement or represent each section. Add annotations
+only after a section-level decision.
+
+## What to link
+
+Prefer sections that state behavior, contracts, inputs/outputs, constraints,
+user-visible behavior, or design decisions.
+
+Treat README files, changelogs, contribution docs, runbooks, logs, and
+release notes as exclusions by default unless a specific section is identified
+as a specification.
+
+Prefer supported public API declarations as link targets. TypeScript starts
+with top-level exported declarations; Swift, Dart, and Rust also support
+member endpoints. Use the scanner-produced canonical ID exactly; see
+`docbridge docs show annotations`.
+
+Do not decide project workflow policy such as branch or pull-request
+strategy.
+
+## Propose candidates
+
+1. Confirm docs scope first. Inspect the repository and agree the
+   documentation directories before proposing links.
+2. Find section candidates. Prioritize unlinked sections. Include already
+   linked sections at lower priority when an additional link may be justified.
+   Ignore prose-only sections, changelog entries, runbook steps, and project
+   process unless they are specifications.
+3. For each candidate section, propose at most three code symbols. Rank them
+   from heading text and section body, exported symbol names, existing
+   documentation comments, file paths, and the implementation body only when
+   that surrounding information is insufficient. For each symbol, state why it
+   may match and what remains uncertain.
+4. Present 5–10 section candidates per round. For each section, choose:
+   - adopt: select one or more code symbols to link
+   - exclude: do not link this section
+   - hold: keep undecided for later
+
+   A symbol that is not in the proposed top three may still be named.
+
+5. Classify no-match sections instead of forcing a link:
+   - not implemented yet
+   - spans multiple symbols without a clear public representative
+   - likely stale docs
+   - not a specification section
+   - target appears internal or not exported
+
+## After confirmation
+
+Add `@code` directly above the Markdown heading and `@doc` on the chosen
+declaration. If the declaration has no documentation comment, create a
+minimal one containing only `@doc`. If one side already exists, show it and
+add the missing backlink after confirmation. Preserve existing annotations;
+do not replace or clean up suspicious links in this pass.
+
+Do not split Markdown sections or rename headings. If a section is too broad
+or ambiguous, classify it as held or no-match. Multiple code symbols may link
+to one docs section when each role is clear. One code symbol may link to
+multiple docs sections when each section covers a distinct specification
+aspect. Do not link solely because names are similar.
+
+Verify with `docbridge check`, then inspect the affected links with
+`docbridge context` or `docbridge graph --json --include-content`.

package/docs/user/troubleshooting.md

@@ -0,0 +1,61 @@
+---
+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.
+
+`config_unknown_key` and `config_invalid_value` mean a present file has a key
+or value the schema rejects. 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
+`code_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.
+
+`code_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.
+
+## Link-authoring errors
+
+These codes appear while writing `@doc` / `@code` pairs:
+
+| 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; see `docs show annotations`       |
+| `duplicate_doc_anchor`                               | two headings share an anchor in one file | rename one heading so anchors stay unique             |
+| `duplicate_code_symbol`                              | two annotated declarations share an ID   | keep one `@doc` per canonical ID in that file         |
+| `duplicate_link`                                     | the same source repeats the same target  | remove the extra annotation                           |
+
+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.