Timmy
8f6ba69bf2
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>
112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
# 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.
|