docbridge 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-06-18
+
+### Added
+
+- npm distribution support for the Bun-only `speclink` package, including
+  `dist/index.js` as the package binary, a runtime package allowlist, dist
+  verification, packed-package smoke testing, and release workflow publishing.
+- Platform-staged Swift and Dart scanner binary layout under
+  `dist/bin/<platform>/`, with initial npm scanner support for `darwin-arm64`
+  and `linux-x64`.
+- Dart scanner worker support, including analyzer-based `@doc` extraction,
+  type/member canonical IDs (without parameter signatures, since Dart has no
+  overloading), public-by-naming visibility, and Dart end-to-end
+  check/context/graph/LSP integration. The Dart toolchain is provided by the Nix
+  dev shell.
+- Swift scanner worker support for SwiftPM source checkouts, including
+  SwiftSyntax-based `@doc` extraction, type/member canonical IDs, visibility
+  filtering, and Swift end-to-end check/context/graph/LSP integration.
+- Worker-backed scanner protocol foundation for Swift and Dart adapters,
+  including stdin/stdout JSON invocation and scanner availability/failure
+  diagnostics.
+- `speclink graph`: prints the resolved link graph as human-readable output or
+  as JSON following `schemas/graph-output.schema.json`, including resolvable
+  one-way links, pair completeness, optional lightweight node content, and
+  diagnostics that do not prevent graph construction.
+- Distributable adoption skills under `templates/skills/`: `speclink-adopt`
+  for existing-project setup, `speclink-link` for docs-first annotation
+  candidate confirmation, and `speclink-review` for whole-graph semantic
+  review using `speclink graph --json --include-content`.
+
+### Changed
+
+- `speclink context` and `speclink graph --json` now carry code language
+  metadata for code blocks/nodes so Swift endpoints render and serialize as
+  Swift.
+- SpecLink's distributable skills are now dogfooded from `.agents/skills/` and
+  `.claude/skills/` as symlinks to the canonical `templates/skills/` entries.
+- TypeScript scanner endpoints now include `signatureRange` in addition to the
+  existing full `declarationRange`, allowing graph consumers to read the
+  public JSDoc/signature surface without implementation bodies.
+
+### Fixed
+
+- Worker-backed scanner responses now fail when the returned file list does not
+  exactly match the requested files, and worker failures suppress derived link
+  diagnostics for the failed file.
+- The npm-distributed CLI now resolves its bundled `dist/bin/<platform>` Swift
+  and Dart scanner binaries when launched through the `node_modules/.bin`
+  symlink, which previously resolved to the wrong directory on Linux and
+  reported the scanner as unavailable.
+
+## [0.3.0] - 2026-06-14
+
+### Added
+
+- `speclink context`: prints the content of the counterparts linked from a set
+  of input files (positional arguments or newline-separated stdin via
+  `--stdin`) — full Markdown sections for doc counterparts, full declarations
+  including JSDoc for code counterparts. Default output is Markdown suitable
+  for direct injection into an agent prompt; `--json` emits a machine-readable
+  report following `schemas/context-output.schema.json`. Extraction is
+  best-effort: check diagnostics located in the input files are reported on
+  stderr (or in the `diagnostics` field) without affecting the exit code.
+- TypeScript scanner: records a `declarationRange` covering each supported
+  declaration including its JSDoc block, backing `context` content extraction.
+- `just context`: prints the linked counterpart content of the uncommitted
+  changes.
+- AI integration recipes under `docs/integrations/`: on-edit counterpart
+  awareness and gate triage for Claude Code and Codex, and a CI recipe for
+  gating the PR change set and reporting counterpart content.
+- Copyable agent hook scripts under `examples/hooks/`: a `PostToolUse` hook
+  that surfaces linked counterpart content on edit, and a `Stop` hook that
+  reports `related --gate` findings with the flagged counterparts' content as
+  Stop `additionalContext`.
+- Distributable agent skills under `templates/skills/`: `speclink-annotate`
+  (create `@doc`/`@code` link pairs and verify them with `speclink check`) and
+  `speclink-sync` (triage `related --gate` findings using `speclink context`).
+  Both are also installed in this repository's `.claude/skills/`.
+
+### Changed
+
+- Markdown section extraction moved from the LSP layer into `src/core/` and is
+  now shared by LSP hover and `speclink context` (no behavior change).
+
+## [0.2.0] - 2026-06-11
+
+### Added
+
+- `speclink related`: an informational command that lists the linked
+  counterparts of a set of changed files (positional arguments or
+  newline-separated stdin via `--stdin`), marking whether each counterpart is
+  itself in the change set. Designed to sit behind `git diff --name-only` in
+  pre-commit hooks and CI. Supports `--root` and `--json`; always exits `0` on
+  success.
+- `speclink related --gate`: a gate mode that reports only the counterparts
+  that are not themselves in the change set and exits `1` when any exist. The
+  check is symmetric (changed code with unchanged linked docs, and changed
+  docs with unchanged linked code). Combines with `--json` for a
+  machine-readable violations report.
+- `speclink lsp`: a Language Server over stdio that exposes the SpecLink link
+  graph to editors, with JSON-RPC `Content-Length` framing and the standard
+  `initialize` / `initialized` / `shutdown` / `exit` lifecycle.
+- `textDocument/publishDiagnostics`: the existing v0.1 diagnostics surfaced in
+  the editor, refreshed on document changes with a short debounce.
+- `textDocument/hover`: inline Markdown spec sections for linked code symbols,
+  and the declaration signature line for linked headings.
+- `textDocument/definition` and `textDocument/references` over the symmetric
+  counterpart relation, including one-to-many navigation.
+- Scanner range enrichment (`nameRange`, `headingTextRange`, `targetRange`) and
+  a whole-project model with buffer overlay backing the language server.
+- A minimal VS Code client extension under `editors/vscode/` to verify the
+  server in a real editor.
+
+## [0.1.0] - 2026-06-07
+
+Initial release of the SpecLink CLI.
+
+### Added
+
+- `@doc` annotation parsing from TypeScript JSDoc via the TypeScript Compiler API.
+- `@code` annotation parsing from Markdown HTML comments.
+- Markdown scanner with v0.1 heading anchor generation.
+- Configuration loading (`speclink.config.json`) with `*`/`**` glob scanning.
+- Bidirectional link resolution between code and documentation.
+- Deterministic, machine-readable diagnostics.
+- `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.4.0...HEAD
+[0.4.0]: https://github.com/salan70/docbridge/releases/tag/v0.4.0
+[0.3.0]: https://github.com/salan70/docbridge/releases/tag/v0.3.0
+[0.2.0]: https://github.com/salan70/docbridge/releases/tag/v0.2.0
+[0.1.0]: https://github.com/salan70/docbridge/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DocBridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,420 @@
+# DocBridge
+
+[![Japanese README](https://img.shields.io/badge/README-%E6%97%A5%E6%9C%AC%E8%AA%9E-blue)](docs/ja/README.md)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/salan70/docbridge)
+
+Bring Markdown into the LSP world.
+
+DocBridge creates bidirectional links between TypeScript, Swift, or Dart code
+and Markdown documentation, enabling LSP-like experiences such as Hover,
+Definition, References, and Diagnostics across implementation and specification
+files.
+
+## Motivation
+
+Modern software projects often suffer from a gap between implementation and documentation:
+
+- Code changes without documentation updates
+- Documentation changes without implementation updates
+- Difficulty finding which specifications relate to a given implementation
+- Difficulty finding which implementation relates to a given specification
+- AI coding agents missing relevant context during code modifications
+
+DocBridge makes relationships between code and documentation explicit, navigable, and machine-readable.
+
+## Concept
+
+Traditional documentation tools often focus on one direction:
+
+```text
+Code -> Documentation
+```
+
+DocBridge focuses on both directions:
+
+```text
+Code <-> Documentation
+```
+
+DocBridge links supported code declarations to Markdown sections. TypeScript is
+scanned in-process; Swift and Dart are scanned through bundled first-party
+worker packages.
+
+## Example
+
+TypeScript:
+
+```ts
+/**
+ * @doc docs/auth.md#login-spec
+ */
+export async function login() {
+  // ...
+}
+```
+
+Markdown:
+
+```md
+<!-- @code src/auth/login.ts#login -->
+## Login Spec
+
+Login flow specification.
+```
+
+Swift and Dart use the same `@doc` and `@code` model. Their code fragments are
+the scanner-produced canonical IDs, so members are type-qualified:
+
+```swift
+/// @doc docs/auth.md#login-spec
+public struct AuthService {
+  public func login(email: String, password: String) {}
+}
+```
+
+```md
+<!-- @code Sources/AuthService.swift#AuthService.login(email:password:) -->
+## Login Spec
+```
+
+## Scope
+
+DocBridge recognizes the following elements.
+
+Supported code declarations:
+
+- TypeScript top-level exported declarations: `function`, `class`,
+  `abstract class`, `interface`, `type`, `const`, `enum`, and supported
+  `declare` / named default forms
+- 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
+
+Supported Markdown elements:
+
+- ATX headings
+- HTML comments
+- `@code` annotations attached to the next heading
+
+Projects must define scan targets in `docbridge.config.json`. There is no
+implicit default configuration; when the config file is missing, DocBridge
+reports `config_file_invalid` and does not scan project files.
+
+Minimal TypeScript configuration:
+
+```json
+{
+  "include": {
+    "code": {
+      "typescript": {
+        "patterns": ["src/**/*.ts"]
+      }
+    },
+    "docs": ["docs/**/*.md"]
+  }
+}
+```
+
+Multilanguage configuration is language-keyed. The old `include.code` array
+shape is intentionally invalid; migrate it to a `typescript` entry:
+
+```json
+{
+  "include": {
+    "code": {
+      "typescript": { "patterns": ["src/**/*.ts"] },
+      "swift": { "patterns": ["Sources/**/*.swift"] },
+      "dart": { "patterns": ["lib/**/*.dart"] }
+    },
+    "docs": ["docs/**/*.md"]
+  }
+}
+```
+
+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.
+
+## Installation
+
+DocBridge is distributed as the `docbridge` npm package and is intended to run
+with Bun:
+
+```sh
+bunx docbridge check
+```
+
+The npm package is Bun-only; Node.js runtime compatibility is not part of the
+initial distribution. The package includes prebuilt Swift and Dart scanner
+binaries for `darwin-arm64` and `linux-x64`. TypeScript and Markdown checks run
+without scanner binaries. Configured Swift or Dart projects on unsupported
+platforms report `code_scanner_unavailable` and name the supported platform
+keys.
+
+## CLI
+
+Check links:
+
+```sh
+just check
+```
+
+Check another root:
+
+```sh
+just check-example
+```
+
+Emit JSON:
+
+```sh
+just check-example-json
+```
+
+Run audit diagnostics:
+
+```sh
+just audit
+```
+
+Audit diagnostics include:
+
+- `undocumented_symbol`
+
+List the linked counterparts of changed files:
+
+```sh
+git diff --name-only | docbridge related --stdin
+```
+
+`docbridge related` is informational: it reports each counterpart and whether it
+is itself in the change set, and always exits `0` on success. Changed files can
+also be passed as positional arguments. Add `--gate` to report only the
+counterparts that are not themselves in the change set and exit `1` when any
+exist; `just related-gate` runs this over uncommitted changes. Both modes
+support `--root` and `--json`. See [docs/specs/cli.md](docs/specs/cli.md) for
+details.
+
+Print the content of the linked counterparts of changed files:
+
+```sh
+git diff --name-only | docbridge context --stdin
+```
+
+`docbridge context` answers "what do the linked counterparts say": full
+Markdown sections for doc counterparts, full declarations including JSDoc for
+code counterparts. The default output is Markdown suitable for direct
+injection into an agent prompt; `--json` follows
+[schemas/context-output.schema.json](schemas/context-output.schema.json).
+Extraction is best-effort and the command exits `0` on success even when the
+tree has broken links. See [docs/specs/cli.md](docs/specs/cli.md) for details.
+
+Inspect the resolved link graph:
+
+```sh
+docbridge graph
+docbridge graph --json --include-content
+```
+
+`docbridge graph` prints the resolved endpoint graph, including resolvable
+one-way links. JSON output follows
+[schemas/graph-output.schema.json](schemas/graph-output.schema.json).
+
+## 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.
+- [templates/skills](templates/skills) — distributable agent skills:
+  `docbridge-annotate`, `docbridge-sync`, `docbridge-adopt`, `docbridge-link`,
+  and `docbridge-review`.
+
+This repository dogfoods the hooks and skills in its own guardrails under
+`.claude/`, `.codex/`, and `.agents/`.
+
+## Editor support
+
+DocBridge ships a language server that exposes the same link graph to editors:
+
+```sh
+docbridge lsp
+```
+
+`docbridge lsp` speaks LSP over stdio and provides Diagnostics, Hover,
+Definition, and References across linked code and Markdown. It takes no
+options; the project root comes from the editor's `initialize` request.
+`docbridge check` is unchanged.
+
+A minimal VS Code-compatible client lives in [editors/vscode](editors/vscode);
+see its README to install it into VS Code or Cursor for local testing. Full
+behavior is specified in [docs/specs/lsp.md](docs/specs/lsp.md).
+
+## Diagnostics
+
+Errors:
+
+- `config_file_invalid`
+- `config_unknown_key`
+- `config_invalid_value`
+- `invalid_link_target`
+- `doc_file_not_found`
+- `doc_anchor_not_found`
+- `code_file_not_found`
+- `code_backlink_not_found`
+- `doc_backlink_not_found`
+- `duplicate_doc_anchor`
+- `duplicate_code_symbol`
+- `code_parse_error`
+- `file_read_error`
+
+Warnings:
+
+- `duplicate_link`
+- `dangling_code_annotation`
+- `unsupported_declaration`
+- `undocumented_symbol` when `--audit` is enabled
+
+Exit code policy:
+
+- `1` when any error exists
+- `0` when there are only warnings or no diagnostics
+
+## Development
+
+### Prerequisites
+
+Recommended:
+
+- Nix
+- direnv
+
+The Nix development shell provides the tools used by this repository:
+
+- Bun
+- just
+- Git
+- Dart SDK
+
+If you do not use Nix, install Bun and just locally before running the project
+commands. Swift scanner development also requires a Swift 6 toolchain on
+`PATH`; CI installs Swift separately from Nix.
+
+### Setup
+
+Enable the development environment with direnv:
+
+```sh
+direnv allow
+```
+
+Or enter the Nix development shell manually:
+
+```sh
+nix develop
+```
+
+Install dependencies:
+
+```sh
+bun install --frozen-lockfile
+```
+
+Install repository Git hooks:
+
+```sh
+just install-git-hooks
+```
+
+If `just` is not on `PATH` yet, run:
+
+```sh
+nix develop -c just install-git-hooks
+```
+
+The pre-commit hook runs `just check` and `just test`.
+
+### Common Tasks
+
+Run common tasks with `just`:
+
+```sh
+just --list
+just check
+just check-example
+just check-swift-example
+just check-dart-example
+just check-fixture <code>
+just audit
+just related-gate
+just test
+just test-swift-scanner
+just test-dart-scanner
+just build
+just verify-dist
+```
+
+`just check`, `just test`, and `just build` are the default local and CI gates.
+`just test` includes TypeScript, Swift, and Dart end-to-end integration tests;
+the Swift and Dart scanner binaries must be built before those integration
+tests can spawn them. Scanner-native tests are mandatory in CI and are useful
+locally when changing worker code. `just verify-dist` builds confidence in the
+npm entry point by checking the Bun shebang, executable bit, `--version`,
+`--help`, and a TypeScript example check from `dist/index.js`.
+
+### Project Constraints
+
+Runtime:
+
+- Bun
+
+Language:
+
+- TypeScript
+- Swift scanner worker package
+- Dart scanner worker package
+
+Task runner:
+
+- just
+
+Environment loader:
+
+- direnv
+
+Core dependencies should stay minimal. The CLI should primarily rely on Bun and
+the TypeScript Compiler API; Swift and Dart parser dependencies stay isolated
+inside their worker packages.
+
+## Documentation
+
+- Japanese documentation: [docs/ja/README.md](docs/ja/README.md)
+- Specifications: [docs/specs](docs/specs)
+- v0.1 decisions: [docs/decisions/v0.1.md](docs/decisions/v0.1.md)
+- v0.2 decisions: [docs/decisions/v0.2.md](docs/decisions/v0.2.md)
+- v0.3 decisions: [docs/decisions/v0.3.md](docs/decisions/v0.3.md)
+- AI agent integration recipes: [docs/integrations](docs/integrations)
+- Commit message convention: [docs/contributing/commits.md](docs/contributing/commits.md)
+- Testing convention: [docs/contributing/testing.md](docs/contributing/testing.md)
+
+## Roadmap
+
+Completed v0.1–v0.3 capabilities are documented above and in
+[CHANGELOG.md](CHANGELOG.md). The current roadmap tracks upcoming work only.
+
+v0.5:
+
+- MCP server exposing the link graph and `docbridge context` output as tools
+- Editor and agent delivery channels built on it (Claude Code, Cursor, Zed,
+  Codex)
+
+## Vision
+
+DocBridge is not a documentation generator.
+
+Its purpose is to make relationships between code and documentation visible, navigable, and machine-readable so humans and AI agents can reach relevant context with minimal effort.

package/dist/bin/darwin-arm64/SHA256SUMS

@@ -0,0 +1,2 @@
+4e8638f664e3cb08e36146dd03097d1dfe1c35be39b79219c6d633ea07e7742f  speclink-swift-scanner
+ef5e2d41194493de9f3cea22bc8f268c35bbd0f69ff63e275e303b6476b658a1  speclink_dart_scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -0,0 +1,2 @@
+4100cc8c861a24821fca240c758ba188a42f677a403fe40a76bac4271a918bfe  speclink-swift-scanner
+2145eac2afd09696ced849e0196a2557d6f7041224f13da1d5ef21c552ecf7bc  speclink_dart_scanner