A small CLI that collects facts about the symbols a git diff changed, so a human can
decide where to read first. It explains nothing and judges nothing — it points.
It is not a static analyzer or a code-review tool: it runs no semantic analysis. v0.x — symbols are found with a parser (tree-sitter), but the signals attached to them are crude on purpose; the output is meant to be skimmed and falsified, not trusted.
signals → prioritize → interrogate
chsig optional LLM human / agent
collect choose a understand
facts reading order adversarially
- Facts, not judgment.
refs=1is a fact; "safe to skip" is a judgment.chsignever crosses that line: it emits no skip verdict and does not rank by risk. It prints per file in diff order. Ranking is the next stage's job. - The numbers exist so a human can cheaply falsify them, not to make you trust the tool.
So
refsis "lines matching the name", not "resolved references" — crude on purpose. - Reducing load by reducing what you read is the opposite of generating a better
explanation. If
chsigever started explaining, it would be a worse explainer. It stays in the "where to look" lane and leaves understanding to the reader.
cargo install --locked --path . # puts `chsig` on PATHNeeds a Rust toolchain and a C compiler (for the tree-sitter grammars). Run chsig from
inside the repo you want to read. The chsig-prioritize stage also needs the claude CLI
on PATH.
chsig main...HEAD # args go straight to `git diff`; run inside the target repo
chsig # no args = working diffsrc/cache/store.ts
getOrFetch refs=14, branch+5
calls: cache.get, +client.fetch, -fetchRecord, +cache.set
evictExpired refs=6, branch+1
pruneStale refs=0, branch-2, deleted
calls: -cache.keys, -cache.delete
src/db/records.ts
loadRecord refs=12
calls: -db.query, +tx.select, +tx.where
calls lists the callees on a symbol's changed lines as written (receiver.method, or the
name a call chain starts from): + only on added lines, - only on removed ones, bare on
both. chsig attaches no meaning to them; whether tx.select is a database read is for the
reader to judge.
Pipes the signals to claude -p, which names the 3–5 symbols to read first with
signal-grounded reasons, and ends by naming one to interrogate.
/path/to/change-signals/chsig-prioritize main...HEAD # run inside the target repoThis is a thin shell layer, deliberately not part of the Rust binary: the LLM call is
non-deterministic I/O and stays outside the deterministic core (shell = fetch / toolbox = compute). No judgment leaks back into the extractor.
Read the selected code and challenge it: verify assumptions, consider alternatives, look for failure conditions — by hand or with a coding agent. Deliberately outside chsig: the tool picks where to look, not what to conclude.
- Symbols are found for Rust and TypeScript/JavaScript only; other files are skipped.
- A symbol is the outermost named function or method: free functions, methods of an
impl/trait/class/object literal (shown asFoo::new,Client.fetch), variables bound to a function or, outside an anonymous function, to a call handed one (memo(() => ...); inside one,const ids = xs.map(f)is a local value), and an anonymousexport defaultof either (shown asdefault, withrefs=?since it has no name to grep for). A named function inside another one is not a symbol of its own — a component's handlers attribute to the component. - Changes outside every symbol are not shown: types, imports, module-level statements,
doc comments above a function, decorators on a class, and code only inside anonymous
callbacks (most of a
describe/ittest file). A function's attributes and decorators (#[cfg],@Get(...)) belong to it, since they change what it does. - Added lines are placed on the new side's symbols and removed lines on the old side's.
Symbols are matched across the two sides by name; one whose name exists on only one side
is marked
newordeleted, so a rename shows as one of each (no rename is inferred). - When the parser hits syntax it can't read, chsig warns
parse errors in <file> at line 12; symbol ranges may be offon stderr, naming up to three lines where it went wrong (<file> (old side)for the old side). The TypeScript grammar does not readimport('...')types inside type arguments (e.g.importOriginal<typeof import('x')>()), nor call signatures in an interface or type literal separated only by newlines, nor a&before a letter in JSX text or an attribute string unless it closes as&name;(href="?a=1&b=2"warns;&doesn't). - Pass revisions and paths. An option that changes the diff's format (
--color,--word-diff,--stat,-R) is refused with an error, since chsig reads the plain patch. A combined diff (a merge,<merge>^!, or a conflicted file) is skipped with a notice; name one parent instead (<merge>^1 <merge>, orHEADduring a conflict). So is a path git still quotes (one with",\, or a control character), which chsig doesn't unquote. - A working file is read only if it hashes (with git's filters) to the diff's new-side blob; otherwise it is skipped with a notice, as for a retargeted symlink. A filter that swaps the whole content, such as Git LFS, still passes the check while the diff describes the pointer.
refsisgit grep-based (tracked files across the whole repo, as in the working tree), matching the bare name, not resolved references. With a range or--cached, chsig says on stderr when changed files in the working tree are not the diff's new side (a PR reviewed from its base checkout, say), since refs then counts another revision; run from a checkout of the new side (a worktree of the PR's head) for refs that match the diff.callsresolves nothing. A receiver with no name to show ((a + b).abs(), a literal) is*, and a call through an expression (fns[i]()) is not listed. Nor is a TypeScript tagged template with type arguments (sql<Row>`...`): the grammar misreads it, often without a parse error.branchis the net change in branch points on changed lines, read from the syntax tree:if(anelse ifcounts once), a finalelse,case/default/ match arms, ternaries,&&/||/??, and Rust'slet ... else; loops are not counted. It counts syntax, not paths through the code.
The signals stay crude on purpose: making them precise means type resolution, which would turn this into a different, heavier tool. The coarseness keeps a human in the loop.
cargo test — unit tests pin the current behavior (including known defects) as a
regression anchor. I/O functions (git, disk) are left to integration.