docbridge 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,99 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-08-16
+
+### Added
+
+- Rust is a first-party code language. Configure `include.code.rust`, place
+  `@doc` in `///` / `//!` / `/** */` comments on modules, structs, enums, free
+  functions, and inherent `impl` methods, and check links with the bundled
+  `docbridge-rust-scanner` worker (same platforms as Swift/Dart). Default
+  visibility is `pub` only; set `visibility` to include `private` for
+  non-`pub` items. Canonical IDs use Rust path style (`Type::method`).
+- `docbridge docs list [--json]` and `docbridge docs show <name>` provide six
+  task-oriented, version-matched guides from the installed npm package, with
+  packed-package smoke coverage under Node.js and Bun.
+- CLI invocation errors now list valid commands, suggest close command names,
+  and include runnable command-specific recovery guidance. Missing check
+  configuration also points to `docbridge init` and `docbridge init-with-agent`.
+- TypeScript type members can be link endpoints, closing the last functional
+  asymmetry with Swift and Dart. `@doc` on a class method, property, getter,
+  setter, constructor, or static member, on an interface member, or on a member
+  of a type alias written directly as an object type literal resolves to a
+  type-qualified endpoint such as `AuthService.login`. Canonical IDs carry no
+  parameter signatures: overload groups and getter/setter pairs each describe
+  one member and collapse to one endpoint, and a collision — including a static
+  and an instance member of the same name — reports `duplicate_code_symbol`.
+  Only identifier-named members qualify, because a link target is
+  `file#fragment` with one `#` and no whitespace.
+- `include.code.typescript.visibility` accepts `public`, `protected`, and
+  `private`, defaulting to `public` and `protected`. It scopes type members
+  only; top-level declarations remain scoped by `export`.
+
+### Changed
+
+- Scanner worker request and response payloads now have a published JSON Schema,
+  and malformed nested worker output fails explicitly instead of degrading into
+  incomplete scan data. Graph and context output schemas share their diagnostic
+  definitions and are checked against real CLI output. The configuration schema
+  now matches the CLI's per-language suffix and visibility rules.
+- `docbridge context` and `docbridge graph --include-content` strip the common
+  leading indentation from an extracted declaration, so a type member reads at
+  its own level. Output for top-level declarations is unchanged.
+- A `@doc` on a TypeScript type member was previously collected by nothing and
+  silently ignored. It is now a real annotation, so an existing one can surface
+  link diagnostics — `invalid_link_target`, `doc_file_not_found`,
+  `doc_anchor_not_found`, `doc_backlink_not_found` — that were always latent,
+  and an annotation on a `private` member becomes `unsupported_declaration`.
+  `check --audit` output is unchanged: members never count as
+  `undocumented_symbol`.
+- `docbridge check --audit` reports `unlinked_doc_section`, a warning for
+  in-scope documentation sections that carry no `@code` annotation. It is the
+  documentation-side counterpart to `undocumented_symbol`, so the audit now
+  covers both directions of the link graph. Reporting is rolled up over the
+  heading tree: only the topmost heading of a fully unannotated subtree is
+  reported, and a heading is treated as annotated whenever a `@code` comment is
+  attached to it, even if that annotation fails to parse or resolve. Empty
+  headings create no anchor and are never reported, but they still close the
+  section before them, so a deeper heading following one is a separate region
+  rather than a suppressed descendant. Runs
+  without `--audit` are unaffected, and the diagnostic is a warning, so exit
+  codes do not change.
+
+### Fixed
+
+- Swift and Dart scanners now report malformed and duplicate `@doc` targets as
+  `invalid_link_target` and `duplicate_link`, matching TypeScript instead of
+  silently accepting or discarding the annotations.
+- `docbridge graph --include-content` no longer truncates a signature at an
+  object type. It cut the rendered text at the first `{`, which for
+  `login(options: { verbose: boolean })` produced `login(options: {}`. A
+  `signatureRange` already ends where the implementation body begins in every
+  language, so no body has to be cut out of it.
+- The VS Code extension manifest is version-aligned with the npm package again
+  (`0.4.1` had drifted from `0.6.1`), so a checkout of `main` is a valid input
+  to `just package-vsix`. Release Prepare now bumps both manifests through
+  `scripts/set-release-version.ts` and stages both in the release commit, so a
+  CLI release can no longer leave the extension version behind.
+- `just package-vsix` bundles the server the VSIX ships with `--target node`,
+  matching the npm build. The Bun-targeted bundle it built before still carried
+  a `#!/usr/bin/env node` shebang and crashed with `__require is not a function`
+  when the packaging flow's own `verify-dist` step executed it.
+
+### Removed
+
+- The agent-hook integration is gone from the product surface: the copyable
+  scripts under `examples/hooks/` and the hook recipes in
+  `docs/integrations/claude-code.md` and `docs/integrations/codex.md` no longer
+  ship. Wiring DocBridge into an agent's `PostToolUse`/`Stop` hooks covered only
+  the agents that read those configuration files; the documented guardrail is
+  now a Git `pre-commit` hook, which applies to every contributor and every
+  tool. Both integration documents survive as skill-installation guides,
+  `docbridge context` and `docbridge related --gate` are unchanged, and
+  `docbridge docs show agent-integration` describes the Git-hook shape instead.
+  Copies already installed in adopters' repositories keep working.
+
 ## [0.6.1] - 2026-07-27
 
 ### Changed
@@ -222,7 +315,8 @@ 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.6.1...HEAD
+[Unreleased]: https://github.com/salan70/docbridge/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/salan70/docbridge/releases/tag/v0.7.0
 [0.6.1]: https://github.com/salan70/docbridge/releases/tag/v0.6.1
 [0.6.0]: https://github.com/salan70/docbridge/releases/tag/v0.6.0
 [0.5.2]: https://github.com/salan70/docbridge/releases/tag/v0.5.2

package/README.md

@@ -6,7 +6,7 @@
 
 Bring Markdown into the LSP world.
 
-DocBridge creates bidirectional links between TypeScript, Swift, or Dart code
+DocBridge creates bidirectional links between TypeScript, Swift, Dart, or Rust code
 and Markdown documentation, enabling LSP-like experiences such as Hover,
 Definition, References, and Diagnostics across implementation and specification
 files.
@@ -22,13 +22,13 @@ npx docbridge check
 bunx docbridge check
 ```
 
-The current release is
-[v0.5.0](https://github.com/salan70/docbridge/releases/tag/v0.5.0), published
-as `docbridge@0.5.0` on npm.
+See the npm badge above or
+[Releases](https://github.com/salan70/docbridge/releases) for the current
+version.
 
-The package includes prebuilt Swift and Dart scanner
+The package includes prebuilt Swift, Dart, and Rust scanner
 binaries for `darwin-arm64` and `linux-x64`. TypeScript and Markdown checks run
-without scanner binaries. Configured Swift or Dart projects on unsupported
+without scanner binaries. Configured Swift, Dart, or Rust projects on unsupported
 platforms report `code_scanner_unavailable` and name the supported platform
 keys.
 
@@ -98,6 +98,16 @@ bunx docbridge check
 
 ## Usage
 
+Discover a command:
+
+```sh
+bunx docbridge --help
+bunx docbridge context --help
+```
+
+Every command accepts `--help` (alias `-h`) and prints its usage, when to use
+it, and its options on stdout.
+
 Check links:
 
 ```sh
@@ -124,7 +134,8 @@ bunx docbridge check --audit
 
 Audit diagnostics include:
 
-- `undocumented_symbol`
+- `undocumented_symbol` — in-scope code endpoints with no `@doc`
+- `unlinked_doc_section` — in-scope documentation sections with no `@code`
 
 List the linked counterparts of changed files:
 
@@ -193,7 +204,7 @@ Code <-> Documentation
 ```
 
 DocBridge links supported code declarations to Markdown sections. TypeScript is
-scanned in-process; Swift and Dart are scanned through bundled first-party
+scanned in-process; Swift, Dart, and Rust are scanned through bundled first-party
 worker packages.
 
 ## Supported Inputs
@@ -205,11 +216,15 @@ Supported code declarations:
 - TypeScript top-level exported declarations: `function`, `class`,
   `abstract class`, `interface`, `type`, `const`, `enum`, and supported
   `declare` / named default forms
+- TypeScript type members: class methods, properties, accessors, constructors,
+  and static members, plus interface and object-type-alias signatures
 - Swift public/open declarations and configured internal declarations:
   top-level and member types, functions, variables, constants, initializers,
   and extension members
 - Dart public declarations: top-level functions/variables, classes, enums,
   mixins, constructors, fields, accessors, methods, and extension members
+- Rust `pub` declarations (and configured non-`pub` with `visibility`):
+  modules, structs, enums, free functions, and inherent `impl` methods
 
 Supported Markdown elements:
 
@@ -217,8 +232,29 @@ Supported Markdown elements:
 - HTML comments
 - `@code` annotations attached to the next heading
 
-Swift and Dart use the same `@doc` and `@code` model. Their code fragments are
-the scanner-produced canonical IDs, so members are type-qualified:
+All four languages use the same `@doc` and `@code` model. Code fragments are
+the scanner-produced canonical IDs, so members are type-qualified.
+
+TypeScript member IDs carry no parameter signature; overload signatures and a
+getter/setter pair each collapse to one endpoint, and the constructor is
+`<Type>.constructor`. By default `public` and `protected` members are scanned;
+`private` members require `include.code.typescript.visibility`. Members are
+linkable but are never reported by `check --audit`.
+
+```ts
+export class AuthService {
+  /** @doc docs/auth.md#login-spec */
+  login(email: string, password: string): void {}
+}
+```
+
+```md
+<!-- @code src/auth/service.ts#AuthService.login -->
+
+## Login Spec
+```
+
+Swift, Dart, and Rust canonical IDs follow their own conventions:
 
 ```swift
 /// @doc docs/auth.md#login-spec
@@ -268,27 +304,27 @@ shape is intentionally invalid; migrate it to a `typescript` entry:
 }
 ```
 
-Swift and Dart projects must build their scanner workers in source checkouts
-before checking those languages. Run `just build-swift-scanner` for Swift and
-`just build-dart-scanner` for Dart, or use the native test recipes below.
+Swift, Dart, and Rust projects must build their scanner workers in source checkouts
+before checking those languages. Run `just build-swift-scanner` for Swift,
+`just build-dart-scanner` for Dart, and `just build-rust-scanner` for Rust, or
+use the native test recipes below.
 
 ## AI agent integration
 
 DocBridge's link graph is built to be consumed by AI coding agents:
 
 - [docs/integrations](docs/integrations) — recipes for Claude Code, Codex,
-  and CI: on-edit counterpart awareness with `docbridge context`, gate triage
-  with `docbridge related --gate`, and PR reporting.
-- [examples/hooks](examples/hooks) — copyable agent hook scripts implementing
-  those recipes.
+  and CI: gate triage with `docbridge related --gate`, counterpart content with
+  `docbridge context`, and PR reporting.
 - [templates/skills](templates/skills) — distributable agent skills installed by
   `docbridge init`; `docbridge init-with-agent` installs `docbridge-adopt`
-  first, then `docbridge-adopt` installs the companion skills:
-  `docbridge-annotate`, `docbridge-sync`, `docbridge-adopt`, `docbridge-link`,
-  and `docbridge-review`.
+  alone, then `docbridge-adopt` installs the companion skills:
+  `docbridge-annotate`, `docbridge-link`, `docbridge-review`, and
+  `docbridge-sync`.
 
-This repository dogfoods the hooks and skills in its own guardrails under
-`.claude/`, `.codex/`, and `.agents/`.
+This repository dogfoods the skills under `.claude/` and `.agents/`, and keeps
+its guardrail in the Git `pre-commit` hook under `.githooks/` rather than in
+any agent's configuration.
 
 ## Editor support
 
@@ -339,6 +375,8 @@ Errors:
 - `duplicate_doc_anchor`
 - `duplicate_code_symbol`
 - `code_parse_error`
+- `code_scanner_unavailable`
+- `code_scanner_failed`
 - `file_read_error`
 
 Warnings:
@@ -347,6 +385,7 @@ Warnings:
 - `dangling_code_annotation`
 - `unsupported_declaration`
 - `undocumented_symbol` when `--audit` is enabled
+- `unlinked_doc_section` when `--audit` is enabled
 
 Exit code policy:
 
@@ -373,7 +412,7 @@ repository setup, testing matrix, commit convention, and pull request workflow.
 
 ## Roadmap
 
-Completed v0.1–v0.5 capabilities are documented above and in
+Completed v0.1–v0.6 capabilities are documented above and in
 [CHANGELOG.md](CHANGELOG.md).
 
 Remaining editor delivery work:

package/dist/bin/darwin-arm64/SHA256SUMS

@@ -1,2 +1,3 @@
-e5dc0117b9afe4e617fac20f9a8cf9797fa307f66d5a3f12e8ea6554639adce3  docbridge-swift-scanner
-8268ae8b1d3329a96ce30590c8f177b0c19ea1a887a458647e04d8d295c74a71  docbridge_dart_scanner
+bc9e7548f993e48d280c3a487be4cc90a3e6549491c6f93f0e518ccc4239d991  docbridge-swift-scanner
+ceb237b7e5b2047d091f961c0a43ba436b8c624c741cc7f864e5783d9248a4eb  docbridge_dart_scanner
+a1b129d980c981a2d24f0c9682e614a9695d4e9f9b8174d61b0dacb3fc9e3c79  docbridge-rust-scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -1,2 +1,3 @@
-396d365794cb5c427817b358bb3d9f2280000cd33fe3fc7d6d5a772a29ebcae4  docbridge-swift-scanner
-b5de2b74d56c6d8c9f8edd859d4b0d8846ff32d8e1d50b6fa41683d9a310b9f5  docbridge_dart_scanner
+114f780cebfb8834f200ef60f3a828ca7dc4668b23f6e646971e3e56c377b37a  docbridge-swift-scanner
+095c4c172da615be155bee15dcce7b99faaf2a8bb26f3cad3e0b17881495ddf2  docbridge_dart_scanner
+d89a1146ed10dcb01151ef5351a746862c3955286431c47f3cf91cf6639866ba  docbridge-rust-scanner