Churnloom
Churnloom is a fast codebase-health CLI that weaves together code size, Git churn, lightweight structural complexity, Cargo ownership, and test-only Rust code. It is designed to answer two questions in one run:
- How large is this project, language by language and crate by crate?
- Which files combine enough size, complexity, and recent change to deserve attention?
It combines mature source counting with parallel structural analysis and one batched Git history query, so a report needs no per-file or per-commit subprocesses.
Install
cargo install churnloom --locked
Or install the latest development version from GitHub:
cargo install --git https://github.com/Sekkmer/churnloom
To install from a source checkout:
git clone https://github.com/Sekkmer/churnloom.git
cd churnloom
cargo install --path .
Churnloom requires Rust 1.97.1 or newer and the git and cargo executables when
their respective analyses are available.
Use
Run the default overview on the current repository:
churnloom
Analyze another checkout, show 30 hotspots, and write a stable JSON report:
churnloom ~/git/my-project --top 30
churnloom ~/git/my-project --format json > code-health.json
churnloom ~/git/my-project --format json --json-top 40
Useful controls:
--short-days 7 recent churn window
--long-days 30 longer churn window
--jobs 8 parallel worker limit (default: min(logical CPUs, 8))
--ext .rs analyze one file extension; repeatable
--include-prefix PATH analyze only matching repository-relative prefixes
--exclude-prefix PATH omit matching repository-relative prefixes
--exclude PATTERN add a gitignore-style exclusion; repeatable
--include-generated include recognized generated sources
--all-files ignore VCS/dot ignore rules and include hidden files
--no-cargo produce project/language/hotspot data without Cargo metadata
--top 0 print every ranked file
--json-top 40 emit only 40 ranked files in JSON (0 emits every file)
--show-daily print the long window's per-day throughput
The compatibility spellings --days-short and --days-long remain accepted.
Window sizes are calendar-day counts, so a seven-day report never claims eight
active days even when the current time crosses the original commit timestamp cutoff.
The text report contains project totals, short/long throughput, language totals, Cargo crate totals, and ranked files. JSON includes every file by default and the full Cargo test breakdown for automation.
Library integration
Churnloom can be embedded in another Rust tool without invoking the CLI:
[]
= "0.1"
Then configure an analysis and consume the structured report:
use ;
The library call does not write to standard output. Cargo and Git failures that do not
prevent source analysis are returned in report.warnings; invalid options and file
discovery failures return an error. See examples/library.rs for a runnable example.
What it measures
Lines of code
Churnloom embeds tokei as a library. This keeps language detection, nested-comment handling, embedded-language counting, ignore behavior, and parallel traversal consistent with a mature LOC counter without spawning one process per scope.
Project and language totals are tokei-like and include recognized documentation and configuration languages. Hotspot ranking is intentionally narrower: Rust, Python, shell, JavaScript/TypeScript, C/C++, and common shader source extensions. This keeps a large Markdown plan or JSON manifest visible in size totals without calling it a code modularization hotspot.
Cargo ownership and test-only code
cargo metadata --no-deps supplies workspace membership and target roots. Every
recognized source file is assigned to the deepest containing workspace package, so
nested packages do not leak into parents. Each crate is split into:
- production targets and
src/code; - inline unit-test code (
#[cfg(test)],#[test], and#[bench]items); - integration-test targets and
tests/; benches/,examples/, and build scripts;- other recognized code/configuration under the package root.
Inline test measurement parses Rust with syn, finds top-level test-only spans, and
counts those spans with tokei's Rust parser. A condition such as
cfg(any(test, feature = "fixture")) is not called test-only because it can ship in a
non-test build. A condition such as cfg(all(test, unix)) is test-only.
Git churn and throughput
One git log --numstat --find-renames pass covers the long window. Churnloom derives
the short window from commit timestamps in that same stream and filters it to current,
analyzed files. Binary changes are ignored. Reports include additions, deletions,
changed lines, commits touching eligible code, active days, and average changed lines
per calendar day.
Hotspot score
The default formula is:
complexity × (1 + 0.9 × norm(short churn) + 0.35 × norm(long churn))
+ 0.25 × norm(context cost)
Structural complexity combines control-flow tokens, maximum brace depth, longest function, and control density. Context cost combines code LOC and longest-function length. These are triage signals, not a compiler-grade cyclomatic-complexity proof.
Architecture
The implementation keeps each source of truth isolated:
CLI/library → discovery/tokei ─┬→ Cargo ownership + test classification
├→ Git churn/throughput
└→ structural metrics
↓
scoring → report
The main performance choices are parallel file discovery/counting inside tokei, parallel per-file Rust/structure analysis with Rayon, a single Cargo metadata call, and a single Git history process. No file or commit is queried through a per-item subprocess.
Limitations
- Macro-generated code has no source span to classify and is measured at its checked-in call site only.
- Out-of-line modules declared behind
#[cfg(test)]are classified by their Cargo path; the declaration line is recognized, but arbitrary module resolution is not emulated. - Churn covers committed history. LOC always describes the current working tree.
- The brace/function metrics are deliberately fast heuristics and may count syntax in unusual strings or macros.
Development
cargo fmt --all --check
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo rustdoc --lib -- -D missing-docs
cargo deny check
cargo build --release
These are the same quality gates enforced in CI.
License
Licensed under either of:
at your option.