fallow health

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 templateUrl files and inline @Component({ template }) literals contribute synthetic <template> findings, and a component whose class and template both score emits a <component> rollup whose totals drive ranking and --targets. Inline-template findings and the rollup are suppressible with // fallow-ignore-next-line complexity above the decorator or the worst class method; external-template findings with <!-- fallow-ignore-file complexity --> at the top of the template. See Complexity metrics for what each shape counts and how to act on it.

fallow health

Options

Thresholds

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, maxCrap, and maxUnitSize, and can include a reason. They keep exceptions visible in output instead of hiding them with suppression comments.

Output

For every --sort mode, tied complexity findings are ordered by file path, line, column, then function name. This keeps their order and --top selection stable across checkout locations and thread settings without changing the metric's priority.

Section selection

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

Multiple section flags can be combined (e.g., --complexity --hotspots).

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

Hotspot options

Scoping

Snapshots & trends

Baseline

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:

--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.

File score metrics

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 formula and its components are documented under File health scores.

Each file score reports these metrics (informational, not in the formula):

Hotspot metrics

The hotspot score identifies files that are both complex and frequently changed; the formula, the recency weighting, and the trend rules are documented under Hotspot metrics.

Per-file hotspot metrics

Each hotspot entry includes:

Hotspot summary

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

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

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:

Email privacy

By default, fallow renders author emails as their local-part (e.g. [email protected] shows as alice). GitHub-style noreply prefixes are unwrapped ([email protected] shows as alice). Override with --ownership-emails:

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 [abc] is a glob 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\].

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.

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:

1. Omit merge commits. Otherwise the merge author looks like a contributor to every merged file, inflating bus-factor and skewing the trend.
2. Omit binary-file rows entirely (do not emit 0/0). git skips binary -/- numstat rows.
3. 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.)
4. 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)

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.

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.

Snapshot format

{
  "snapshot_schema_version": 10,
  "version": "3.23.0",
  "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
  }
}

Examples

# Report functions exceeding default thresholds
fallow health

Example output

● 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)

● 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

Each section's fields appear only when that section is enabled; a disabled section is absent from the envelope, not empty.

Complexity findings

{
  "schema_version": 11,
  "version": "3.23.0",
  "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"
    }
  ]
}

Complexity findings evaluated with local ceilings include effective_thresholds and threshold_source: "override". When configured threshold overrides affect a run, JSON also includes a top-level threshold_overrides[] array; see Threshold overrides below.

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.

Threshold overrides

When configured health.thresholdOverrides[] entries affect a run, JSON includes a threshold_overrides[] array with one row per threshold dimension each entry participates in: complexity covers the maxCyclomatic, maxCognitive, and maxUnitSize ceilings, and crap covers maxCrap alone. An entry that configures both a structural ceiling and maxCrap therefore produces two rows sharing one override_index; group on override_index to count configured entries rather than rows.

{
  "status": "insufficient",
  "override_index": 0,
  "dimension": "crap",
  "outstanding": [
    "complexity",
    "crap"
  ],
  "path": "src/legacy.ts",
  "function": "legacyFlow",
  "line": 1,
  "col": 7,
  "configured_thresholds": {
    "max_cyclomatic": 5,
    "max_crap": 40.0
  },
  "effective_thresholds": {
    "max_cyclomatic": 5,
    "max_cognitive": 3,
    "max_crap": 40.0,
    "max_unit_size": 60
  },
  "metrics": {
    "cyclomatic": 7,
    "cognitive": 6,
    "crap": 56.0
  },
  "reason": "raised but still exceeded"
}

This row reads: the first configured entry raised the CRAP ceiling to 40, but legacyFlow scores 56, so the CRAP finding survives the override; outstanding shows the unit also still breaches the complexity dimension. An insufficient row means the override applied but did not settle the finding, so either raise the ceiling further or fix the function.

With file scores

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

{
  "schema_version": 11,
  "version": "3.23.0",
  "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
    }
  ]
}

With hotspots

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

{
  "schema_version": 11,
  "version": "3.23.0",
  "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"
    }
  ]
}

With refactoring targets

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

{
  "schema_version": 11,
  "version": "3.23.0",
  "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

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 with the metrics listed under Vital signs, plus the nested counts object. The snapshot format shows a complete example.

With health score

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

{
  "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. Penalty fields are null (absent from JSON) when the corresponding pipeline didn't run. The penalty formulas, formula_version, and the letter-grade bands are documented under Health score.

With trend

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

{
  "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.

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.

The analysis is mock-aware. A test that replaces a module with vi.mock / jest.mock and a statically closed factory (one that provably never loads the original: no vi.importActual / jest.requireActual, no outer imports of the mocked module) does not count as reaching that module, so a module only ever imported behind such a mock can surface as a gap. Anything fallow cannot prove keeps coverage credit: automock (vi.mock / jest.mock without a factory) never removes credit because the runner may still evaluate the original module, and vi.doMock / jest.doMock never remove credit because they are unhoisted and order-sensitive. doMock additionally credits its target and, for path-shaped static specifiers like ./services/api, the __mocks__ sibling; bare package specifiers (vi.doMock('axios')) credit the package but not a root __mocks__ file, and templated specifiers credit nothing.

The coverage-gaps rule supports error, warn, or off severity in your config (default off):

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

{
  "schema_version": 11,
  "version": "3.23.0",
  "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.

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.

{
  "schema_version": 11,
  "version": "3.23.0",
  "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:

The runtime_coverage object is extended additively as the fallow-cov protocol evolves: summary.capture_quality is optional, and HotPath.end_line lets a consumer do line-range overlap against a --diff-file.

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

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "3.23.0",
  "runs": [{
    "tool": { "driver": { "name": "fallow", "version": "3.23.0" } },
    "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
  }
}

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.

See also