fallow audit

Audit changed files for dead code, complexity, duplication, and styling. Returns a pass, warn, or fail verdict based on the severity of issues found. Scoping to changed files keeps signal-to-noise high: by default only issues introduced by the current PR or commit fail the gate; inherited findings in touched files are shown as context.

fallow audit

Options

Base ref

Diff scoping

Gate

The gate has three surface forms. They all accept the same values (new-only, all) and the precedence is 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 so it can attribute each finding as introduced or inherited. When every changed file is either a non-behavioral doc (.md, .markdown, .txt, .rst, .adoc) or token-equivalent at the base ref (a comment-only or whitespace-only edit on a .ts/.tsx/.js/.jsx/.mjs/.mts/.cjs/.cts source file), audit reuses the current run's findings as the base snapshot, classifies everything as inherited, and skips the second worktree analysis entirely. Common case: docs-only PRs and formatter sweeps complete in roughly one analysis pass instead of two.

Run fallow audit --base main --gate new-only --performance to see whether the fast path fired: the JSON output includes base_snapshot_skipped: true|false and the human output prints the same on stderr. The optimization activates automatically whenever every entry in the diff qualifies; there is no flag to opt in or out.

New-only duplication demotion

Clone-group attribution carries one carve-out under --gate new-only: an introduced clone group none of whose instances overlap an added line from the run's diff is demoted to inherited. This covers changes that remove duplication elsewhere and thereby re-shape a surviving clone group into a new structural key: the group is new to the report, but no duplicated line was written by this change, so it does not fail the gate.

Every demotion is observable. The gate-excluded note on stderr gains a sub-line naming 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, capped like the clone listing: the group's dup:<fingerprint> id (matching the listing and fallow dupes --trace), its instance locations, and the deciding rule, plus a closing line naming the diff source. In JSON, each demoted entry in duplication.clone_groups[] carries 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 supplied via --diff-file, --diff-stdin, or FALLOW_DIFF_FILE wins over the merge-base worktree diff. A supplied diff computed against a narrower base than the merge base (for example a last-commit-only diff on a multi-commit branch) can demote duplication the branch genuinely introduced, so derive supplied diffs from the same base the audit compares against. When no diff is available at all, the check is skipped and every introduced clone group keeps gating.

Output

Review brief

Scoping

Thresholds

Baselines

The global --baseline / --save-baseline flags are rejected on audit (exit 2) because audit runs three analyses with incompatible baseline formats. Use the per-analysis flags above, or configure 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/, because fallow init adds that directory to .gitignore for machine-local cache.

CLI flags override config. Baselines are a no-op if unset; any subset (e.g. dead-code only) is allowed.

Verdict

Dead code issues follow your rules configuration severity (error/warn/off). Complexity findings above configured thresholds are always errors; thresholds are inherited from your fallow health config (defaults: cyclomatic 20, cognitive 15). Duplication is a warning unless a --threshold is configured. With the default new-only gate, inherited error-severity findings can appear in the report while the audit exits 0.

JSON contract: which fields are severity-aware

Audit emits three counts that look interchangeable but answer different questions. CI integrations and downstream consumers must gate on the right one:

Rule of thumb for CI gating: branch on verdict == "fail" (or check the exit code, which mirrors the verdict). Counting introduced findings re-introduces the bug command: audit was designed to fix: a project with unused-exports: warn would fail CI on every PR that introduces a warn-tier finding, even though the verdict correctly says warn ("do not fail"). The official GitHub Action and GitLab CI template already do this; third-party wrappers should mirror the same contract.

Rule of thumb for AI agents: read verdict first to know whether the run passed or failed, then read attribution for new-vs-inherited counts and walk the per-category finding arrays for actionable details. Use introduced: true to filter to changes the current PR is responsible for.

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. It is suppressed with --quiet.

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 not imported by any reachable file: 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 thresholds: 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: uses --base if provided, then FALLOW_AUDIT_BASE, otherwise auto-detects the git merge-base (fork point) against the branch's upstream (@{upstream}) or the remote default (origin/HEAD → origin/main → origin/master). Resolving the merge-base, rather than a bare branch name, means a feature branch compares against where it actually forked rather than a possibly-stale local main. Repositories with no origin remote fall back to the local main / master branch. Hard-errors if no base can be determined.
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, runs the same analyses at the base ref and compares structural issue keys.
5. Compute verdict: new-only gates only introduced findings; all gates every finding in changed files without the extra base-snapshot analysis.

JSON output

{
  "schema_version": 10,
  "version": "3.23.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": [],
    "stats": { "duplication_percentage": 0.0 }
  }
}

Key fields

The dead_code, complexity, and duplication sub-objects contain full results in the same format as fallow dead-code, fallow health, and fallow dupes respectively. These are omitted when no files changed. By default, the complexity sub-object can also include the health report's css_analytics and styling_findings blocks. When --runtime-coverage is supplied, 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 base is omitted it resolves as described under How it works; set FALLOW_AUDIT_BASE in the server env to pin it. Set gate to all for strict mode. Styling findings are included by default; set css_deep to false to skip project-wide styling reachability, or true to force it back on when config disables it. 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 so tsconfig extends chains into installed packages and path aliases resolve like the working tree. Snapshots are unregistered from git immediately after materialization, so they never appear in git worktree list, IDE repo views, or .git/worktrees/, even if the process is force-killed. Entries registered by earlier fallow versions are deregistered automatically on the next audit, with their warm caches preserved.

Each project root keeps one root-owned base-snapshot cache, rebuilt in place when the resolved base SHA changes, and the reuse lock is held for the whole audit so cleanup can never remove files under a running audit. Automatic age-based GC runs on every audit: the FALLOW_AUDIT_CACHE_MAX_AGE_DAYS env var (or the audit.cacheMaxAgeDays config field) tunes the 30-day default, and 0 disables the age-based sweep. Two subcommands maintain the caches on demand.

audit-cache remove

To reclaim one project's caches unconditionally (warm or not), use 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 would be removed without touching the filesystem, and non-interactive removal requires --yes. Lock-contended entries (an audit is mid-rebuild) are left in place and reported, and the command exits 2.

audit-cache prune

fallow audit-cache prune applies the same GC policy every fallow audit run applies silently (orphaned-sidecar cleanup, age-based reclaim under the resolved threshold, and reclaim of abandoned entries whose recorded owner root no longer exists) and reports every cache entry it considered, with sizes and ages. Entries owned by other live projects are never touched. Reach for it when audit caches from deleted checkouts or long-gone branches are holding disk space and you want the cleanup now, with a visible decision per entry, instead of waiting for the next audit's silent sweep.

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. Reported sizes come from 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. Entries kept because another live project owns them come with a hint naming audit-cache remove as the way to clear that project's own cache, and the closing line totals the reclaimed bytes.

Unlike remove, prune exits 0 whenever it ran, including runs with lock-contention skips (an audit is mid-rebuild) or per-entry failures; on a shared runner, entries owned by other users are reported as kept rather than failing the invocation. Exit code 2 is reserved for validation errors and an unreadable scan root. Machine consumers gate on the complete field of the JSON envelope, not the exit code.

With --format json, prune emits its own maintenance envelope, separate from the audit envelope and a sibling of 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
}

To see the same per-entry decisions during a normal audit run (where the GC is silent), set RUST_LOG=fallow=debug: both 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, audit output is unchanged.

Review brief and decision surface

fallow review is an alias for fallow audit --brief. It produces a deterministic, graph-derived review brief and always exits 0: the verdict is carried informationally, unlike fallow audit, which gates (exits non-zero on a fail verdict). --format is orthogonal to --brief, so the brief renders in human or json like any other audit output.

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

Decision surface

The decision surface is the ranked, capped (--max-decisions) set of coupling-boundary, public-api-contract, and dependency decisions the change embeds, each a framed judgment question anchored to a signal_id. fallow decision-surface emits it on its own and documents the categories, the fields each decision carries, and suppression.

JSON envelope

fallow review --format json carries decisions, focus, deltas, impact_closure, partition, and graph_facts.

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

partition carries independent_slices only when there are two or more of them: the connected components of the inter-unit dependency graph, each a sorted list of module directories. Two or more slices mean the change splits along a graph-proven seam into pieces that can be reviewed and merged on their own; a single slice would only repeat order, so the field is absent. An orientation fact, never a demand to split.

Agent walkthrough loop

The walkthrough guide turns the brief into a strict agent contract. The verifier is the graph, not a second model: every judgment an agent returns is post-validated against the live graph, and the agent's free-text framing is fenced as non-deterministic and never gates.

1. Fetch the guide.

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

Returns digest (brief + decision surface), direction, graph_snapshot_hash, agent_schema, injection_note, emitted_signal_ids, and change_anchors. The digest is built from the graph only (PR prose is never folded in, so it is injection-resistant), and the snapshot hash is pinned into the digest.

Each direction.units[] entry carries test_adjacency: none (no test file imports the changed unit directly), untouched (a test imports it and none of those tests is in the diff), or changed (at least one importing test moved with the change). It is absent when the graph was not retained or the unit is itself a test file. A graph fact about direct importers, not a coverage claim.

agent_schema publishes action_vocabulary (block, address, consider, fyi), the closed set a judgment's action may use, and a recommended concern_vocabulary (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 on the wire; a value from the list lets a review surface group judgments by lens.

change_anchors is a per-hunk anchor set: one stable, content-addressed chg: id per changed region, derived from the same diff source the run used. Its id is content-addressed (file path + normalized added text, line numbers excluded) so it survives an edit above the hunk and a whitespace-only change, and it is rename-durable via previous_change_anchor. It lets an agent anchor a judgment about a changed REGION that has no graph finding (a trade-off with no signal_id), so the broader trade-off can still be post-validated rather than hallucinated.

2. The agent returns judgment JSON. Each judgment cites a signal_id fallow emitted OR a change_anchor fallow emitted; echo 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 receiving author what to do with the judgment: block and address are required actions, consider is optional, fyi needs nothing. It is the reviewer's instruction, fenced with the framing, never a gate.

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

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

Each judgment is sorted into one of these outcomes:

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

See also