Merge runtime coverage into fallow health to see which functions actually execute in production-like traffic, which stay cold, and which hot paths changed.
Use this file to discover all available pages before exploring further.
Runtime coverage adds a runtime layer on top of fallow health. Static analysis can tell you which exports have no references and which files are not test-reachable. Runtime coverage answers a different question: which functions actually executed when your deployed app handled real traffic.
When runtime coverage is enabled, fallow merges runtime evidence into the existing health report and assigns each function a per-finding verdict combining the static reachability signal with observed production invocations:
Verdict
Meaning
safe_to_delete
Statically unused AND V8 tracked AND zero invocations. The strongest delete signal fallow emits.
review_required
Statically used but never invoked in production. Needs a human look: could be seasonal, error-path-only, or legitimately dead.
low_traffic
Invoked in production, but below the configured --low-traffic-threshold ratio of total trace count (spec default 0.1%). Effectively dead for the observed period.
coverage_unavailable
V8 could not track the function (lazy-parsed, worker-thread isolate, dynamic eval, or the source map did not resolve). Advisory, not a dead-code signal.
active
Invoked in production above the low-traffic threshold. Not dead.
unknown
Forward-compat sentinel returned by newer sidecars. Rare.
Fallow also surfaces:
Output
Meaning
verdict
Overall report status: 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 the post-processing pass detected, independent of verdict (which is the single most actionable signal under the current context). Ordered severity-descending; omitted entirely when empty. A typical PR run emits ["cold-code-detected", "hot-path-touched"] together when both apply.
summary
Aggregate counts (functions_tracked, functions_hit, functions_unhit, functions_untracked, coverage_percent) plus trace_count, period_days, deployments_seen, and an optional capture_quality block (window_seconds, instances_observed, lazy_parse_warning, untracked_ratio_percent) on protocol-0.3+ sidecars that flags short-window captures where lazy-parsed scripts may not appear.
findings
Cold or unresolved functions with a stable id (fallow:prod:<hash>), line, per-finding verdict, confidence, supporting evidence, and machine-readable actions.
hot_paths
The busiest runtime functions with a stable id, line, invocations, and percentile rank.
watermark
Trial/license grace marker applied when paid-feature access is in warning mode.
warnings
Non-fatal merge diagnostics, for example partial source-map remapping.
Every finding carries an evidence block so the “why” behind a verdict is machine-readable without re-deriving it:
Two flags tune how aggressively fallow applies verdicts:
Flag
Default
Effect
--min-observation-volume <N>
5000
Minimum total trace volume before the sidecar is allowed to emit high-confidence safe_to_delete or review_required verdicts. Below this threshold, confidence is capped at medium to protect against overconfident verdicts on new or low-traffic services.
--low-traffic-threshold <RATIO>
0.001
Fraction of trace_count below which an invoked function is classified low_traffic rather than active. Expressed as a decimal (0.001 = 0.1%).
These three surfaces live side by side inside fallow health, but they answer different questions:
Surface
Flag
Input
Answers
Paid
Static reachability gaps
--coverage-gaps
none
Which runtime files and exports have no transitive test path?
no
Exact CRAP scoring
--coverage
Istanbul JSON
How covered is each function for CRAP calculation?
no
Runtime runtime coverage
--runtime-coverage
V8 directory, V8 JSON file, or Istanbul JSON
Which functions actually ran, which stayed cold, and which hot paths changed?
yes
Use --coverage-gaps when you want to find untested code. Use --coverage when you want better CRAP scores. Use --runtime-coverage when you want runtime evidence about real execution paths.
./coverage created with NODE_V8_COVERAGE=./coverage
Single V8 JSON file
./coverage/12345.json
Single Istanbul coverage map JSON file
./coverage/coverage-final.json
If a V8 dump includes Node’s source-map-cache, fallow remaps supported source-map URLs before analysis, including file paths, relative paths, webpack://..., and vite://.... Unsupported virtual schemes fall back safely to raw V8 handling instead of failing the whole run.
Follow the generated recipe in docs/collect-coverage.md.
Re-run fallow coverage setup or fallow health --runtime-coverage <path> once coverage exists.
fallow coverage setup is resumable. It checks license state, installs or locates fallow-cov, writes a framework-specific collection recipe, detects an existing coverage artifact when present, and then hands off into fallow health --runtime-coverage.
Runtime coverage becomes especially useful during change review:
fallow health --changed-since main --runtime-coverage ./coverage
When changed files touch hot runtime code, fallow can upgrade the overall verdict to hot-path-touched. That gives PR review a stronger signal than static complexity alone.For tighter line-level scoping, pass a pre-computed unified diff:
A hot function is then flagged only when the diff modifies a line inside its [start_line, end_line] range, instead of matching the whole file. The bundled GitHub Action and GitLab CI template already pre-compute the diff and pass it through, so PR comments only highlight hot paths the change actually touches. Hot-path matching needs protocol 0.5 or newer in the sidecar (older sidecars only report a start line, so fallow falls back to file-level scoping).
Runtime coverage is a paid feature with a trial flow. Verification is offline against a compiled-in Ed25519 public key; only fallow license activate --trial and fallow license refresh require network access.If a license is expired but still inside the grace window, fallow keeps the analysis available but annotates the output with a watermark. Once the hard-fail window is exceeded, paid features are blocked until the license is refreshed.
