JeanFrancoisGagne/crapkit

crapkit scores every function in your repo on complexity times uncovered risk, ranks the
worst ones by how often the file changes, and blocks commits that add more. It reads
Python, TypeScript, TSX, JavaScript, Swift, Go, Rust, shell, PowerShell, C and C++,
Objective-C, Vue, Java and Zig through lizard, and
joins per-function branch coverage from the istanbul or coverage.py artifact your own test
command already writes. JSON commands use sorted keys and a versioned schema for
scripts, coding agents and the optional MCP server.
The name is not ours: C.R.A.P. (Change Risk Anti-Patterns) was coined for crap4j by
Alberto Savoia and Bob Evans in 2007.
ccn is the smaller of standard and modified cyclomatic complexity, both read off one
lizard pass. cov is branch coverage inside the function's span; with no branches it
falls back to statement coverage, and with no statements to invoked-or-not, so a
half-executed straight-line function never reads as fully covered.
**Above the ceiling, coverage cannot save you. Decompose.** At the default ceiling of 6, a
function at ccn 7 with 100% coverage still scores 7 and still fails the gate. The only
move that clears it is splitting the function.
**Why 6 and not 30.** crap4j's conventional threshold of 30 is a CRAP score: it lets an
untested ccn 5 through (25 + 5 = 30) and a fully covered ccn 30 too. crapkit's default
is a complexity ceiling, because coverage can at best collapse CRAP to ccn, and a
function you cannot cover past ccn 6 is one you decompose. Set target = 30 in
crapkit.toml if you want the crap4j number. A repo with existing debt does not need to:
ratchet seed marks today's over-ceiling functions at today's score, the gate then judges
only the functions a change touches, and marks may only fall, so adoption never starts with
a wall of red. Next to crap4py, radon, xenon, wily and SonarQube:
docs/comparison.md.
crapkit scores **git-tracked files only**. Source you have not git added is invisible to
it; init and verify name the first three such files they find.
| Start with | When |
|---|---|
| Install and the 60-second start | You want the first score in an existing Git repository. |
| Python or TypeScript quickstart | You want a worked example from setup through a passing verify. |
| Adoption | You need to choose scopes, wire tests or introduce a ratchet to existing debt. |
| Upgrading | You already have saved runs, ratchet marks or an installed plugin. |
| Subcommands and JSON/MCP reference | You are scripting commands or connecting a coding agent. |
---
The 60-second start
Not a Python repo? uvx crapkit init runs the same commands and adds nothing to your
manifest: see A repo that is not Python. A Python repo
skips uvx and installs crapkit as above, or with uv tool install or pipx install; that
section says why. pip stops with externally-managed-environment? See
When pip refuses.
coverage measures a commit, so a fresh git init repo needs its first commit before
it. Until then it exits 4 and says so:
init detects pytest, Vitest and Jest from the repository's own files. Review the
generated config before running its commands. When detection leaves a commented
lane, fill it in using the lane recipes.
Commit the adoption files, then run crapkit verify to establish a passing verdict.
Install the commit gate when the config and ratchet are ready.
Each step prints the next one: init names coverage, coverage names worklist,
worklist names ratchet seed, and ratchet seed names the commit and verify.
coverage scores, worklist ranks:
risk 14.0 is ccn times a churn weight of one: a one-commit repo has no spread of commits
to weight, so each commit counts once and the ranking is complexity order until the
history grows (Risk). crap 38.5 and cov 50% are the
score and the coverage behind it.
ratchet seed signs today's debt at today's score. From then on marks only ever fall, so
the repo can get better and never worse while you burn it down.
**One thing stops most first runs: the coverage plugin.** init writes a lane that shells
out to your own test runner, and the runner needs its coverage package installed:
pytest-cov for pytest, @vitest/coverage-v8 (pinned to your vitest major) for vitest.
Without it the lane produces no artifact and coverage exits 5 quoting the runner's own
error. A pytest lane also needs coverage.py 7.13.1 or newer, which writes the function
start lines crapkit reads; an older one fails the lane at exit 5. For pytest, init probes the python its lane will run and prints the install
command when pytest_cov is missing; pip install "crapkit[py]" pulls the plugin
alongside crapkit when the two share a venv. On a Windows PATH holding only the py