Code health: health, risk · repowise docs

repowise health scores every file on defect risk, maintainability and performance; repowise risk ranks a commit or diff range against recent commits.

`repowise health`

Compute per-file code-health scores from deterministic markers (McCabe complexity, nesting, brain methods, LCOM4 cohesion, god classes, native clone detection, untested hotspots, coverage gradient, git-behavioural risk, and static performance risk), surfaced as three signals: defect risk, maintainability, and performance. Zero LLM calls, just pure Python over tree-sitter + git data.

By default it reads the analysis the last init or update stored, the same rows MCP and the web UI serve, writes nothing, and returns in seconds. --recompute analyzes the working tree in-process instead, and is the only option outside an indexed repo. When a listed finding or plan sits on a language whose layer is still in preview, the report prints one line with the measurement behind it.

repowise health [PATH] [OPTIONS]

Parameter	Type	Default	Description
`--file`	string	—	Deep-dive a single file (relative path)
`--module`	string	—	Restrict the report to files under this path prefix
`--scope`	string	all	Which files every figure describes: all or production
`--counts`	string	everything	What the score counts: everything or code_shape
`--refactoring-targets`	boolean	false	Print the refactoring queue the index stored, in the order MCP and the web UI serve it
`--plan`	string	—	Print one stored refactoring plan as the recipe an agent applies: preconditions, steps and checks (JSON with --format json)
`--recompute`	boolean	false	Analyze the working tree in-process instead of reading the stored analysis. A whole-repo table run writes the result back to the index
`--generate-code`	string	—	Generate an actual refactoring patch for one target (file.py::Symbol). The only health flag that calls an LLM; needs a configured provider.
`--trend`	boolean	false	Print the last 10 snapshots + declining / predicted-decline alerts
`--badge`	boolean	false	Print a ready-to-paste health badge (Markdown) for this repo's README
`--score`	string	—	Score these files as they are on disk (repeatable), before an update or a PR. Structure comes from the bytes; history, coverage, test pairing and dependents from the index. With no index, the code-shape reading. --format json gives files and score_change
`--against`	string	—	With --score: also score the files at this revision and print before, after and the change, plus the nloc-weighted average at that revision
`--format`	string	table	Output: table, json, md
`--repo`	string	—	In workspace mode, target a specific repo
`--no-workspace`	boolean	false	Force single-repo mode
`--verbose / -v`	boolean	false	Show debug logs from the pipeline

repowise health                                # KPIs + lowest-scoring files
repowise health --file src/api/server.py       # one file in detail
repowise health --module src/api               # restrict to a directory
repowise health --refactoring-targets          # the stored refactoring queue
repowise health --plan <id>                    # one plan as an agent recipe
repowise health --recompute                    # analyze the working tree now
repowise health --generate-code src/api/server.py::handler   # LLM patch for one target
repowise health --trend                        # snapshot history + alerts
repowise health --scope production             # skip test files
repowise health --counts code_shape            # drop the git-derived half
repowise health --score src/app.py --against origin/main   # live score, before and after
repowise health --format json | jq .kpis       # machine-readable

To gate a pull request on the findings it introduces, use repowise health check.

What the headline number is counting

Two flags change the meaning of the score rather than the set of rows printed, so they are worth understanding before you quote a figure at anyone.

--scope picks the files every figure describes. all is the default and includes tests. production drops them. Test files tend to score higher than the code they exercise, so narrowing to production lowers the repo average without a single new defect having been found. That is the point of the flag: the all number is flattered by a large test suite, and production tells you what the shipped code looks like on its own.

--counts picks which half of the deduction is applied. Roughly half of a file's deduction comes from git-derived markers: churn, co-change, ownership, prior fixes. Those rise as a file is worked on, which is correct for predicting defects and useless for answering "is my code getting better". everything is the default and is the calibrated score, the one the defect-risk signal is built around. code_shape subtracts the history half and reports the code alone.

Both halves are stored per file, so code_shape is a subtraction rather than a rescore; it costs nothing. Files indexed before the split was recorded have no stored structure half, and they are dropped from the code_shape reading and counted as unmeasured rather than printed as a confident 10.0.

Neither flag applies to --trend. The trend reads stored snapshots, which carry the calibrated score only, and the command says so instead of printing a projected headline over unprojected history.

Coverage is ingested separately with repowise coverage add <report>, and repowise health automatically folds in whatever coverage you have already ingested, no flag needed. coverage add also builds a per-test test-to-code map when the report carries contexts (a coverage.py .coverage recorded with pytest --cov=<package> --cov-context=test, which needs pytest-cov).

repowise init and repowise update populate the health tables automatically, no separate step needed. repowise status prints a one-line summary:

Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: payments/processor.ts)

Coverage markers (untested_hotspot, coverage_gap, coverage_gradient) only fire once you've ingested a report with repowise coverage add. Per-file marker overrides live in .repowise/health-rules.json. --refactoring-targets emits structured, graph-aware fix plans. See Refactoring intelligence.

`repowise risk`

Just-in-time change-risk scoring for a commit or diff range. No LLM calls, and it works without repowise init (pure git + learned constants). With no revision it scores your uncommitted work, or HEAD when the tree is clean; pass a base..head range (or base...head, from the merge-base) to score a whole branch or PR as one change. With --fail-above-percentile or a markdown / github format and no revision, it scores the CI change against its target branch.

The output opens with size and spread: the change's percentile among the repo's own recent commits, sampled live, labelled as diff size and not a bug predictor. The touched files' bug-fix record follows. The 0 to 10 model score is shown as a secondary, corpus-anchored number. The CI markdown and get_change_risk lead the same way.

Size and spread: 82nd percentile of recent commits (diff size, not a bug predictor)

repowise risk [REVSPEC] [OPTIONS]

Parameter	Type	Default	Description
`--path`	string	—	Path to the git repository (default: current directory)
`--ext`	string	—	Comma-separated file suffixes to count (e.g. .py or .ts,.tsx)
`--baseline`	number	200	Recent commits to sample for the repo-relative percentile. 0 shows only the absolute calibrated band.
`--exclude / -x`	string	—	Gitignore-style pattern to exclude. Repeatable; also applies to the baseline.
`--fail-above-percentile`	number	—	CI gate: exit 1 when the change ranks above this percentile of recent commits (never the 0 to 10 score); exit 2 when it cannot be ranked.
`--format`	string	table	Output: table, json, markdown, github (annotations plus a job summary)
`--full`	boolean	false	Emit the complete tool payload as JSON (implies --format json)

repowise risk                 # score uncommitted work, or HEAD
repowise risk main..HEAD      # score a branch / PR range as one change
repowise risk --ext .ts,.tsx  # restrict to specific suffixes
repowise risk --fail-above-percentile 95 --format github   # CI gate

Use it in a pre-push hook or CI to flag unusual changes before review. For agentic workflows, get_risk exposes the same signals per file plus PR blast-radius analysis.

`repowise risk --target`: what history says about these files

A second mode, same command. Instead of scoring a change, --target asks what the repo's history says about touching specific files: bug-fix pressure, churn trend, dependents, co-change partners, ownership. This reads the index (the repo must be indexed), unlike the REVSPEC mode above which is pure git. It's a thin CLI adapter over the same get_risk MCP tool.

repowise risk --target PATH [--target PATH ...] [--changed-file PATH ...] [OPTIONS]

Parameter	Type	Default	Description
`--target / -t`	string	—	Score what history says about this file. Repeatable.
`--changed-file`	string	—	With --target: PR mode. The response leads with a directive naming what the change may break, which co-changes and tests are missing, and what to run. Repeatable.
`--format`	string	table	Output: table or json
`--full`	boolean	false	Emit the complete tool payload as JSON (implies --format json)

repowise risk --target src/api/auth.py                    # one file's history
repowise risk -t src/api/auth.py -t src/api/routes.py     # several files
repowise risk -t src/api/auth.py --changed-file src/api/auth.py --changed-file src/api/routes.py
                                                             # PR mode: directive first

PR mode (--changed-file) leads with a directive: what the change may break, missing co-changes, files without tests, and which tests to run. Each --target card shows hotspot score, dependents, ownership, bug-fix history, co-change partners, and security signals where present.