fallow audit

fallow audit tells you if a PR passes your quality gate. It checks the changed files for dead code, complexity, duplication, and styling, and returns a pass, warn, or fail verdict from the severity of the issues it finds.

Audit checks only the changed files, which keeps the signal-to-noise ratio high. By default, only issues that the current PR or commit introduces fail the gate. Inherited findings in touched files show as context.

Dependency findings (unused, misplaced, type-only or test-only dependencies, overrides and catalog entries) are in the audit only when the change touches the package.json or catalog file that declares them. Unlisted dependencies follow their import sites. fallow dead-code reports all of them.

fallow audit

Options

Base ref

Diff scoping

Gate

You can set the gate in three places. All three accept the same values (new-only, all). Precedence: CLI flag > config > MCP param > default.

fallow audit --gate all

Docs-only-diff fast path

Under --gate new-only, audit normally runs every analysis twice: once on the current tree, and once on a temporary worktree at the base ref. The second run tells audit if each finding is introduced or inherited.

audit skips the second run when every changed file is one of these:

• a non-behavioral doc (.md, .markdown, .txt, .rst, .adoc)
• a .ts/.tsx/.js/.jsx/.mjs/.mts/.cjs/.cts source file that is token-equivalent at the base ref (a comment-only or whitespace-only edit)

In that case, audit reuses the findings of the current run as the base snapshot and classifies all of them as inherited. Docs-only PRs and formatter sweeps then take about one analysis pass instead of two.

To check if the fast path fired, run fallow audit --base main --gate new-only --performance. The JSON output has base_snapshot_skipped: true|false, and the human output prints the same value on stderr. The fast path turns on automatically when every entry in the diff qualifies. No flag turns it on or off.

New-only duplication demotion

Under --gate new-only, clone-group attribution has one exception. When no instance of an introduced clone group overlaps an added line in the diff of the run, audit demotes the group to inherited. This happens when a change removes duplication elsewhere and so gives a remaining clone group a new structural key. The group is new to the report, but the change wrote no duplicated line, so the group does not fail the gate.

You can see every demotion. The stderr note about findings that the gate excluded gets an extra line with the demoted count and the diff that decided it:

audit gate excluded 3 inherited findings (run with --gate all to enforce)
  of which 1 clone group was reclassified as pre-existing: no duplicated line was added by this change (diff source: merge-base worktree diff vs main)

With --explain, the duplication section adds one line per demoted group, with the same cap as the clone listing. Each line shows:

• the group's dup:<fingerprint> id (matching the listing and fallow dupes --trace)
• its instance locations
• the deciding rule

A closing line names the diff source. In JSON, each demoted entry in duplication.clone_groups[] has a demotion_reason field, and the attribution block counts demotions in duplication_demoted. See Key fields.

The decision uses the same diff precedence as diff scoping. A diff from --diff-file, --diff-stdin, or FALLOW_DIFF_FILE wins over the merge-base worktree diff. A supplied diff with a narrower base than the merge base can demote duplication that the branch really introduced. An example is a diff of only the last commit on a branch with several commits. Compute a supplied diff from the same base that the audit compares against. When no diff is available, audit skips this check and every introduced clone group still gates.

Output

Review brief

Scoping

Thresholds

Runtime coverage

fallow audit accepts these two runtime coverage flags. For the coverage formats, the capture steps and the hot-path rules, see fallow coverage.

Baselines

audit rejects the global --baseline / --save-baseline flags (exit 2), because audit runs three analyses with incompatible baseline formats. Use the per-analysis flags above, or set defaults in .fallowrc.json:

{
  "audit": {
    "deadCodeBaseline": "fallow-baselines/dead-code.json",
    "healthBaseline":   "fallow-baselines/health.json",
    "dupesBaseline":    "fallow-baselines/dupes.json"
  }
}

Store committed baselines outside .fallow/. fallow init adds that directory to .gitignore for the machine-local cache.

CLI flags override config. An unset baseline has no effect. You can set any subset (for example dead-code only).

Audit cannot judge a baseline

An audit analyzes only the files that changed against its base. A whole-project baseline therefore matches less of the run. The narrow scope causes this, not a stale baseline. An audit loads the baselines that you pass, but it does not judge them.

Each loaded baseline has its own baseline_staleness object in the envelope:

• dead_code.baseline_staleness
• duplication.baseline_staleness
• complexity.summary.baseline_staleness

All three report change_scoped: true. Their scope_reasons names what narrowed that sub-pass: changed-since for dead_code, and changed-files for duplication and complexity. All three report gate_trips: false. A section that loaded a baseline it cannot read as its own reports true. Do not build a gate on these values.

To judge a baseline, run the command that owns it over the whole project. The section label is not the command name: duplication belongs to fallow dupes, complexity to fallow health, and dead_code to fallow dead-code.

An audit that loaded a baseline also has gate_outcomes["stale-baseline"] set to {"status": "skipped", "enforced": false}. There is one entry for any number of loaded baselines. The entry puts this fact on the gate outcomes line, which the pull-request comment and the merge-request note render. The entry also stays skipped for a baseline of another kind. See CI for what the shipped integrations report per baseline.

An audit checks the kind of every baseline that it loads, and reports every mismatch. Each mismatch prints a warning on stderr that names the flag with the path: --dead-code-baseline, --dupes-baseline or --health-baseline. That section has baseline_staleness.unrecognised_format: true. Next to it, saved_by names the command that saved the file: dead-code, dupes, or health. The saved_by field is absent for an empty file, for a baseline saved before files named their writer, and for a writer that this version does not know. To fix it, point that flag at a baseline from the command that owns it.

audit accepts --fail-on-stale-baseline, but in audit this gate never runs. A run that sets the flag with a baseline prints one warning on stderr, which names the commands that can run the gate.

--fail-on-baseline-growth does run in audit. It does not judge the findings of the run. It compares each file of --dead-code-baseline, --dupes-baseline and --health-baseline with the same file at the base ref, so a scoped run can judge it. See Baseline growth gate.

Verdict

Dead code issues use the severity from your rules configuration (error/warn/off). Complexity findings above the configured thresholds use the complexity rules. They default to error. With warn, a complexity finding gives a warn verdict. The thresholds come from your fallow health config (defaults: cyclomatic 20, cognitive 15). Duplication is a warning unless you configure a --threshold. With the default new-only gate, the report can show inherited error-severity findings while the audit exits 0. The audit ignores --fail-on-issues and keeps its own verdict.

The parse error gate (--fail-on-parse-error or failOnParseError) checks every file that the audit parsed, not only the changed files. The verdict does not include this gate. Read gate_outcomes for the exit reason.

JSON contract: which fields are severity-aware

Audit reports three counts that look alike but answer different questions. A CI integration or other tool that reads the output must gate on the right one:

Rule of thumb for CI gating: branch on verdict == "fail", or check the exit code, which follows the verdict. Do not count introduced findings. A count brings back the bug that command: audit was built to fix: a project with unused-exports: warn would fail CI on every PR that adds a warn-tier finding, although the verdict correctly says warn ("do not fail"). The official GitHub Action and GitLab CI template already gate on the verdict. Third-party wrappers should follow the same contract.

Rule of thumb for AI agents: read verdict first to see if the run passed or failed. Then read attribution for the new and inherited counts, and walk the finding arrays per category for the details. To keep only the findings that the current PR introduced, filter on introduced: true.

Examples

# Auto-detect base branch
fallow audit

# Explicit base ref
fallow audit --base main

# Audit last 3 commits
fallow audit --base HEAD~3

# Strict mode: fail on inherited findings too
fallow audit --gate all

Example output

Audit scope: 8 changed files vs main (d4a2f91..HEAD)
✓ No issues in 8 changed files (1.18s)

Audit scope: 8 changed files vs main (d4a2f91..HEAD)
■ dead code 0 · complexity 2 (warn, max cyclomatic: 12) · duplication 0
✓ dead code: 0 issues · complexity: 2 findings (warn) · 8 changed files (1.18s)

The ■ summary line appears only on warn verdicts, before any detail sections. --quiet hides it.

Audit scope: 12 changed files vs main (d4a2f91..HEAD)

── Dead Code ──────────────────────────────────────

● Unused exports (2)
  src/components/Button.tsx (2)
    :42 OldButton
    :67 deprecatedHelper
  Exported symbols with no known consumers
  https://docs.fallow.tools/explanations/dead-code#unused-exports

── Duplication ────────────────────────────────────

● Duplicates (1 clone group)

    23 lines  2 instances
    src/utils/helpers.ts:10-32
    src/legacy/compat.ts:5-27

── Complexity ─────────────────────────────────────

● High complexity functions (1)
  src/parser.ts
    :45 parseExpression
         28 cyclomatic  32 cognitive  80 lines
  Functions exceeding cyclomatic, cognitive, or CRAP thresholds; ! marks the
  dimension that breached
  https://docs.fallow.tools/explanations/health#complexity-metrics

✗ dead code: 2 issues · complexity: 1 finding · duplication: 1 clone group · 12 changed files (2.14s)

How it works

1. Resolve base ref: audit uses --base if you set it, then FALLOW_AUDIT_BASE. Otherwise it auto-detects the git merge-base (fork point) with the branch's upstream (@{upstream}) or the remote default (origin/HEAD → origin/main → origin/master). Because audit uses the merge-base and not a bare branch name, a feature branch compares against the point where it forked, not against a local main that can be stale. Repositories with no origin remote fall back to the local main / master branch. If audit cannot find a base, it stops with an error.
2. Find changed files: runs git diff --name-only <base>...HEAD (three-dot diff, showing changes since the merge base).
3. Run three analyses scoped to changed files: dead code, complexity, duplication.
4. Compute attribution: with new-only, audit runs the same analyses at the base ref and compares structural issue keys. A dead-code key is the line-free canonical key of the finding: the rule, the root-relative path and the names, the same input as the finding_id. A line shift above a finding therefore keeps it inherited. The keys compare by count, so a new second finding with the key of an inherited finding is introduced. An unlisted dependency is keyed by the package, so a new import site of a package that the base already reports stays inherited.
5. Compute verdict: new-only gates only introduced findings. all gates every finding in changed files and skips the extra base-snapshot analysis.

JSON output

{
  "kind": "audit",
  "schema_version": 11,
  "version": "3.31.0",
  "command": "audit",
  "verdict": "fail",
  "changed_files_count": 12,
  "base_ref": "main",
  "head_sha": "d4a2f91",
  "elapsed_ms": 2140,
  "summary": {
    "dead_code_issues": 2,
    "dead_code_has_errors": true,
    "complexity_findings": 1,
    "max_cyclomatic": 28,
    "duplication_clone_groups": 0
  },
  "attribution": {
    "gate": "new-only",
    "dead_code_introduced": 2,
    "dead_code_inherited": 0,
    "complexity_introduced": 1,
    "complexity_inherited": 0,
    "duplication_introduced": 0,
    "duplication_inherited": 0,
    "styling_introduced": 0,
    "styling_inherited": 0,
    "duplication_demoted": 0
  },
  "dead_code": {
    "schema_version": 9,
    "total_issues": 2,
    "unused_exports": [
      { "path": "src/components/Button.tsx", "export_name": "OldButton", "introduced": true, "actions": [...] }
    ]
  },
  "complexity": {
    "findings": [...]
  },
  "duplication": {
    "clone_groups": [],
    "clone_families": [],
    "stats": { "duplication_percentage": 0.0 }
  }
}

Key fields

The dead_code, complexity, and duplication sub-objects hold full results in the same format as fallow dead-code, fallow health, and fallow dupes. audit omits them when no files changed. By default, the complexity sub-object can also include the css_analytics and styling_findings blocks of the health report. When you pass --runtime-coverage, it can also include runtime_coverage and additive coverage_intelligence blocks.

MCP tool

The audit MCP tool wraps fallow audit --format json --quiet --explain:

{
  "tool": "audit",
  "arguments": {
    "base": "main",
    "gate": "new-only",
    "css_deep": true
  }
}

When you omit base, the tool resolves it as described under How it works. To pin it, set FALLOW_AUDIT_BASE in the server environment. Set gate to all for strict mode. The tool includes styling findings by default. Set css_deep to false to skip project-wide styling reachability, or to true to force it back on when config turns it off. The tool returns the same JSON envelope as the CLI.

See MCP integration for setup instructions.

Audit cache maintenance

Under --gate new-only, audit creates a temporary base snapshot (a git worktree checkout) to compare against the base ref.

• When the current checkout has node_modules, audit links it into the snapshot. tsconfig extends chains into installed packages and path aliases then resolve as in the working tree.
• audit unregisters the snapshot from git right after it creates it. The snapshot never appears in git worktree list, IDE repo views, or .git/worktrees/, even if the process is force-killed.
• The next audit deregisters entries that earlier fallow versions registered, and keeps their warm caches.

Each project root keeps one base-snapshot cache that the root owns. audit rebuilds it in place when the resolved base SHA changes. audit holds the reuse lock for the whole run, so cleanup can never remove files under a running audit.

Every audit runs an automatic age-based garbage collection (GC). The default age is 30 days. To change it, set the FALLOW_AUDIT_CACHE_MAX_AGE_DAYS env var or the audit.cacheMaxAgeDays config field. 0 turns off the age-based sweep. Two subcommands clean the caches on demand.

audit-cache remove

To remove all caches of one project, warm or not, run fallow audit-cache remove --root <PATH>:

fallow audit-cache remove --root ./my-project --dry-run   # preview what would be removed
fallow audit-cache remove --root ./my-project --yes        # remove (required in non-interactive shells)

--dry-run reports what the command would remove and does not touch the filesystem. Removal in a non-interactive shell requires --yes. The command leaves lock-contended entries (an audit is in the middle of a rebuild) in place, reports them, and exits 2.

audit-cache prune

Use fallow audit-cache prune when audit caches from deleted checkouts or old branches take disk space. It cleans up now, with a visible decision per entry, and you do not wait for the silent sweep of the next audit.

prune applies the same GC policy that every fallow audit run applies silently:

• cleanup of orphaned sidecars
• age-based reclaim under the resolved threshold
• reclaim of abandoned entries whose recorded owner root no longer exists

It reports every cache entry that it considered, with sizes and ages. It never touches entries that other live projects own.

fallow audit-cache prune --dry-run          # preview every decision without touching the filesystem
fallow audit-cache prune                    # apply the GC policy now
fallow audit-cache prune --max-age-days 7   # tighter age threshold for this run

--root is optional for prune and defaults to the current directory. The command measures sizes with a full recursive walk of each cache entry, which can take a few seconds on large caches.

Human output prints one row per considered entry, sorted by path, with the decision, reason, size, and age. An entry that stays because another live project owns it gets a hint: run audit-cache remove to clear the cache of that project. The closing line gives the total of reclaimed bytes.

prune exits 0 whenever it ran, unlike remove. This includes runs that skip entries because of lock contention (an audit is in the middle of a rebuild) and runs with per-entry failures. On a shared runner, the command reports entries of other users as kept and does not fail. Exit code 2 is only for validation errors and an unreadable scan root. Scripts gate on the complete field of the JSON envelope, not on the exit code.

With --format json, prune returns its own maintenance envelope. It is separate from the audit envelope, and sits next to the audit-cache-remove envelope:

{
  "kind": "audit-cache-prune",
  "schema_version": 1,
  "command": "audit-cache prune",
  "root": "/work/my-project",
  "scan_root": "/tmp",
  "dry_run": false,
  "max_age_days": 30,
  "max_age_source": "default",
  "entries": [
    {
      "path": "/tmp/fallow-audit-base-cache-1a2b3c4d",
      "pass": "foreign",
      "disposition": "removed",
      "reason": "aged-out",
      "age_days": 41,
      "size_bytes": 187563008,
      "owner_root": "/work/deleted-checkout"
    }
  ],
  "found": 1,
  "removed": 1,
  "kept": 0,
  "skipped": 0,
  "failed": 0,
  "complete": true,
  "reclaimed_bytes": 187563008
}

A normal audit run does its GC silently. To see the per-entry decisions, set RUST_LOG=fallow=debug. fallow audit and audit-cache prune then log one diagnostic line per considered entry, with its decision, reason, age, and threshold. With RUST_LOG unset, the audit output does not change.

Review brief and decision surface

fallow review shows a reviewer where to look in a change. It is an alias for fallow audit --brief. It produces a deterministic review brief from the module graph and always exits 0. The output includes the verdict for information only. fallow audit is the command that gates (exits non-zero on a fail verdict). --format is independent of --brief, so the brief renders in human or json like any other audit output.

The brief answers "where do I look?", not "will CI block this?". It runs the same analysis as the gating audit and organizes the result around four jobs:

Decision surface

The decision surface is the ranked set of coupling-boundary, public-api-contract, and dependency decisions in the change, capped by --max-decisions. Each decision is a framed judgment question anchored to a signal_id. fallow decision-surface prints the decision surface alone. That page documents the categories, the fields of each decision, and suppression.

JSON envelope

fallow review --format json returns decisions, focus, deltas, impact_closure, partition, and graph_facts. When the project has a CODEOWNERS file, it also returns ownership. The brief schema_version is 11 since the ownership section. A consumer can read it to detect the section.

deltas also has the dependency keys that the decision surface reads: dependency_added (<manifest>::<name>) and dependency_major_bumped (<manifest>::<name>@<from>-><to>). The envelope names what changed even when the cap collapses the decision. Both keys are always present, as empty arrays when nothing changed.

impact_closure reports the blast radius as a magnitude, a sample, and a distribution instead of one long list:

• affected_count is the exact number of files outside the diff that the change reaches, computed before any cap.
• affected_not_shown is a path-sorted sample of at most ten of those files. It is a prefix of the sorted set, so it clusters in the directory that sorts first. Use it to open representative files. Do not use it to list the full reach or to infer its shape.
• affected_by_dir gives the shape as { dir, count } rows: heaviest directory first, the directory path as tie-breaker, at most twenty-five rows. affected_by_dir_omitted counts the lighter directories that did not fit. The count in every row is exact.
• coordination_gap is separate and has no cap. It is not a subset of the sample. It skips, on purpose, the story and test consumers that the affected set counts.

partition has independent_slices only when there are two or more slices. A slice is a connected component of the dependency graph between units, given as a sorted list of module directories. Two or more slices mean that the change splits along a seam that the graph proves, into pieces that you can review and merge separately. A single slice would only repeat order, so fallow leaves the field out. The field helps you orient. It never asks you to split the change.

ownership shows how many CODEOWNERS owner groups the change reaches:

• group_count counts the owner groups of the changed files and of the impact closure. (unowned) counts as one group.
• transitive_only_count counts the groups that own no changed file and that the change reaches only through the impact closure.
• unowned_direct_count counts the changed files that no CODEOWNERS rule owns.
• groups is a capped list of { owner, direct_count, affected_count } rows, sorted by direct_count (highest first), then affected_count (highest first), then owner. groups_omitted counts the groups that did not fit.
• slices is present only when partition.independent_slices is present, with the same order. Each entry is { module_dirs, owners, separable }. separable is true when the slice has one owner.

Each file maps to its primary owner: the last matching rule, and the first owner of that rule. The section reads only the CODEOWNERS file (the configured codeowners path, else the standard locations), so it does not need git history. routing reads the same configured path. Without a readable CODEOWNERS file, the ownership key is absent. A configured path that fallow cannot read prints a warning. The human output lists the owner groups, and names each slice that has one owner. Fallow does not split the change: the reviewer decides.

Agent walkthrough loop

The walkthrough guide turns the brief into a strict contract with a coding agent. The graph checks the agent, not a second model. Fallow validates every judgment that the agent returns against the live graph. Fallow fences the free-text framing of the agent as non-deterministic, and that framing never gates.

1. Fetch the guide.

fallow review --base main --walkthrough-guide --format json

The response has digest (brief + decision surface), direction, graph_snapshot_hash, agent_schema, injection_note, emitted_signal_ids, and change_anchors. Fallow builds the digest from the graph only and never adds PR prose, so the digest resists injection. The snapshot hash is pinned into the digest.

Each direction.units[] entry has test_adjacency:

• none: no test file imports the changed unit directly.
• untouched: a test imports the unit, and none of those tests is in the diff.
• changed: at least one importing test changed together with the unit.

The field is absent when the graph was not retained or the unit is itself a test file. It is a graph fact about direct importers, not a coverage claim. Mocks, fixtures and snapshots help tests but are not tests, so an importer under __mocks__/, fixtures/, __fixtures__/ or __snapshots__/, or a *.fixture.* file, does not count. An importer inside a test directory, such as test/fixtures/, still counts.

agent_schema publishes two lists:

• action_vocabulary (block, address, consider, fyi): the closed set of values for the action of a judgment.
• a recommended concern_vocabulary with the thirteen trade-off lenses: abstraction, coupling, data-model, error-handling, control-flow, performance, dependencies, api-ergonomics, compatibility, state-ownership, extensibility, testability, trust-boundary.

concern stays free text in the JSON. A value from the list lets a review tool group judgments by lens.

change_anchors has one stable chg: id per changed region (hunk), derived from the same diff source that the run used. The id is content-addressed (file path + normalized added text, without line numbers). It survives an edit above the hunk and a whitespace-only change, and it survives a rename through previous_change_anchor. With a change anchor, an agent can anchor a judgment about a changed REGION that has no graph finding (a trade-off with no signal_id). Fallow can then validate that broader trade-off, so the agent cannot invent it.

2. The agent returns judgment JSON. Each judgment cites a signal_id OR a change_anchor that fallow emitted. The agent echoes the hash.

{
  "graph_snapshot_hash": "<echoed>",
  "judgments": [
    {
      "signal_id": "<one fallow emitted>",
      "change_anchor": "<or one fallow emitted chg: id, for a changed region with no finding>",
      "framing": "<reasoning>",
      "concern": "<optional>",
      "action": "<optional: block | address | consider | fyi>"
    }
  ]
}

action tells the author of the change what to do with the judgment. block and address are required actions, consider is optional, and fyi needs nothing. It is the instruction of the reviewer. Fallow fences it together with the framing, and it never gates.

3. Post-validate the judgment against the live graph.

fallow review --base main --walkthrough-file judgment.json --format json

Fallow sorts each judgment into one of these outcomes:

An accepted judgment echoes action next to agent_framing when the agent set one.

See also