fallow: codebase intelligence for TypeScript and JavaScript

Analyze function complexity and file-level health across your codebase. By default, fallow reports all standard health sections: health score, complexity findings, file health scores, hotspot analysis, and refactoring targets. Coverage layers are opt-in: static reachability via --coverage-gaps, exact CRAP scoring via --coverage, and runtime production evidence via --runtime-coverage. Angular templates are scanned alongside JavaScript and TypeScript functions: external .html files referenced via templateUrl and inline @Component({ template: \…` })literals both contribute synthetic<template> findings when the template uses control-flow blocks (@if, @for, @switch, @case, @defer (when …), @let), legacy structural directives (*ngIf, *ngFor), or expression-bound attributes ([x], (x)). Inline-template findings anchor at the @Componentdecorator line and are suppressible with// fallow-ignore-next-line complexitydirectly above the decorator; external-template findings carry an HTML comment action and are suppressible with<!— fallow-ignore-file complexity —>` at the top of the template. Angular components whose class AND template both contribute complexity also emit a synthetic <component> rollup finding. The rollup’s cyclomatic and cognitive totals are worst_class_method + template, so a component whose class scores moderately (3/4) and whose template scores moderately (6/9) surfaces as one heavy finding (cyc 9, cog 13) rather than two scattered medium findings. The JSON component_rollup payload carries the pre-summation breakdown (class_worst_function, class_cyclomatic/class_cognitive, template_path, template_cyclomatic/template_cognitive, plus a component identifier derived from the .ts owner’s file stem). The rollup is strictly additive: per-function and per-<template> entries stay where they are, so existing suppression sites continue to work. The rollup is anchored at the worst class method’s line, so a // fallow-ignore-next-line complexity placed above that method hides both the function finding and the rollup. Ranking and --targets use the rolled-up numbers so a template-heavy component wins selection over scattered same-magnitude function findings.

All sections are enabled by default, including the health score. Use section flags to select individual sections. Add --top N to limit results.

fallow health

Options

Thresholds

Flag	Description
`--max-cyclomatic <N>`	Maximum cyclomatic complexity before reporting (default: 20)
`--max-cognitive <N>`	Maximum cognitive complexity before reporting (default: 15)
`--max-crap <N>`	Maximum CRAP score before reporting (default: 30.0). Functions meeting or exceeding this score appear alongside complexity findings. Pair with `--coverage` for accurate per-function CRAP; without it fallow estimates coverage from the module graph.
`--effort <LEVEL>`	Filter refactoring targets by effort level: `low`, `medium`, or `high`. Only targets at or below the specified effort are shown. Implies `--targets`.

Use health.thresholdOverrides[] in config for documented local ceilings on known legacy functions. Overrides match files globs and optional exact functions, can set maxCyclomatic, maxCognitive, and maxCrap, and can include a reason. They keep exceptions visible in output instead of hiding them with suppression comments.

Output

Flag	Description
`-f, --format <FORMAT>`	Output format: `human` (default), `json`, `sarif`, `compact`, `markdown`, `codeclimate`, `gitlab-codequality`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab`, `badge`
`--top <N>`	Show only the top N results per section (findings, file scores, hotspots, targets)
`--sort <METRIC>`	Sort complexity findings by: `cyclomatic` (default), `cognitive`, `lines`, `severity`
`--explain`	Add metric explanations. In human format, prints a `Description:` line under each section header. In JSON format, adds a `_meta` object with metric descriptions and docs links.
`--summary`	Print a one-line summary of counts at the end of the run. In JSON format, adds a `summary` counts object.

Section selection

By default, all standard sections are included. Use these flags to select individual sections:

Flag	Description
`--complexity`	Show only complexity findings (functions exceeding thresholds).
`--complexity-breakdown`	Add a per-decision-point `contributions[]` array to each complexity finding in `--format json`, explaining which constructs drove the score. Each entry names the construct (`if`, `else-if`, `ternary`, `&&` / `\|\|` / `??`, loop, `case`, `catch`, `optional-chain`, …) and carries its source line, the metric it adds to (`cyclomatic` or `cognitive`), its weight, and the nesting depth. Off by default to keep CLI/CI output lean; used by the VS Code inline editor breakdown and the MCP `check_health` tool.
`--css`	Add a structural CSS analytics section (`css_analytics` in JSON, `CSS health` in human, `## CSS Health` in markdown). Surfaces codebase-scale CSS slop that per-rule linters do not aggregate: specificity hotspots (id selectors, deep compound selectors), `!important` density, over-complex selectors, deep nesting, empty rules, and design-token sprawl (the count of distinct color, `font-size`, `z-index`, `box-shadow`, `border-radius`, and `line-height` values across the whole codebase). Cleanup candidates include custom properties (`--x`) and `@keyframes` defined but never referenced, dead Vue `<style scoped>` classes, unused `@property` / `@layer` at-rules, Tailwind arbitrary-value bypasses like `w-[13px]`, Tailwind v4 `@theme` design tokens (`unused_theme_tokens`), unused `@font-face` families (`unused_font_faces`), class typo candidates (`unresolved_class_references`), undefined animations (`undefined_keyframes`), and mixed font-size units (`font_size_unit_mix`). Each CSS analytics candidate carries a read-only verification step; a token can still be used from JavaScript, inline HTML, Tailwind plugins, or external templates, so the descriptive analytics remain evidence. Rule-backed styling issues are emitted separately as first-class `styling_findings` with configured severity and actions. Opt-in because it reads project stylesheets and cross-checks source files. Standard CSS and Vue/Svelte/Astro standard `<style>` blocks are parsed structurally; Sass/Less sources are scanned only where fallow can stay conservative without expanding preprocessor semantics. Also derives a descriptive `styling_health` A-F grade (CSS quality, scored separately from the code health score, never gating) that weights design-token drift over byte-identical repetition; see Styling health grade.
`--file-scores`	Show only per-file health scores. Requires the full analysis pipeline (graph + dead code detection). File scores are sorted by risk-aware triage concern: lower maintainability index and higher CRAP risk first. `--sort` and `--baseline` apply to complexity findings only, not file scores.
`--hotspots`	Show only hotspot analysis: files that are both complex and frequently changing. Combines git churn history with complexity data. Uses git history; outside a git repository the section degrades to empty (with a stderr note) and exits 0 instead of erroring, so combined-mode `--format json` always emits a single document.
`--targets`	Show only refactoring targets: ranked recommendations with priority scores, effort estimates, contributing factors, and evidence for AI agents. Each target’s JSON can include `direct_callers[]` (direct importers with the symbols they import) and `clone_siblings[]` (duplicate-code siblings with stable `dup:<8hex>` fingerprints, ready for `fallow dupes --trace`); both arrays are omitted when empty. Human output adds `importers:` and `clones:` lines only when that evidence is present.
`--score`	Show only the project health score (0-100) with letter grade (A/B/C/D/F). The score is included by default when no section flags are set. As of v2.55.0, plain `--score` skips the churn-backed hotspot penalty so the score doesn’t run a `git log` shell-out per invocation. Pass `--hotspots` (or `--targets` with `--score`) to include the hotspot penalty; snapshot (`--save-snapshot`) and trend (`--trend`) flows still trigger hotspot vital signs so saved data stays complete.
`--coverage-gaps`	Show runtime files and exports that no test dependency path reaches. Opt-in (default off). Configure severity via the `coverage-gaps` rule.
`--coverage <PATH>`	Path to Istanbul-format coverage data (`coverage-final.json`) for accurate per-function CRAP scores. Produced by Jest, Vitest, c8, nyc. When provided, uses the canonical formula `CC^2 * (1-cov/100)^3 + CC` instead of the static binary model. Relative paths resolve against `--root`. Falls back to `FALLOW_COVERAGE`, then `health.coverage`, then auto-detection.
`--coverage-root <PATH>`	Absolute prefix to strip from file paths in coverage data before prepending the project root. Use when coverage was generated in a different environment (CI runner, Docker), for example `/home/runner/work/myapp`. Falls back to `FALLOW_COVERAGE_ROOT`, then `health.coverageRoot`.
`--runtime-coverage <PATH>`	Merge runtime coverage into the health report. Accepts a V8 coverage directory, a single V8 JSON file, or a single Istanbul coverage map JSON file. A single local capture is free and does not require a license; continuous or multi-capture runtime monitoring requires a valid license or trial.
`--min-invocations-hot <N>`	Threshold for hot-path classification when `--runtime-coverage` is active (default: `100`).
`--min-observation-volume <N>`	Minimum total trace volume before the sidecar may emit high-confidence `safe_to_delete` / `review_required` verdicts. Below this, confidence is capped at `medium` (default: `5000`).
`--low-traffic-threshold <RATIO>`	Fraction of total trace count below which an invoked function is classified `low_traffic` rather than `active` (default: `0.001` = 0.1%).

Multiple section flags can be combined (e.g., --complexity --hotspots). Without any section flags, all sections are included.

Type-aware coupling

Use --type-aware --type-coupling to add advisory public-signature type coupling. It reports exact type edges and cycles without changing the health score.

fallow health --type-aware --type-coupling --format json --quiet

Add repeatable --type-aware-project <PATH> flags when automatic project selection misses a consumer project. Use --type-aware-require complete when partial or unavailable checker evidence must fail CI. See Type-aware TypeScript analysis.

Health score options

Flag	Description
`--min-score <N>`	Fail (exit code 1) only when the health score is below this threshold. Implies `--score`. The authoritative CI quality gate: when set, complexity findings are demoted to informational and the exit code is driven solely by the score, so `--min-score 0` always exits 0. Composes with `--min-severity` (the run fails if either gate trips).
`--min-severity <LEVEL>`	Only exit with an error for findings at or above this severity (`moderate`, `high`, `critical`). Composes with `--min-score`.
`--report-only`	Print the score and findings but never fail CI (always exit 0). Advisory mode for surfacing health in logs without blocking. Mutually exclusive with `--min-score` and `--min-severity`.

Hotspot options

Flag	Description
`--since <DURATION>`	Git history window for hotspot analysis (default: `6m`). Accepts durations (`6m`, `90d`, `1y`, `2w`) or ISO dates (`2025-06-01`). Ignored when `--churn-file` is set (the file is authoritative for the window).
`--min-commits <N>`	Minimum number of commits for a file to be included in hotspot ranking (default: 3).
`--churn-file <PATH>`	Import change history from a `fallow-churn/v1` JSON file instead of `git log`, so hotspots, ownership, and targets work on projects with no git repository (Yandex Arc, Mercurial, Perforce). Resolved relative to `--root`; wins over git when both are present. See Importing churn from a non-git VCS.
`--ownership`	Attach ownership signals to each hotspot entry: bus factor (Avelino truck factor), contributor count, top contributor with stale-days, recent contributors (top-3), `suggested_reviewers`, declared CODEOWNERS owner, `ownership_state`, ownership drift, and unowned-hotspot detection. Human output gains a project-level summary line above the hotspot list. Test paths get a `[test]` tag. Implies `--hotspots`. Uses git history; outside a git repository the hotspot/ownership section degrades to empty.
`--ownership-emails <MODE>`	Privacy mode for author emails: `handle` (default, local-part only with GitHub noreply unwrap and deterministic same-handle disambiguation), `anonymized` (stable `xxh3:` pseudonym), legacy `hash` (same as `anonymized`), or `raw` (full email). Implies `--ownership`. Use `anonymized` in regulated environments where author identities are sensitive. Configure the default via `health.ownership.emailMode` in config.

Scoping

Flag	Description
`-w, --workspace <NAME>`	Scope output to one or more workspace packages while keeping the full cross-workspace graph. Comma-separated values, globs (`apps/`, `@scope/`), and `!`-prefixed negation are supported. Vital signs, health score, hotspots, file scores, findings, and `summary.files_analyzed` are all recomputed against the scoped subset.
`--changed-since <REF>`	Only analyze functions in files changed since the given git ref (e.g., `main`, `HEAD~5`). Also applies to hotspot analysis.
`--group-by <owner\|directory\|package\|section>`	Partition the report into per-group sections. JSON output adds `grouped_by` plus a `groups` array; each group contains its own `vital_signs`, `health_score`, `findings`, `file_scores`, `hotspots`, `large_functions`, and `targets` recomputed against the group’s files. The top-level metrics stay project-wide so consumers that ignore grouping still see the project headline. Human output adds a per-group score / files / hot / p90 summary block (sorted worst-first when `--score`). SARIF tags every result with `properties.group` and CodeClimate adds a top-level `group` field per issue, so GitHub Code Scanning and GitLab Code Quality can partition findings per team / package. Compact, markdown, and badge fall back to ungrouped output with a stderr note pointing at `--format json`.

Snapshots & trends

Flag	Description
`--save-snapshot [PATH]`	Save a vital signs snapshot for trend tracking. Default path: `.fallow/snapshots/<timestamp>.json`. Forces file-scores and hotspot computation for complete metrics.
`--trend`	Compare current metrics against the most recent saved snapshot. Reads from `.fallow/snapshots/` and shows per-metric deltas with directional indicators (improving/declining/stable). Implies `--score`.

--score, --trend, and --save-snapshot also work on bare fallow (all analyses combined). See global flags for details.

Baseline

Flag	Description
`--save-baseline`	Save current complexity findings as a baseline for future comparison
`--baseline`	Compare against a saved baseline and only report new findings. Applies to complexity findings only, not file scores.

Exit codes

The default fallow health (no gate flag) is advisory-by-default for plain visibility but still fails on any finding, for back-compatibility. The gate flags change what drives the exit code:

Invocation	Exit 0 when	Exit 1 when
`fallow health` (no gate flag)	no function exceeds a threshold	any function exceeds a threshold
`fallow health --min-score N`	score >= N (findings are informational)	score < N
`fallow health --min-severity LEVEL`	no finding at or above LEVEL	any finding at or above LEVEL
`fallow health --min-score N --min-severity LEVEL`	score >= N AND no finding at or above LEVEL	score < N OR a finding at or above LEVEL
`fallow health --report-only`	always	never

--report-only cannot be combined with --min-score or --min-severity (exit code 2). The runtime-coverage gate (--runtime-coverage) and coverage-gap gate remain independent explicit opt-ins and are not demoted by --min-score. For a gate on newly-introduced complexity only, use fallow audit --gate new-only.

Maintainability index formula

File scores are ordered by risk-aware triage concern: the larger of low-MI concern and CRAP risk. This keeps files with very high untested complexity near the top even when their Maintainability Index is not the lowest. The per-file maintainability index is a weighted composite score:

fan_out_penalty = min(ln(fan_out + 1) × 4, 15)
MI = 100 - (complexity_density × 30) - (dead_code_ratio × 20) - fan_out_penalty

Clamped to 0–100. Higher is better. Files with zero functions (barrel/re-export files) are excluded by default.

Component	Description	Weight
`complexity_density`	Total cyclomatic complexity / lines of code	×30
`dead_code_ratio`	Fraction of value exports with zero references (0.0–1.0). Type-only exports (interfaces, type aliases) are excluded.	×20
`fan_out_penalty`	Logarithmic scaling of import count, capped at 15 points. Each additional import adds less penalty than the last.	max 15

Additional metrics reported per file (informational, not in the formula):

Metric	Description
`fan_in`	Number of files that import this file
`total_cyclomatic`	Sum of cyclomatic complexity across all functions
`total_cognitive`	Sum of cognitive complexity across all functions
`function_count`	Number of functions in the file
`lines`	Total lines of code
`crap_max`	Highest CRAP score among the file’s functions. Combines cyclomatic complexity with test coverage to estimate untested risk. See CRAP metric for details.
`crap_above_threshold`	Number of functions in the file with a CRAP score at or above the threshold (default: 30).

Hotspot score formula

The hotspot score identifies files that are both complex and frequently changed. These files are the most likely to harbor bugs and slow down development. The score combines git churn with complexity density:

normalized_churn = weighted_commits / max_weighted_commits (0..1)
normalized_complexity = complexity_density / max_density (0..1)
score = normalized_churn × normalized_complexity × 100

Clamped to 0–100. Higher means higher risk. Scores are normalized within the project, so the highest-risk file always scores close to 100.

Component	Description
`weighted_commits`	Recency-weighted commit count using exponential decay with a 90-day half-life. Recent changes contribute more than old ones.
`complexity_density`	Cyclomatic complexity / lines of code. Measures how densely complex the code is.

Per-file hotspot metrics

Each hotspot entry includes:

Metric	Description
`path`	Relative file path
`score`	0–100 hotspot score (higher = higher risk)
`commits`	Raw commit count in the analysis window
`weighted_commits`	Recency-weighted commit count (exponential decay, 90-day half-life)
`lines_added`	Total lines added in the analysis window
`lines_deleted`	Total lines deleted in the analysis window
`complexity_density`	Cyclomatic complexity / lines of code
`fan_in`	Blast radius: number of files importing this file
`trend`	`Accelerating`, `Stable`, or `Cooling`. Shows the direction of recent change activity.

Hotspot summary

The hotspot summary (included in JSON output) provides context about the analysis:

Field	Description
`since`	Display string for the analysis window (e.g., “6 months”)
`min_commits`	Minimum commit threshold used
`files_analyzed`	Files meeting the `min_commits` threshold
`files_excluded`	Files below the `min_commits` threshold
`shallow_clone`	Detection flag. Warns if a shallow clone was detected.

Hotspot analysis uses git history. Outside a git repository the section degrades to empty with a note: hotspot analysis skipped: no git repository found at project root on stderr (suppressed by --quiet); standalone fallow health --hotspots --format json exits 0 with hotspots and hotspot_summary omitted, and combined-mode --format json always emits a single JSON document. Shallow clones may produce incomplete results. Fallow detects this and warns you. For best results, ensure a full clone with git fetch --unshallow.

Ownership analysis

Pass --ownership (alongside or instead of --hotspots) to enrich each hotspot entry with ownership signals derived from git author history and the repository’s CODEOWNERS file. Useful for surfacing knowledge-loss risk, finding unowned high-churn files, and routing review requests.

fallow health --hotspots --ownership
fallow health --hotspots --ownership --ownership-emails anonymized --format json

Project-level summary

Human output prepends a summary line above the hotspot list showing how many hotspots depend on a single recent contributor and the top authors across the set:

● Hotspots (10 files, since 6 months)

  9/10 hotspots depend on a single recent contributor  ·  top authors: alice (6), bob (4)

Per-hotspot ownership fields

Field	Description
`bus_factor`	Avelino truck factor: minimum contributors covering at least 50% of recency-weighted commits. `1` is the canonical “single point of failure” signal.
`contributor_count`	Distinct authors after bot-pattern filtering.
`top_contributor`	Object with `identifier`, `format` (`raw`/`handle`/`anonymized`/`hash`), `share` (0..1), `stale_days`, and `commits` for the highest-share contributor. The `identifier` is rendered per the configured `ownership.emailMode`; do not assume it is an email address.
`recent_contributors`	Up to three additional contributors by share (top-3 excluding the top contributor).
`suggested_reviewers`	Subset of `recent_contributors` whose `stale_days` is below 90. First-class field so AI agents can route “Request review from @X, @Y” without re-filtering. Omitted when empty.
`declared_owner`	The CODEOWNERS-resolved primary owner for this file, when a rule matches.
`ownership_state`	Stable discriminator for ownership routing: `active`, `unowned`, `declared_inactive`, or `drifting`. Declared owners suppress vague git-history drift only when fallow can match them to an active contributor offline.
`unowned`	Tristate: `true` = a CODEOWNERS file exists but no rule matches; `false` = a rule matches; `null` = no CODEOWNERS file was discovered (cannot determine).
`drift`	True when the file’s original author no longer maintains it. Fires only when file age >= 30 days AND the original author’s recency-weighted share is below 10%.
`drift_reason`	Human-readable explanation of the drift, populated only when `drift` is `true`.

Severity in human output

The bus= marker is color-coded proportional to the actual risk:

bus=1 (sole author): red + bold when share is 100% (one person, no co-authors)
bus=1 (at risk): red + bold when bus=1 AND trend is accelerating (active, high-concentration file)
bus=1: yellow for the common case (bus=1 without extreme share or acceleration)
bus=2 / bus=N: dimmed (healthy)

This keeps red reserved for the strongest signals so it stays meaningful on repos where most hotspots are single-contributor.

Test-path tag

Files matching common test conventions (**/__tests__/**, **/__mocks__/**, **/*.test.*, **/*.spec.*, **/test/**, **/tests/**) are intentionally kept in the hotspot ranking (test maintenance IS real work) but tagged with [test] so readers can distinguish them from production code. JSON consumers see an is_test_path: true field.

Ownership-derived JSON actions

When --ownership is enabled, the actions array on hotspot entries gains up to three additional action types so AI agents can act on ownership signals:

Action type	When emitted	Suggested follow-up
`low-bus-factor`	`bus_factor == 1`	Add a second reviewer to the file. The `note` names specific candidate reviewers (from `suggested_reviewers`) when they exist, softens for low-commit files, or is omitted to avoid boilerplate.
`unowned-hotspot`	`unowned == true` (CODEOWNERS exists, no rule matches)	Add a CODEOWNERS entry. The action’s `suggested_pattern` field offers a sensible default (the deepest directory containing the file, e.g. `/src/api/users/`), and a `heuristic: "directory-deepest"` field discriminates the strategy.
`ownership-drift`	`ownership_state == "drifting"` and `drift == true`	Update CODEOWNERS to the new top contributor.

Email privacy

By default, fallow renders author emails as their local-part (e.g. alice@example.com shows as alice). GitHub-style noreply prefixes are unwrapped (12345+alice@users.noreply.github.com shows as alice). Override with --ownership-emails:

Mode	Output	When to use
`handle` (default)	Local-part only, with deterministic domain suffixes for same-handle collisions on the same file	Most projects. Balances readability and privacy.
`anonymized`	`xxh3:<16hex>` non-cryptographic pseudonym	Regulated environments where author identities are sensitive.
`hash`	Same as `anonymized`	Legacy configs and scripts.
`raw`	Full email address	Public OSS repositories where git history is already exposed.

The anonymized/hash mode uses xxh3 for stable pseudonyms across runs but is not a cryptographic primitive: a known list of org emails can be brute-forced into a rainbow table. The intent is to keep raw PII out of CI artifacts (SARIF, code-scanning uploads), not to provide strong privacy.

Configuration

Configure ownership defaults under health.ownership:

{
  "health": {
    "ownership": {
      "botPatterns": ["custom-svc-*", "*\\[bot\\]*"],
      "emailMode": "handle"
    }
  }
}

botPatterns are glob patterns matched against the raw author email. The default list covers *\[bot\]* (escaped brackets, since globset treats [abc] as a character class), dependabot*, renovate*, github-actions*, svc-*, and *-service-account*. *noreply* is intentionally NOT a default: most human GitHub contributors commit from <id>+<handle>@users.noreply.github.com (GitHub’s privacy default), so filtering on noreply would silently exclude the majority of real authors. The actual bot accounts already match via \[bot\].

Ownership signals are computed only when --hotspots runs and a file passes the min_commits threshold (default 3). This gates the analysis on enough history to be meaningful. Squash-merged commits inflate single-author dominance, and shallow clones distort the picture further; fallow warns about both when --ownership is active.

Importing churn from a non-git VCS

--hotspots, --ownership, and --targets read change history from git log. On a project with no git repository (Yandex Arc, Mercurial, Perforce) they would otherwise print note: hotspot analysis skipped: no git repository found and exit 0. --churn-file <PATH> lets you feed history from a normalized JSON file instead. A small wrapper translates your VCS log into the contract; fallow then runs all the same recency-weighting, trend, and ownership logic on the imported events. The file is resolved relative to --root and wins over git when both are present.

fallow health --hotspots --ownership --churn-file churn.json

The `fallow-churn/v1` contract

{
  "schema": "fallow-churn/v1",
  "events": [
    { "path": "src/foo.ts", "timestamp": 1717459200, "author": "dev@corp", "added": 10, "deleted": 5 }
  ]
}

One entry per (commit, file) touched, the natural shape of a <vcs> log --numstat.

Field	Required	Meaning
`path`	yes	Repo-root-relative, forward-slash. Joined to `--root`.
`timestamp`	yes	Commit time, unix seconds UTC (not milliseconds). Drives the recency half-life and the accelerating/stable/cooling trend.
`author`	no	Opaque identity, email recommended. Drives ownership and bus-factor. Absent leaves the event counting toward churn/trend but contributing no author signal.
`added` / `deleted`	yes	Lines changed in that file in that commit. Best-effort: the hotspot score keys on commit-event count, not lines, so imprecise counts still rank correctly; lines feed display only.

Extra fields are ignored, so a wrapper may carry additional metadata (a commit id, a timezone) without breaking.

Producer requirements

fallow’s git path runs git log --numstat --no-merges --no-renames --use-mailmap. A wrapper should reproduce these four behaviors or hotspots and ownership skew:

Omit merge commits. Otherwise the merge author looks like a contributor to every merged file, inflating bus-factor and skewing the trend.
Omit binary-file rows entirely (do not emit 0/0). git skips binary -/- numstat rows.
Renames: emit under the new path only, with the real add/delete count; do not emit a delete-of-old row. (Perforce models a move as delete-old + add-new full-size rows, which would create fake hotspots.)
One row per (commit, file), with timestamp in UTC seconds.

Two more notes:

Author identity is an opaque key. fallow does NOT apply mailmap to imported authors, so emit a single canonical form per person (email preferred). If your VCS commits land under a merge/CI bot identity, add it to health.ownership.botPatterns in config or bus-factor collapses to 1 everywhere.
Validation is strict where the math depends on it. A timestamp more than a year in the future (almost always a millisecond value mistaken for seconds) is rejected with exit 2; an empty events array is valid (no hotspots), not an error; a malformed file is a loud hard error, not a silent skip.

Reference wrapper (Mercurial)

The wrapper translates your VCS log into the contract. This Mercurial example pulls the last six months, excludes merges, and emits one event per file per commit:

# hg-churn.sh: emit fallow-churn/v1 for the last 6 months (no merges).
hg log --no-merges --rev 'date(">6 months ago")' \
  --template '{date|hgdate}\t{author|email}\t{join(files, "\t")}\n' \
| python3 -c '
import json, sys
events = []
for line in sys.stdin:
    cols = line.rstrip("\n").split("\t")
    if len(cols) < 3:
        continue
    ts = int(cols[0].split()[0])   # hgdate is "epoch tzoffset"; take the epoch
    author = cols[1]
    for path in cols[2:]:
        events.append({"path": path, "timestamp": ts, "author": author,
                       "added": 0, "deleted": 0})
print(json.dumps({"schema": "fallow-churn/v1", "events": events}))
' > churn.json

The hg template separates fields with tabs (\t), which never appear in paths or emails. Per-file added/deleted are left 0; fill them in if your VCS exposes line counts cheaply. The hotspot score is driven by commit-event count rather than line totals, so ranking stays correct either way. For Yandex Arc, drive the same shape from arc log; for Perforce, from p4 changes + p4 describe.

Scope

--churn-file powers the churn-backed health signals only: --hotspots, --ownership, and --targets. The diff-based commands stay git-only because they need the base revision’s tree, not just history:

--changed-since line/file filtering already has a file-based equivalent: --diff-file / --diff-stdin accept a unified diff. If your VCS can emit a git-format patch, point those at it.
fallow audit and fallow impact check out the base revision into a temporary git worktree and re-analyze it, which needs real base-tree contents. They require git.

Vital signs

When file-scores are enabled (either explicitly via --file-scores or implicitly via --save-snapshot), the JSON output includes a vital_signs object with high-level codebase health metrics. These metrics provide a single-glance summary of code quality.

Metric	Description
`dead_file_pct`	Percentage of files with zero inbound references
`dead_export_pct`	Percentage of value exports with zero references
`avg_cyclomatic`	Average cyclomatic complexity across all functions
`critical_complexity_pct`	Percentage of functions at or above the critical cyclomatic threshold. Used by health score formula v2.
`p90_cyclomatic`	90th percentile cyclomatic complexity
`duplication_pct`	Percentage of duplicated code. Populated automatically when `--score` is used; null otherwise.
`hotspot_count`	Number of files with a hotspot score >= 50
`hotspot_top_pct_count`	Number of positive-score files in the top 1% of the within-project hotspot ranking
`maintainability_avg`	Average maintainability index across all scored files
`maintainability_low_pct`	Percentage of scored files with maintainability index below 70
`unused_dep_count`	Number of unused dependencies detected
`unused_deps_per_k_files`	Unused dependencies per 1,000 files
`circular_dep_count`	Number of circular dependency cycles detected
`circular_deps_per_k_files`	Circular dependency cycles per 1,000 files
`unit_size_profile`	Per-function risk distribution by LOC (percentage per bin)
`functions_over_60_loc_per_k`	Functions above 60 LOC per 1,000 functions
`unit_interfacing_profile`	Per-function risk distribution by parameter count (percentage per bin)
`p95_fan_in`	95th percentile fan-in across files
`coupling_high_pct`	Percentage of files exceeding the fan-in threshold
`counts`	Raw numerator/denominator counts behind the percentage metrics (e.g. `dead_files`, `total_files`, `dead_exports`, `total_exports`, `unused_deps`, `circular_deps`)

Snapshots

Use --save-snapshot to capture a point-in-time record of your codebase’s vital signs. Snapshots enable trend tracking across builds, sprints, or releases.

# Save snapshot to the default path (.fallow/snapshots/<timestamp>.json)
fallow health --save-snapshot

# Save snapshot to a specific path
fallow health --save-snapshot ./snapshot.json

The --save-snapshot flag forces file-scores and hotspot computation so that all vital signs metrics are available, regardless of which section flags are passed.

Snapshot format

snapshot.json

{
  "snapshot_schema_version": 8,
  "version": "3.9.1",
  "timestamp": "2026-03-25T14:30:00Z",
  "git_sha": "a1b2c3d",
  "git_branch": "main",
  "shallow_clone": false,
  "vital_signs": {
    "dead_file_pct": 4.2,
    "dead_export_pct": 12.8,
    "avg_cyclomatic": 3.1,
    "critical_complexity_pct": 1.2,
    "p90_cyclomatic": 11,
    "duplication_pct": null,
    "hotspot_count": 5,
    "hotspot_top_pct_count": 3,
    "maintainability_avg": 72.4,
    "maintainability_low_pct": 9.1,
    "unused_dep_count": 3,
    "unused_deps_per_k_files": 11.5,
    "circular_dep_count": 1,
    "circular_deps_per_k_files": 3.8,
    "unit_size_profile": {
      "low_risk": 82.1,
      "medium_risk": 11.4,
      "high_risk": 4.3,
      "very_high_risk": 2.2
    },
    "functions_over_60_loc_per_k": 22.0,
    "unit_interfacing_profile": {
      "low_risk": 95.6,
      "medium_risk": 3.8,
      "high_risk": 0.5,
      "very_high_risk": 0.1
    },
    "p95_fan_in": 8,
    "coupling_high_pct": 2.3
  },
  "counts": {
    "dead_files": 11,
    "total_files": 262,
    "dead_exports": 48,
    "total_exports": 375,
    "unused_deps": 3,
    "circular_deps": 1
  }
}

Field	Description
`snapshot_schema_version`	Schema version for forward compatibility (currently v8)
`version`	Fallow version that produced the snapshot
`timestamp`	ISO 8601 timestamp of the snapshot
`git_sha`	Current git commit SHA (if in a git repo)
`git_branch`	Current git branch name
`shallow_clone`	Whether a shallow clone was detected
`vital_signs`	High-level health metrics (see Vital signs)
`counts`	Raw numerators and denominators behind the percentage metrics
`score`	Project health score (0-100). Present in v2+ snapshots.
`grade`	Letter grade (A/B/C/D/F). Present in v2+ snapshots.

Store snapshots in CI artifacts or commit them to your repo to build a history of codebase health over time. Snapshots automatically include the health score and grade.

Examples

# Report functions exceeding default thresholds
fallow health

# Show the 10 most complex functions
fallow health --top 10

# Sort by cognitive complexity
fallow health --top 10 --sort cognitive

# Sort by lines of code
fallow health --top 10 --sort lines

# Project health score with letter grade
fallow health --score

# CI quality gate: fail if score below 70
fallow health --min-score 70

# JSON output with penalty breakdown
fallow health --score --format json

# Per-file health scores
fallow health --file-scores

# Top 20 files by triage concern
fallow health --file-scores --top 20

# JSON output with file scores
fallow health --file-scores --format json

# Identify hotspots (complex + frequently changed)
fallow health --hotspots

# Custom history window and commit threshold
fallow health --hotspots --since 90d --min-commits 5

# Top 10 hotspots in JSON
fallow health --hotspots --top 10 --format json

# Hotspots for a specific workspace
fallow health --hotspots --workspace my-app

# Hotspots using an ISO date
fallow health --hotspots --since 2025-06-01

# Combine with file scores for full picture
fallow health --hotspots --file-scores

# Ranked refactoring recommendations with effort estimates
fallow health --targets

# Only low-effort quick wins
fallow health --targets --effort low

# Top 5 targets
fallow health --targets --top 5

# JSON with evidence for AI agents
fallow health --targets --format json

# Combine with file scores and hotspots
fallow health --targets --file-scores --hotspots

# Save baseline, then only show new targets
fallow health --targets --save-baseline fallow-baselines/health.json
fallow health --targets --baseline fallow-baselines/health.json

# Stricter thresholds
fallow health --max-cyclomatic 10 --max-cognitive 8

# Only check cognitive complexity
fallow health --max-cyclomatic 999 --max-cognitive 10

# Fail when any function has CRAP >= 30 (complex AND poorly tested)
fallow health --max-crap 30 --coverage ./coverage/coverage-final.json

# Effectively disable the CRAP gate for focused cyclomatic runs
fallow health --max-cyclomatic 10 --max-crap 10000

# Scope to a single workspace package
fallow health --workspace my-app

# Only check changed files in a PR
fallow health --changed-since main

# Save current findings as baseline
fallow health --save-baseline

# Only report new findings compared to baseline
fallow health --baseline

# SARIF output for GitHub Code Scanning
fallow health --format sarif

# JSON output for pipelines
fallow health --format json

# Compact output for summaries
fallow health --format compact

# Markdown for PR comments
fallow health --file-scores --format markdown

# Markdown piped to a PR comment
fallow health --file-scores --format markdown | gh pr comment --body-file -

# Save snapshot to default path (.fallow/snapshots/<timestamp>.json)
fallow health --save-snapshot

# Save snapshot to a specific file
fallow health --save-snapshot ./snapshot.json

# CI: save snapshot as a build artifact
fallow health --save-snapshot ./snapshot.json --format json

# Compare current metrics against the most recent snapshot
fallow health --trend

# JSON output with trend deltas
fallow health --trend --format json

# Find runtime code not reached by any test
fallow health --coverage-gaps

# Coverage gaps in JSON
fallow health --coverage-gaps --format json

# Combine with file scores
fallow health --coverage-gaps --file-scores

Example output

$ fallow health --file-scores --top 3

● High complexity functions (3 shown, 24 total)
  CRAP scores are estimated from export references; run `fallow health --coverage <coverage-final.json>` for exact scores.
  src/diff/index.js
    :48 diff
          67 cyclomatic  138 cognitive  290 lines
         420.0 CRAP
    :381 diffElementNodes
          63 cyclomatic  105 cognitive  200 lines
         305.0 CRAP
  src/utils/parser.ts
    :15 parseExpression
          25 cyclomatic   31 cognitive   98 lines
          42.0 CRAP
  Functions exceeding cyclomatic, cognitive, or CRAP thresholds (https://docs.fallow.tools/explanations/health#complexity-metrics)

● File health scores (3 files) · sorted by triage concern

   52.3    src/legacy/handler.ts      risk
            312 LOC    2 fan-in   18 fan-out   45% dead  0.38 density  42.0 risk

   68.4    src/diff/index.js          risk
            847 LOC    3 fan-in   12 fan-out    0% dead  0.89 density  12.0 risk

   75.1    src/utils/parser.ts        structure
            198 LOC    8 fan-in    4 fan-out   25% dead  0.22 density   6.0 risk

  Sorted by triage concern: the larger of low-MI concern and CRAP risk. The risk / structure tag marks which one placed each file. MI reflects complexity, coupling, and dead code; risk reflects untested complexity (CRAP) and can diverge from MI. Risk: low <15, moderate 15-30, high >=30. CRAP estimated from export references (85% direct, 40% indirect, 0% untested). Run `fallow health --coverage <coverage-final.json>` for exact scores. https://docs.fallow.tools/explanations/health#file-health-scores

✗ 24 above threshold · 847 analyzed (0.08s)

$ fallow health --hotspots --top 3

● Hotspots (3 files, since 6 months)

   92.0 ▲  src/diff/index.js
           47 commits   2460 churn  0.89 density   3 fan-in  ▲ accelerating

   71.0 ─  src/legacy/handler.ts
           23 commits    720 churn  0.38 density   2 fan-in  ─ stable

   38.0 ▼  src/utils/parser.ts
           12 commits    300 churn  0.22 density   8 fan-in  ▼ cooling

  18 files excluded (< 3 commits)

  Files with high churn and high complexity: https://docs.fallow.tools/explanations/health#hotspot-metrics

✗ 3 hotspots · 847 analyzed (0.32s)

JSON output

Complexity findings

$ fallow health --format json --top 2

{
  "schema_version": 3,
  "version": "3.9.1",
  "elapsed_ms": 140,
  "summary": {
    "files_analyzed": 252,
    "functions_analyzed": 5424,
    "functions_above_threshold": 24,
    "max_cyclomatic_threshold": 20,
    "max_cognitive_threshold": 15
  },
  "findings": [
    {
      "path": "src/diff/index.js",
      "name": "diff",
      "line": 48,
      "col": 0,
      "cyclomatic": 67,
      "cognitive": 138,
      "line_count": 290,
      "exceeded": "both"
    }
  ]
}

When configured threshold overrides affect a run, JSON includes threshold_overrides[] with active, stale, or no_match status. Complexity findings evaluated with local ceilings include effective_thresholds and threshold_source: "override". When --css is active, JSON also includes css_analytics for descriptive CSS evidence and styling_findings for first-class styling issues. Each styling finding has code, sub_kind, effective_severity, location, evidence value, and read-only actions, and can be configured through the styling rules.

With file scores

When --file-scores is used, the JSON output includes additional fields:

$ fallow health --file-scores --format json --top 2

{
  "schema_version": 3,
  "version": "3.9.1",
  "elapsed_ms": 320,
  "summary": {
    "files_analyzed": 252,
    "functions_analyzed": 5424,
    "functions_above_threshold": 24,
    "max_cyclomatic_threshold": 20,
    "max_cognitive_threshold": 15,
    "files_scored": 2,
    "average_maintainability": 68.9,
    "coverage_model": "static_estimated"
  },
  "findings": [
    {
      "path": "src/diff/index.js",
      "name": "diff",
      "line": 48,
      "col": 0,
      "cyclomatic": 67,
      "cognitive": 138,
      "line_count": 290,
      "exceeded": "both"
    }
  ],
  "file_scores": [
    {
      "path": "demo/index.jsx",
      "fan_in": 0,
      "fan_out": 24,
      "dead_code_ratio": 1.0,
      "complexity_density": 0.04,
      "maintainability_index": 66.8,
      "total_cyclomatic": 2,
      "total_cognitive": 1,
      "function_count": 2,
      "lines": 54,
      "crap_max": 6.0,
      "crap_above_threshold": 0
    }
  ]
}

Without --file-scores, the file_scores array and summary.files_scored / summary.average_maintainability / summary.coverage_model fields are omitted entirely from the JSON output. The coverage_model field indicates how CRAP coverage was determined: static_estimated (default, per-function estimation from export references: 85% direct, 40% indirect, 0% untested) or istanbul (real per-function statement coverage from --coverage flag or auto-detected coverage-final.json). CRAP findings carry coverage_source; when such findings are emitted, summary.coverage_source_consistency reports uniform or mixed even if summary.coverage_model is omitted. Each file score includes crap_max (highest CRAP score among the file’s functions) and crap_above_threshold (count of functions at or above the CRAP threshold).

With hotspots

When --hotspots is used, the JSON output includes a hotspots array and hotspot_summary:

$ fallow health --hotspots --format json --top 2

{
  "schema_version": 3,
  "version": "3.9.1",
  "elapsed_ms": 480,
  "summary": {
    "files_analyzed": 252,
    "functions_analyzed": 5424,
    "functions_above_threshold": 24,
    "max_cyclomatic_threshold": 20,
    "max_cognitive_threshold": 15
  },
  "findings": [
    {
      "path": "src/diff/index.js",
      "name": "diff",
      "line": 48,
      "col": 0,
      "cyclomatic": 67,
      "cognitive": 138,
      "line_count": 290,
      "exceeded": "both"
    }
  ],
  "hotspot_summary": {
    "since": "6 months",
    "min_commits": 3,
    "files_analyzed": 21,
    "files_excluded": 18,
    "shallow_clone": false
  },
  "hotspots": [
    {
      "path": "src/diff/index.js",
      "score": 92,
      "commits": 47,
      "weighted_commits": 38.4,
      "lines_added": 1840,
      "lines_deleted": 620,
      "complexity_density": 0.89,
      "fan_in": 3,
      "trend": "Accelerating"
    },
    {
      "path": "src/legacy/handler.ts",
      "score": 71,
      "commits": 23,
      "weighted_commits": 14.2,
      "lines_added": 540,
      "lines_deleted": 180,
      "complexity_density": 0.38,
      "fan_in": 2,
      "trend": "Stable"
    }
  ]
}

Without --hotspots, the hotspots array and hotspot_summary fields are omitted entirely from the JSON output. Hotspot analysis can be combined with --file-scores to include all sections in a single output.

With refactoring targets

When --targets is used, the JSON output includes a targets array:

$ fallow health --targets --format json --top 2

{
  "schema_version": 3,
  "version": "3.9.1",
  "elapsed_ms": 520,
  "summary": {
    "files_analyzed": 252,
    "functions_analyzed": 5424,
    "functions_above_threshold": 24,
    "max_cyclomatic_threshold": 20,
    "max_cognitive_threshold": 15
  },
  "targets": [
    {
      "path": "src/core/processor.ts",
      "priority": 92.3,
      "efficiency": 30.8,
      "recommendation": "Actively-changing file with growing complexity, stabilize before adding features",
      "category": "urgent_churn_complexity",
      "effort": "high",
      "confidence": "low",
      "factors": [
        {
          "metric": "complexity_density",
          "value": 0.83,
          "threshold": 0.3,
          "detail": "density 0.83 exceeds 0.3"
        }
      ]
    },
    {
      "path": "src/helpers/util.ts",
      "priority": 38.8,
      "efficiency": 38.8,
      "recommendation": "Remove 12 unused exports to reduce surface area (86% dead)",
      "category": "remove_dead_code",
      "effort": "low",
      "confidence": "high",
      "factors": [
        {
          "metric": "dead_code_ratio",
          "value": 0.86,
          "threshold": 0.5,
          "detail": "12 unused of 14 value exports (86%)"
        }
      ],
      "evidence": {
        "unused_exports": ["assertEqual", "assertIs", "assertNever"]
      }
    }
  ],
  "target_thresholds": {
    "fan_in_p95": 12.0,
    "fan_in_p75": 5.0,
    "fan_out_p95": 15.0,
    "fan_out_p90": 8
  }
}

Targets are sorted by efficiency (priority / effort) descending, surfacing quick wins first. Each target includes efficiency, effort (low/medium/high), confidence (high/medium/low, based on data source reliability), and factors with raw value/threshold for programmatic use. The target_thresholds object exposes the adaptive percentile-based thresholds used for scoring, so consumers can interpret scores in context. The evidence field provides actionable detail for supported categories (remove_dead_code, extract_complex_functions, break_circular_dependency, add_test_coverage); omitted for other categories.

Target categories

Category	Label	Description
`urgent_churn_complexity`	churn+complexity	Actively-changing file with growing complexity
`break_circular_dependency`	circular dependency	File participates in a dependency cycle
`split_high_impact`	high impact	High fan-in with high complexity; changes ripple widely
`remove_dead_code`	dead code	Majority of exports are unused
`extract_complex_functions`	complexity	Contains functions with very high cognitive complexity
`extract_dependencies`	coupling	Excessive imports reduce testability and increase coupling
`add_test_coverage`	untested risk	Multiple complex functions lack test dependency path. Fires when a file has 2+ functions above the CRAP threshold and complexity density > 0.3. The `crap_max` contributing factor appears on these targets.

Without --targets, the targets array and target_thresholds are omitted entirely from the JSON output.

With vital signs

When file-scores are enabled (via --file-scores or implicitly via --save-snapshot), the JSON output includes a top-level vital_signs object:

$ fallow health --file-scores --format json (vital_signs excerpt)

{
  "schema_version": 3,
  "version": "3.9.1",
  "vital_signs": {
    "dead_file_pct": 4.2,
    "dead_export_pct": 12.8,
    "avg_cyclomatic": 3.1,
    "critical_complexity_pct": 1.2,
    "p90_cyclomatic": 11,
    "duplication_pct": null,
    "hotspot_count": 5,
    "hotspot_top_pct_count": 3,
    "maintainability_avg": 72.4,
    "maintainability_low_pct": 9.1,
    "unused_dep_count": 3,
    "unused_deps_per_k_files": 11.5,
    "circular_dep_count": 1,
    "circular_deps_per_k_files": 3.8,
    "unit_size_profile": {
      "low_risk": 82.1,
      "medium_risk": 11.4,
      "high_risk": 4.3,
      "very_high_risk": 2.2
    },
    "functions_over_60_loc_per_k": 22.0,
    "unit_interfacing_profile": {
      "low_risk": 95.6,
      "medium_risk": 3.8,
      "high_risk": 0.5,
      "very_high_risk": 0.1
    },
    "p95_fan_in": 8,
    "coupling_high_pct": 2.3,
    "counts": {
      "dead_files": 11,
      "total_files": 262,
      "dead_exports": 48,
      "total_exports": 375,
      "unused_deps": 3,
      "circular_deps": 1
    }
  }
}

Without file-scores enabled, the vital_signs object is omitted from the JSON output. The duplication_pct field is populated automatically when --score is used, or when duplication analysis runs via fallow dupes, bare fallow, or fallow dead-code --include-dupes. It is null otherwise.

With health score

When --score is used, the JSON output includes a health_score object with score, grade, and penalty breakdown:

$ fallow health --score --format json (health_score excerpt)

{
  "health_score": {
    "formula_version": 2,
    "score": 72.9,
    "grade": "B",
    "penalties": {
      "dead_files": 3.1,
      "dead_exports": 6.0,
      "complexity": 0.0,
      "p90_complexity": 0.0,
      "maintainability": 0.0,
      "unused_deps": 10.0,
      "circular_deps": 4.0,
      "unit_size": 0.0,
      "coupling": 0.0,
      "duplication": 4.0
    }
  }
}

The score is reproducible from the penalties: 100 - sum(penalties) == score. formula_version identifies the scoring formula; version 2 uses scale-invariant density and tail metrics such as critical_complexity_pct, hotspot_top_pct_count, and dependency densities per 1,000 files. Penalty fields are null (absent from JSON) when the corresponding pipeline didn’t run. --score computes the score and automatically runs duplication analysis; add --hotspots (or combine --score --targets) when the score should include the churn-backed hotspot penalty. Letter grades: A (score >= 85), B (70-84), C (55-69), D (40-54), F (below 40).

Without --score, the health_score object is omitted entirely from the JSON output. --min-score implies --score.

With trend

When --trend is used, the JSON output includes a health_trend object comparing current metrics against the most recent saved snapshot:

$ fallow health --trend --format json (health_trend)

{
  "health_trend": {
    "compared_to": {
      "timestamp": "2026-03-25T14:30:00Z",
      "git_sha": "a1b2c3d",
      "score": 74.2,
      "grade": "B"
    },
    "metrics": [
      {
        "name": "score",
        "label": "Health Score",
        "previous": 74.2,
        "current": 76.9,
        "delta": 2.7,
        "direction": "improving",
        "unit": ""
      },
      {
        "name": "dead_file_pct",
        "label": "Dead Files",
        "previous": 5.1,
        "current": 4.2,
        "delta": -0.9,
        "direction": "improving",
        "unit": "%",
        "previous_count": { "value": 13, "total": 255 },
        "current_count": { "value": 11, "total": 262 }
      },
      {
        "name": "dead_export_pct",
        "label": "Dead Exports",
        "previous": 12.8,
        "current": 12.8,
        "delta": 0.0,
        "direction": "stable",
        "unit": "%",
        "previous_count": { "value": 46, "total": 359 },
        "current_count": { "value": 48, "total": 375 }
      },
      {
        "name": "avg_cyclomatic",
        "label": "Avg Cyclomatic",
        "previous": 3.0,
        "current": 3.1,
        "delta": 0.1,
        "direction": "declining",
        "unit": ""
      },
      {
        "name": "maintainability_avg",
        "label": "Maintainability",
        "previous": 71.8,
        "current": 72.4,
        "delta": 0.6,
        "direction": "improving",
        "unit": ""
      },
      {
        "name": "unused_dep_count",
        "label": "Unused Deps",
        "previous": 4.0,
        "current": 3.0,
        "delta": -1.0,
        "direction": "improving",
        "unit": ""
      },
      {
        "name": "circular_dep_count",
        "label": "Circular Deps",
        "previous": 1.0,
        "current": 1.0,
        "delta": 0.0,
        "direction": "stable",
        "unit": ""
      },
      {
        "name": "hotspot_count",
        "label": "Hotspots",
        "previous": 6.0,
        "current": 5.0,
        "delta": -1.0,
        "direction": "improving",
        "unit": ""
      },
      {
        "name": "unit_size_very_high_pct",
        "label": "Oversized Fns",
        "previous": 2.8,
        "current": 2.2,
        "delta": -0.6,
        "direction": "improving",
        "unit": "%"
      },
      {
        "name": "p95_fan_in",
        "label": "P95 Fan-in",
        "previous": 9.0,
        "current": 8.0,
        "delta": -1.0,
        "direction": "improving",
        "unit": ""
      }
    ],
    "snapshots_loaded": 3,
    "overall_direction": "improving"
  }
}

Each metric includes direction (improving, declining, or stable) based on whether the change is beneficial. Percentage metrics include previous_count and current_count with raw numerator/denominator. The overall_direction summarizes across all metrics by majority vote.

--trend requires at least one saved snapshot in .fallow/snapshots/. Use --save-snapshot to create snapshots first. Without any snapshots, the health_trend object is omitted.

With coverage gaps

When --coverage-gaps is used, the JSON output includes a coverage_gaps object listing runtime files and exports that no test dependency path reaches. This helps identify production code with no transitive test coverage. The coverage-gaps rule supports error, warn, or off severity in your config (default off):

{
  "rules": {
    "coverage-gaps": "warn"
  }
}

[rules]
coverage-gaps = "warn"

$ fallow health --coverage-gaps --format json

{
  "schema_version": 3,
  "version": "3.9.1",
  "elapsed_ms": 280,
  "coverage_gaps": {
    "summary": {
      "runtime_files": 84,
      "covered_files": 72,
      "file_coverage_pct": 85.7,
      "untested_files": 12,
      "untested_exports": 38
    },
    "files": [
      {
        "path": "src/utils/parser.ts",
        "value_export_count": 2
      },
      {
        "path": "src/legacy/handler.ts",
        "value_export_count": 1
      }
    ],
    "exports": [
      {
        "path": "src/core/processor.ts",
        "export_name": "transform",
        "line": 42,
        "col": 0
      }
    ]
  }
}

The files array lists runtime files where no export is reached by any test dependency path. The exports array lists individual exports in otherwise-covered files that lack test reachability.

Without --coverage-gaps, the coverage_gaps object is omitted entirely from the JSON output. The flag is opt-in and the coverage-gaps rule defaults to off.

With runtime coverage

When --runtime-coverage is used, the JSON output includes a runtime_coverage object that merges runtime evidence into the standard health report.

$ fallow health --runtime-coverage ./coverage --format json

{
  "schema_version": 4,
  "version": "3.9.1",
  "elapsed_ms": 412,
  "runtime_coverage": {
    "verdict": "hot-path-touched",
    "signals": ["cold-code-detected", "hot-path-touched"],
    "summary": {
      "functions_tracked": 128,
      "functions_hit": 93,
      "functions_unhit": 21,
      "functions_untracked": 14,
      "coverage_percent": 72.7,
      "trace_count": 284729,
      "period_days": 7,
      "deployments_seen": 3,
      "capture_quality": {
        "window_seconds": 604800,
        "instances_observed": 3,
        "lazy_parse_warning": false,
        "untracked_ratio_percent": 10.9
      }
    },
    "findings": [
      {
        "id": "fallow:prod:a7f3b2c1",
        "path": "src/server/featureFlags.ts",
        "function": "staleGate",
        "line": 44,
        "verdict": "review_required",
        "invocations": 0,
        "confidence": "medium",
        "evidence": {
          "static_status": "used",
          "test_coverage": "not_covered",
          "v8_tracking": "tracked",
          "observation_days": 7,
          "deployments_observed": 3
        },
        "actions": [
          {
            "type": "remove-dead-code",
            "description": "Tracked in runtime coverage with zero invocations.",
            "auto_fixable": false
          }
        ]
      }
    ],
    "hot_paths": [
      {
        "id": "fallow:hot:c9f5d4e3",
        "path": "src/server/router.ts",
        "function": "handleRequest",
        "line": 42,
        "invocations": 1842,
        "percentile": 99
      }
    ]
  }
}

Key points:

Field	Meaning
`verdict`	Overall runtime verdict: `clean`, `cold-code-detected`, `hot-path-touched`, `license-expired-grace`, or `unknown`. Promotes `hot-path-touched` over `cold-code-detected` in PR-review contexts when `--diff-file` (or `--changed-since`) is set.
`signals`	Array of every signal post-processing detected, independent of `verdict` (the single most actionable one). Ordered severity-descending; omitted when empty. A PR run that hits both cold code and a hot path emits `["cold-code-detected", "hot-path-touched"]`.
`summary`	Aggregate counts of tracked, hit, unhit, and untracked functions; the coverage ratio; total trace volume; and the observation window.
`findings`	Cold or unresolved functions. Each finding has a stable `id` (`fallow:prod:<hash>`), `verdict` (`safe_to_delete` / `review_required` / `low_traffic` / `coverage_unavailable` / `active` / `unknown`), and an `evidence` block explaining the verdict.
`hot_paths`	Highest-invocation runtime functions, filtered by `--min-invocations-hot`. Each has a stable `id` (`fallow:hot:<hash>`) and `percentile` rank.
`coverage_intelligence`	Additive decision layer emitted when runtime coverage can be combined with static usage, test coverage, CRAP/complexity, ownership, or change scope. It summarizes `risky-change-detected`, `high-confidence-delete`, `review-required`, and `refactor-carefully` findings with stable `fallow:coverage-intel:<hash>` IDs, compact evidence, related runtime IDs, and actions. Omitted when no combined finding is available.
`watermark`	Present only when trial/license grace rules require visible annotation in the output.
`warnings`	Non-fatal coverage merge diagnostics.

The schema_version: 4 envelope was introduced with fallow-cov-protocol 0.2 and is extended additively as the protocol evolves. Protocol 0.3 added the optional summary.capture_quality block. Protocol 0.5 (current) added HotPath.end_line so the consumer can do line-range overlap against a --diff-file, and split the previous single-verdict surface into a signals array alongside verdict. Earlier schema_version: 3 output used a different finding shape (state instead of verdict, no stable IDs, renamed summary fields); see the v2.39.0 release notes for the full migration. --runtime-coverage accepts a V8 directory, a single V8 JSON file, or a single Istanbul coverage map JSON file. A single local capture runs without a license. Use fallow coverage setup for first-run capture instructions; start a trial with fallow license when you need continuous or multi-capture runtime monitoring. For the conceptual model and trade-offs, see Runtime coverage.

Markdown output

Formatted for PR comments. Pipe directly to gh pr comment:

fallow health --file-scores --format markdown | gh pr comment --body-file -

$ fallow health --file-scores --format markdown --top 2

## Fallow Health: 24 functions above threshold

### High complexity functions (2 shown)

| File | Function | Line | Cyclomatic | Cognitive | Lines |
|:-----|:---------|-----:|-----------:|----------:|------:|
| src/diff/index.js | diff | 48 | 67 | 138 | 290 |
| src/diff/index.js | diffElementNodes | 381 | 63 | 105 | 200 |

### File health scores (2 files)

| File | Maintainability | LOC | Fan-in | Fan-out | Dead code | Density |
|:-----|---:|---:|-------:|--------:|----------:|--------:|
| src/legacy/handler.ts | 52.3 | 312 | 2 | 18 | 45% | 0.38 |
| src/diff/index.js | 68.4 | 847 | 3 | 12 | 0% | 0.89 |

SARIF output

SARIF format for GitHub Code Scanning and other static analysis tools:

fallow health --format sarif

$ fallow health --format sarif (excerpt)

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "3.9.1",
  "runs": [{
    "tool": { "driver": { "name": "fallow", "version": "3.9.1" } },
    "results": [
      {
        "ruleId": "fallow/high-cyclomatic-complexity",
        "level": "warning",
        "message": { "text": "Function 'diff' has cyclomatic complexity 67 (threshold: 20)" },
        "locations": [{
          "physicalLocation": {
            "artifactLocation": { "uri": "src/diff/index.js" },
            "region": { "startLine": 48, "startColumn": 1 }
          }
        }]
      }
    ]
  }]
}

Upload to GitHub Code Scanning in CI:

- run: fallow health --format sarif > health.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: health.sarif
    category: fallow-health

Configuration

Configure default thresholds and ignore patterns in your config file:

{
  "health": {
    "maxCyclomatic": 20,
    "maxCognitive": 15,
    "maxCrap": 30,
    "crapRefactorBand": 5,
    "ignore": ["**/*.generated.ts", "src/legacy/**"],
    "thresholdOverrides": [
      {
        "files": ["src/legacy/**"],
        "functions": ["parseLegacy"],
        "maxCyclomatic": 40,
        "maxCognitive": 35,
        "reason": "Queued legacy parser cleanup"
      }
    ],
    "suggestInlineSuppression": true
  }
}

[health]
maxCyclomatic = 20
maxCognitive = 15
maxCrap = 30
crapRefactorBand = 5
ignore = ["**/*.generated.ts", "src/legacy/**"]
suggestInlineSuppression = true

[[health.thresholdOverrides]]
files = ["src/legacy/**"]
functions = ["parseLegacy"]
maxCyclomatic = 40
maxCognitive = 35
reason = "Queued legacy parser cleanup"

See Configuration for the full config reference.

Inline suppression

Suppress individual functions from complexity findings with inline comments:

// fallow-ignore-next-line complexity
function* parseCsv(text) {
  // ...
}

Both cyclomatic and cognitive metrics are suppressed together. File scores and vital signs are unaffected (they reflect actual complexity, not alerting). Use // fallow-ignore-file complexity to suppress all functions in a file. For coverage gaps: // fallow-ignore-file coverage-gaps excludes the file from untested-code reporting.

`suggestInlineSuppression` and baselines

The JSON output for each health finding includes an actions array with machine-actionable hints (refactor, add coverage, suppress). The suppress-line hint is omitted automatically when:

--baseline or --save-baseline is active. The baseline file already suppresses existing findings, so adding // fallow-ignore-next-line comments on top would create dead annotations once the baseline regenerates.
health.suggestInlineSuppression is set to false in config. Use this when your team manages suppressions exclusively through hand-authored // fallow-ignore-* comments and does not want CI-driven inline suppression hints in JSON output.

When the hint is omitted, a top-level actions_meta: { "suppression_hints_omitted": true, "reason": "baseline-active" | "config-disabled" } breadcrumb is added to the health JSON envelope so consumers can audit the omission.

Action selection by coverage tier

For findings triggered by CRAP, the primary action is selected by a formula-aware rule, with the coverage_tier field choosing the description:

Coverage CAN clear CRAP (cyclomatic < maxCrap): the function’s CRAP score can be brought below maxCrap by improving coverage, since CRAP = CC^2 * (1 - cov/100)^3 + CC bottoms out at CC at 100% coverage. The tier picks the description:
- none (file not test-reachable, or Istanbul reports 0%): emits add-tests with a “start from scratch” description.
- partial (some coverage exists, Istanbul (0, 70), or estimated 40% band): emits increase-coverage with a “targeted branch coverage” description, since the file already has a test path.
- high (Istanbul >= 70, or estimated 85% band): emits increase-coverage (NOT refactor) because additional coverage can still drop CRAP below threshold for a function whose cyclomatic is small enough.
Coverage CANNOT clear CRAP (cyclomatic >= maxCrap): no amount of coverage will bring CRAP under threshold; emits refactor-function instead, regardless of tier. Reducing cyclomatic complexity is the only remaining lever.

When CRAP-only and the function’s cyclomatic count is within health.crapRefactorBand of maxCyclomatic, a secondary refactor-function action is also emitted alongside the coverage action, but only when cognitive complexity is at or above maxCognitive / 2. The default band is 5; set it to 0 to only add the secondary refactor once cyclomatic already reaches maxCyclomatic. The cognitive floor suppresses the secondary refactor on flat type-tag dispatchers and JSX render maps where high cyclomatic comes from a single switch with near-zero cognitive load (refactoring those is wrong-target advice). See Inline suppression for all suppressible issue types.

Health metrics explained

CRAP metric, maintainability index, hotspot scoring, and coverage model details.

Dead code analysis

Find unused code alongside complexity hotspots.

Configuration

Set default thresholds in your config file.

CI integration

Enforce complexity limits in your pipeline.

​Options

​Thresholds

​Output

​Section selection

​Type-aware coupling

​Health score options

​Hotspot options

​Scoping

​Snapshots & trends

​Baseline

​Exit codes

​Maintainability index formula

​Hotspot score formula

​Per-file hotspot metrics

​Hotspot summary

​Ownership analysis

​Project-level summary

​Per-hotspot ownership fields

​Severity in human output

​Test-path tag

​Ownership-derived JSON actions

​Email privacy

​Configuration

​Importing churn from a non-git VCS

​The fallow-churn/v1 contract

​Producer requirements

​Reference wrapper (Mercurial)

​Scope

​Vital signs

​Snapshots

​Snapshot format

​Examples

​Example output

​JSON output

​Complexity findings

​With file scores

​With hotspots

​With refactoring targets

​Target categories

​With vital signs

​With health score

​With trend

​With coverage gaps

​With runtime coverage

​Markdown output

​SARIF output

​Configuration

​Inline suppression

​suggestInlineSuppression and baselines

​Action selection by coverage tier

​See also

Health metrics explained

Dead code analysis

Configuration

CI integration

Options

Thresholds

Output

Section selection

Type-aware coupling

Health score options

Hotspot options

Scoping

Snapshots & trends

Baseline

Exit codes

Maintainability index formula

Hotspot score formula

Per-file hotspot metrics

Hotspot summary

Ownership analysis

Project-level summary

Per-hotspot ownership fields

Severity in human output

Test-path tag

Ownership-derived JSON actions

Email privacy

Configuration

Importing churn from a non-git VCS

The `fallow-churn/v1` contract

Producer requirements

Reference wrapper (Mercurial)

Scope

Vital signs

Snapshots

Snapshot format

Examples

Example output

JSON output

Complexity findings

With file scores

With hotspots

With refactoring targets

Target categories

With vital signs

With health score

With trend

With coverage gaps

With runtime coverage

Markdown output

SARIF output

Configuration

Inline suppression

`suggestInlineSuppression` and baselines

Action selection by coverage tier

See also