docbridge 0.4.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "docbridge",
+  "version": "0.4.0",
+  "description": "A Bun CLI that links Markdown specifications and code declarations.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "docbridge": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/salan70/docbridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/salan70/docbridge/issues"
+  },
+  "homepage": "https://github.com/salan70/docbridge#readme",
+  "keywords": [
+    "documentation",
+    "markdown",
+    "specification",
+    "cli",
+    "bun",
+    "lsp"
+  ],
+  "engines": {
+    "bun": ">=1.1.31"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "templates/skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "docbridge": "bun run src/cli/index.ts",
+    "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"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.0"
+  }
+}

package/schemas/context-output.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DocBridge Context Output",
+  "description": "Shape of `docbridge context --json` output. See docs/specs/cli.md#context-command.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contexts", "diagnostics", "summary"],
+  "properties": {
+    "contexts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["endpoint", "kind", "filePath", "startLine", "endLine", "linkedFrom", "content"],
+        "properties": {
+          "endpoint": {
+            "type": "string",
+            "description": "Counterpart endpoint in `file#fragment` form."
+          },
+          "kind": {
+            "type": "string",
+            "enum": ["code", "doc"]
+          },
+          "filePath": {
+            "type": "string",
+            "description": "Project-root-relative POSIX path of the counterpart file."
+          },
+          "language": {
+            "type": "string",
+            "enum": ["typescript", "swift", "dart"],
+            "description": "Code language for code context blocks."
+          },
+          "startLine": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-based first line of `content` within `filePath`."
+          },
+          "endLine": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-based last line of `content` within `filePath`, inclusive."
+          },
+          "linkedFrom": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            },
+            "description": "Endpoints in the input files that link to this counterpart, sorted."
+          },
+          "content": {
+            "type": "string",
+            "description": "Full Markdown section (doc) or full declaration source including JSDoc (code)."
+          }
+        }
+      }
+    },
+    "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 }
+            }
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["inputFiles", "contexts"],
+      "properties": {
+        "inputFiles": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Distinct input files after normalization."
+        },
+        "contexts": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of context blocks."
+        }
+      }
+    }
+  }
+}

package/schemas/docbridge.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DocBridge Configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["include"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "include": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "docs"],
+      "properties": {
+        "code": {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": {
+            "typescript": { "$ref": "#/$defs/codeLanguageEntry" },
+            "swift": { "$ref": "#/$defs/codeLanguageEntry" },
+            "dart": { "$ref": "#/$defs/codeLanguageEntry" }
+          }
+        },
+        "docs": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "codeLanguageEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/graph-output.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DocBridge Graph Output",
+  "description": "Shape of `docbridge graph --json` output. See docs/specs/cli.md#graph-command.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["nodes", "edges", "pairs", "diagnostics", "summary"],
+  "properties": {
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "endpoint", "filePath", "location"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable node identifier; equal to `endpoint`."
+          },
+          "kind": {
+            "type": "string",
+            "enum": ["code", "doc"]
+          },
+          "endpoint": {
+            "type": "string",
+            "description": "Endpoint in `file#fragment` form."
+          },
+          "filePath": {
+            "type": "string",
+            "description": "Project-root-relative POSIX path of the endpoint file."
+          },
+          "language": {
+            "type": "string",
+            "enum": ["typescript", "swift", "dart"],
+            "description": "Code language for code nodes."
+          },
+          "location": { "$ref": "#/$defs/location" },
+          "range": { "$ref": "#/$defs/range" },
+          "content": {
+            "oneOf": [
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind", "symbolName", "signature"],
+                "properties": {
+                  "kind": { "const": "code" },
+                  "symbolName": { "type": "string" },
+                  "signature": {
+                    "type": "string",
+                    "description": "JSDoc plus declaration signature; implementation body is omitted."
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind", "headingText"],
+                "properties": {
+                  "kind": { "const": "doc" },
+                  "headingText": { "type": "string" }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "source", "target", "location"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["doc", "code"],
+            "description": "`doc` is a code-to-doc @doc annotation; `code` is a doc-to-code @code annotation."
+          },
+          "source": {
+            "type": "string",
+            "description": "Source endpoint of the annotation edge."
+          },
+          "target": {
+            "type": "string",
+            "description": "Resolved target endpoint of the annotation edge."
+          },
+          "location": { "$ref": "#/$defs/location" },
+          "range": { "$ref": "#/$defs/range" }
+        }
+      }
+    },
+    "pairs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["codeEndpoint", "docEndpoint", "hasDocEdge", "hasCodeEdge"],
+        "properties": {
+          "codeEndpoint": { "type": "string" },
+          "docEndpoint": { "type": "string" },
+          "hasDocEdge": {
+            "type": "boolean",
+            "description": "True when a resolved @doc annotation exists from code to doc."
+          },
+          "hasCodeEdge": {
+            "type": "boolean",
+            "description": "True when a resolved @code annotation exists from doc to code."
+          }
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/diagnostic" }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "nodes",
+        "edges",
+        "codeNodes",
+        "docNodes",
+        "bidirectionalPairs",
+        "oneWayEdges",
+        "diagnostics"
+      ],
+      "properties": {
+        "nodes": { "type": "integer", "minimum": 0 },
+        "edges": { "type": "integer", "minimum": 0 },
+        "codeNodes": { "type": "integer", "minimum": 0 },
+        "docNodes": { "type": "integer", "minimum": 0 },
+        "bidirectionalPairs": { "type": "integer", "minimum": 0 },
+        "oneWayEdges": { "type": "integer", "minimum": 0 },
+        "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/templates/skills/README.md

@@ -0,0 +1,31 @@
+# DocBridge skill templates
+
+Distributable agent skills for projects that use DocBridge. Installation is
+copy-based: copy a skill directory into your repository's skill location
+(`.claude/skills/` for Claude Code or `.agents/skills/` for Codex-style
+project skills) and adjust nothing unless your DocBridge invocation differs
+from the examples inside.
+
+- [`docbridge-annotate`](docbridge-annotate/SKILL.md) — create correct
+  `@doc`/`@code` link pairs and verify them with `docbridge check`.
+- [`docbridge-sync`](docbridge-sync/SKILL.md) — triage `related --gate`
+  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, and handling simple CI/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.
+- [`docbridge-review`](docbridge-review/SKILL.md) — review the whole DocBridge
+  graph for semantic validity using `docbridge graph --json --include-content`.
+
+This repository dogfoods the distributable DocBridge skills from both
+`.claude/skills/` and `.agents/skills/` as skill-level symlinks to this
+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/).

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

@@ -0,0 +1,78 @@
+---
+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.
+---
+
+# docbridge-adopt
+
+Adopt DocBridge in an existing project. This skill assumes it is already
+installed in the agent environment; installing agent skills into another
+project is documented outside this skill.
+
+The goal is to make the repository ready for DocBridge links, then continue
+into an initial docs-first link-candidate pass. Do not assume a pull request.
+
+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`.
+
+## Procedure
+
+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
+   - existing `@doc` / `@code` annotations
+   - package scripts, CI files, git hooks, and agent 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
+     whose supported declarations should be linkable
+   - CI/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.
+
+3. **Create or improve config.**
+   - If no config exists, create `docbridge.config.json` with the confirmed
+     `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": [...] } }`.
+   - If config exists, read it, explain the current scope, propose any
+     improvement, and edit only after confirmation.
+   - Never replace a user-authored config blindly.
+
+4. **Handle CI/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
+     snippet instead of editing.
+   - Prefer non-blocking awareness early in adoption unless the user requests a
+     hard gate.
+
+5. **Verify the setup.** Run `docbridge check` or the repository's equivalent.
+   If the project intentionally has no links yet, a clean zero-link result is
+   acceptable. Surface config or scanning diagnostics before proceeding.
+
+6. **Continue into initial candidate discovery.** After setup, inspect the
+   confirmed docs scope and present 5-10 high-value section candidates using
+   the `docbridge-link` rules. Candidate discovery may continue in the same
+   turn, but annotation edits still require section-level user confirmation.
+
+## Scope Rules
+
+- Prefer docs sections that state behavior, contracts, inputs/outputs,
+  constraints, user-visible behavior, or design decisions.
+- Treat README, changelogs, contribution docs, runbooks, logs, and release
+  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
+  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

@@ -0,0 +1,98 @@
+---
+name: docbridge-annotate
+description: Create bidirectional DocBridge links between supported code declarations and Markdown sections. Use when asked to link code to its specification, add @doc or @code annotations, annotate new code with docs, or fix DocBridge link diagnostics.
+---
+
+# docbridge-annotate
+
+Create a DocBridge link pair: a `@doc` tag in the code documentation comment
+and a `@code` comment above the Markdown heading. A link is valid only when
+both directions exist and point at each other.
+
+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`.
+
+## Link anatomy
+
+Code side — a `@doc` tag in the documentation comment of a supported
+declaration:
+
+```ts
+/**
+ * @doc docs/auth.md#login-spec
+ */
+export async function login() {}
+```
+
+```swift
+/// @doc docs/auth.md#login-spec
+public struct AuthService {
+  public func login(email: String, password: String) {}
+}
+```
+
+Markdown side — a standalone HTML comment directly above the heading of the
+section:
+
+```md
+<!-- @code src/auth/login.ts#login -->
+## Login Spec
+```
+
+Both targets are `file#fragment`: the file path is project-root-relative with
+`/` separators (no `./`, `../`, or absolute paths), and the fragment is
+required. Optional text after the target is allowed and ignored
+(`@doc docs/auth.md#login-spec human note`).
+
+## Rules that decide whether the link resolves
+
+- `@doc` works only on top-level exported declarations: `function`, `class`,
+  `abstract class`, `interface`, `type`, `enum`, `const enum`, `const` with a
+  single declarator, named default `function`/`class`, and their `declare`
+  forms. Anything else (anonymous default exports, multi-declarator `const`,
+  namespaces, re-exports, non-exported declarations) produces
+  `unsupported_declaration`.
+- Swift `@doc` works on supported public/open declarations and configured
+  internal declarations. Member endpoints are type-qualified and include
+  argument labels, for example `AuthService.login(email:password:)`.
+- Dart `@doc` works on supported public declarations. Member endpoints are
+  type-qualified without parameter signatures, for example
+  `AuthService.login`; setters carry a trailing `=`.
+- The code-side fragment is the scanner-produced canonical ID.
+- The doc-side fragment is the anchor generated from the ATX heading
+  (`#`–`######`): lowercase via JavaScript `toLowerCase()`, Unicode letters
+  and numbers preserved, whitespace and punctuation runs collapsed to `-`,
+  leading/trailing `-` removed. Example: `## Login Spec (v2)` →
+  `#login-spec-v2`. Setext headings have no anchors.
+- The `@code` comment must be standalone, indented at most 3 spaces, with the
+  body starting with `@code`. Blank lines between the comment and its heading
+  are fine; any other text in between makes it `dangling_code_annotation`.
+- One declaration may carry multiple `@doc` tags and one heading multiple
+  `@code` comments; each pair is an independent link.
+- Anchors must be unique within one Markdown file; symbols must be unique
+  among annotated declarations in one TypeScript file.
+
+## Procedure
+
+1. Identify the two endpoints: the exported declaration and the Markdown
+   section. If the section does not exist yet, write it first — the heading
+   text fixes the anchor.
+2. Add the `@doc` tag to the declaration's documentation comment (create the
+   documentation comment if missing), pointing at the doc file and the
+   generated heading anchor.
+3. Add the `@code` comment directly above the heading, pointing back at the
+   code file and the scanner-produced canonical ID.
+4. Verify with `docbridge check`. The link is correct only when no diagnostic
+   mentions either endpoint.
+
+## 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 |