From 8f6ba69bf2ae4f17b95fed96a9022b73ca21827d Mon Sep 17 00:00:00 2001
From: Timmy <timmy@storkit>
Date: Thu, 14 May 2026 17:10:13 +0100
Subject: [PATCH] docs: add README for source-map-gen crate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers the two binaries (source-map-check, source-map-regen), the
library entry points, and the why — that .huskies/source-map.json
is embedded directly in every autonomous coder's orientation
prompt, so determinism and freshness are load-bearing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 crates/source-map-gen/README.md | 111 ++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 crates/source-map-gen/README.md

diff --git a/crates/source-map-gen/README.md b/crates/source-map-gen/README.md
new file mode 100644
index 00000000..077fda57
--- /dev/null
+++ b/crates/source-map-gen/README.md
@@ -0,0 +1,111 @@
+# source-map-gen
+
+LLM-friendly source map generation and documentation coverage checking for the
+huskies pipeline.
+
+The crate exposes two artifacts:
+
+- A **library** that extracts public-item signatures from Rust and TypeScript
+  source files, writes them to a JSON map, and checks doc-comment coverage on a
+  changed-file set.
+- Two **CLI binaries** (`source-map-check`, `source-map-regen`) used by
+  `script/check` and by autonomous coder agents.
+
+## Why this exists
+
+The huskies orchestrator embeds `.huskies/source-map.json` directly into the
+orientation prompt of every autonomous coder it spawns (see
+`server/src/agents/local_prompt.rs`). The map is a compact, sorted index of
+every public item in the project — function and method signatures, struct
+fields, exported TS symbols — that lets a fresh agent answer "what's already
+here?" without scanning the tree itself.
+
+Two properties matter:
+
+1. **Determinism.** Running the regenerator twice on an unchanged tree must
+   produce a byte-identical file. Sorted keys, sorted arrays, stable formatting.
+2. **No stale entries.** The map cannot reference items that no longer exist,
+   or the orientation bundle lies to agents.
+
+## Binaries
+
+### `source-map-check`
+
+Doc-coverage validator. Used by the pre-commit gate and by coder agents before
+they commit.
+
+```
+cargo run -p source-map-gen --bin source-map-check -- \
+    --worktree . --base master
+```
+
+Collects every file that differs from `--base` in any git state (committed,
+staged, unstaged, untracked), runs the per-language adapter's check, and exits
+non-zero with one actionable line per undocumented public item:
+
+```
+server/src/foo.rs:42: add a doc comment to fn `bar`. Example: `/// Brief description.` above the declaration
+```
+
+Coverage is *ratcheted to added lines*: only items whose declaration falls
+inside a hunk added since `--base` are reported. Pre-existing undocumented
+items in untouched lines are ignored, so the gate cannot retroactively block
+work on an unrelated change.
+
+### `source-map-regen`
+
+Rebuilds `.huskies/source-map.json` from scratch.
+
+```
+cargo run -p source-map-gen --bin source-map-regen -- --project-root .
+```
+
+Enumerates every tracked file via `git ls-files`, extracts its public items via
+the language adapter, and writes a sorted JSON map. Wired into `script/check`
+so each pre-commit run captures a fresh snapshot. Cannot leave stale entries —
+unlike incremental update, this path always starts from the empty map.
+
+## Library
+
+```rust
+use source_map_gen::{check_files_ratcheted, regenerate_source_map, CheckResult};
+```
+
+Key entry points:
+
+- `regenerate_source_map(worktree, source_map_path)` — full rebuild from
+  `git ls-files`. Deterministic.
+- `check_files_ratcheted(files, worktree, base)` — doc-coverage check filtered
+  to lines added since `base`.
+- `check_files(files)` — non-ratcheted variant; reports every undocumented
+  public item.
+- `added_line_ranges(worktree, base, file)` — 1-based inclusive line ranges in
+  `file` added since `base`, covering all git states (committed, staged,
+  unstaged, untracked).
+- `update_source_map(passing_files, source_map_path, root)` — patches the map
+  in place for the given files. Used by the incremental path; production code
+  prefers `regenerate_source_map` to avoid stale entries.
+
+Languages plug in via the `LanguageAdapter` trait. The crate ships
+`RustAdapter` and `TypeScriptAdapter`.
+
+## Map format
+
+`.huskies/source-map.json` is a JSON object keyed by repo-relative file path,
+each value an array of public-item signatures from that file:
+
+```json
+{
+  "server/src/foo.rs": [
+    "pub fn parse_config(path: &Path) -> Result<Config, Error>",
+    "pub struct Config"
+  ],
+  "frontend/src/api.ts": [
+    "export function fetchStories(): Promise<Story[]>"
+  ]
+}
+```
+
+Keys are sorted alphabetically; each value array preserves the order returned
+by the adapter. The file is checked into git only as a generated artifact —
+treat it as build output, not as something to hand-edit.