Skip to Content
Code Scanning

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 .

The xgrep analytics dashboard: a hotspots table ranking files by churn × complexity, the code x-ray naming the function that makes the top file hot, the churn × complexity scatter, the commit-size histogram, single-owner continuity, and the validation notes

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.

The security half of the analytics dashboard: security hotspots, the taint-proven reachability breakdown with the reachable findings listed, severity and category distributions, the OWASP Top 10 coverage scoreboard and the top CWEs

Two classification tables come with it:

  • OWASP Top 10 — a coverage scoreboard across all ten categories, marked where this scan's findings landed. --owasp-edition picks 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 it

Options

FlagEffect
--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)
--jsonemit 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: reaching

A 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 peak

The 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:

ScopeRunsMeaning
reachingtests that can link a tracked packagethe full-suite number, cheaply (default)
allevery test packagethe same number, the slow way
selfthe tracked packages' own testsa 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

On this page