Code-risk analytics
See where a codebase's risk actually concentrates — the churn × complexity hotspots worth refactoring first, the functions driving them, and how your scan findings land on top of that picture.
A scan tells you what is wrong right now. xgrep analytics tells you where the
trouble keeps coming from — the files that are both changed constantly and hard
to change safely, which is where defects concentrate and where a refactor buys the
most.
It reads two things you already have: your git history and the complexity of the code itself. No scanning, no network, no configuration.
xgrep analytics .
Start here: the hotspot
The first table is the answer to "what should we refactor first?". A file high on
both axes — changed often and structurally complex — is where defects cluster
and where every future change is expensive. Those are marked ● hotspot.
peakCCN is the cyclomatic complexity of the file's most complex function, so a
high number means the complexity is concentrated rather than spread thin.
Code X-ray then takes the hot files apart and names the functions carrying
the churn and the complexity. That is what turns "payments.py is a problem" into a
refactor you can actually schedule: it is charge, 27 lines, complexity 6, touched
in 15 of the last commits.
The rest of the picture
Churn × complexity plots the whole codebase into the plane, so you can see whether risk is concentrated in a few files or smeared across all of them — a different problem with a different fix.
Trend tracks per-file complexity across releases, so you can tell a file that has always been gnarly from one that is getting worse.
Coupling finds files that keep changing together without obviously belonging together. That is usually a hidden dependency, and it is what makes an innocuous change break something across the repo.
Commit size is a log-scaled histogram of lines changed. The median is rarely interesting; the tail is — the giant commits are the ones review did not really catch.
Continuity shows single-owner files. This is bus-factor risk, and it is about coverage and continuity, never individual output.
Validation says whether the ranking is trustworthy for this repository — enough history, no suspect paths dominating — so a thin result reads as thin rather than as a verdict.
Your findings, on the same map
When a previous xgrep scan left its findings cache, analytics crosses the
security picture with the maintenance one — which files carry findings and churn,
how much of the finding set is taint-proven rather than pattern-only, and where the
severity sits.

Two classification tables come with it:
- OWASP Top 10 — a coverage scoreboard across all ten categories, marked where
this scan's findings landed.
--owasp-editionpicks the 2021 or 2025 edition (2025 by default). - Top CWEs — the most frequent weakness types by finding count.
Both are also available at the end of an ordinary scan via
xgrep scan --owasp / --cwe,
and in --json under security.owasp / security.cwe.
xgrep scan . # findings, cached
xgrep analytics . # the maintenance picture, with those findings on itOptions
| Flag | Effect |
|---|---|
--window <when> | analysis window, e.g. "12 months ago", "6 weeks ago" (default 12 months ago) |
--top <n> | how many hotspots to rank, blame, and trend (default 30) |
--coverage <file> | add an escape-risk axis from a coverage report (Cobertura XML / lcov.info / coverage-final.json / a Go coverprofile) |
--owasp-edition <year> | OWASP Top 10 edition for the coverage scoreboard: 2021 or 2025 (default 2025) |
--json | emit the full report as JSON for further processing |
xgrep analytics is local-only: it prints the dashboard and uploads nothing. To
send the maintenance-risk stream to Mondoo Platform alongside your findings, use
xgrep scan --analytics or xgrep ci --analytics, which report on the same asset
and under the same conditions as the security findings.
Settings a repository keeps
Anything you would otherwise re-type on every run can live in
.xgrep/config.yml, committed alongside the code, so your run and your CI job
measure the same thing:
version: 1
analytics:
window: '12 months ago'
top: 30
track:
- ./...
ledger: metrics/analytics.jsonl
coverage:
file: .xgrep/coverage/module.cover
scope: reachingA flag always wins over the file, and the file always wins over the built-in default. A missing file means the defaults, silently; a file that will not parse is an error, because a project that wrote one meant it.
Tracking coverage over time
analytics.track names the packages worth watching. Entries are repo-relative
paths, and an entry ending in /... matches that directory and everything
beneath it, the same spelling go list uses — ./... is the whole module. A
list that has to be edited every time someone adds a package is a list that goes
stale.
Each entry is one package and carries one row. A file belongs to the package whose directory holds it, not to every ancestor, so the rows never overlap and can be read as parts of a whole.
Packages with nothing to instrument are dropped rather than recorded at 0%: a
directory of tests only, and one whose non-test files are all machine-generated.
On this repository ./... covers 133 packages and 54 are dropped that way,
leaving 79. A pattern matching no package at all is an error, as is naming a
package outright that has nothing to measure — both mean the config asks for
something the repository cannot give, and tracking less than was asked for is
how a series quietly stops covering what someone thinks it covers.
Three commands turn that into a series:
xgrep analytics coverage # measure, writing analytics.coverage.file
xgrep analytics diff-coverage # coverage of the lines THIS change added
xgrep analytics --record # append one row per tracked package to the ledger
xgrep analytics regressions # compare the newest rows against the series peakThe ledger is append-only JSONL: a row per package per run, carrying the covered
and total statement counts as well as the fraction, so a change in the
DENOMINATOR is visible instead of hidden inside a ratio. regressions reads only
the committed file — no scan, no test run — which makes it cheap enough to gate a
pull request. It exits non-zero when a tracked number went backwards.
Recording and gating are separate commands on purpose: the recorder is routinely pointed at one package while iterating, and a partial snapshot must not read as a regression.
regressions compares against the peak of each package's comparable rows,
not the row before it. A predecessor comparison leaves a hole: a series can fall
by less than the noise floor on every run and arrive anywhere, having never once
tripped. A peak cannot be walked down that way.
That makes an intentional drop fail until it is acknowledged, which is what
metrics/accepted-regressions.jsonl is for:
{
"pkg": "pkg/core",
"metric": "coverage",
"from": 0.8173,
"to": 0.8109,
"reason": "deleted the legacy evaluator and the tests that only covered it"
}A waiver names the exact drop it accepts, so it expires the moment the number
moves again — it can acknowledge a known regression and can never mask the next
one. A waiver without a reason is rejected.
Coverage of what you just changed
A package figure is a lagging aggregate, and it has a blind spot a gate on it cannot see: a change can ship untested code while the total goes up. Add 1,000 statements with 900 covered and a package moves from 81.73% to 81.84%. The number improves, and 100 new untested statements went out with it.
$ xgrep analytics diff-coverage --base origin/main
pkg/core/ast_notinside_stmt.go 34/40 uncovered: 36-37,70-71,86-87
pkg/core/eval.go 134/179 uncovered: 12212-12213,12239-12246,…
diff coverage vs origin/main: 168/219 changed lines covered (76.7%)The diff is three-dot (base...HEAD), so it is your change's own lines and not
everything that has landed on the base branch since you left it.
Only instrumented lines count. A changed line that is a comment, an import, a
const or a bare brace sits in no coverage block, and no test could cover it —
counting it would make the metric impossible to satisfy. A change made entirely
of those reports "nothing to report" rather than 0%.
Pass --min (or set analytics.coverage.diff_min) to fail below a threshold.
Without it the command reports and exits zero.
Measuring only the tests that can reach the code
xgrep analytics coverage runs your test suite with coverage instrumentation
limited to the tracked packages, and by default runs only the test packages whose
test binary LINKS one of them. The rest are skipped, and skipping them cannot
change the result: a test binary that does not link the package being measured
has no way to execute a statement in it.
How much that prunes depends entirely on how much you track. Tracking
pkg/core alone drops 58 of 121 test packages for an identical number; tracking
./... prunes nothing, because every test package links something. The setting
earns its keep on a subset, and costs nothing when it does not.
Use --dry-run to see the split before committing to a run:
$ xgrep analytics coverage --dry-run
scope reaching: instrumenting 2 package(s)
go.mondoo.com/xgrep/pkg/core
go.mondoo.com/xgrep/pkg/core/ghactions
would run 63 test package(s); pruned 58 that cannot link a target--scope (or analytics.coverage.scope) chooses what runs:
| Scope | Runs | Meaning |
|---|---|---|
reaching | tests that can link a tracked package | the full-suite number, cheaply (default) |
all | every test package | the same number, the slow way |
self | the tracked packages' own tests | a different, lower number: it excludes every caller |
What a coverage percentage here does not tell you
Go measures statement coverage, not branch coverage, and has no native way to
do otherwise. A line like if a && b counts as covered once it has executed,
whichever way the condition went. A statement-coverage figure is therefore a
weaker claim than a branch-coverage figure of the same number would be, and
"covered" never means "every path through this line was taken".
The scope is recorded with each ledger row, and rows taken at different scopes are never compared. That matters more than it sounds: a coverage file records what was instrumented and what executed, never which test binaries were invoked, so nothing else in the row can tell two scopes apart. Without it, switching how you measure reads as the code getting worse.
This command runs your test suite, so point it only at a tree you trust. If your
coverage does not come from go test, produce the file with your own tooling and
name it in analytics.coverage.file — xgrep reads that file and never executes
anything to obtain it.
Last updated on
AI risk
xgrep's AI risk rules trace untrusted data into and out of LLM calls — request input reaching a system prompt, model output reaching SQL, HTML, code execution or a deserializer, model-chosen tool arguments reaching a shell, SQL, files or the network, unpinned and pickled models, and risky MCP server configuration — mapped to the OWASP Top 10 for LLM Applications.
Supported languages
Languages with tree-sitter AST matching, and the generic/text files matched with regex patterns.