huskies/crates/source-map-gen

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

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:

{
  "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.