cstat/cstat-agent-use.md

# 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

Start with the focused commands that answer the current cleanup question:

```sh
cstat loc --json --path <project_root>
cstat symbols --json --path <project_root>
cstat deps --json --path <project_root>
cstat dead-code --json --path <project_root>
cstat test-reachability --json --path <project_root>
```

The stale `summary`, `report`, and `advanced` entry points have been removed.
Use focused root commands directly.

## 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 branching --json --path .` — per-function decision/path complexity.
- `cstat signature --json --path .` — per-function API boundary complexity.
- `cstat span --json --path .` — per-function implementation span metrics.


## Cleanup workflow

1. Run the focused `cstat` commands that match the cleanup target.
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 the same focused `cstat` commands 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.