huskies/crates/source-map-gen/README.md

# 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.