Zachery Aaron Shores-Chmielewski
f35326b5e8
Authored by Claude, lovingly guided by Zachery Aaron Shores-Chmielewski
100 lines
4.6 KiB
Markdown
100 lines
4.6 KiB
Markdown
# cstat-driven codebase cleanup — agent reference
|
|
|
|
## What is cstat
|
|
|
|
cstat is a static analysis CLI for Rust codebases. It measures structure; it
|
|
does not modify code. Use it before and after a cleanup stage to verify that
|
|
objective metrics moved in the intended direction while the project's own build
|
|
and tests preserve behavior.
|
|
|
|
## Starting point
|
|
|
|
Run the focused report first:
|
|
|
|
```sh
|
|
cstat report --json --path <project_root>
|
|
```
|
|
|
|
Omitting the command is equivalent to `cstat summary`, which is the same focused
|
|
report. The JSON contains:
|
|
|
|
- `line_counts`: total code lines, physical lines, and per-file counts.
|
|
- `symbols`: total and per-file counts for functions, structs, enums, traits,
|
|
`trait_impls`, consts, statics, and parse-error state. `trait_impls` means
|
|
`impl Trait for Type` blocks only, not inherent `impl Type` blocks.
|
|
- `dependencies`: module list, module interdependency matrix, edge count, and
|
|
fan-in/fan-out degrees.
|
|
- `dead_code`: functions not statically reachable from main, tests, or
|
|
benchmarks.
|
|
- `test_reachability`: static test/benchmark reachability, step counts, max
|
|
depth, and per-function/per-edge reaching-entry counts.
|
|
|
|
The focused report intentionally excludes older exploratory dashboards. They
|
|
remain available under `cstat advanced ...`.
|
|
|
|
## Focused drilldowns
|
|
|
|
Each accepts `--json` for structured output.
|
|
|
|
- `cstat loc --explain --json` — machine-readable `loc` contract: modes,
|
|
`code_lines` rules, project JSON fields, and selected-file JSON fields.
|
|
- `cstat loc --json --path .` — project size-shape data.
|
|
- `cstat loc --json --path src/lib.rs` — selected-file projected static line
|
|
reachability.
|
|
- `cstat symbols --json --path .` — symbol totals by kind and per file; pass a
|
|
Rust source file to `--path` for selected-file rows and line spans.
|
|
- `cstat deps --json --path .` — dependency edges, coupling, fan-in/fan-out,
|
|
and cohesion.
|
|
- `cstat dead-code --json --path .` — static cold-function candidates.
|
|
- `cstat test-reachability --json --path .` — static test/benchmark
|
|
reachability and reaching-entry counts.
|
|
- `cstat complexity --json --path .` — per-function cyclomatic, cognitive,
|
|
nesting, parameter, and line metrics.
|
|
|
|
## Advanced / legacy commands
|
|
|
|
Use these only when the focused report points to a question they answer:
|
|
|
|
- `cstat advanced summary --json --path .` — previous broad dashboard.
|
|
- `cstat advanced flow --json --path .` — raw static call graph.
|
|
- `cstat advanced graph --json --path .` — graph centrality, SCCs, PageRank.
|
|
- `cstat advanced flow-heatmap --json --path .` — previous random-walk heatmap.
|
|
- `cstat advanced circuits --json --path .` — call-graph community detection.
|
|
- `cstat advanced redundancy --json --path .` — similar/duplicate function
|
|
candidates.
|
|
- `cstat advanced dist --json --path .` — metric histograms/correlation views.
|
|
- `cstat advanced map --json --path .` — terminal architecture map.
|
|
- `cstat advanced dump --path .` — previous diagnostic-score dump.
|
|
- `cstat advanced guide <topic>` — metric reference material.
|
|
|
|
## Cleanup workflow
|
|
|
|
1. Run `cstat report --json --path .`.
|
|
2. Read the focused sections in this order:
|
|
- line counts: find oversized files first;
|
|
- symbols: find files with too many definitions;
|
|
- dependency matrix: find high fan-in/fan-out modules and cycles;
|
|
- dead code: review cold candidates before deleting;
|
|
- test reachability: compare code surface against what tests/benches can statically reach.
|
|
3. Plan one cleanup stage at a time.
|
|
4. After each stage, rerun `cstat report --json --path .` and the project's own
|
|
build/tests. cstat metrics do not prove correctness.
|
|
|
|
## Safety rules
|
|
|
|
- Dead-code findings are static. Check macros, trait-object calls, public API
|
|
use, build scripts, and string-based dispatch before deleting.
|
|
- Test-reachability counts are static entry-root reachability: how many
|
|
test/benchmark roots can reach a function or edge. They are not runtime hit-count profiling.
|
|
- Dependency edges come from source-level `use`/`mod` relationships. Generated
|
|
code and macro expansion can hide edges.
|
|
- For exact `loc` `code_lines` rules and JSON fields, run
|
|
`cstat loc --explain` or `cstat loc --explain --json`; that command is the
|
|
canonical contract.
|
|
- Symbol counts come from `syn` Rust AST parsing. They are not semantic name
|
|
resolution, rustc integration, macro expansion, or proof of public API usage.
|
|
Parse errors are reported instead of ignored; selected-file mode is used when
|
|
`--path` points at a Rust source file under a crate's source, test, or bench
|
|
root.
|
|
- Prefer targeted reductions: remove dead code, split large files, move symbols
|
|
across modules, then reduce per-function complexity.
|