# Adopt Fallow in an existing repo
Source: https://docs.fallow.tools/adoption

Bring an existing TypeScript or JavaScript codebase to a clean Fallow policy, then keep new changes clean with fallow audit. Drive the cleanup with an AI agent.

This guide is for repositories that already have backlog: unused code, duplicates, complexity hotspots, and existing exceptions.

By the end of this guide you will have:

* a repo-level Fallow policy encoded in config
* dead code fixed or intentionally modeled
* duplication at or below your chosen threshold
* complex functions refactored or consciously widened with a written justification
* `fallow audit` enforcing the same policy on changed files

## Repo clean vs PR clean

These are different goals. Both matter. Do them in order.

<CardGroup>
  <Card title="Repo clean (this guide)" icon="broom">
    Full-repo analysis to understand and clean the whole codebase.
    Use `fallow`, `fallow dead-code`, `fallow dupes`, and `fallow health`.
  </Card>

  <Card title="PR clean" icon="shield-check" href="/cli/audit">
    Changed-files gate that enforces the policy on every PR.
    Use `fallow audit` after the repo is clean.
  </Card>
</CardGroup>

Start with repo clean. Then turn on PR clean.

## Before you start

<CardGroup>
  <Card title="Coming from knip?" icon="right-left" href="/migration/from-knip">
    Run `fallow migrate` first to port your knip config, then follow this guide.
  </Card>

  <Card title="Large monorepo?" icon="folder-tree" href="/configuration/workspaces">
    Apply this flow per workspace package. Use `fallow --workspace <name>` and a shared root config.
  </Card>
</CardGroup>

## 1. First run: get the whole picture

From your project root:

```bash theme={null}
npx fallow
```

The [quick start](/quickstart) covers the focused commands you will use during cleanup (`dead-code`, `dupes`, `health`) and `fallow init` for generating a starting config.

## 2. Decide the project policy before triage

Do not start by suppressing findings one by one. That path turns into an ever-growing list of inline exceptions and no coherent policy.

<Info>
  Not the policy owner? Run section 3 first on a branch, then bring the findings into the policy discussion. Fallow output is a good forcing function for the "what do we actually care about" conversation.
</Info>

First decide, as a team:

* what counts as a real entry point (workers, scripts, route files, dynamically loaded modules)
* which files are generated or out of scope
* which packages are public APIs that ship exports outside the repo
* which dependencies are runtime-provided or intentionally retained
* which health thresholds you actually want to enforce
* whether duplication should warn or fail

A reasonable starting point:

```jsonc theme={null}
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "ignorePatterns": ["**/*.generated.ts", "**/*.d.ts"],
  "rules": {
    "unresolved-imports": "error",
    "unlisted-dependencies": "error",
    "unused-exports": "warn"
  }
}
```

Rules you do not list inherit their defaults. Health thresholds default to `maxCyclomatic: 20` and `maxCognitive: 15`; override in a `health` block only when your repo's realistic baseline differs.

<Tip>
  Use `warn` during rollout when you need visibility without blocking CI. Promote rules to `error` as the backlog shrinks. See the [rules reference](/configuration/rules) for every issue type and severity.
</Tip>

## 3. Work findings in the right order

Use this order for most existing repos. Each step removes noise that would otherwise distort the next step.

<Steps>
  <Step title="Fix unresolved imports and unlisted dependencies">
    High confidence, low debate. These are real bugs waiting to happen and should be cleared first.

    ```bash theme={null}
    npx fallow dead-code --unresolved-imports
    npx fallow dead-code --unlisted-deps
    ```
  </Step>

  <Step title="Delete unused files">
    Unreachable files are usually safe cleanup. Use `fallow list --entry-points` to sanity-check reachability before deleting anything you are unsure about.

    ```bash theme={null}
    npx fallow dead-code --unused-files
    npx fallow list --entry-points
    ```
  </Step>

  <Step title="Remove unused dependencies">
    Remove dead packages early. This reduces noise in later steps and speeds up installs.

    ```bash theme={null}
    npx fallow dead-code --unused-deps
    ```
  </Step>

  <Step title="Clean up unused exports, types, enum members, and class members">
    Usually the biggest category. Fix real dead code. Model intentional API surface with visibility tags or config instead of suppressing it. Hand this step to an agent using the [prompt in section 8](#8-clean-up-with-an-agent).

    ```bash theme={null}
    npx fallow dead-code --unused-exports --unused-types
    ```

    Add `--unused-enum-members` and `--unused-class-members` when you want to focus on those categories explicitly. In a TypeScript project, add `--type-aware` when aliases, re-exports, class contracts, packages, or exact consumers affect the decision. This starts an optional, slower semantic pass. See [Type-aware TypeScript analysis](/analysis/type-aware) and the [`fallow dead-code` reference](/cli/dead-code).
  </Step>

  <Step title="Consolidate duplication">
    Merge repeated logic into shared helpers. Only ignore generated or template-heavy files when the duplication is genuinely intentional.

    ```bash theme={null}
    npx fallow dupes
    npx fallow dupes --mode semantic   # also catch renamed-variable clones
    ```
  </Step>

  <Step title="Split health hotspots">
    `fallow health` output includes Hotspots and Targets sections that rank the worst offenders. Use those to prioritize. Do not bike-shed every file above the mean.

    ```bash theme={null}
    npx fallow health
    ```
  </Step>
</Steps>

## 4. Match the reason to the right mechanism

Do not default to inline suppression. Pick the mechanism that matches the reason.

### External or public API

Exports consumed outside the repo (published libraries, SDKs, public packages).

Prefer, in order:

* `@public`, `@internal`, `@beta`, `@alpha` JSDoc visibility tags on the export
* [`publicPackages`](/configuration/overview#publicpackages) as the coarse switch for "this whole package is external API"
* [`ignoreExports`](/configuration/overview#ignoreexports) only when file-level or export-level exceptions cannot be expressed any other way

`publicPackages` and visibility tags are complementary, not alternatives: `publicPackages` marks the package as externally consumed; `@public`/`@internal` tags distinguish public API from internal helpers that happen to be exported for cross-file use.

### Framework or runtime-discovered entry points

Files your framework or runtime invokes but no other module imports directly (workers, CLI scripts, route files, plugin modules).

Prefer, in order:

* built-in plugin detection (Next.js, Vite, NestJS, Remotion, and [dozens more](/frameworks/built-in) are handled out of the box)
* [`entry`](/configuration/overview#entry) for project-specific entry globs
* [`dynamicallyLoaded`](/configuration/overview#dynamicallyloaded) for code pulled in through reflection, manifests, or dynamic imports
* `fallow list --entry-points` to inspect what Fallow already considers reachable

### Generated or vendored files

Files produced by a build step, code generator, or vendored third-party bundle.

Prefer:

* [`ignorePatterns`](/configuration/overview#ignorepatterns) to exclude them from analysis entirely
* `health.ignore` when the noise is health-only and dead-code analysis should still run
* duplication configuration for clone-heavy generated code

### Runtime-provided or intentionally retained dependencies

Packages installed for runtime usage only (no static import), CLI tools, or peer dependencies.

Prefer:

* [`ignoreDependencies`](/configuration/overview#ignoredependencies) with the exact package names

### One-off intentional unused export

An export you want to keep around deliberately (compatibility shims, future API).

Prefer:

* `/** @expected-unused */` on the export

<Tip>
  `@expected-unused` is self-cleaning. Unlike inline `fallow-ignore` comments, Fallow tracks the tag for staleness: the moment the export becomes imported, the tag is reported as a stale suppression so you can remove it. Use it liberally for shims and future API surface.
</Tip>

### One-off false positive

A specific site where Fallow is wrong and no config rule captures the reason cleanly.

Prefer:

* `// fallow-ignore-next-line <issue>` on the line above
* `// fallow-ignore-file <issue>` only when the whole file is truly exceptional

### Repo-wide policy change

The project genuinely has a different standard for a whole category.

Prefer:

* `rules`, `health`, duplication thresholds, or `overrides` blocks

Do this only when it reflects a real team policy, not to hide a few ugly hotspots.

<Info>
  See [suppression](/configuration/suppression) for the full decision tree and examples, and [configuration overview](/configuration/overview) for every key.
</Info>

## 5. Keep exceptions narrow and reviewable

Narrow exceptions are an asset. Broad exceptions are a debt.

Good:

* a single `@public` export on a library entry point
* one `ignoreDependencies` entry for a runtime-provided package
* one `entry` pattern for worker scripts
* one file-level generated-code ignore with a comment explaining why

Bad:

* broad `ignorePatterns` that silently exclude half the repo
* repeated inline suppressions that could be one config rule
* raising global `health.maxCyclomatic` to hide a handful of hotspots (acceptable only when the new threshold reflects a thought-through project standard with written justification)

If you cannot explain an exception in one sentence, it is probably the wrong mechanism.

## 6. Define done

Work in two stages. Most teams ship `fallow audit` at the end of stage 1 and finish stage 2 over the following weeks.

### Stage 1: good enough to ship `fallow audit`

* the chosen policy is encoded in config, not accumulated in scattered suppressions
* unresolved imports and unlisted dependencies are cleared
* blatant dead code (unused files, unused dependencies) is removed
* `fallow audit` is wired into CI and passes for new changes against the default branch

### Stage 2: ideal state

* no functions above your chosen health thresholds, either by refactoring or by consciously widening the threshold with written justification
* duplication at or below the chosen threshold
* stale suppressions gone or consciously accepted

## 7. Turn on PR enforcement

Once stage 1 is done, add the PR gate:

```bash theme={null}
npx fallow audit
```

`fallow audit` runs dead code, duplication, and complexity analysis scoped to changed files, then returns a `pass`, `warn`, or `fail` verdict. See the [`fallow audit` reference](/cli/audit) for flags and CI recipes.

### Pick one rollout strategy

<Tabs>
  <Tab title="Option A: warn-everywhere">
    Best for smaller teams. CI never blocks; fixes land under social pressure.

    ```jsonc theme={null}
    {
      "rules": {
        "unused-exports": "warn",
        "unused-files": "warn",
        "unused-dependencies": "warn"
      }
    }
    ```

    Risk: warn-only gates become warning-forever gates. Set a calendar reminder to promote rules to `error` after the first clean month.
  </Tab>

  <Tab title="Option B: error + baselines">
    Best for larger orgs. CI blocks on new issues; pre-existing debt on touched files is baselined.

    ```bash theme={null}
    # Save baselines once on the default branch
    fallow dead-code --save-baseline fallow-baselines/dead-code.json
    fallow health    --save-baseline fallow-baselines/health.json
    fallow dupes     --save-baseline fallow-baselines/dupes.json

    # Audit only new issues on PRs
    fallow audit \
      --dead-code-baseline fallow-baselines/dead-code.json \
      --health-baseline    fallow-baselines/health.json \
      --dupes-baseline     fallow-baselines/dupes.json
    ```

    Store committed baselines outside `.fallow/` (which `fallow init` adds to `.gitignore` for machine-local cache). `fallow-baselines/` is the recommended default. Commit the baseline files so every PR compares against the same snapshot, and regenerate on a schedule (quarterly, or per release) rather than per merge, otherwise teams silently absorb new debt every time CI runs.
  </Tab>

  <Tab title="Option C: local agent gate">
    Best when Claude Code is the main pusher. Add a project-level `PreToolUse` hook that intercepts `git commit` and `git push`, runs `fallow audit --format json --quiet --explain`, and blocks only on `verdict: "fail"`. Claude receives the raw audit JSON on stderr, fixes the findings, and retries the command.

    Pair this with Option A or B, not instead of them. This is a local reinforcement layer. Keep CI on `fallow audit` so human pushes and non-Claude workflows are still covered.

    Runtime errors (no base ref yet, first commit in an empty repo, config errors) fail open so new repos do not get stuck.

    See [Claude Code hooks](/integrations/claude-hooks) for the full recipe, or generate the files with:

    ```bash theme={null}
    fallow hooks install --target agent
    ```
  </Tab>
</Tabs>

You can also configure baselines in `.fallowrc.json` and run `fallow audit` with no flags:

```jsonc theme={null}
{
  "audit": {
    "deadCodeBaseline": "fallow-baselines/dead-code.json",
    "healthBaseline":   "fallow-baselines/health.json",
    "dupesBaseline":    "fallow-baselines/dupes.json"
  }
}
```

<Warning>
  Baselines are a debt ledger, not a steady state. If the baseline file only grows, the policy is not being enforced.
</Warning>

## 8. Clean up with an agent

Fallow finds the problems. An AI agent (Claude Code, Cursor, Codex, Windsurf, any shell-capable coding assistant) is the right tool to fix them: edits are mechanical but decisions ("delete this export" vs. "mark it `@public`" vs. "add it to `entry`") benefit from code-aware judgement.

Three levels of integration, pick whichever your agent supports:

<CardGroup>
  <Card title="Skills (best)" icon="wand-magic-sparkles" href="/integrations/agent-skills">
    Install `fallow-skills` for Claude Code, Cursor, Windsurf, or any Agent Skills compatible agent. Once installed, the skill works offline; the agent does not need to fetch docs URLs during use.
  </Card>

  <Card title="MCP" icon="robot" href="/integrations/mcp">
    Structured tool calling with JSON output and `_meta` explanations. Works alongside skills.
  </Card>

  <Card title="Plain shell" icon="terminal">
    Any agent that can run a shell command can drive Fallow. Use the copy-paste prompt below.
  </Card>
</CardGroup>

<Accordion title="Copy-paste adoption prompt (for agents without skills or MCP)">
  Paste this prompt into your agent. It is self-contained: the agent does not need to fetch this page to follow it.

  ```text theme={null}
  Adopt Fallow in this repository.

  Goal:
  - use full-repo analysis first (`fallow`, `fallow dead-code`, `fallow dupes`, `fallow health`), not `fallow audit`
  - fix real dead code, duplication, and complexity issues in code
  - model intentional exceptions with the narrowest correct mechanism
  - end with no functions above the repo's chosen health thresholds, or a consciously widened threshold with written justification
  - then set up `fallow audit` as a PR gate

  Process:
  1. Run `npx fallow`, then `npx fallow dead-code`, `npx fallow dupes`, and `npx fallow health`. Use `--format json` if you want structured output.
  2. If no config exists, run `fallow init` and create a minimal repo policy.
  3. Fix high-confidence issues first:
     - unresolved imports
     - unlisted dependencies
     - unused files (sanity-check with `fallow list --entry-points`)
     - unused dependencies
  4. For each remaining finding, choose one path:
     - fix it in code (preferred)
     - model it in config
     - add a narrow inline exception only if it is truly one-off
  5. Match reasons to mechanisms:
     - external API: `@public` / `@internal` / `@beta` / `@alpha`, or `publicPackages`
     - runtime or framework entry point: `entry`, `dynamicallyLoaded`, plugin-aware config
     - generated code: `ignorePatterns`, `health.ignore`
     - intentionally retained dependency: `ignoreDependencies`
     - intentional unused export: `@expected-unused` (preferred over inline comments because it self-cleans)
     - one-off false positive: `fallow-ignore-next-line`
     - repo-wide policy: `rules`, `health`, duplication settings, `overrides`
  6. Prefer config-level modeling over repeated suppression.
  7. Keep every exception narrow and explain why it exists in a commit message.
  8. Re-run Fallow after each batch until the repo is clean under the chosen policy.
  9. Only after repo cleanup, run `npx fallow audit` and wire it into CI.

  At the end, report:
  - code changes
  - config changes
  - exceptions added and why
  - anything left
  - the final commands and outputs that show the repo is clean
  ```
</Accordion>

## Next steps

<CardGroup>
  <Card title="fallow audit" icon="shield-check" href="/cli/audit">
    Enforce the policy on changed files in CI.
  </Card>

  <Card title="Configuration overview" icon="gear" href="/configuration/overview">
    Every config key, with examples.
  </Card>

  <Card title="Suppression" icon="comment-slash" href="/configuration/suppression">
    Visibility tags, inline comments, and when to use each.
  </Card>

  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/integrations/agent-skills">
    Install `fallow-skills` for agent-driven adoption.
  </Card>
</CardGroup>


# Auto-fix
Source: https://docs.fallow.tools/analysis/auto-fix

Automatically remove unused exports and dependencies from your TypeScript and JavaScript codebase. Supports dry-run preview and non-interactive agent workflows.

`fallow fix` removes unused exports and unused dependencies from your codebase.

In agent workflows, `fallow fix --yes --format json` cleans up dead code non-interactively after code generation.

<Tip>
  Always commit your changes before running `fallow fix`. Git lets you undo if needed.
</Tip>

## Recommended workflow

<Steps>
  <Step title="Preview changes">
    Run a dry run to see exactly what would be removed without making any changes.

    ```bash theme={null}
    fallow fix --dry-run
    ```

    ```bash title="$ fallow fix --dry-run" theme={null}
    Would remove export from src/components/Card/index.ts:1 `CardFooter`
    Would remove export from src/providers/trpc-provider/index.tsx:12 `TRPCProvider`
    Would remove export from src/server/jobs/queue.ts:61 `enqueueJobDelayed`
    Would remove export from src/server/jobs/queue.ts:206 `sweepStuckProcessingJobs`
    Would remove export from src/server/jobs/queue.ts:276 `getDeadLetterJobs`
    Would remove `@trpc/react-query` from dependencies

    6 fixes available (5 exports, 1 dependency). Run without --dry-run to apply.
    ```
  </Step>

  <Step title="Review the output">
    Check that every proposed removal is safe. Pay attention to exports consumed by external packages or dynamic imports that fallow can't detect statically.

    ```bash theme={null}
    fallow fix --dry-run --format json
    ```
  </Step>

  <Step title="Apply fixes">
    After reviewing the preview, apply the changes. In interactive terminals, fallow asks for confirmation before writing.

    ```bash theme={null}
    fallow fix
    ```

    In CI or non-TTY environments, use `--yes` to skip confirmation:

    ```bash theme={null}
    fallow fix --yes
    ```

    <Info>
      Agents typically use `fallow fix --yes --format json` to apply fixes non-interactively. The JSON output confirms exactly what was changed, so the agent can verify the result.
    </Info>
  </Step>

  <Step title="Verify the result">
    Run your build and tests to confirm nothing broke.

    ```bash theme={null}
    npm run build && npm test
    ```
  </Step>
</Steps>

## What gets fixed

* **Unused exports**: the `export` keyword is removed, keeping the declaration. For exported enums where the enum itself is never referenced outside its body in the file, the entire `enum` block is deleted.
* **Unused dependencies**: removed from `package.json` when they are not imported by another workspace
* **Unused enum members**: removed from the enum declaration. When every member of an exported enum is unused, the whole declaration is deleted in one pass instead of leaving behind an empty `export enum X {}` shell. Importers in other files now reference a name that no longer exists, so run your TypeScript build to find and clean them up.
* **Unused pnpm catalog entries**: removed from `pnpm-workspace.yaml` by line-aware deletion. Object-form entries are removed as one block. By default, fallow also removes a contiguous YAML comment block immediately above the entry when it clearly belongs to that entry; configure this with [`fix.catalog.deletePrecedingComments`](/configuration/overview) (`"auto"`, `"always"`, or `"never"`). Other comments and stylistic choices in the file are preserved. When the last entry of a catalog group is removed, the header is rewritten to `catalog: {}` (or `<name>: {}`) instead of leaving bare `catalog:`, because pnpm rejects null-valued catalogs with `Cannot convert undefined or null to object` at install time. After a successful catalog edit fallow reminds you to run `pnpm install` so `pnpm-lock.yaml` stays in sync.

<Warning>
  Auto-fix does not delete entire files. Class methods are eligible only when type-aware analysis supplies complete evidence that they are unused and the declaration still matches the analyzed source. Other class members require manual review.
</Warning>

## Incomplete analysis

If source files could not be read or parsed completely, or discovery skipped source files, affected findings carry `reachability_caveats`. Read `workspace_diagnostics` for the files and reasons. The finding remains visible, but its removal is withheld from `fallow fix`, editor quick fixes, MCP fixes, and one-click review suggestions.

Caveats can apply to unused files, exports, types, dependencies, enum members, and class members. An unseen import can point outside the affected file, so a caveat may apply across the project. Resolve the diagnostic and rerun the analysis before applying the proposed removal. A type-aware result does not override incomplete source evidence.

## `auto_fixable` is per-finding, not per action type

Every action in a finding's `actions[]` array carries an `auto_fixable` bool. The value is evaluated **per finding**, not per action type: the same action type may appear with `auto_fixable: true` on one finding and `auto_fixable: false` on another, depending on per-instance guards in the `fallow fix` applier.

Agents that filter on `auto_fixable: true` to decide what is safe to apply blindly must branch on the bool of each individual action, not on the action `type` alone.

Per-instance flips today:

* **`remove-catalog-entry`** (unused-catalog-entries): `true` only when the finding's `hardcoded_consumers` array is empty. When a workspace package still pins a hardcoded version of the same package, `fallow fix` skips the entry to avoid breaking `pnpm install`, and the action is emitted with `auto_fixable: false`.
* **`remove-dependency` vs `move-dependency`** (dependency findings): when the finding's `used_in_workspaces` array is non-empty, the primary action flips to `move-dependency` with `auto_fixable: false` because `fallow fix` will not remove a dependency that another workspace imports. On findings without cross-workspace consumers the action stays `remove-dependency` with `auto_fixable: true`.
* **`add-to-config` for `ignoreExports`** (duplicate-exports): `true` when `fallow fix` can safely apply the action, which today means EITHER a fallow config file already exists OR no config exists and the working directory is NOT inside a monorepo subpackage. In the second case the applier creates `.fallowrc.json` using the same scaffolding `fallow init` emits and layers the new rules on top. `false` inside a monorepo subpackage with no workspace-root config, because the applier refuses to fragment per-package configs across the monorepo and points at the workspace root instead. Pass `--no-create-config` to `fallow fix` from pre-commit hooks, CI bots, and `fallow watch` to opt out of the create-fallback; the action then surfaces with `auto_fixable: false` and is skipped at apply time.
* **`update-catalog-reference`** (unresolved-catalog-references): always `false` today. The catalog-switching applier is not yet wired; the field is non-singleton so future enablement does not require a schema change.

All `suppress-line` and `suppress-file` actions are uniformly `auto_fixable: false`.

## JSON output

For scripting, CI, and agent workflows:

```bash theme={null}
fallow fix --dry-run --format json
```

```json theme={null}
{
  "dry_run": true,
  "fixes": [
    {
      "type": "remove_export",
      "path": "src/greet.ts",
      "line": 2,
      "name": "unusedGreeting"
    }
  ],
  "total_fixed": 0,
  "skipped": 0,
  "skipped_content_changed": 0,
  "skipped_mixed_line_endings": 0,
  "skipped_low_confidence_exports": 0,
  "skipped_low_confidence_dependencies": 0,
  "skipped_low_confidence_members": 0
}
```

`fixes` lists the proposed actions. During a dry run, `total_fixed` stays at `0` because no files were changed. Paths are relative to the project root.

## See also

<CardGroup>
  <Card title="CLI: fix" icon="terminal" href="/cli/fix">
    Full reference for the `fallow fix` command and its flags.
  </Card>

  <Card title="Dead Code Analysis" icon="skull-crossbones" href="/analysis/dead-code">
    Understand what fallow detects before auto-fixing.
  </Card>
</CardGroup>


# Architecture boundaries
Source: https://docs.fallow.tools/analysis/boundaries

Enforce architecture rules with directory-based import boundaries. Define zones for UI, data, and shared code. Fallow catches violations at Rust speed.

`fallow dead-code` enforces architecture boundaries by checking that imports between directories follow your rules. Define <Tooltip>zones</Tooltip> and declare which zones may import from which.

```bash theme={null}
fallow dead-code --boundary-violations
```

<Info>
  Boundary violations are included in `fallow dead-code` output by default. Use `--boundary-violations` to show only boundary issues.
</Info>

## Quick start with presets

The fastest way to add boundaries is with a built-in preset. Fallow ships four presets for common architecture patterns:

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "preset": "bulletproof"
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [boundaries]
  preset = "bulletproof"
  ```
</CodeGroup>

Run `fallow list --boundaries` to see the expanded zones and rules:

```bash title="$ fallow list --boundaries" theme={null}
Boundaries: 5 zones, 5 rules

Zones:
  app                  3 files  src/app/**
  features/auth        7 files  src/features/auth/**
  features/billing     5 files  src/features/billing/**
  shared               8 files  src/components/**, src/hooks/**, src/lib/**, ...
  server               4 files  src/server/**

Rules:
  app                  → features/auth, features/billing, shared, server
  features/auth        → shared, server
  features/billing     → shared, server
  server               → shared
  shared               (isolated, no imports allowed)
```

## Presets

<Tabs>
  <Tab title="Bulletproof">
    A widely used React/Next.js pattern. Feature modules are isolated from each other; shared utilities and server infrastructure form the base layers.

    **4 logical zones:** `app`, `features`, `shared`, `server`. The `features` zone auto-discovers immediate child directories so sibling features are isolated as `features/<name>` zones. Top-level files inside `src/features/` (barrels, shared types) fall back to the parent `features` zone; the parent rule automatically allows discovered children, so barrels can re-export features without false positives while non-barrel top-level files still obey the `features` rule.

    ```
    app              → every feature, shared, server
    features/<name>  → shared, server
    server           → shared
    shared           (isolated)
    ```

    The `shared` zone covers: `components`, `hooks`, `lib`, `utils`, `utilities`, `providers`, `shared`, `types`, `styles`, `i18n`.

    <Tip>
      This preset matches the architecture from [Bulletproof React](https://github.com/alan2207/bulletproof-react) and is the most common pattern in modern React and Next.js projects.
    </Tip>
  </Tab>

  <Tab title="Layered">
    Classic N-tier architecture with four layers. Infrastructure may import from both domain and application (common for dependency injection).

    **4 zones:** `presentation`, `application`, `domain`, `infrastructure`

    ```
    presentation    → application
    application     → domain
    domain          (isolated)
    infrastructure  → domain, application
    ```
  </Tab>

  <Tab title="Hexagonal">
    Ports and adapters pattern. The domain has zero outward dependencies; adapters implement port interfaces.

    **3 zones:** `adapters`, `ports`, `domain`

    ```
    adapters  → ports
    ports     → domain
    domain    (isolated)
    ```
  </Tab>

  <Tab title="Feature-Sliced">
    [Feature-Sliced Design](https://fsd.how/) with strict downward-only imports. Each layer may only import from layers below it.

    **6 zones:** `app`, `pages`, `widgets`, `features`, `entities`, `shared`

    ```
    app       → pages, widgets, features, entities, shared
    pages     → widgets, features, entities, shared
    widgets   → features, entities, shared
    features  → entities, shared
    entities  → shared
    shared    (isolated)
    ```
  </Tab>
</Tabs>

### Source root detection

Preset zone patterns use `{rootDir}/{zone}/**`. Fallow auto-detects the source root from `tsconfig.json`:

```jsonc title="tsconfig.json" theme={null}
{
  "compilerOptions": {
    "rootDir": "./lib"  // zones become lib/app/**, lib/features/**, etc.
  }
}
```

If no `rootDir` is found, fallow falls back to `src`.

## Custom zones and rules

For full control, define zones and rules directly:

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "zones": [
        { "name": "ui", "patterns": ["src/components/**", "src/pages/**"] },
        { "name": "data", "patterns": ["src/db/**", "src/api/**"] },
        { "name": "shared", "patterns": ["src/lib/**", "src/utils/**"] }
      ],
      "rules": [
        { "from": "ui", "allow": ["shared"] },
        { "from": "data", "allow": ["shared"] },
        { "from": "shared", "allow": [] }
      ]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [[boundaries.zones]]
  name = "ui"
  patterns = ["src/components/**", "src/pages/**"]

  [[boundaries.zones]]
  name = "data"
  patterns = ["src/db/**", "src/api/**"]

  [[boundaries.zones]]
  name = "shared"
  patterns = ["src/lib/**", "src/utils/**"]

  [[boundaries.rules]]
  from = "ui"
  allow = ["shared"]

  [[boundaries.rules]]
  from = "data"
  allow = ["shared"]

  [[boundaries.rules]]
  from = "shared"
  allow = []
  ```
</CodeGroup>

### How zones work

* A file belongs to the **first zone** whose pattern matches (first-match wins)
* Files that don't match any zone are **unrestricted**: they can import from and be imported by any zone
* **Self-imports** are always allowed (files in the same zone can freely import each other)
* A zone with **no rule entry** is unrestricted: it can import from any zone
* A zone with a rule and an **empty `allow` list** is isolated: it cannot import from other zones

### Auto-discovered feature zones

Use `autoDiscover` when one logical zone should create one concrete zone per child directory. This is useful for feature-module architectures where `src/features/auth` and `src/features/billing` should be isolated from each other without writing a zone and rule for every feature.

```jsonc theme={null}
{
  "boundaries": {
    "zones": [
      { "name": "app", "patterns": ["src/app/**"] },
      { "name": "features", "patterns": ["src/features/**"], "autoDiscover": ["src/features"] },
      { "name": "shared", "patterns": ["src/shared/**"] }
    ],
    "rules": [
      { "from": "app", "allow": ["features", "shared"] },
      { "from": "features", "allow": ["shared"] }
    ]
  }
}
```

If `src/features/auth` and `src/features/billing` exist, fallow expands this to `features/auth` and `features/billing`. Rules that reference the logical `features` parent apply to every discovered feature. Explicit child rules, such as `from: "features/auth"`, override generated parent rules.

When the zone also has `patterns`, top-level files inside the auto-discover directory fall back to the parent zone, whose rule automatically allows its discovered children. See [Auto-discovered zones](/configuration/boundaries#auto-discovered-zones) for the full semantics.

### Subtree scope (`root`)

Monorepos with per-package boundaries usually have the same internal directory layout under each package (`packages/app/src/`, `packages/core/src/`, ...). Writing flat patterns from the project root forces zone definitions to scale with the cross product of (zones, packages):

```jsonc theme={null}
// Without `root`: one zone per (layer, package) pair.
{ "name": "ui-app",      "patterns": ["packages/app/src/**"] },
{ "name": "domain-core", "patterns": ["packages/core/src/**"] }
```

Set `root` on a zone to scope its patterns to a subtree. At classification time, fallow checks that the file's path starts with the `root` prefix and strips that prefix before matching the patterns against the remainder. Files outside the subtree never match the zone.

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "zones": [
        { "name": "ui",     "patterns": ["src/**"], "root": "packages/app/" },
        { "name": "domain", "patterns": ["src/**"], "root": "packages/core/" }
      ],
      "rules": [
        { "from": "ui", "allow": [] }
      ]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [[boundaries.zones]]
  name = "ui"
  patterns = ["src/**"]
  root = "packages/app/"

  [[boundaries.zones]]
  name = "domain"
  patterns = ["src/**"]
  root = "packages/core/"

  [[boundaries.rules]]
  from = "ui"
  allow = []
  ```
</CodeGroup>

In this example, `packages/app/src/login.tsx` classifies as `ui` and `packages/core/src/order.ts` classifies as `domain`. Adding `packages/billing/` later only requires another zone entry with the same `patterns: ["src/**"]` and a different `root`.

Trailing slashes and a leading `./` are normalized for you, so `"packages/app"`, `"packages/app/"`, and `"./packages/app/"` are equivalent. Backslashes are converted to forward slashes.

<Warning>
  Patterns must NOT redundantly include the root prefix. `root: "packages/app/"` paired with `patterns: ["packages/app/src/**"]` is rejected at config-resolve time with `FALLOW-BOUNDARY-ROOT-REDUNDANT-PREFIX`, because patterns are already resolved relative to the root. Drop the root prefix from the pattern (`patterns: ["src/**"]`).
</Warning>

### Overriding preset zones

Start from a preset and customize specific zones or rules. Zones with the same name replace the preset zone; rules with the same `from` replace the preset rule. See [Merging presets with custom config](/configuration/boundaries#merging-presets-with-custom-config) for examples.

## Suppressing violations

Suppress individual findings with inline comments:

```typescript theme={null}
// fallow-ignore-next-line boundary-violation
import { db } from '../data/client';
```

Or suppress all boundary violations in a file:

```typescript theme={null}
// fallow-ignore-file boundary-violation
```

To suppress boundary checking entirely, set the rule severity to `off`:

```jsonc theme={null}
{
  "rules": {
    "boundary-violation": "off"
  }
}
```

The `boundary-violation` token and rule cover the whole boundary family: import-direction violations, [coverage violations](/configuration/boundaries#boundary-coverage), and [forbidden-call violations](/configuration/boundaries#forbidden-calls). The rule-id-shaped `boundary-call-violation` and `boundary-call-violations` tokens are accepted as aliases; any of the three suppresses every boundary finding on that line or file.

<Tip>
  When introducing boundaries to an existing codebase, start with `"warn"` severity. Fix violations incrementally, then switch to `"error"` once the codebase is clean.
</Tip>

## Output formats

Boundary violations appear in all output formats:

<Tabs>
  <Tab title="Human">
    ```bash title="$ fallow dead-code --boundary-violations" theme={null}
    Boundary violations (2)

      src/features/auth/login.ts:3 → src/features/billing/api.ts (features → features)
      src/components/Button.tsx:1 → src/server/db/client.ts (shared → server)
    ```
  </Tab>

  <Tab title="JSON">
    ```json theme={null}
    {
      "boundary_violations": [
        {
          "from_path": "src/features/auth/login.ts",
          "to_path": "src/features/billing/api.ts",
          "from_zone": "features",
          "to_zone": "features",
          "import_specifier": "../billing/api",
          "line": 3,
          "col": 0
        }
      ]
    }
    ```

    <Note>
      The full JSON output includes a `schema_version`, `version`, `elapsed_ms`, and all issue type arrays. Only `boundary_violations` is shown here.
    </Note>
  </Tab>

  <Tab title="Compact">
    ```
    boundary-violation:src/features/auth/login.ts:3:src/features/auth/login.ts -> src/features/billing/api.ts (features -> features)
    ```
  </Tab>
</Tabs>

## See also

<CardGroup>
  <Card title="fallow dead-code" icon="terminal" href="/cli/dead-code">
    CLI reference for the dead code command, including all issue type filters.
  </Card>

  <Card title="Rules & Severity" icon="scale-balanced" href="/configuration/rules">
    Set boundary violations to error, warn, or off.
  </Card>

  <Card title="Inline Suppression" icon="comment-slash" href="/configuration/suppression">
    Suppress individual findings in source code.
  </Card>
</CardGroup>


# CSS, SCSS, and Tailwind analysis
Source: https://docs.fallow.tools/analysis/css-analysis

How fallow tracks CSS imports, SCSS partials, Tailwind dependencies, and CSS Module class names using AST-based extraction. Zero false positives on @use, @forward, and partial imports.

Fallow tracks CSS and SCSS files using dedicated extraction. `@use`, `@forward`, SCSS partials (`_prefix` files), and Tailwind directives are all resolved accurately. No manual configuration needed.

## SCSS import resolution

Fallow understands the full SCSS module system. Imports create edges in the module graph, and re-exports propagate through the dependency chain.

| Directive          | How fallow handles it                                        |
| :----------------- | :----------------------------------------------------------- |
| `@use 'path'`      | Resolved as a module import, creating a graph edge           |
| `@forward 'path'`  | Treated as a re-export in the module graph                   |
| `@import 'path'`   | Legacy import, tracked as a side-effect edge                 |
| `@use 'sass:math'` | Recognized as a Sass built-in module, not flagged as missing |

SCSS partial resolution follows the standard convention. When fallow encounters `@use 'components/button'`, it resolves through these candidates in order:

1. `components/_button.scss` (partial convention)
2. `components/button/_index.scss` (directory index)
3. `components/button/index.scss` (plain index)

```scss styles/theme.scss theme={null}
@use 'sass:color';
@use 'variables';
@use 'mixins/responsive';

@forward 'tokens' show $primary, $secondary;
```

Fallow sees this file as:

* Importing the `sass:color` built-in (correctly ignored, not a project dependency)
* Importing `./variables`, resolved to `_variables.scss` via partial convention
* Importing `./mixins/responsive`, resolved to `mixins/_responsive.scss`
* Re-exporting `$primary` and `$secondary` from `./tokens`

<Note>
  SCSS include paths (configured via frameworks like Angular) are also supported. When a bare specifier like `@use 'variables'` cannot be resolved locally, fallow searches configured include directories with the same partial and index conventions.
</Note>

## CSS Module class tracking

Files with `.module.css`, `.module.scss`, `.module.sass`, or `.module.less` extensions receive special treatment. Fallow extracts every class name from selectors and exposes it as a named export. Repeated selectors for the same class remain one export rather than producing duplicate findings.

```css Button.module.css theme={null}
.root {
  display: flex;
  align-items: center;
}

.primary {
  background: var(--color-primary);
}

.disabled {
  opacity: 0.5;
  pointer-events: none;
}
```

This file exports three named symbols: `root`, `primary`, and `disabled`.

When a component imports a CSS module, fallow tracks which classes are actually accessed. Default imports may use any local alias, and passing or otherwise consuming the whole imported object conservatively credits every class:

```tsx Button.tsx theme={null}
import styles from './Button.module.css';

export const Button = ({ variant }: Props) => (
  <button className={`${styles.root} ${styles.primary}`}>
    Click me
  </button>
);
```

Here, `styles.root` and `styles.primary` are marked as used. The `disabled` class is never referenced, so fallow reports it as an unused export.

```bash title="$ fallow dead-code --unused-exports" theme={null}
● Unused exports (1)
  src/Button.module.css
    :3 disabled
  Exported symbols with zero references: https://docs.fallow.tools/explanations/dead-code#unused-exports

✗ 1 issue (0.02s)
```

<Tip>
  Start with `fallow dead-code --unused-exports` to see which CSS module class names are unused across your project.
</Tip>

## Tailwind CSS integration

When fallow encounters `@apply` or `@tailwind` directives in any CSS or SCSS file, it creates a synthetic dependency on the `tailwindcss` package. This prevents false "unused dependency" reports.

```css globals.css theme={null}
@tailwind base;
@tailwind components;
@tailwind utilities;

.btn {
  @apply px-4 py-2 rounded-md font-medium;
}
```

Fallow detects both `@tailwind` and `@apply` directives and marks `tailwindcss` as a used dependency.

### `@plugin` directive (Tailwind v4)

Tailwind v4 moves plugin registration into CSS via the `@plugin` directive. Fallow extracts each `@plugin` target as a default import, so package plugins are credited as used dependencies and relative plugin files have their default export marked used.

```css app.css theme={null}
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "daisyui" {
  themes: light --default;
}
@plugin "./tailwind-local-plugin.js";
```

Fallow marks `@tailwindcss/typography` and `daisyui` as used dependencies, and treats `./tailwind-local-plugin.js` as a reachable file whose `default` export is consumed. The directive is also recognized inside Vue and Svelte `<style>` blocks. Unlike SCSS `@use`, extensionless package names such as `daisyui` stay bare even in `.scss` and `.sass` files (they are package specifiers, not local partials).

### Unused Tailwind v4 `@theme` tokens

With `fallow health --css`, Tailwind v4 projects also get cleanup candidates for `@theme` design tokens whose generated utility is not referenced anywhere fallow can see.

```css theme.css theme={null}
@import "tailwindcss";

@theme {
  --color-brand: #f05a28;
  --shadow-glow: 0 0 8px red;
}
```

```tsx App.tsx theme={null}
export const App = () => <div className="bg-brand" />;
```

In this example, `--color-brand` is credited because `bg-brand` uses the generated utility suffix. `--shadow-glow` is reported in `css_analytics.unused_theme_tokens` with a read-only verification action.

Fallow also credits `var(--token)` reads, `@apply` utilities, arbitrary values such as `rounded-[--radius-card]`, and token-to-token references inside `@theme` blocks. The check is conservative: it only runs for Tailwind v4 projects, abstains when Tailwind plugins or published CSS surfaces may consume tokens invisibly, and treats every result as a candidate, never as an auto-fix.

Other CSS cleanup signals follow the same contract. `css_analytics.unreferenced_css_classes` (a plain-CSS class defined but matched by no `class`/`className` in project markup), `css_analytics.unresolved_class_references` (the reverse: a markup class one edit away from a defined class, a likely typo), `css_analytics.unused_font_faces`, `css_analytics.undefined_keyframes`, and `css_analytics.font_size_unit_mix` are advisory candidates with read-only verification actions. They are meant to send a reviewer to the likely stale class, font, animation, or type-scale mismatch without claiming it is always safe to delete.

### Token blast-radius (`token_consumers`)

The inverse of the unused-token signal: instead of asking "is this token dead?", `token_consumers` answers "what consumes this token?" so you can see a token's blast radius before changing it. On Tailwind v4 projects `fallow health --css --format json` adds `css_analytics.token_consumers`, a reverse index over the same gated `@theme` token set:

```json theme={null}
{
  "token": "--color-brand",
  "namespace": "color",
  "definition_path": "src/theme.css",
  "definition_line": 4,
  "consumer_count": 12,
  "consumers": [
    { "path": "src/Button.tsx", "line": 7, "kind": "utility" },
    { "path": "src/theme.css", "line": 9, "kind": "theme-var" }
  ]
}
```

Each consumer location carries a `kind`: `utility` (a markup class ending in `-<name>`, such as `bg-brand`), `apply` (a class inside an `@apply` body), `css-var` (a regular-CSS `var(--token)` read), or `theme-var` (a `var()` reference inside another `@theme` token). `consumers` is a capped sample; `consumer_count` is the full total.

`consumer_count` is a static lower bound: a computed class name like `bg-${color}` is invisible to the scan, so a `0` here is a "nothing fallow can see consumes this" signal, the same population that surfaces in `unused_theme_tokens`, not a proof that the token is safe to delete. `token_consumers` is descriptive context for change decisions; the cleanup candidate stays `unused_theme_tokens`.

#### CSS-in-JS tokens

`token_consumers` also covers CSS-in-JS token DEFINITIONS, so changing a StyleX `defineVars`, vanilla-extract `createTheme` / `createThemeContract` / `createGlobalTheme`, or PandaCSS `defineTokens` token shows its blast radius the same way an `@theme` token does. These tokens are defined in JS objects and consumed through cross-module member access (`import { vars } from './tokens'; vars.color.primary`) or Panda `token('colors.brand')` calls, so the entry shape differs by origin:

```json theme={null}
{
  "token": "vars.color.primary",
  "namespace": "vars",
  "definition_path": "src/tokens.stylex.ts",
  "definition_line": 3,
  "consumer_count": 4,
  "consumers": [
    { "path": "src/Card.tsx", "line": 12, "kind": "js-member" }
  ]
}
```

The origins are disambiguated by the consumer `kind` and by the `token` shape: a Tailwind token's `token` is the `--`-prefixed custom property (`--color-brand`) with `kind` `theme-var` / `css-var` / `utility` / `apply`; StyleX and vanilla-extract tokens use a binding-qualified dotted access path (`vars.color.primary`) with `kind` `js-member`; PandaCSS tokens use the defining binding plus token path (`tokens.colors.brand`) and `token(...)` consumers are tagged `js-call`. The cross-file scan resolves import edges to their defining files before matching, so an unrelated same-named `vars` from a different module is never counted.

Two caveats are sharper than the Tailwind case. The cross-file scan uses fallow's shared import resolver, so relative imports, tsconfig `paths` aliases, and workspace package imports can resolve to the token definition. Dynamic import strings, unresolved aliases, generated package state, and computed token access still keep `consumer_count` a lower bound. And unlike Tailwind there is no corroborating dead-token finding (no CSS-in-JS analogue of `unused_theme_tokens`), so a CSS-in-JS `consumer_count` of `0` is a weaker "fallow sees no consumers" signal, not a deletion verdict. CSS-in-JS token blast-radius is gated on a declared CSS-in-JS library (`@stylexjs/stylex`, `@vanilla-extract/css`, or `@pandacss/dev`).

### Tailwind v3 config

The Tailwind plugin provides additional coverage by parsing `tailwind.config.{js,ts,cjs,mjs}`:

* **Content globs** from the `content` array are treated as always-used file patterns
* **Plugin packages** referenced via `require()` or string arrays are marked as used dependencies
* **Presets** are tracked as referenced dependencies
* **Imports** in the config file (e.g., `import defaultTheme from 'tailwindcss/defaultTheme'`) are tracked

```js tailwind.config.js theme={null}
import defaultTheme from 'tailwindcss/defaultTheme';

export default {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
};
```

Fallow marks `tailwindcss`, `@tailwindcss/typography`, and `@tailwindcss/forms` as used dependencies.

## CSS `@import` tracking

Plain CSS `@import` statements create edges in the module graph. Both relative paths and package imports are tracked.

```css styles/main.css theme={null}
@import './reset.css';
@import './typography.css';
@import '@fontsource/inter/400.css';
```

Fallow resolves `./reset.css` and `./typography.css` as local file imports, and `@fontsource/inter` as a package dependency. Remote URLs (`https://...`) and data URIs are correctly ignored.

## Styling health grade

On top of the raw `css_analytics`, `fallow health --css` derives a **styling health** grade: a descriptive A-F letter (and a 0-100 score) for the quality of the CSS itself, scored **separately** from the JavaScript/TypeScript code health score. It appears as `styling_health` in JSON and a `Styling health:` line under `CSS health` in human output.

```json theme={null}
"styling_health": {
  "formula_version": 3,
  "score": 96.0,
  "grade": "A",
  "penalties": { "duplication": 0.0, "dead_surface": 0.0, "broken_references": 0.0, "token_erosion": 4.0, "structural": 0.0 },
  "confidence": "high",
  "confidence_reason": null
}
```

The score starts at 100 and subtracts five capped penalties:

| Penalty             | What it measures                                                                                                                                                                                                                              |
| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `duplication`       | Removable declarations from copy-paste declaration blocks. Down-weighted to a soft hint (exact CSS duplication is the least-harmful pattern: it gzips away and CSS has no native abstraction).                                                |
| `dead_surface`      | Unused `@theme` tokens (as a share of all defined tokens) plus unreferenced classes, unused `@property`/`@layer` at-rules, and dead `@font-face` families.                                                                                    |
| `broken_references` | Markup classes one edit from a defined class, plus animations referencing a `@keyframes` defined nowhere (likely typos or stale renames).                                                                                                     |
| `token_erosion`     | Design-token erosion: mixed `font-size` units, Tailwind arbitrary-value bypasses, and **hardcoded value drift** (the count of distinct hardcoded `box-shadow` / `border-radius` / `line-height` values above a healthy per-property palette). |
| `structural`        | `!important` density above a healthy floor, plus deep style-rule nesting.                                                                                                                                                                     |

### Value drift over exact repetition

The grade weights design-token **drift** (inconsistency) more than byte-identical repetition, because divergent values are what design tokens exist to fix. The `token_erosion` value-drift signal counts only **hardcoded** literals: a system that references its scale through custom properties (`box-shadow: var(--shadow-md)`) scores **zero** drift no matter how many tokens it defines, because `var(--*)` references and `@theme` definitions are never counted as distinct hardcoded values. A system that hardcodes many ad-hoc shadows/radii/line-heights accrues a small, gently-growing penalty: a nudge toward tokenizing, never a cliff.

### Confidence and scope

A grade computed from a thin CSS surface (few authored declarations, or predominantly compile-time-atomic CSS-in-JS like StyleX/Panda) is marked `confidence: "low"` with a stated reason, so a sparse-surface grade is not presented with the same authority as one from a full design system. Confidence is metadata only: it never changes the score.

Styling health is **descriptive-only**. It never gates an exit code, a badge, or CI, and it never affects the JavaScript/TypeScript `health_score`. Treat it as a design-system credibility signal, not a pass/fail gate.

<Note>
  `formula_version` increments whenever the styling-health rubric is recalibrated (independently of the code-health formula version), so you can tell a score shift caused by a weight change apart from one caused by an actual change to your CSS. If you diff `styling_health.score` / `grade` over time (snapshot CIs, trend dashboards), gate on `formula_version` and re-baseline when it bumps.
</Note>

## Common patterns that just work

| Pattern                       | Example                               | How fallow handles it                                  |
| :---------------------------- | :------------------------------------ | :----------------------------------------------------- |
| SCSS partial imports          | `@use 'mixins'`                       | Resolves to `_mixins.scss`                             |
| Sass built-in modules         | `@use 'sass:math'`                    | Correctly ignored, not flagged as missing              |
| `@use` with namespace         | `@use 'colors' as c`                  | Tracked as module import                               |
| `@forward` with `show`/`hide` | `@forward 'tokens' show $primary`     | Re-export with filtering                               |
| CSS custom properties         | `var(--color-primary)`                | File-level tracking (not per-property)                 |
| PostCSS plugins               | `postcss.config.js`                   | Plugin dependencies detected via PostCSS plugin config |
| Scoped CSS packages           | `@import '@company/tokens/base.scss'` | Resolved as npm package, not local file                |
| SCSS directory index          | `@use 'components'`                   | Resolves to `components/_index.scss`                   |

## See also

<CardGroup>
  <Card title="Dead code analysis" icon="skull-crossbones" href="/analysis/dead-code">
    How fallow builds the module graph and detects unused code.
  </Card>

  <Card title="Non-JS file types" icon="file-code" href="/analysis/file-types">
    All non-JavaScript file types fallow analyzes automatically.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Configure entry points, rules, and analysis scope.
  </Card>
</CardGroup>


# Dead code analysis
Source: https://docs.fallow.tools/analysis/dead-code

Find unused files, exports, dependencies, types, class members, circular dependencies, and boundary violations in TypeScript and JavaScript. Inheritance-aware class member detection, CSS/SCSS tracking, and cycle detection built into the module graph.

`fallow dead-code` performs dead code analysis on your TypeScript project. It builds a module graph from your <Tooltip>entry points</Tooltip> and reports anything that isn't reachable.

Finding dead code requires building a complete module graph. Fallow does this deterministically in milliseconds, giving agents, developers, and CI pipelines the same reliable results.

```bash theme={null}
fallow dead-code
```

## Issue types

Fallow detects these types of dead code:

| Issue type                      | Description                                                                                                                                                                               |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Unused files**                | Files not reachable from any entry point                                                                                                                                                  |
| **Unused exports**              | Exported symbols never imported elsewhere                                                                                                                                                 |
| **Unused types**                | Type aliases and interfaces never referenced                                                                                                                                              |
| **Unused dependencies**         | Packages in `dependencies` never imported or used as script binaries                                                                                                                      |
| **Unused devDependencies**      | Packages in `devDependencies` never imported or used as script binaries                                                                                                                   |
| **Unused optionalDependencies** | Packages in `optionalDependencies` never imported or used as script binaries                                                                                                              |
| **Unused enum members**         | Enum values never referenced                                                                                                                                                              |
| **Unused class members**        | Class methods and properties never referenced outside their class, with inheritance tracking, configurable decorator exclusion via `ignoreDecorators`, and framework lifecycle allowlists |
| **Unused catalog entries**      | Entries in `pnpm-workspace.yaml`'s `catalog:` or `catalogs:` maps that no workspace package references via the `catalog:` protocol                                                        |
| **Unresolved imports**          | Import specifiers that cannot be resolved                                                                                                                                                 |
| **Unlisted dependencies**       | Imported packages missing from `package.json`                                                                                                                                             |
| **Duplicate exports**           | Same symbol exported from multiple modules                                                                                                                                                |
| **Circular dependencies**       | Modules that import each other directly or transitively                                                                                                                                   |
| **Boundary violations**         | Imports that cross user-defined architecture zone boundaries                                                                                                                              |
| **Type-only dependencies**      | Production dependencies only imported via `import type` (should be devDependencies)                                                                                                       |
| **Test-only dependencies**      | Production dependencies only imported by test files (should be devDependencies)                                                                                                           |
| **Stale suppressions**          | `fallow-ignore` comments or `@expected-unused` JSDoc tags that no longer match any issue                                                                                                  |

<Tip>
  Most projects find 50+ unused exports on first run. Start with `--unused-exports` for the most impactful cleanup.
</Tip>

Here's what typical output looks like when fallow finds multiple issue types:

```bash title="$ fallow dead-code" theme={null}
● Unused files (9)
  scripts/check-db.ts
  src/features/forecasting/hooks/useCashFlowForecast.ts
  src/features/forecasting/hooks/useIncomeForecast.ts
  src/features/forecasting/hooks/useTargetProgress.ts
  src/features/forecasting/hooks/useYearComparison.ts
  ... and 4 more
  Files not imported or referenced by any entry point: https://docs.fallow.tools/explanations/dead-code#unused-files

● Unused exports (24)
  test/component-helpers.tsx (5)
    :33 ThemeContext
    :58 ToastContext
    :1 within (re-export)
    :1 waitFor (re-export)
    :1 act (re-export)
  src/server/jobs/queue.ts (3)
    :61 enqueueJobDelayed
    :206 sweepStuckProcessingJobs
    :276 getDeadLetterJobs
  Exported symbols with zero references: https://docs.fallow.tools/explanations/dead-code#unused-exports

✗ 401 issues (0.16s)
```

## Filtering by issue type

Report only specific issue types:

```bash theme={null}
fallow dead-code --unused-files
fallow dead-code --unused-exports --unused-types
fallow dead-code --unresolved-imports --unlisted-deps
```

## Output formats

<Tabs>
  <Tab title="Human (default)">
    Colored terminal output designed for readability.

    ```bash theme={null}
    fallow dead-code --format human
    ```

    ```ansi theme={null}
    src/components/Card/index.ts
      unused-export  CardFooter  (line 1)

    src/server/jobs/queue.ts
      unused-export  enqueueJobDelayed  (line 61)
      unused-export  sweepStuckProcessingJobs  (line 206)

    src/server/jobs/worker.ts
      unused-file  Not reachable from any entry point

    Found 401 issues (17 errors, 384 warnings)
    ```
  </Tab>

  <Tab title="JSON">
    Machine-readable JSON for scripting and tooling integration.

    ```bash theme={null}
    fallow dead-code --format json
    ```

    ```json theme={null}
    {
      "schema_version": 9,
      "version": "3.24.1",
      "elapsed_ms": 160,
      "total_issues": 401,
      "unused_files": [
        { "path": "src/server/jobs/worker.ts" }
      ],
      "unused_exports": [
        {
          "path": "src/server/jobs/queue.ts",
          "export_name": "enqueueJobDelayed",
          "is_type_only": false,
          "line": 61,
          "col": 0,
          "span_start": 1420,
          "is_re_export": false
        }
      ],
      "unused_dependencies": [
        {
          "package_name": "@trpc/react-query",
          "location": "dependencies",
          "path": "package.json",
          "line": 18,
          "used_in_workspaces": ["apps/web"]
        }
      ]
    }
    ```
  </Tab>

  <Tab title="SARIF">
    <Tooltip>SARIF</Tooltip> format for GitHub Code Scanning and other static analysis tools.

    ```bash theme={null}
    fallow dead-code --format sarif
    ```

    ```json theme={null}
    {
      "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
      "version": "3.24.1",
      "runs": [{
        "tool": { "driver": { "name": "fallow", "version": "3.24.1" } },
        "results": [
          {
            "ruleId": "fallow/unused-export",
            "level": "error",
            "message": { "text": "Export 'enqueueJobDelayed' is never imported by other modules" },
            "locations": [{
              "physicalLocation": {
                "artifactLocation": { "uri": "src/server/jobs/queue.ts" },
                "region": { "startLine": 61, "startColumn": 1 }
              }
            }]
          }
        ]
      }]
    }
    ```
  </Tab>

  <Tab title="Compact">
    One-line-per-issue output, ideal for grep and editor integration.

    ```bash theme={null}
    fallow dead-code --format compact
    ```

    ```text theme={null}
    unused-file:src/server/jobs/worker.ts
    unused-file:src/server/jobs/cron.ts
    unused-export:src/server/jobs/queue.ts:61:enqueueJobDelayed
    unused-export:src/components/Card/index.ts:1:CardFooter
    ```
  </Tab>

  <Tab title="Markdown">
    Formatted markdown output for PR comments and documentation.

    ```bash theme={null}
    fallow dead-code --format markdown
    ```

    ```markdown theme={null}
    ## Fallow: 4 issues found

    ### Unused files (2)

    - `src/server/jobs/worker.ts`
    - `src/server/jobs/cron.ts`

    ### Unused exports (2)

    - `src/server/jobs/queue.ts`
      - :61 `enqueueJobDelayed`
      - :206 `sweepStuckProcessingJobs`
    ```

    Pipe directly to `gh pr comment`:

    ```bash theme={null}
    fallow dead-code --format markdown | gh pr comment --body-file -
    ```
  </Tab>

  <Tab title="CodeClimate">
    CodeClimate JSON for GitLab Code Quality inline MR annotations.

    ```bash theme={null}
    fallow dead-code --format codeclimate
    ```

    ```json theme={null}
    [
      {
        "type": "issue",
        "check_name": "fallow/unused-file",
        "description": "File is not reachable from any entry point",
        "categories": ["Bug Risk"],
        "severity": "major",
        "fingerprint": "a1b2c3d4e5f67890",
        "location": {
          "path": "src/server/jobs/worker.ts",
          "lines": { "begin": 1 }
        }
      },
      {
        "type": "issue",
        "check_name": "fallow/unused-export",
        "description": "Export 'enqueueJobDelayed' is never imported by other modules",
        "categories": ["Bug Risk"],
        "severity": "major",
        "fingerprint": "b2c3d4e5f6789012",
        "location": {
          "path": "src/server/jobs/queue.ts",
          "lines": { "begin": 61 }
        }
      }
    ]
    ```

    Use in GitLab CI for inline annotations:

    ```yaml theme={null}
    fallow:
      script: npx fallow dead-code --format codeclimate > gl-code-quality-report.json
      artifacts:
        reports:
          codequality: gl-code-quality-report.json
    ```
  </Tab>
</Tabs>

## Incremental analysis

Only check files changed since a git ref:

```bash theme={null}
fallow dead-code --changed-since main
fallow dead-code --changed-since HEAD~5
```

This is useful in CI to only report new issues in a pull request.

```bash title="$ fallow dead-code --changed-since main" theme={null}
● Unused exports (2)
  src/features/savings/hooks/usePotGroups.ts
    :8  usePotGroupTotals
  src/server/jobs/queue.ts
    :276 getDeadLetterJobs
  Exported symbols with zero references: https://docs.fallow.tools/explanations/dead-code#unused-exports

✗ 2 issues (0.04s)
```

## Baseline comparison

Adopt fallow incrementally by saving a baseline of existing issues:

```bash theme={null}
# Save current issues as baseline
fallow dead-code --save-baseline

# Only fail on new issues (compared to baseline)
fallow dead-code --baseline
```

## Debugging

Trace why an export is or isn't considered used:

```bash theme={null}
fallow dead-code --trace src/utils.ts:formatDate
fallow dead-code --trace-file src/utils.ts
fallow dead-code --trace-dependency lodash
```

## How it works

Fallow uses syntactic analysis with scope-aware binding resolution via Oxc. No TypeScript compiler, no type information. That's what makes it fast.

```mermaid theme={null}
flowchart TB
  A["Discovery<br/>Entry points from package.json + plugins"] --> B["Parsing<br/>Parallel with Oxc + oxc_semantic + rayon"]
  B --> C["Resolution<br/>Import specifiers to file paths"]
  C --> D["Graph<br/>Module graph with re-export chains"]
  D --> E["Analysis<br/>Walk from entry points, report unreachable code"]
```

The graph-based approach guarantees completeness regardless of project size.

<Note>
  Fallow works best with projects using `isolatedModules: true` (required for esbuild, swc, and Vite). `oxc_semantic` scope analysis detects unused import bindings (imports where the bound name is never read), but legacy tsc-only projects without `isolatedModules` may still see edge cases with type-only imports.
</Note>

## Script binary analysis

Fallow parses `package.json` scripts to detect CLI tool usage. This reduces false positives in unused dependency detection. When you have a script like `"lint": "eslint src/"`, fallow recognizes that `eslint` is a binary provided by the `eslint` package and marks it as used.

How it works:

* **Binary name to package name mapping:** Script commands like `tsc`, `vitest`, or `next` are mapped back to their parent packages (`typescript`, `vitest`, `next`). These packages won't be reported as unused even when they're never `import`-ed in source code.
* **`--config` arguments as entry points:** When a script references a config file (e.g., `jest --config jest.e2e.config.ts`), fallow treats that config file as an entry point. Config files won't be flagged as unused.
* **File path arguments:** Direct file references in scripts (e.g., `node scripts/seed.js`) are also recognized as entry points.
* **Env wrappers and package manager runners:** Commands prefixed with `cross-env`, `npx`, `pnpx`, `yarn dlx`, or `node -r` are unwrapped to find the actual tool binary.

```json theme={null}
{
  "scripts": {
    "build": "tsc && vite build",
    "test": "vitest --config vitest.config.ts",
    "lint": "cross-env NODE_ENV=production eslint src/"
  }
}
```

In this example, fallow detects `typescript`, `vite`, `vitest`, and `eslint` as used dependencies, and `vitest.config.ts` as an entry point.

## Infrastructure entry points

Fallow scans infrastructure config files for source file references and treats them as entry points. Worker processes, migration scripts, and other infrastructure-defined files won't be reported as unused.

Supported files:

| File type                                                      | What fallow extracts                                      |
| :------------------------------------------------------------- | :-------------------------------------------------------- |
| **Dockerfiles** (`Dockerfile`, `Dockerfile.*`, `*.Dockerfile`) | `RUN node`, `CMD`, `ENTRYPOINT`, esbuild invocations      |
| **Procfiles**                                                  | Process definitions (e.g., `worker: node dist/worker.js`) |
| **fly.toml** / **fly.\*.toml**                                 | `release_command` and process definitions                 |
| **CI pipelines** (`.gitlab-ci.yml`, `.github/workflows/*.yml`) | `npx` and binary invocations in CI steps                  |

Fallow searches the project root and common subdirectories (`config/`, `docker/`, `deploy/`) for these files.

```dockerfile theme={null}
# Fallow detects scripts/migrate.ts and src/worker.ts as entry points
FROM node:20
RUN node scripts/migrate.ts
CMD ["node", "src/worker.ts"]
```

## Dynamic import resolution

Fallow resolves dynamic imports that use patterns rather than static strings. When you write ``import(`./locales/${lang}.json`)``, the import target isn't known at analysis time. Fallow converts these patterns into glob expressions and matches them against discovered files.

Supported patterns:

| Pattern              | Example                                       | Resolved as         |
| :------------------- | :-------------------------------------------- | :------------------ |
| Template literals    | ``import(`./icons/${name}.svg`)``             | `./icons/*.svg`     |
| String concatenation | `import("./routes/" + path)`                  | `./routes/*`        |
| `import.meta.glob`   | `import.meta.glob("./modules/*.ts")`          | `./modules/*.ts`    |
| `require.context`    | `require.context("./themes", true, /\.css$/)` | `./themes/**/*.css` |

Matched files are marked as reachable in the module graph, so they won't be reported as unused. Useful for locale files, icon sets, route modules, and other convention-based directory structures.

<Note>
  Dynamic imports with fully runtime-computed paths (e.g., `import(userInput)`) cannot be resolved statically. Use `entry` in your config to mark those directories as entry points.
</Note>

## Re-export chain resolution

Fallow resolves `export *` chains through multiple levels of barrel files with cycle detection.

```typescript theme={null}
// utils/math.ts
export const add = (a: number, b: number) => a + b;

// utils/index.ts (barrel)
export * from './math';

// src/index.ts (barrel)
export * from './utils';

// app.ts
import { add } from './src';
```

```mermaid theme={null}
flowchart TB
  A["app.ts<br/>import ﹛ add ﹜ from './src'"] --> B["src/index.ts<br/>export * from './utils'"]
  B --> C["utils/index.ts<br/>export * from './math'"]
  C --> D["utils/math.ts<br/>export const add ✓"]
```

In this example, fallow traces the import of `add` in `app.ts` through `src/index.ts` and `utils/index.ts` back to `utils/math.ts`. The `add` export is correctly marked as used across the entire chain.

Resolution handles:

* **Multi-level chains:** Any depth of `export *` re-exports is followed until the original declaration is found.
* **Cycle detection:** Circular re-export chains (e.g., `a` re-exports from `b`, `b` re-exports from `a`) are detected and handled gracefully.
* **Mixed re-exports:** Named re-exports (`export { foo } from './bar'`) and namespace re-exports (`export * from './bar'`) are both tracked.

When two `export *` sources contribute the same name, ECMAScript treats that
name as ambiguous and the barrel does not export it. Fallow suppresses findings
that would otherwise blame the contributing declarations, members, components,
or injections until the barrel collision is fixed. Use
[`fallow trace FILE:NAME`](/cli/trace) to inspect the contributing source files
and whether the collision occurs in the type namespace, value namespace, or
both.

## Namespace import narrowing

When a file uses `import * as ns from './module'`, fallow narrows which exports are actually consumed by scanning for member accesses (`ns.foo`, `ns.bar`) and destructuring patterns (`const { foo, bar } = ns`) in the importing file.

```ts theme={null}
import * as utils from './utils';

// Only foo and bar are marked as used. baz remains unused
const { foo } = utils;
utils.bar();
```

Works with static imports, dynamic imports (`const mod = await import('./x')`), and require (`const mod = require('./x')`).

Fallow also uses `oxc_semantic` scope analysis to detect imports where the binding is never read. An `import { foo } from './utils'` where `foo` is never referenced in the file does not count as a reference to the `foo` export. This improves unused-export detection precision.

<Note>
  Whole-object consumption patterns like `Object.values(ns)`, `{ ...ns }`, `for (const k in ns)`, and rest destructuring (`const { a, ...rest } = ns`) conservatively mark all exports as used. Fallow can't determine which specific members are accessed in these cases.
</Note>

## Class member detection

Fallow detects unused public class members (methods and properties) that are never referenced outside their defining class. Unlike simple text matching, fallow understands class inheritance, decorators, and framework conventions.

```typescript theme={null}
class OrderService {
  // Used: called in checkout.ts
  async createOrder(items: Item[]) { /* ... */ }
  
  // Unused: never called outside this class
  private validateItems(items: Item[]) { /* ... */ }
  
  // Excluded: decorator indicates runtime wiring
  @Post('/orders')
  handleCreateOrder() { /* ... */ }
}
```

What fallow handles automatically:

* **Inheritance**: A method defined on a parent class and called via the parent type credits the child's override as used
* **Decorators**: Decorated members are excluded from detection by default. Decorators like `@Get()`, `@Column()`, `@Injectable()` indicate runtime wiring
* **Framework lifecycle methods**: `componentDidMount`, `ngOnInit`, `connectedCallback`, and other framework lifecycle methods are never flagged
* **Whole-object patterns**: `Object.values(instance)`, `Object.keys()`, spread operators, and `for..in` loops conservatively mark all members as used

### Opting decorators out via `ignoreDecorators`

If you use utility decorators that do NOT imply reflective consumption (Playwright's `@step("label")`, internal labeling decorators like `@measure`, `@log`, `@retry`), list their names in the `ignoreDecorators` config option so methods decorated with ONLY those names are checked for usage like undecorated methods.

```jsonc theme={null}
// .fallowrc.json
{
  "ignoreDecorators": ["@step"]
}
```

Conservative semantics: a method carrying any decorator NOT in the list still gets skipped, so `@step` combined with `@Inject` on the same method stays treated as framework-managed.

See [`ignoreDecorators`](/configuration/overview#ignoredecorators) for the matching rules and the unmatched-entry warning.

<Note>
  Class member detection works via syntactic analysis, without invoking the TypeScript compiler. This means fallow tracks member access through the import graph, not through type resolution.
</Note>

## CSS and SCSS tracking

Fallow tracks CSS and SCSS imports using dedicated extraction. SCSS `@use`, `@forward`, and partial imports (`_prefix` files) are resolved accurately. CSS Module class names are extracted as named exports and tracked through `styles.className` member accesses.

See [CSS, SCSS, and Tailwind analysis](/analysis/css-analysis) for full details.

## Entry-point partial unused exports

When a file is an entry point (matched by a plugin or the `entry` config), fallow traditionally marks all its exports as used. Starting in v2.15.0, fallow can detect partially unused exports in entry-point files: exports that exist in an entry file but are never imported by any other module in the project.

This is especially useful for framework convention files (Next.js pages, SvelteKit routes) where the framework consumes specific named exports (like `default`, `loader`, or `getStaticProps`) but the file may also export helper functions that nothing uses.

<Note>
  Entry-point files are still considered used (never reported as unused files), but individual exports within them that have zero references are now reported as unused exports.
</Note>

## Cross-reference with duplication

Running `fallow dead-code --include-dupes` cross-references dead code findings with code duplication analysis. Clone instances in unused files, or overlapping with unused exports, are flagged as **combined high-priority findings**.

```bash theme={null}
fallow dead-code --include-dupes
```

Use `--include-dupes` to prioritize cleanup: if a block of code is both duplicated *and* unused, removing it eliminates dead code and reduces duplication at the same time.

What the cross-reference finds:

* **Clone instances in unused files:** If a file is unreachable from entry points and contains duplicated code, the duplication finding is elevated.
* **Clone instances overlapping unused exports:** If an unused export contains code that is duplicated elsewhere, both findings are reported together.

## Circular dependency benchmarks

This is not a like-for-like comparison. `fallow dead-code --circular-deps` runs the full analysis pipeline (dead code, dependencies, boundaries, cycles) while madge and dpdm only build an import graph. dpdm reports incomplete cycle counts on these fixtures, so its timings are not directly comparable. Cold runs, fastest tool per row in bold.

| Project                                               |  Files |    fallow |     madge |     vs madge |      dpdm |     vs dpdm |
| :---------------------------------------------------- | -----: | --------: | --------: | -----------: | --------: | ----------: |
| [zod](https://github.com/colinhacks/zod)              |    174 |  **43ms** |     532ms | fallow 12.4x |     192ms | fallow 4.5x |
| [preact](https://github.com/preactjs/preact)          |    244 |  **75ms** |     299ms |  fallow 4.0x |     134ms | fallow 1.8x |
| [fastify](https://github.com/fastify/fastify)         |    286 |  **97ms** |     224ms |  fallow 2.3x |     165ms | fallow 1.7x |
| [vue/core](https://github.com/vuejs/core)             |    522 | **137ms** |     173ms |  fallow 1.3x |     145ms | dpdm faster |
| [TypeScript](https://github.com/microsoft/TypeScript) | 38,146 |     2.18s |     5.16s |  fallow 2.4x | **136ms** | dpdm faster |
| [next.js](https://github.com/vercel/next.js)          | 20,552 |     3.00s | **485ms** | madge faster |     463ms | dpdm faster |

<Info>
  Fallow is faster on small and mid-size projects and on the large TypeScript repo versus madge, while madge wins on large monorepos like next.js and astro. dpdm is fast but reports incomplete cycle counts on these fixtures. Fallow reuses the module graph already built for dead code analysis, so cycle detection adds no extra graph build.
</Info>

## See also

<CardGroup>
  <Card title="CLI: dead-code" icon="terminal" href="/cli/dead-code">
    Full reference for the `fallow dead-code` command and its flags.
  </Card>

  <Card title="Rules & Severity" icon="scale-balanced" href="/configuration/rules">
    Control which issue types are errors, warnings, or disabled.
  </Card>

  <Card title="Auto-fix" icon="wand-magic-sparkles" href="/analysis/auto-fix">
    Automatically remove the dead code fallow finds.
  </Card>
</CardGroup>


# Debugging & troubleshooting
Source: https://docs.fallow.tools/analysis/debugging

Trace export usage, diagnose false positives, and debug fallow's analysis pipeline with built-in tracing and performance profiling tools.

When fallow reports something unexpected, built-in tracing and performance tools help you understand *why*.

## Tracing export usage

Use `--trace FILE:EXPORT` to see the full usage chain for a specific export.

```bash theme={null}
fallow dead-code --trace src/utils/format.ts:formatCurrency
```

```bash title="$ fallow dead-code --trace src/utils/format.ts:formatCurrency" theme={null}
  UNUSED formatCurrency in src/utils/format.ts

  File: reachable
  Reason: No references found, export is unused
```

Prints every file that imports `formatCurrency`, including indirect usage through barrel re-exports. Use this when:

* An export you expected to be used is reported as unused.
* You want to understand which consumers depend on a symbol before removing it.
* A re-export chain is not being resolved as expected.

## Tracing file edges

Use `--trace-file PATH` to see all incoming and outgoing edges for a file in the module graph.

```bash theme={null}
fallow dead-code --trace-file src/components/Button.tsx
```

Shows every import the file makes and every file that imports from it. Use this when:

* A file is reported as unused but you believe something should reference it.
* You want to verify that a file is reachable from entry points.
* You're investigating why a file's exports are all marked unused (maybe the file itself is unreachable).

## Tracing dependency usage

Use `--trace-dependency PACKAGE` to find everywhere a package is used: imports, script binaries, and plugin detection.

```bash theme={null}
fallow dead-code --trace-dependency lodash
```

```bash title="$ fallow dead-code --trace-dependency moment" theme={null}
  UNUSED moment (0 import(s))
```

Reports all import sites, `package.json` script binary usage, and plugin-based detection for the given package. Use this when:

* A dependency is reported as unused but you believe it's used in scripts or config files.
* You want to audit which parts of your codebase depend on a specific package.
* You're evaluating whether a dependency can be removed.

## Tracing duplication clones

Use `dupes --trace FILE:LINE` to see all clone instances at a specific source location.

```bash theme={null}
fallow dupes --trace src/utils/validate.ts:42
```

Shows every other location that shares the same clone group as the code at the given line. Use this when:

* You want to find all copies of a duplicated block before refactoring.
* You're deciding whether to extract a shared function or module.
* A duplication finding seems incorrect and you want to inspect the matched instances.

## Performance profiling

Use `--performance` to get a timing breakdown of each pipeline stage.

```bash theme={null}
fallow dead-code --performance
fallow dupes --performance
```

```bash title="$ fallow dead-code --performance" theme={null}
┌─ Pipeline Performance ─────────────────────────────
│  discover files:       13.2ms  (520 files)
│  workspaces:            2.1ms  (0 workspaces)
│  plugin detection:     21.4ms  (+10.5ms plugin globs under entry points)
│  script analysis:       3.0ms
│  parse/extract:        17.6ms  (520 modules, 520 cached, 0 parsed)
│  cache update:          2.0ms
│  entry points:         12.3ms  (92 entries)
│    root package         1.5ms
│    workspaces           0.0ms
│    plugin globs        10.5ms
│      compile            9.9ms
│      match              0.2ms
│      (other)            0.4ms
│    infrastructure       0.2ms
│    dynamic globs        0.0ms
│    dedup                0.0ms
│    (other)              0.0ms
│  resolve imports:       0.0ms
│  build graph:           5.1ms
│  analyze:              19.3ms
│  (other):               0.0ms
│  ────────────────────────────────────────────────
│  TOTAL:                61.4ms
└───────────────────────────────────────────────────
```

The indented rows under `entry points` partition that stage rather than add to it, so they are not part of the `TOTAL` sum. They appear only when the stage cost at least 5ms, which keeps a fast project's box short. Use them when entry-point discovery is the expensive stage and you want to know whether the cost is plugin glob compilation, workspace traversal, or something else.

The `(other)` row is the time inside `TOTAL` not attributed to a named stage (report assembly and inter-stage glue), so the sequential stages plus `(other)` sum to `TOTAL`. In combined mode (`fallow` with no subcommand) the `duplication` stage runs concurrently with the rest of the pipeline and is marked `(concurrent)`; it is shown for reference but is not part of the `TOTAL` sum, so it can legitimately exceed `TOTAL` when duplication detection runs longer than the dead-code pass.

Use this when:

* Analysis is slower than expected and you want to find the bottleneck.
* You want to verify the cache is working (high hit rate means incremental runs are fast).
* You're comparing performance across different configuration options.

### Parallel parse timing

`parse/extract` runs across all cores. When the parse work was substantial and genuinely parallel, the line gains a `(parallel: ~Nms CPU)` suffix reporting the summed parse CPU across workers:

```bash title="$ fallow dead-code --performance (cold cache)" theme={null}
│  parse/extract:       382.4ms  (21033 modules, 0 cached, 21033 parsed)  (parallel: ~594ms CPU)
```

Here the stage finished in 382ms of wall-clock but spent \~594ms of CPU across cores. When that figure is much larger than the wall-clock the stage is CPU-bound and benefits from more cores; when it is close to the wall-clock the stage is I/O-bound and extra threads will not help. The suffix is omitted on warm or trivial runs where there is little real parse work to report.

In combined mode (`fallow` with no subcommand), the health breakdown reuses the discovered and parsed files from the dead-code pass, so its `discover files` and `parse/extract` rows read `(measured above)` and point you at the Pipeline Performance box where that cost is attributed.

In `--format json`, the timings carry `parse_cpu_ms` (summed parse CPU) alongside the wall-clock fields, and the health timings carry `shared_parse`. These are observational and vary run to run, so do not gate CI on them.

## Cache behavior

Fallow caches parsed AST data using bincode serialization with xxh3 hashing. On later runs, unchanged files load from cache instead of being re-parsed.

```bash theme={null}
# Run with caching (default)
fallow dead-code

# Skip the cache entirely
fallow dead-code --no-cache
```

Use `--no-cache` when:

* You suspect stale cache entries are causing incorrect results.
* You've changed fallow versions and want a clean analysis.
* You're benchmarking full parse performance.

The `--performance` flag shows cache statistics, including how many files were cache hits vs. misses. A high hit rate on incremental runs is expected. Only modified files need re-parsing.

### A refused cache says so

A run that had a cache but could not reuse it prints the reason under the stage that paid for it, so a refusal never reads like a first run:

```bash title="$ fallow dead-code --performance" theme={null}
│  parse/extract:        16.2ms  (335 modules, 0 cached, 335 parsed)  (parallel: ~98ms CPU)
│  parse cache not reused: cache format version changed
```

The module-graph cache reports the same way on its own line, `graph cache not reused`, under `build graph`. Neither line appears when the cache was reused, and neither appears under `--no-cache`, where you asked for the cold path. [`fallow doctor`](/cli/doctor) reports the same two states before you run an analysis.

## Common false positives

### Dynamic imports with runtime values

Fallow resolves template literals and `import.meta.glob`, but fully dynamic imports like `import(variable)` can't be resolved statically.

**Fix**: Add the target directory to `entry` in your config:

```jsonc theme={null}
{
  "entry": ["src/plugins/*.ts"]
}
```

### Convention-based exports

Some frameworks consume exports by naming convention rather than explicit imports. For example, Next.js `generateStaticParams` or Remix `loader` functions.

**Fix**: Fallow's built-in plugins already handle most frameworks. If you're using a niche framework, create a [custom plugin](/frameworks/custom-plugins) or use `ignoreExports`:

```jsonc theme={null}
{
  "ignoreExports": [
    { "file": "src/routes/**/*.ts", "exports": ["loader", "action"] }
  ]
}
```

### Dependency injection frameworks

DI containers (NestJS, Angular, InversifyJS) resolve dependencies at runtime via decorators and metadata. Fallow skips decorated class members by default, but injected services may look unused if they're only referenced via DI tokens.

**Fix**: Add the DI-registered files as entry points, or suppress specific findings:

```typescript theme={null}
// fallow-ignore-next-line unused-export
export class UserService { /* ... */ }
```

If your codebase uses utility decorators that DO NOT imply reflective use (Playwright `@step`, internal `@measure`, `@log`, etc.), opt them out of the skip via `ignoreDecorators` so methods carrying ONLY those names are checked for usage normally:

```jsonc theme={null}
// .fallowrc.json
{ "ignoreDecorators": ["@step"] }
```

A method carrying any decorator NOT in the list stays skipped, so `@step + @Inject` keeps the conservative DI-friendly behavior.

### Peer dependencies and optional dependencies

Packages listed in `peerDependencies` or `optionalDependencies` are not analyzed by default since they may be provided by the consuming project.

**Fix**: If fallow incorrectly flags these, add them to `ignoreDependencies`:

```jsonc theme={null}
{
  "ignoreDependencies": ["react", "react-dom"]
}
```

### Config files not recognized as entry points

If a config file (e.g., `tailwind.config.ts`) is reported as unused, its framework plugin may not be active.

**Fix**: Run `fallow list` to check which plugins are active. If the relevant plugin isn't detected, add the config file to `entry`:

```jsonc theme={null}
{
  "entry": ["tailwind.config.ts"]
}
```

## Missing findings

### Files in a hidden directory are missing

If a file under a dot-prefixed directory never appears in any finding, discovery
did not traverse it. Hidden directories are skipped apart from a few conventional
names and the ones an active framework plugin owns. Check the run's diagnostics:

```bash theme={null}
fallow dead-code --format json --quiet | jq '.workspace_diagnostics[] | select(.kind == "skipped-source-dotdir")'
```

**Fix**: No config field adds a directory to traversal. Analyze it on its own
with `fallow dead-code --root .claude`, or add it to `ignorePatterns` if it is
tool state you never want analyzed. See
[Known limitations](/analysis/limitations) for the full behavior.

## See also

<CardGroup>
  <Card title="Dead Code Analysis" icon="skull-crossbones" href="/analysis/dead-code">
    Overview of how fallow detects unused code.
  </Card>

  <Card title="CLI: dead-code" icon="terminal" href="/cli/dead-code">
    Full reference for the `fallow dead-code` command and all its flags.
  </Card>

  <Card title="Inline Suppression" icon="comment-slash" href="/configuration/suppression">
    Suppress individual findings with inline comments.
  </Card>
</CardGroup>


# Code duplication
Source: https://docs.fallow.tools/analysis/duplication

Detect copy-pasted code blocks across your TypeScript and JavaScript codebase. Built in to the same binary as dead-code, dependency, complexity, and architecture analysis.

`fallow dupes` finds duplicated code blocks across your entire codebase. jscpd v5 is faster for raw duplication scanning on the current README benchmark fixtures; fallow's advantage is running duplication inside the same audit flow as dead code, dependency, complexity, and architecture checks.

```bash theme={null}
fallow dupes
```

## Why built-in duplication matters

Most dead-code analysis tools stop at finding unused exports and unreachable files. Fallow goes further: it includes duplication detection in the same binary, using the same module graph. This means you can cross-reference dead code with duplication in a single pass.

When you run `fallow dead-code --include-dupes`, fallow identifies code blocks that are both duplicated and unused. These are the highest-value cleanup targets: removing them eliminates dead code and reduces duplication simultaneously.

Running duplication analysis alongside dead-code detection also means:

* **One tool, one config, one CI step**: No need to install and configure a separate duplication detector
* **Shared file discovery**: The same ignore patterns, entry points, and workspace config apply to both analyses
* **Cross-analysis insights**: Clone families that span unused files are flagged as combined findings
* **Consistent output formats**: JSON, SARIF, markdown, compact, and CodeClimate output work the same way for duplication as for dead code

## Detection modes

<Tabs>
  <Tab title="Strict">
    Exact token-for-token clones only. No normalization is applied; the code must be character-identical after tokenization.

    ```bash theme={null}
    fallow dupes --mode strict
    ```

    Best for finding exact copy-paste where nothing was changed.
  </Tab>

  <Tab title="Mild (default)">
    The default mode. Strict and mild modes produce identical results. AST-based tokenization already strips whitespace and comments before comparison.

    ```bash theme={null}
    fallow dupes --mode mild
    ```

    The recommended starting point for general-purpose detection.
  </Tab>

  <Tab title="Weak">
    Matches clones even when string literal values differ. Variable names must still match.

    ```bash theme={null}
    fallow dupes --mode weak
    ```

    Good for finding code that was duplicated and only had strings (URLs, messages, labels) changed.
  </Tab>

  <Tab title="Semantic">
    Catches clones with renamed variables and different literal values. Uses token-type normalization to match structurally equivalent code.

    ```bash theme={null}
    fallow dupes --mode semantic
    ```

    The most aggressive mode. Finds code that was copied and then adapted with new variable names and values.
  </Tab>
</Tabs>

<Info>
  `dupes --mode semantic` still compares normalized code structure. To find
  complete functions that may share intent despite different structure, use
  the separate, opt-in [`fallow similar-code`](/analysis/similar-code)
  workflow. Its model-backed results are always unverified and require review.
</Info>

### Near-miss clones

Add `--near` to include function-scoped clones with small structural edits:

```bash theme={null}
fallow dupes --near
```

Near-miss detection uses semantic token normalization and requires at least 80% shingle similarity between every pair in a group. It runs alongside exact clone detection and remains opt-in because it does more work and can surface code that needs human review. Set `duplicates.near` to `true` to enable it by default, or use `fallow.duplication.near` in VS Code.

Here's what typical output looks like:

```bash title="$ fallow dupes" theme={null}
● Duplicates (3 clone groups)

     57 lines  2 instances
    src/components/Calendar/CalendarMonth.stories.tsx:597-653
    src/components/Calendar/CalendarYear.stories.tsx:818-874

     42 lines  3 instances
    src/features/forecasting/server/procedures/analytics.ts:141-181
    src/features/forecasting/server/procedures/cashflow.ts:153-194
    src/features/forecasting/server/procedures/income.ts:590-631

  Identical code blocks detected via suffix-array analysis, https://docs.fallow.tools/explanations/duplication#clone-groups

✓ 27,255 lines (19.4%) duplicated across 398 files (0.23s)
```

In semantic mode, fallow also reports renamed identifiers:

```bash title="$ fallow dupes --mode semantic" theme={null}
● Duplicates (2 clone groups)

    196 lines  2 instances
    src/lib/dutch-holidays.ts:193-388
    src/lib/dutch-holidays.ts:389-584
    Renamed: holidays2024→holidays2025, year2024→year2025

     42 lines  3 instances
    src/features/forecasting/server/procedures/analytics.ts:141-181
    src/features/forecasting/server/procedures/cashflow.ts:153-194
    src/features/forecasting/server/procedures/income.ts:590-631
    Renamed: analyticsData→cashflowData→incomeData

  Identical code blocks detected via suffix-array analysis, https://docs.fallow.tools/explanations/duplication#clone-groups

✗ 94,457 lines (67.2%) duplicated across 775 files (3.74s)
```

## Thresholds and limits

```bash theme={null}
fallow dupes --min-tokens 50        # Minimum tokens per clone (default: 50)
fallow dupes --min-lines 5          # Minimum lines per clone (default: 5)
fallow dupes --min-occurrences 3    # Only report clones repeated 3+ times (default: 2)
fallow dupes --threshold 5          # Fail if duplication exceeds 5%
fallow dupes --skip-local           # Only cross-directory duplicates
```

### Minimum occurrences

By default fallow reports every duplicated pair (`minOccurrences: 2`). If you follow the "rule of three" and only want to refactor logic once it appears in three or more places, raise the threshold:

```jsonc theme={null}
{
  "duplicates": {
    "minOccurrences": 3
  }
}
```

Values below `2` are rejected, since a single occurrence is not a duplicate. Raising this skips context-sensitive pairs and focuses on widespread copy-paste worth abstracting. The VS Code extension exposes the same control as the `fallow.duplication.minOccurrences` setting.

### Spread-aware ranking

Fallow multiplies duplicated token count by occurrence count, then applies a spread boost. Spread is the maximum directory-tree distance between copies. Copies in the same file use one spread step per 250 lines of separation. The boost is capped at 15%, so larger and more repeated clones remain the main priority.

The default report and `--top` use this order. JSON output includes `spread` on every clone group, plus `similarity` for near-miss groups.

### Reviewed clone groups

Use `duplicates.ignoredClones` when a specific clone group is intentional but you want other duplication findings to remain active:

```jsonc theme={null}
{
  "duplicates": {
    "ignoredClones": ["dup:6f12ab34:2"]
  }
}
```

Each entry combines the group's `fingerprint` with its instance count. Copy the fingerprint from the human listing or `clone_groups[].fingerprint` in JSON, then append `:<instance_count>`. A token change or a new copy makes the group reportable again. Formatting-only edits keep the same fingerprint.

JSON output sets `stats.clone_groups_ignored` when reviewed groups are hidden. Near-miss runs set `stats.near_candidates_skipped` if bounded-work limits skip candidate comparisons, which means the near-miss result may be incomplete.

#### Migrating collision handles

Ordinary `dup:<8hex>` handles and widened `dup:<16hex>` handles are unchanged. When groups share a full content fingerprint, their handles use `dup:<16hex>-rN`. These collision handles stay the same when an identical report is produced from another checkout location, but can change when the colliding groups change.

Older numeric collision handles such as `dup:<16hex>-1` still load in `ignoredClones`, but no longer hide or select a group. A baseline containing those handles also lets the affected findings reappear. Run `fallow dupes` again, review each affected group, then copy its reported handle into your configuration or refresh the baseline. Do not mechanically replace `-1` with `-r1`: the ordinal can refer to a different group.

Upgrade every runner that reads a shared configuration before adding `-rN` keys to `ignoredClones`. Older binaries reject that syntax.

## Clone families

Clone groups sharing the same file set are grouped into **clone families** with refactoring suggestions:

* **Extract function**: clones are in the same file
* **Extract module**: clones span multiple files

## Cross-language detection

Compare TypeScript and JavaScript files by stripping type annotations:

```bash theme={null}
fallow dupes --cross-language
```

Fallow normalizes `.ts` files to their `.js` equivalent for comparison. This catches clones where one copy was converted from TypeScript to JavaScript or vice versa.

## Ignoring imports

Files with the same module wiring are a structural property of well-formatted code, not copy-paste, so that wiring is stripped from the token stream by default. This covers ES imports, re-export declarations, and top-level static `require()` binding declarations.

To count module wiring as clone candidates again, opt out on the command line:

```bash theme={null}
fallow dupes --no-ignore-imports
```

Or set it permanently in config:

```jsonc theme={null}
{
  "duplicates": {
    "ignoreImports": false
  }
}
```

Runtime code, local exports, side-effect `require()` calls, nested `require()` calls, dynamic require arguments, and mixed declarations are still counted.

## Incremental analysis

Only check duplication in files changed since a git ref:

```bash theme={null}
fallow dupes --changed-since main
```

Useful in CI to only report new duplication introduced in a pull request.

## Baseline comparison

Adopt duplication limits incrementally:

```bash theme={null}
# Save current duplication as baseline
fallow dupes --save-baseline fallow-baselines/dupes.json

# Fail only on new duplication
fallow dupes --baseline fallow-baselines/dupes.json
```

## Debugging

Trace all clones of a specific code location:

```bash theme={null}
fallow dupes --trace src/utils.ts:42
```

## Benchmarks vs jscpd

Cold runs (no cache) so each tool works from scratch. Fastest tool per row in bold.

| Project                                               |  Files | fallow |     jscpd |      Faster |
| :---------------------------------------------------- | -----: | -----: | --------: | ----------: |
| [astro](https://github.com/withastro/astro)           |  2,859 |  549ms | **189ms** |  jscpd 2.9x |
| [fastify](https://github.com/fastify/fastify)         |    286 |   90ms |  **64ms** |  jscpd 1.4x |
| [next.js](https://github.com/vercel/next.js)          | 20,552 | 12.66s | **861ms** | jscpd 14.7x |
| [preact](https://github.com/preactjs/preact)          |    244 |   58ms |  **49ms** |  jscpd 1.2x |
| [TanStack/query](https://github.com/TanStack/query)   |    901 |  133ms |  **96ms** |  jscpd 1.4x |
| [svelte](https://github.com/sveltejs/svelte)          |  3,337 |  317ms | **172ms** |  jscpd 1.8x |
| [TypeScript](https://github.com/microsoft/TypeScript) | 38,146 | 13.45s | **4.58s** |  jscpd 2.9x |
| [vite](https://github.com/vitejs/vite)                |  1,420 |  174ms |  **74ms** |  jscpd 2.3x |
| [vue/core](https://github.com/vuejs/core)             |    522 |  109ms |  **78ms** |  jscpd 1.4x |
| [zod](https://github.com/colinhacks/zod)              |    174 |   54ms |  **53ms** |  jscpd 1.0x |

jscpd's Rust rewrite (v5) is faster than fallow for raw duplication scanning across these projects. Fallow's advantage is running duplication inside the same single audit pass as dead code, dependency, complexity, CSS, framework, and security checks, not raw scan speed.

Fallow uses a <Tooltip>suffix array</Tooltip> with <Tooltip>LCP</Tooltip> for clone detection, avoiding quadratic pairwise comparison.

## See also

<CardGroup>
  <Card title="CLI: dupes" icon="terminal" href="/cli/dupes">
    Full reference for the `fallow dupes` command and its flags.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Set default duplication thresholds and modes in your config file.
  </Card>

  <Card title="Semantic similar code" icon="code-compare" href="/analysis/similar-code">
    Find differently written functions that may share intent.
  </Card>
</CardGroup>


# Non-JS file types
Source: https://docs.fallow.tools/analysis/file-types

Fallow analyzes HTML, Vue, Svelte, Astro, MDX, GraphQL, CSS modules, SCSS, and React Native files automatically. No plugins or config needed.

Fallow analyzes more than `.js` and `.ts` files. It extracts imports and exports from non-JavaScript file types automatically based on their extension. No plugins or config needed.

<Tabs>
  <Tab title="HTML">
    Fallow discovers `.html` files and extracts edges from `<script src>` and `<link>` tags. This covers projects that use HTML entry points (such as Parcel or vanilla setups).

    **What's supported:**

    * `<script src="./main.js">` script references
    * `<link rel="stylesheet" href="./styles.css">` stylesheet references
    * `<link rel="modulepreload" href="./vendor.js">` module preload references
    * Root-relative paths (e.g., `<script src="/src/main.tsx">`) are resolved against the project root, matching the convention used by Vite, Parcel, and similar dev servers. Root-relative resolution also applies when the reference comes from a JSX/TSX/JS/TS source file (see the JSX templates tab).

    ```html index.html theme={null}
    <!DOCTYPE html>
    <html>
      <head>
        <link rel="stylesheet" href="./styles/main.css" />
        <link rel="modulepreload" href="./vendor/lodash.js" />
      </head>
      <body>
        <div id="app"></div>
        <script src="./src/main.ts"></script>
      </body>
    </html>
    ```

    Fallow sees this file as referencing `./styles/main.css`, `./vendor/lodash.js`, and `./src/main.ts`.

    <Tip>
      The Parcel plugin automatically adds `index.html` as an entry pattern, so HTML entry files are picked up without any extra config.
    </Tip>

    **Angular template complexity.** Standalone `.html` files referenced via `templateUrl` and inline `@Component({ template: \`...\` })`literals both contribute synthetic`\<template>`complexity findings to`fallow health`. The scanner recognises control-flow blocks (`@if`, `@for`, `@switch`, `@case`, `@defer (when ...)`, `@let`), legacy structural directives (`\*ngIf`, `\*ngFor`), bound attributes (`\[x]`, `(x)`, `bind-x`, `on-x`), and ``interpolations. Inline-template findings anchor at the`@Component`decorator line and suppress with`// fallow-ignore-next-line complexity`directly above the decorator; external-template findings suppress with`\<!-- fallow-ignore-file complexity -->`at the top of the`.html\` file.
  </Tab>

  <Tab title="Vue / Svelte">
    Fallow extracts the `<script>` block from Vue and Svelte single-file components and analyzes it like a standalone JS/TS module. It also scans `<template>` sections for component references, directives, and expression usage, so imports used only in templates are correctly tracked.

    **Script extraction:**

    * `<script>` and `<script setup>` blocks
    * `lang="ts"` and `lang="tsx"` attributes
    * `<script src="./external.ts">` external script references
    * HTML comments (`<!-- ... -->`) are filtered out before parsing

    **Vue template tracking:**

    * Component tags: `<MyComponent>` resolves to imported `MyComponent`
    * Custom directives: `v-focus-trap` resolves to imported `vFocusTrap`
    * `v-on` and `v-bind` object syntax (e.g., `v-on="handlers"`)
    * Template expressions: `{{ formatDate() }}` marks `formatDate` as used
    * Namespace member access: `utils.formatDate` in templates tracks the member usage

    **Svelte template tracking:**

    * Component tags: `<Button>` resolves to imported `Button`
    * Directives: `use:tooltip`, `transition:fade`, `animate:flip`, `in:fly`, `out:fade`
    * Attribute expressions: `{expression}` and shorthand attributes `{variable}`
    * `$store` subscriptions: `$myStore` marks `myStore` as used

    ```vue Example.vue theme={null}
    <script setup lang="ts">
    import { ref } from 'vue'
    import { formatDate } from '@/utils/date'
    import FocusTrap from '@/components/FocusTrap.vue'

    const count = ref(0)
    </script>

    <template>
      <FocusTrap>
        <div>{{ formatDate(new Date()) }}</div>
      </FocusTrap>
    </template>
    ```

    Fallow sees this file as importing `ref` from `vue`, `formatDate` from `@/utils/date`, and `FocusTrap` from `@/components/FocusTrap.vue`. The `<FocusTrap>` tag and `formatDate` reference in the template are tracked, so they won't be reported as unused even though they don't appear in the script block.

    <Warning>
      Svelte components export props implicitly. Fallow cannot distinguish between props and utility exports, which may cause false negatives for unused exports in `.svelte` files. See [Limitations](/analysis/limitations) for details.
    </Warning>
  </Tab>

  <Tab title="SSR layouts">
    SSR frameworks like [Hono](https://hono.dev) render HTML from layout components using either JSX or a tagged template literal (`` html`...` ``). Fallow treats `<script src="...">` and `<link rel="stylesheet|modulepreload" href="...">` inside both forms the same way it treats them in plain HTML: as asset references that keep the target file reachable.

    **What's supported:**

    * `<script src="./app.js">` inside JSX/TSX layouts and `` html`...` `` tagged templates
    * `<link rel="stylesheet" href="./global.css">` inside JSX/TSX layouts and `` html`...` `` tagged templates
    * `<link rel="modulepreload" href="./vendor.js">` inside JSX/TSX layouts and `` html`...` `` tagged templates
    * Root-relative paths (`<link href="/static/style.css">`) resolve against the source file's parent directory first, then the project root, matching how Vite/Parcel/Hono serve static assets

    ```tsx Layout.tsx theme={null}
    export const Layout = () => (
      <html>
        <head>
          <link rel="stylesheet" href="/static/style.css" />
          <script src="/static/app.js"></script>
        </head>
        <body>
          <h1>Hello from Hono</h1>
        </body>
      </html>
    );
    ```

    ```ts layout.ts theme={null}
    import { html } from 'hono/html'

    export const Layout = ({ title, body }: { title: string; body: string }) => html`
      <!doctype html>
      <html>
        <head>
          <title>${title}</title>
          <link rel="stylesheet" href="/static/style.css" />
          <script defer src="/static/app.js"></script>
        </head>
        <body>${body}</body>
      </html>
    `
    ```

    Fallow sees both files as referencing `/static/style.css` and `/static/app.js`, so sibling files in `static/` are correctly marked reachable.

    <Note>
      In JSX, only lowercase intrinsic elements (`<script>`, `<link>`) and plain string literals (`src="foo.css"`) are tracked. Capitalized React-style components (`<Script>`, `<Link>`) and expression containers (`href={someVar}`) are intentionally skipped because they have component-specific semantics that fallow can't statically resolve.

      In tagged templates, only the bare identifier tag `html` is matched. Other tags like `css`, `sql`, and `gql` are left alone. Asset references split across an interpolation boundary (`` html`<script src="${base}/app.js">` ``) are skipped rather than producing garbled specifiers.
    </Note>
  </Tab>

  <Tab title="JSDoc">
    Plain JavaScript files can reference TypeScript types through JSDoc `import()` expressions. Fallow extracts these references and marks the referenced types as used, so untyped JS files don't produce false unused-export reports.

    ```js app.js theme={null}
    /**
     * @param cfg {import('./types.ts').Config}
     * @returns {import('./types.ts').Result}
     */
    function boot(cfg) {
      return { ok: true };
    }
    ```

    Fallow tracks the `Config` and `Result` types from `./types.ts` as used, even though no `import` statement binds them. This works across all JSDoc tag contexts (`@param`, `@returns`, `@type`, `@typedef`, `@callback`) and supports union annotations with multiple `import()` expressions (`{import('./a').A | import('./b').B}`), nested member access, bare package specifiers, and parent-relative paths.

    <Note>
      Only `/** */` JSDoc blocks are scanned. Single-star `/* */` comments are not JSDoc and are ignored, matching the TypeScript compiler's behavior.
    </Note>
  </Tab>

  <Tab title="Astro">
    Astro components use a frontmatter block delimited by `---` at the top of the file. Fallow extracts everything between the two `---` delimiters and analyzes it as TypeScript.

    Fallow also follows per-component client scripts in the template body: `<script src="...">` references and ESM `import` statements inside inline `<script>` blocks. Astro bundles both into the page output at build time, so their targets stay reachable.

    ```astro Layout.astro theme={null}
    ---
    import Header from '../components/Header.astro'
    import Footer from '../components/Footer.astro'
    import type { Props } from './types'
    ---

    <html>
      <body>
        <Header />
        <slot />
        <Footer />
        <script src="../scripts/analytics.ts"></script>
        <script>
          import '../scripts/hydrate'
        </script>
      </body>
    </html>
    ```

    Fallow sees this file as importing `Header`, `Footer`, the `Props` type, plus `../scripts/analytics.ts` (external) and `../scripts/hydrate` (inline ESM).
  </Tab>

  <Tab title="MDX">
    MDX files can contain JavaScript `import` and `export` statements alongside Markdown content. Fallow extracts these statements and includes them in the module graph.

    ```mdx guide.mdx theme={null}
    import { CodeBlock } from '../components/CodeBlock'
    import { Callout } from '../components/Callout'

    export const meta = { title: 'Getting Started' }

    # Getting Started

    <CodeBlock language="bash">
      npm install fallow
    </CodeBlock>
    ```

    Fallow tracks the imports of `CodeBlock` and `Callout`, and the named export `meta`.
  </Tab>

  <Tab title="GraphQL">
    GraphQL document files can reference fragments from nearby `.graphql` and `.gql` files with `#import` comments. Fallow extracts those relative document links and keeps imported fragment files reachable.

    **What's supported:**

    * `#import "./fragment.graphql"` relative imports
    * `# import '../shared/fields.gql'` with optional whitespace after `#`
    * Extensionless relative imports such as `#import "./fragment"`, resolved through `.graphql` and `.gql`

    ```graphql query.graphql theme={null}
    #import "./fragments/user-fields"

    query CurrentUser {
      currentUser {
        ...UserFields
      }
    }
    ```

    ```graphql fragments/user-fields.graphql theme={null}
    fragment UserFields on User {
      id
      name
    }
    ```

    Fallow sees `query.graphql` as referencing `./fragments/user-fields`, probes `.graphql` and `.gql` when no extension is present, and marks `fragments/user-fields.graphql` as reachable.

    <Note>
      Only relative `#import` specifiers starting with `./` or `../` are tracked. Package specifiers and schema-loader syntax are intentionally ignored because they do not map to a local source document in the module graph.
    </Note>
  </Tab>

  <Tab title="CSS / SCSS Modules">
    Fallow tracks CSS and SCSS module files (`.module.css` and `.module.scss`) by extracting class names as named exports. When a component imports `styles` from a CSS module, fallow knows which classes exist.

    ```css Button.module.css theme={null}
    .root {
      display: flex;
    }

    .primary {
      background: blue;
    }

    .disabled {
      opacity: 0.5;
    }
    ```

    This file exports `root`, `primary`, and `disabled` as named exports.

    **CSS features fallow tracks:**

    | Feature                | Description                                                                       |
    | :--------------------- | :-------------------------------------------------------------------------------- |
    | `@import`              | CSS import statements create edges in the module graph                            |
    | `@use`                 | Sass `@use` rules are resolved as module imports                                  |
    | `@forward`             | Sass `@forward` rules are treated as re-exports                                   |
    | `@apply` / `@tailwind` | Detected as Tailwind CSS dependency usage                                         |
    | `@plugin`              | Tailwind v4 plugin sources are extracted as default imports (package or relative) |

    <Tip>
      When Tailwind is in your `package.json`, fallow recognizes `@apply` and `@tailwind` directives as evidence that the `tailwindcss` dependency is used, preventing false "unused dependency" reports. Tailwind v4 `@plugin "pkg"` directives credit their package or local plugin file directly.
    </Tip>
  </Tab>

  <Tab title="React Native">
    React Native projects use platform-specific file extensions for different implementations per platform. Fallow understands these extensions and treats them as variants of the same module.

    **Supported platform extensions:**

    | Extension                      | Platform               |
    | :----------------------------- | :--------------------- |
    | `.web.ts` / `.web.tsx`         | Web (react-native-web) |
    | `.ios.ts` / `.ios.tsx`         | iOS                    |
    | `.android.ts` / `.android.tsx` | Android                |
    | `.native.ts` / `.native.tsx`   | Native (iOS + Android) |

    ```text theme={null}
    src/
      Button.tsx          # Default implementation
      Button.web.tsx      # Web override
      Button.native.tsx   # Native override
    ```

    When another file imports `./Button`, fallow resolves it to all platform variants and considers each one reachable.
  </Tab>
</Tabs>

## See also

<CardGroup>
  <Card title="Dead code analysis" icon="skull-crossbones" href="/analysis/dead-code">
    How fallow builds the module graph and detects unused code.
  </Card>

  <Card title="Built-in plugins" icon="puzzle-piece" href="/frameworks/built-in">
    Built-in framework plugins for automatic entry point detection.
  </Card>
</CardGroup>


# Analysis
Source: https://docs.fallow.tools/analysis/index

What Fallow analyzes: dead code, duplication, architecture boundaries, auto-fix, and runtime coverage.

Fallow analyzes your codebase at two levels:

* **Static intelligence**: structure, reachability, duplication, complexity, boundaries, and flags
* **Runtime intelligence**: what actually executed in production

## Static analysis

<CardGroup>
  <Card title="Dead code" icon="skull-crossbones" href="/analysis/dead-code">
    Unused files, exports, types, dependencies, circular deps, and more.
  </Card>

  <Card title="Type-aware TypeScript" icon="code" href="/analysis/type-aware">
    Add exact symbol evidence when a cleanup or refactor needs more than syntax.
  </Card>

  <Card title="Duplication" icon="clone" href="/analysis/duplication">
    Find repeated blocks from exact to semantic clones.
  </Card>

  <Card title="Architecture boundaries" icon="diagram-project" href="/analysis/boundaries">
    Enforce import rules across layers and modules.
  </Card>

  <Card title="Auto-fix" icon="wand-magic-sparkles" href="/analysis/auto-fix">
    Remove unused exports and dependencies automatically.
  </Card>
</CardGroup>

## Runtime analysis

<CardGroup>
  <Card title="Runtime coverage" icon="chart-network" href="/analysis/runtime-coverage">
    Add runtime evidence to `fallow health` for hot paths, cold paths, and deletion confidence.
  </Card>
</CardGroup>

## Supporting topics

<CardGroup>
  <Card title="Production mode" icon="box" href="/analysis/production-mode">
    Exclude test and dev files from analysis.
  </Card>

  <Card title="Non-JS file types" icon="file" href="/analysis/file-types">
    How Fallow handles JSON, HTML, and other file types.
  </Card>

  <Card title="CSS, SCSS, and Tailwind" icon="paintbrush" href="/analysis/css-analysis">
    AST-based CSS Module, SCSS, and Tailwind tracking.
  </Card>

  <Card title="Debugging" icon="bug" href="/analysis/debugging">
    Trace why something is reported (or missed).
  </Card>

  <Card title="Limitations" icon="circle-exclamation" href="/analysis/limitations">
    What Fallow does not cover and why.
  </Card>
</CardGroup>


# Known limitations
Source: https://docs.fallow.tools/analysis/limitations

Known limitations of fallow's syntactic analysis, including dynamic imports, runtime patterns, and framework-specific edge cases with workarounds.

Fallow's default analysis is syntactic: no TypeScript compiler, no type
resolution. The optional [`--type-aware`](/analysis/type-aware) pass adds
bounded checker evidence for Fallow-owned project questions. It does not turn
Fallow into a compiler or general typed linter.

<Info>
  The limitations below apply to specific patterns. Standard TypeScript projects with `isolatedModules: true` are unaffected by most of them.
</Info>

<Accordion title="Syntactic analysis only (no TypeScript type information)">
  By default, Fallow parses source code as syntax trees using Oxc and uses
  `oxc_semantic` for scope-aware binding analysis. It does not invoke the
  TypeScript compiler or resolve type information. This keeps the default path
  fast. Add [`--type-aware`](/analysis/type-aware) for exact symbol identity,
  cross-file private type leaks, targeted tests, and public type coupling.

  **Impact:** Type-only imports (`import type { Foo }`) are handled correctly. Value imports used only as type annotations (e.g., `import { Foo }` followed by `const x: Foo`) are also tracked correctly via `oxc_semantic` reference counting. Conditional type exports or dead code behind generic interfaces would require actual type resolution to detect.

  **Workaround:** Set `isolatedModules: true` in `tsconfig.json`. esbuild, swc, and Vite already require this, so most modern projects have it. With `isolatedModules`, every import is either explicitly `import type` or a real value import, removing ambiguity.

  ```jsonc tsconfig.json theme={null}
  {
    "compilerOptions": {
      "isolatedModules": true
    }
  }
  ```
</Accordion>

<Accordion title="Svelte export let prop ambiguity">
  In Svelte components, `export let` declarations serve double duty: they define component props **and** regular exports. Fallow can't distinguish between props (used by consumers via the template) and utility exports that may genuinely be unused.

  **Impact:** Some unused exports in `.svelte` files may not be reported.

  **Workaround:** No configuration workaround exists. Review Svelte component exports manually. Extract utility functions into separate `.ts` files where fallow can track them accurately.

  <Tip>
    This limitation is about `export let` prop detection only. Fallow **does** track template-visible imports since v2.15.0: component tags, directives (`use:tooltip`, `v-focus-trap`), expressions, `$store` subscriptions in Svelte, and `v-on`/`v-bind` object syntax in Vue are all correctly credited as used. See [File types](/analysis/file-types) for details.
  </Tip>
</Accordion>

<Accordion title="CSS/SCSS regex-based parsing">
  CSS and SCSS files are parsed with lightweight regex extraction rather than a full CSS parser. This covers the most common patterns but not the entire CSS specification.

  **What's tracked:**

  * `@import` and `@use` statements
  * `@forward` rules
  * `@apply` and `@tailwind` directives (as Tailwind dependency usage)
  * `@plugin` directives (Tailwind v4 plugin sources, package or relative)

  **What's not tracked:**

  * `composes:` (CSS Modules composition)
  * `:global()` and `:local()` pseudo-selectors
  * Complex selector-based dependencies

  **Workaround:** If fallow reports false positives for CSS files that use `composes:` or `:global()`, suppress them with `ignorePatterns` or inline comments.

  ```jsonc .fallowrc.json theme={null}
  {
    "ignorePatterns": ["**/legacy-styles/**/*.css"]
  }
  ```
</Accordion>

<Accordion title="NestJS and dependency injection class members">
  Fallow tracks class member usage syntactically by looking for direct references in source code. In NestJS and other DI frameworks, abstract class methods may be invoked at runtime through the DI container without appearing as direct references.

  **Impact:** Abstract class methods and properties consumed via dependency injection may be reported as unused.

  **Workaround:** Disable `unused-class-members` for DI-heavy projects:

  <CodeGroup>
    ```jsonc .fallowrc.json theme={null}
    {
      "rules": {
        "unused-class-members": "off"
      }
    }
    ```

    ```toml fallow.toml theme={null}
    [rules]
    unused-class-members = "off"
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Library consumer types (noisy but correct)">
  If your package exports types for external consumers (e.g., `ButtonProps`, `Config`), fallow correctly reports them as unused within your project, because they are. No internal file imports them.

  **Impact:** Correct findings that are noisy for library authors.

  **Workaround:** Use `ignoreExports` to mark public API files:

  ```jsonc .fallowrc.json theme={null}
  {
    "ignoreExports": [
      { "file": "src/index.ts", "exports": ["*"] },
      { "file": "src/types.ts", "exports": ["*"] }
    ]
  }
  ```
</Accordion>

<Accordion title="Config parsing ceiling">
  Fallow's built-in plugins parse config files (e.g., `vite.config.ts`, `jest.config.js`) using Oxc's AST parser. This handles static objects, arrays, and `defineConfig()` wrappers, but it can't evaluate arbitrary JavaScript.

  **What's handled:**

  * Static object literals and arrays
  * `defineConfig()` / `module.exports` wrappers
  * String concatenation in simple cases

  **What's not handled:**

  * Computed property keys
  * Conditional expressions (`process.env.NODE_ENV === 'production' ? ... : ...`)
  * Nested factory functions
  * Dynamic `require()` with variables

  **Workaround:** Add undetected entry points manually in your fallow config:

  ```jsonc .fallowrc.json theme={null}
  {
    "entry": ["src/dynamic-entry.ts", "scripts/*.ts"]
  }
  ```
</Accordion>

<Accordion title="React Native native modules">
  React Native auto-linked native packages (installed via `npx pod-install` or auto-linking) aren't detected as used by fallow. These packages may not have any explicit `import` in JavaScript code.

  **Impact:** Auto-linked packages like `react-native-screens` or `react-native-gesture-handler` may be reported as unused dependencies.

  **Workaround:** Add auto-linked packages to `ignoreDependencies`:

  ```jsonc .fallowrc.json theme={null}
  {
    "ignoreDependencies": [
      "react-native-screens",
      "react-native-gesture-handler",
      "react-native-safe-area-context"
    ]
  }
  ```
</Accordion>

<Accordion title="Hidden directories are not traversed">
  Discovery skips dot-prefixed directories. Five conventional names are
  traversed by default (`.storybook`, `.vitepress`, `.well-known`,
  `.changeset`, `.github`), and an active framework plugin can contribute the
  hidden directory its framework owns. Everything else is dropped before its
  contents are parsed, which keeps machine-written trees such as `.next`,
  `.turbo`, and `.venv` out of analysis without any configuration.

  **Impact:** First-party source under a hidden directory, for example agent
  hooks in `.claude/hooks/` or plugins in `.omp/extensions/`, is not analyzed.
  Its imports and exports are invisible, so it neither produces findings of its
  own nor credits the modules it imports. The run reports the skip rather than
  dropping it silently: a `skipped-source-dotdir` entry in
  `workspace_diagnostics[]` and one aggregated note on stderr name each hidden
  directory that holds source files your project has not otherwise excluded.

  **Workaround:** No config field adds a directory to traversal. Analyze the
  directory on its own by pointing fallow at it:

  ```bash theme={null}
  fallow dead-code --root .claude
  ```

  If the directory holds tool or agent scratch state you never want analyzed,
  add it to `ignorePatterns` to silence the advisory:

  ```jsonc .fallowrc.json theme={null}
  {
    "ignorePatterns": [".claude/**"]
  }
  ```

  Contents already excluded from the run stay silent on their own, so a hidden
  directory covered by `.gitignore` (including a global gitignore, which
  commonly covers agent tooling) never produces the advisory.
</Accordion>

<Accordion title="LSP column offsets are byte-based">
  The fallow LSP server reports column positions as byte offsets rather than character offsets. For ASCII-only source files this makes no difference. For files with multi-byte characters (emoji, CJK, accented characters), the column number may be off by a few positions.

  **Impact:** Diagnostic squiggles in VS Code may be slightly misaligned on lines containing non-ASCII characters.

  **Workaround:** This is a cosmetic issue only. The line number and file path are always correct, so navigation still works. A fix is planned for a future release.
</Accordion>

## See also

<CardGroup>
  <Card title="Inline suppression" icon="comment-slash" href="/configuration/suppression">
    Suppress individual false positives directly in source code.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Full config file reference for ignorePatterns, ignoreExports, and rules.
  </Card>

  <Card title="Agent integration" icon="robot" href="/integrations/mcp">
    How agents handle false positives via config and suppression.
  </Card>
</CardGroup>


# Production mode
Source: https://docs.fallow.tools/analysis/production-mode

Restrict fallow's dead code analysis to production code by excluding test files, devDependencies, and type-only imports.

Production mode restricts analysis to code that ships to users, ignoring test and development files.

```bash theme={null}
fallow dead-code --production
```

Or set it in your config:

```jsonc theme={null}
// .fallowrc.json
{
  "production": true
}
```

## What changes in production mode

| Behavior                                          | Default     | Production                                                                                                                                                       |
| :------------------------------------------------ | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Test files (`*.test.*`, `*.spec.*`, `__tests__/`) | Included    | Excluded                                                                                                                                                         |
| Story files (`*.stories.*`)                       | Included    | Excluded                                                                                                                                                         |
| Mock files (`__mocks__/`)                         | Included    | Excluded                                                                                                                                                         |
| Package.json scripts analyzed                     | All         | Only `start`, `build`, `serve`, `preview`, `prepare`, `prepublishOnly`, `postinstall`, and `pre`/`post` lifecycle hooks for `start`, `build`, `serve`, `install` |
| Unused devDependencies                            | Reported    | Skipped                                                                                                                                                          |
| Type-only dependencies                            | Not flagged | Flagged (should be devDependencies)                                                                                                                              |

```bash title="$ fallow dead-code --production" theme={null}
● Unused exports (2)
  src/utils/format.ts
    :12 formatCurrency
    :28 formatPercentage
  Exported symbols with zero references: https://docs.fallow.tools/explanations/dead-code#unused-exports

● Unused dependencies (1)
  moment
  Packages in dependencies never imported: https://docs.fallow.tools/explanations/dead-code#unused-dependencies

● Type-only dependencies (1)
  zod  →  move to devDependencies (only imported via 'import type')
  Production dependencies only used as types: https://docs.fallow.tools/explanations/dead-code#type-only-dependencies

✗ 4 issues (19ms, production mode, 623/847 files)
```

## Type-only dependency detection

In production mode, fallow detects dependencies that are only imported via `import type`:

```ts theme={null}
import type { Config } from 'some-package';  // Type-only, erased at runtime
```

These packages belong in `devDependencies` since types are erased at runtime and don't need to be installed in production.

<Tip>
  In monorepos, production mode catches dependencies that should be devDependencies, keeping each package's install footprint minimal.
</Tip>

## Per-analysis production mode

Combined mode (bare `fallow`) and `fallow audit` can enable production mode per analysis instead of globally:

```jsonc theme={null}
// .fallowrc.json
{
  "production": {
    "health": true,
    "deadCode": false,
    "dupes": false
  }
}
```

Use `--production-health`, `--production-dead-code`, or `--production-dupes` for one invocation, or `FALLOW_PRODUCTION_HEALTH=true` and the related env vars in CI. The global `--production` flag still enables production mode for every analysis.

Precedence (highest to lowest): CLI flags, per-analysis env var, global `FALLOW_PRODUCTION`, config. CLI flags only enable; env vars and config can also disable. Worked examples:

```bash theme={null}
# Run health in production mode, dead-code and dupes on the full tree
fallow --production-health

# Same, via env var (useful in CI templates that pass env-only)
FALLOW_PRODUCTION_HEALTH=true fallow

# Per-analysis env wins over the global env, so this runs health in production
# mode even though the global env says off (the typical CI-template case)
FALLOW_PRODUCTION=false FALLOW_PRODUCTION_HEALTH=true fallow

# CLI flags beat env vars; this enables all three regardless of FALLOW_PRODUCTION_* env
fallow --production
```

## See also

<CardGroup>
  <Card title="CI Integration" icon="circle-check" href="/integrations/ci">
    Use production mode in your CI pipeline for lean, fast checks.
  </Card>

  <Card title="Rules & Severity" icon="scale-balanced" href="/configuration/rules">
    Control which issue types are errors, warnings, or disabled.
  </Card>
</CardGroup>


# Runtime coverage
Source: https://docs.fallow.tools/analysis/runtime-coverage

Merge runtime coverage into fallow health to see which functions actually execute in production-like traffic, which stay cold, and which hot paths changed.

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.

```bash theme={null}
fallow license activate --trial --email you@company.com
fallow coverage setup
fallow health --runtime-coverage ./coverage
```

## What it tells you

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 per-finding suppression `id` (`fallow:prod:<hash>`, hashes the current line), an optional cross-surface `stable_id` (`fallow:fn:<hash>`, hashes file + name + start line; one value per function across findings / hot-paths / blast-radius / importance and across V8/Istanbul/oxc producers), an optional content-digest `source_hash` (line-move-immune: a moved-but-unedited function keeps the same value, so baselines stay suppressed across a pure line shift), `line`, per-finding `verdict`, `confidence`, supporting `evidence`, machine-readable `actions`, and an optional `discriminators` block exposing the inputs behind the verdict (`tracking_state` of `called` / `never_called` / `untracked`, `invocation_ratio`, the `low_traffic_threshold` and `min_observation_volume` in effect, and `trace_count` with `meets_observation_volume`) so an agent can reproduce the verdict without re-deriving it. |
| `hot_paths`  | The busiest runtime functions with a stable `id`, an optional `stable_id` join key, `line`, `invocations`, and `percentile` rank.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `actionable` | Whether the report carries enough evidence to act on, with `actionability_reason` and `actionability_verdict`. A capture with no tracked functions reports a first-class `insufficient_evidence` verdict rather than being read as cold. This is a non-action floor: it never gates a positive verdict or a confidence score.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `provenance` | Context block describing the data behind the report (`data_source`, `is_production`, `freshness_days`, `untracked_ratio`, `unresolved_ratio`, `stale`, `stale_after_days`). Context only; it never gates a verdict.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `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:

```json theme={null}
"evidence": {
  "static_status": "used",
  "test_coverage": "not_covered",
  "test_only_reference": false,
  "v8_tracking": "tracked",
  "untracked_reason": null,
  "observation_days": 30,
  "deployments_observed": 14
}
```

`test_only_reference` guards the one case where production mode and static
reachability disagree. Production mode drops test, spec, story, fixture, and
benchmark files from discovery, so an export whose only callers live in those
files reads as statically unused. It is `true` when the function is unreachable
in the production graph but still referenced from an excluded file, which means
it is not dead code: removing it breaks the referencing test. Such a function is
reported as `review_required` rather than `safe_to_delete`, with the action
"Only tests reference this export; delete the test usage together with the
function or keep it". It is `false` when the production graph was compared
against the full tree and no such reference exists, and `null` when the report
was produced without a production filter, so there is no second reachability
answer to report.

## Confidence thresholds

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

## Static coverage vs runtime coverage

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

## Accepted input

`fallow health --runtime-coverage <path>` accepts:

| Input                                  | Example                                                 |
| :------------------------------------- | :------------------------------------------------------ |
| V8 dump directory                      | `./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.

## Production coverage: getting source attribution

Production runtime coverage is collected against your **built bundle** (a Next.js `.next/server/chunks/*.js`, an Electron `out/main/index.js`, a NestJS `dist/`, a minified browser bundle). Those positions cannot map back to your TypeScript or JSX source on their own, so unless you take one of the two steps below the cloud records every function as `unresolved` and `fallow coverage analyze --cloud` surfaces no attributable findings (a `coverage_unresolved` warning explains why).

Pick one:

* **Upload source maps** (for V8 coverage). After the build, upload the `.map` files as a CI step so the cloud can map bundle positions back to source:

  ```bash theme={null}
  fallow coverage upload-source-maps --dir <build-dir>   # e.g. dist, .next, out
  ```

  The maps must be uploaded for the same commit the coverage was collected on. See [`fallow coverage`](/cli/coverage) for the flags, per-commit SHA matching, and CI snippets. When `fallow coverage analyze --cloud` finds built `.map` files locally that have not been uploaded, it prints the exact command to run.

* **Instrument at build time with Istanbul** (no maps needed). `oxc-coverage-instrument` rewrites your source so the original file and line positions are embedded in the coverage itself, so nothing has to be remapped afterward. This is the path the fallow project dogfoods.

## First-run workflow

The intended first-run path is:

1. Start a trial or activate a license with [`fallow license`](/cli/license).
2. Run [`fallow coverage setup`](/cli/coverage).
3. Follow the generated recipe in `docs/collect-coverage.md`.
4. 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`.

## Review changed code

Runtime coverage becomes especially useful during change review:

```bash theme={null}
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:

```bash theme={null}
git diff --unified=0 main...HEAD > /tmp/pr.diff
fallow health --runtime-coverage ./coverage --diff-file /tmp/pr.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).

## Trial and watermark behavior

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.

## See also

<CardGroup>
  <Card title="fallow health" icon="terminal" href="/cli/health">
    Runtime coverage merges into the standard health report and output formats.
  </Card>

  <Card title="License commands" icon="key" href="/cli/license">
    Start a trial, inspect license status, refresh, or deactivate a local token.
  </Card>
</CardGroup>


# Semantic similar code
Source: https://docs.fallow.tools/analysis/similar-code

Find JavaScript and TypeScript functions that may share intent even when their names and syntax differ, using a pinned local model and explicit review.

`fallow similar-code` finds functions that may do the same kind of work even
when they are written differently.

Use it after `fallow dupes` when copied structure is not the whole story. The
normal duplication detector finds exact, normalized, and near-miss copies.
Similar-code discovery compares the meaning represented by complete functions.

<Warning>
  Every result is an unverified candidate. A similarity score is not a
  probability, proof that behavior matches, or permission to refactor. Inspect
  both functions and their tests before making a decision.
</Warning>

## Set up the local model

The matching native companion installs with the main `fallow` npm package.
Check whether its pinned model is ready:

```bash theme={null}
fallow similar-code status
```

The first download needs your explicit confirmation:

```bash theme={null}
fallow similar-code setup --local
```

Setup shows the model, license, and download size before it asks. Use `--yes`
only when you already approved the download and need a non-interactive command.
Project config and agents cannot approve setup for you.

After setup, analysis is offline. Function source stays on your machine. The
companion receives bounded source over local process input and does not save it.
Fallow persists derived vectors in the project cache so later runs are faster.

## Find candidates

```bash theme={null}
fallow similar-code
```

Machine-readable output uses an independent envelope:

```bash theme={null}
fallow similar-code --format json --quiet > similar-code.json
```

A candidate looks like this:

```json theme={null}
{
  "candidate_id": "sc_...",
  "review_key": "scr_...",
  "left": {
    "path": "src/orders/normalize.ts",
    "name": "normalizeOrder",
    "start_line": 12,
    "end_line": 34,
    "source_sha256": "..."
  },
  "right": {
    "path": "src/imports/clean.ts",
    "name": "cleanImportedOrder",
    "start_line": 8,
    "end_line": 31,
    "source_sha256": "..."
  },
  "similarity": 0.91,
  "similarity_band": "high",
  "verification_status": "unverified"
}
```

The score is meaningful only for the pinned model and current settings. Use it
to rank review work, not to compare projects or set a universal quality bar.

The root output also records:

* the exact companion, model revision, artifact digest, and parameters
* whether every analysis phase completed
* limits and skipped work
* vector-cache hits and misses
* non-severity diagnostics

An empty candidate list is conclusive only when `completion.status` is
`"complete"`. A `"partial"` run tells you which limit or provider problem made
the result incomplete.

### Focus the search

```bash theme={null}
fallow similar-code --file src/orders/normalize.ts
fallow similar-code --changed-since main
fallow similar-code --workspace @acme/orders
fallow similar-code --threshold 0.88 --min-lines 6 --top 20
```

`--file` keeps pairs that touch the selected file. `--changed-since` and
workspace options use the same project scoping as other fallow analyses.

## Inspect before judging

Copy `candidate_id` from the discovery output:

```bash theme={null}
fallow similar-code --threshold 0.88 --min-lines 6 \
  inspect similar-code:candidate:v1:... --format json --quiet
```

Run this from the same project root and reuse the discovery scope plus the
effective `generation.threshold` and `generation.min_lines` values. Human
output includes the calibrated part of the inspect command. MCP callers pass
the same discovery options to `inspect_similar_code`.

Inspect first reproduces the candidate against your current source. This
prevents a stale result from being reviewed after either function changed. It
then adds bounded evidence where available:

* source windows for both functions
* import-graph relationship and entry-point reachability
* callers and callees
* CODEOWNERS ownership and recent churn
* related tests
* overlap with deterministic duplication results
* syntax clues such as async behavior, throws, awaits, and possible side effects

Every evidence source has an availability state. Missing context stays missing.
Fallow does not turn absence of evidence into a positive verdict.

## Record a separate verdict

The raw candidate document never changes. A person or agent writes a separate
verdict after inspecting the code:

```json theme={null}
{
  "schema_version": "1",
  "verdicts": [
    {
      "candidate_id": "sc_...",
      "review_key": "scr_...",
      "candidate_worthy": true,
      "behaviorally_equivalent": false,
      "refactor_safe": false,
      "outcome": "related-but-distinct",
      "rationale": "Both normalize orders, but only the import path preserves external IDs."
    }
  ]
}
```

Join the documents:

```bash theme={null}
fallow similar-code review \
  --candidates similar-code.json \
  --verdicts verdicts.json \
  --require-verdict-for-each-candidate \
  --format json --quiet
```

The three yes, no, or unknown judgments answer different questions:

| Field                     | Question                                                                |
| :------------------------ | :---------------------------------------------------------------------- |
| `candidate_worthy`        | Is this pair useful enough to review?                                   |
| `behaviorally_equivalent` | Do both functions behave the same for relevant inputs and side effects? |
| `refactor_safe`           | Is consolidation safe in the current architecture?                      |

Use `null` when you cannot answer. `refactor_safe: true` requires
`behaviorally_equivalent: true`, which requires `candidate_worthy: true`.
Available outcomes are `same-responsibility`, `related-but-distinct`,
`intentional-duplication`, `unrelated`, and `needs-human-review`.

## Use it with an agent

The MCP server exposes two read-only tools:

* `find_similar_code` returns unverified candidates with provenance and
  completion accounting.
* `inspect_similar_code` reproduces one candidate and returns its evidence
  packet.

Neither tool downloads a model, edits source, or produces a verdict. If setup
is missing, the agent should ask you to run `fallow similar-code setup --local`.
An agent should return `needs-human-review` when tests, callers, behavior, or
side effects are unclear.

## Configure project defaults

```jsonc theme={null}
{
  "similarCode": {
    "threshold": 0.8,
    "minLines": 3,
    "ignore": ["src/generated/**"]
  }
}
```

These fields tune candidate discovery only. Config cannot choose a model,
provider, executable, download, or credential.

Clear derived project vectors without deleting the downloaded model:

```bash theme={null}
fallow similar-code cache clear
```

## Where it does not run

Similar-code discovery is separate from bare `fallow`, `audit`, `dupes`, CI
gates, SARIF, LSP, VS Code diagnostics, and auto-fix. It is a review aid, not a
new finding category. It accepts only the official pinned local model and does
not send source to a remote provider.

## See also

<CardGroup>
  <Card title="Code duplication" icon="clone" href="/analysis/duplication">
    Find deterministic and near-miss copied structure.
  </Card>

  <Card title="Agent integration" icon="robot" href="/integrations/mcp">
    Connect the read-only discovery and inspect tools.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Set project-owned thresholds, size floors, and ignore globs.
  </Card>
</CardGroup>


# Type-aware TypeScript analysis
Source: https://docs.fallow.tools/analysis/type-aware

Add exact TypeScript checker evidence to fallow for symbol usage, API leaks, affected tests, and public-signature coupling.

Fallow's default analysis is Rust-native, syntactic, and independent of Node.js
or the TypeScript compiler. Add `--type-aware` when a cleanup or refactor
depends on exact TypeScript symbol identity across aliases, re-exports,
packages, or tests.

The optional companion adds five project-wide capabilities:

* exact symbol-use confirmation for existing dead-code candidates
* symbol traces with namespaces, aliases, and re-export hops
* package API surfaces and cross-file private type leaks
* exact consumers, affected files, and targeted tests
* advisory public-signature type coupling

Use this pass when an actual cleanup or refactor decision depends on TypeScript
identity. Keep the normal syntactic run for fast everyday feedback.

```bash theme={null}
fallow type-aware status --format json --quiet
fallow dead-code --unused-class-members --type-aware --format json --quiet
fallow fix --type-aware --dry-run --format json --quiet
fallow dead-code --type-aware --symbol-impact src/api.ts:Client --format json --quiet
fallow health --type-aware --type-coupling --format json --quiet
```

## What this does not replace

Keep `tsc --noEmit` responsible for compiler correctness. Keep Oxlint
responsible for local lint rules. Fallow does not emit TypeScript diagnostics
or duplicate local typed lint findings.

Type-aware fallow answers project-wide questions those tools do not:

* Is this exact declaration used through an alias or re-export?
* Which production files and tests depend on this exported symbol?
* Does a public signature expose a package-private type?
* Which public types couple packages or modules together?

## Conservative results

Every semantic result reports `complete`, `partial`, or `unavailable`.
Fallow removes a dead-code candidate only when the checker resolves its exact
declaration identity. Partial or unavailable analysis keeps the original
finding and reports a stable omission reason.

`fallow fix --type-aware` offers a class-member removal only after every owning
project returns complete negative evidence and the declaration guard still
matches. Always preview with `--dry-run`.

<Warning>
  Checker-visible evidence is not proof that a published API has no external
  consumers. Keep package exports, `publicPackages`, visibility tags, and
  explicitly selected consumer projects authoritative for library boundaries.
</Warning>

Use `--type-aware-require complete` in CI when incomplete semantic evidence
must fail the job:

```bash theme={null}
fallow dead-code --type-aware --type-aware-require complete \
  --format json --quiet
```

Use repeatable `--type-aware-project` flags when automatic project selection
does not include every consumer:

```bash theme={null}
fallow dead-code --type-aware \
  --type-aware-project tsconfig.json \
  --type-aware-project packages/web/tsconfig.json \
  --format json --quiet
```

## Svelte virtual-module exports

Svelte language tooling creates virtual TypeScript modules for `.svelte`
files. TypeScript-Go does not yet expose the plugin integration needed for
fallow to construct the same virtual modules. Default component imports and
named exports backed by checker-visible declarations remain supported.

When a selected project uses a named import, named re-export, or wildcard
re-export whose `.svelte` target cannot be resolved, fallow abstains with
`svelte-virtual-module-exports`. The project and affected semantic queries are
reported as `unavailable`. Best-effort mode keeps the syntactic result as
advisory evidence, while `--type-aware-require complete` fails the run.

Run `svelte-check` for authoritative Svelte and TypeScript diagnostics. Do not
rewrite valid component exports just to satisfy fallow. Keep the Svelte project
configuration intact and use the omission reason until TypeScript-Go provides
a supported virtual-module host integration.

## Persistent configuration

Keep the feature opt-in per repository:

```jsonc theme={null}
{
  "typeAware": {
    "enabled": true,
    "projects": ["tsconfig.json"],
    "require": "best-effort"
  }
}
```

Start with `best-effort`. Use `complete` only when partial or unavailable
semantic evidence must fail the run.

## Performance

Type-aware analysis constructs an additional TypeScript Program and scans
checker symbols. On the current public release corpus, marginal overhead is
about 92 ms at the median and 2.3 seconds at P95. Large projects can take
longer. Editor sessions reuse the loaded Program, while one-shot CLI and CI
runs pay the cold setup cost.

## Installation

The `fallow` npm package installs a version-matched optional
`fallow-type-aware` companion. If optional dependencies are disabled, install
the exact same version manually. `fallow type-aware status` verifies discovery,
package version, protocol version, and backend version without analyzing the
project.

## See also

<CardGroup>
  <Card title="Dead code CLI" icon="terminal" href="/cli/dead-code">
    Refine cleanup findings and run exact symbol queries.
  </Card>

  <Card title="Health CLI" icon="heart-pulse" href="/cli/health">
    Inspect advisory public-signature type coupling.
  </Card>

  <Card title="Known limitations" icon="triangle-exclamation" href="/analysis/limitations">
    Understand the boundary between default syntactic and optional semantic analysis.
  </Card>
</CardGroup>


# fallow agent
Source: https://docs.fallow.tools/cli/agent

CLI reference for fallow agent. Wire fallow into Claude Code, Codex, and Cursor in one pass: AGENTS.md task map, skill, MCP server registration, and the commit/push gate, with status and uninstall.

Wire fallow into the coding-agent harnesses a project uses, in one command. `fallow agent install` detects Claude Code, Codex, and Cursor, then writes what each one reads: an `AGENTS.md` task map, the fallow skill, the MCP server registration, and the commit/push gate. `fallow agent status` shows what is installed, and `fallow agent uninstall` removes exactly what fallow wrote.

```bash theme={null}
fallow agent install --dry-run   # show the plan first
fallow agent install             # wire every detected harness
```

<Info>
  `fallow init --agents`, `fallow hooks install --target agent`, and the hand-written MCP snippet keep working. `agent install` composes them; it does not replace them.
</Info>

## Detection

Without `--harness`, a harness is selected when any of its signals is present. Nothing is fabricated when no signal exists: a Cursor-only repository never gets a `.claude/` directory.

| Harness     | Project                              | Home         | Session           |
| :---------- | :----------------------------------- | :----------- | :---------------- |
| Claude Code | `.claude/`, `CLAUDE.md`, `.mcp.json` | `~/.claude/` | `CLAUDECODE`      |
| Codex       | `.codex/`                            | `~/.codex/`  | `CODEX_THREAD_ID` |
| Cursor      | `.cursor/`                           | `~/.cursor/` | `CURSOR_AGENT`    |

When nothing is detected, only the harness-neutral files are written (`AGENTS.md` and `.agents/skills/fallow`) and the output names the `--harness` values you can pass. `AGENTS.md` itself is not a detection signal, because every harness and fallow write it.

## What each step writes

| Step    | Claude Code                                                                                                                | Codex                                          | Cursor                                    |
| :------ | :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------- | :---------------------------------------- |
| `guide` | `AGENTS.md` task map; `CLAUDE.md` gains an `@AGENTS.md` import (created when absent, appended as a marked block otherwise) | `AGENTS.md` task map                           | `AGENTS.md` task map (Cursor reads it)    |
| `skill` | `.claude/skills/fallow/`                                                                                                   | `.agents/skills/fallow/`                       | `.agents/skills/fallow/`                  |
| `mcp`   | `mcpServers.fallow` in `.mcp.json`                                                                                         | `[mcp_servers.fallow]` in `.codex/config.toml` | `mcpServers.fallow` in `.cursor/mcp.json` |
| `hooks` | PreToolUse gate in `.claude/settings.json` plus `.claude/hooks/fallow-gate.sh`                                             | marked gate block in `AGENTS.md`               | skipped (`unsupported_harness`)           |

**Skill.** When the project has `node_modules/fallow/skills/fallow`, the installed skill is a small pointer to that copy, so it never drifts from the fallow version the project pins. Without it, the version-matched skill embedded in the binary is written. A skill named `fallow` that fallow did not write is refused (`skill_name_taken`) unless you pass `--force`.

**MCP.** The command is probed before anything is written: `npx --no fallow-mcp` for an npm-installed project, `fallow-mcp` from `PATH`, or the running binary when it is the npm multicall build. When none exists the step is skipped with `mcp_entry_unavailable` instead of writing a registration that cannot start. A project-level `.codex/config.toml` only applies once Codex trusts the project, so the output leads with the `codex mcp add fallow -- ...` command that works immediately.

**Approval.** Claude Code asks before starting a project-scoped MCP server. `--approve` records that approval for you by listing `fallow` in `.claude/settings.local.json`; it is opt-in and refused when that file is tracked by git.

## Markers, idempotency, and uninstall

Every file or block carries a `<!-- fallow:agent-install v1 ... -->` marker. Re-running is byte-stable and reports every step as `unchanged`. Files fallow did not write are never overwritten without `--force`; a `fallow` MCP entry counts as fallow's only when its command is one fallow writes, so a hand-written entry is refused (`mcp_entry_foreign`) and kept. `--force` on an unparsable config file saves the old bytes as `<file>.fallow-bak` first. `uninstall` removes managed blocks and entries, deletes a config file it emptied, and deletes `AGENTS.md` or `CLAUDE.md` only while the file still matches what fallow authored.

## Options

| Flag                                      | Applies to             | Description                                                                                                                                                                                |
| :---------------------------------------- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--harness <auto\|claude\|codex\|cursor>` | `install`, `uninstall` | Repeatable; default `auto`                                                                                                                                                                 |
| `--without <guide\|skill\|mcp\|hooks>`    | `install`              | Skip a step; repeatable                                                                                                                                                                    |
| `--dry-run`                               | `install`, `uninstall` | Print the plan without touching the filesystem                                                                                                                                             |
| `--force`                                 | `install`, `uninstall` | Replace or remove skills, hook scripts, or config files fallow did not write                                                                                                               |
| `--approve`                               | `install`              | Pre-approve the project MCP server for yourself in `.claude/settings.local.json`                                                                                                           |
| `--user`                                  | `install`, `uninstall` | Skill and MCP config under `$HOME` instead of the project; the guide step is skipped, and Claude Code prints the `claude mcp add --scope user` command instead of editing `~/.claude.json` |
| `--gitignore-claude`                      | `install`              | Append `.claude/` to `.gitignore`                                                                                                                                                          |

The root is the git toplevel of the current directory unless `--root` is passed explicitly, so a run from a monorepo package still writes where the harnesses read. The chosen root is the first line of output.

## Output

Human output groups paths under "Shared with your team (commit these)" and "Local to you". With `--format json` the envelope carries `kind` (`agent-install`, `agent-uninstall`, `agent-status`), `schema_version`, and `fallow_version`, and every step carries `harness`, `step`, `status` (`written`, `removed`, `unchanged`, `skipped`, `refused`, `failed`), `scope`, `path`, and a `reason` when it was skipped or refused, followed by `next_actions` (each flagged `mutating` when running it would write harness config, unlike the read-only `next_steps` of the analysis commands). The exit code is 2 when any step is `refused` or `failed`; every other step still runs.

`agent status` reports a different shape: `surfaces[]`, each with `harness`, `step`, `path`, and a `state` of `absent`, `installed`, or `stale`. `stale` means fallow wrote the surface but an older version did, or the surface is installed and would not do its job. A `hooks` gate written by an older fallow is `stale`, and so is an installed gate whose run-time prerequisites are missing, with the reason in `detail` and a matching entry in `next_actions[]`. Two gate conditions report that way: `gate-requires-jq`, because the gate script exits 0 after one stderr line when `jq` is absent and a PreToolUse hook never surfaces that, and `gate-path-version`, because the gate runs whatever `fallow` PATH resolves rather than the build that installed it. Branch on `state`, not on presence of the path.

```bash theme={null}
fallow agent install --format json --quiet
fallow agent status --format json
fallow agent uninstall --dry-run
```


# fallow audit
Source: https://docs.fallow.tools/cli/audit

CLI reference for fallow audit. Combined dead code, complexity, duplication, and styling analysis scoped to changed files, with a pass/warn/fail verdict for PR quality gates and AI-generated code review.

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.

<Note>
  `fallow audit` is the PR-time gate. For the initial full-repo cleanup on an existing codebase, start with [Adopt Fallow in an existing repo](/adoption), which walks through `fallow`, `fallow dead-code`, `fallow dupes`, and `fallow health`, and hands the actual cleanup to an AI agent before turning `audit` on in CI.
</Note>

```bash theme={null}
fallow audit
```

## Options

### Base ref

| Flag           | Description                                                                                                                                                                                                                                                                                                           |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--base <REF>` | Git ref to compare against (e.g., `main`, `HEAD~5`, a commit SHA). Alias for `--changed-since`. When omitted, the base is the `git merge-base` against the branch's upstream or the remote default (`origin/main`); set [`FALLOW_AUDIT_BASE`](/configuration/environment#fallow_audit_base) to pin it without a flag. |

### Diff scoping

| Flag                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--diff-file <PATH>` | Path to a pre-computed unified diff (e.g. `git diff --unified=0 main...HEAD > /tmp/pr.diff`) that narrows source-anchored findings to lines inside an added hunk. Pass `-` for stdin (`gh pr diff \| fallow audit --diff-file -`) or use the `--diff-stdin` alias. The bundled GitHub Action and GitLab CI template pre-compute the diff and pass it automatically; you only need this flag for non-PR pipelines or local invocations. The filtering rules and the `FALLOW_DIFF_FILE` fallback are documented under [global flags](/cli/global-flags#reference). |

### Gate

| Flag              | Description                                                                                                                                                                                        |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--gate new-only` | Default. Compare against the base ref and fail only on findings introduced by the current changeset. Inherited findings are reported in JSON `attribution` and annotated with `introduced: false`. |
| `--gate all`      | Strict mode. Fail on every finding in changed files, including findings inherited from the base ref. Skips the extra base-snapshot attribution pass for lower latency.                             |

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.

<CodeGroup>
  ```bash CLI theme={null}
  fallow audit --gate all
  ```

  ```toml fallow.toml theme={null}
  [audit]
  gate = "all"
  ```

  ```jsonc MCP theme={null}
  // fallow_audit tool params
  {
    "gate": "all"
  }
  ```
</CodeGroup>

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

```text theme={null}
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](#key-fields).

The decision uses the same diff precedence as [diff scoping](#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

| 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`                                                             |
| `-q, --quiet`           | Suppress progress and status output on stderr                                                                                                                                                                                                         |
| `--explain`             | Add metric explanations in JSON output (`_meta` objects with docs links). In human output, also lists each clone group the new-only gate demoted, with the deciding diff source. See [New-only duplication demotion](#new-only-duplication-demotion). |

### Review brief

| Flag                        | Description                                                                                                                                                                                                                                                                                                            |
| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--brief`                   | Render the deterministic review brief instead of the gating audit report. Answers "where do I look?" rather than "will CI block this?", runs the same analysis, and always exits 0. Orthogonal to `--format`. Implied by `fallow review`. See [Review brief and decision surface](#review-brief-and-decision-surface). |
| `--max-decisions <N>`       | Cap on the number of consequential structural decisions surfaced in the brief's decision surface (the working-memory limit). Default 4; clamped to a 3 to 5 band. Only consulted on the brief path.                                                                                                                    |
| `--walkthrough-guide`       | Emit the agent-contract walkthrough guide: the current digest (brief + decision surface), the review direction, the JSON schema the agent must return, and a deterministic graph-snapshot hash pinned into the digest. Implies the brief; always exits 0. See [Agent walkthrough loop](#agent-walkthrough-loop).       |
| `--walkthrough-file <PATH>` | Ingest an agent's judgment JSON and post-validate it against the live graph; see [Agent walkthrough loop](#agent-walkthrough-loop) for the accepted and rejected outcomes. Implies the brief; always exits 0.                                                                                                          |
| `--walkthrough`             | Render the walkthrough guide as a staged human terminal tour (Stage 1 load-bearing, Stage 2 mechanical), or a paste-into-PR artifact with `--format markdown`. `--format json --walkthrough` emits the same agent-contract JSON as `--walkthrough-guide`. Implies the brief; always exits 0.                           |
| `--mark-viewed <FILE>`      | Record one or more changed files as viewed in the local walkthrough viewed-state ledger, then render the tour. Files already viewed (and still current) collapse into the Cleared panel. Repeatable. Stale marks (the tree moved) are ignored on render but never deleted. Only consulted on the `--walkthrough` path. |
| `--show-cleared`            | Expand the Cleared panel in the human/markdown walkthrough tour: list each de-prioritized and already-viewed file instead of the collapsed one-line summary. Only consulted on the `--walkthrough` path.                                                                                                               |
| `--show-deprioritized`      | Expand the de-prioritized units in the brief's weighted focus map ("show me what you de-prioritized"). The `deprioritized` escape-hatch list is always present in `--format json` regardless; this flag only re-expands the collapse-by-default human focus render. Only consulted on the brief path.                  |

### Scoping

| Flag                     | Description                                                                                                                                                                                                                                                         |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-w, --workspace <NAME>` | Scope to a single workspace package                                                                                                                                                                                                                                 |
| `--production`           | Exclude test/story/dev files (applies to dead-code, health, and dupes)                                                                                                                                                                                              |
| `--production-dead-code` | Production mode for dead-code only. See [global flags](/cli/global-flags#per-analysis-production-mode).                                                                                                                                                             |
| `--production-health`    | Production mode for health only.                                                                                                                                                                                                                                    |
| `--production-dupes`     | Production mode for duplication only.                                                                                                                                                                                                                               |
| `--no-css`               | Disable audit styling analytics entirely.                                                                                                                                                                                                                           |
| `--css-deep`             | Force deep styling analytics on when config disables it. Deep CSS is on by default in audit: project-wide styling reachability is narrowed back to changed anchors, and JSON can include `complexity.css_analytics` plus first-class `complexity.styling_findings`. |
| `--no-css-deep`          | Keep local styling analytics on, but skip project-wide styling reachability.                                                                                                                                                                                        |

### Thresholds

| Flag                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--max-crap <N>`         | Maximum CRAP score before the audit fails (default: 30.0, configurable via `health.maxCrap`). Functions meeting or exceeding this score contribute to the fail verdict alongside dead-code and complexity findings. Pair with `--coverage` for accurate per-function CRAP; without Istanbul data fallow estimates coverage from the module graph.                                                                                                                                                                                                                                                                                |
| `--coverage <PATH>`      | Path to Istanbul-format coverage data (`coverage-final.json`) for accurate per-function CRAP scores in the health sub-analysis. Also configurable via `FALLOW_COVERAGE`, then `health.coverage` (the same chain as `fallow health`). Same format and semantics as [`fallow health --coverage`](/cli/health#coverage); without any of them, fallow auto-detects `coverage/coverage-final.json` or falls back to the static-estimate model. The resolved map feeds both the head pass and the base attribution pass. A configured file that does not exist exits 2, like `fallow health`. Relative paths resolve against `--root`. |
| `--coverage-root <PATH>` | Absolute prefix to strip from file paths in coverage data before prepending the project root. Also configurable via `FALLOW_COVERAGE_ROOT`, then `health.coverageRoot`; a relative `health.coverageRoot` is rejected with exit 2, like `fallow health`. Use when coverage was generated under a different checkout root in CI or Docker (e.g., `/home/runner/work/myapp` on GitHub Actions).                                                                                                                                                                                                                                     |

### Baselines

| Flag                          | Description                                                                                                                           |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `--dead-code-baseline <PATH>` | Baseline file produced by `fallow dead-code --save-baseline`. Dead-code issues present in the baseline are excluded from the verdict. |
| `--health-baseline <PATH>`    | Baseline file produced by `fallow health --save-baseline`. Complexity findings present in the baseline are excluded from the verdict. |
| `--dupes-baseline <PATH>`     | Baseline file produced by `fallow dupes --save-baseline`. Clone groups present in the baseline are excluded from the verdict.         |

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

```jsonc theme={null}
{
  "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

| Verdict   | Exit code | When                                                                           | What to do                                                                                          |
| :-------- | :-------- | :----------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| **pass**  | 0         | No introduced issues in changed files (`new-only`) or no issues at all (`all`) | Ship it.                                                                                            |
| **warn**  | 0         | Issues found, all warn-severity                                                | CI passes, but consider fixing before they become errors.                                           |
| **fail**  | 1         | Error-severity issues found                                                    | Fix the reported issues before merging.                                                             |
| **error** | 2         | Runtime error (invalid ref, not a git repo, config error)                      | Check the error message. In JSON format, emits `{"error": true, "message": "...", "exit_code": 2}`. |

Dead code issues follow your [rules configuration](/configuration/rules) 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.

<Info>
  Inline suppression comments (`// fallow-ignore-next-line`) work in audit. Findings in changed files are suppressed the same way as in `fallow dead-code`.
</Info>

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

| Field                                                                                                                                           | What it counts                                                                              | Severity-aware?                            |
| :---------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | :----------------------------------------- |
| `verdict`                                                                                                                                       | Overall outcome (`pass` / `warn` / `fail`) honoring per-rule severity from `.fallowrc.json` | **Yes**                                    |
| `attribution.dead_code_introduced`, `attribution.complexity_introduced`, `attribution.duplication_introduced`, `attribution.styling_introduced` | Findings introduced by the changeset under `gate: new-only`, regardless of severity         | No                                         |
| `summary.dead_code_issues`, `summary.complexity_findings`, `summary.duplication_clone_groups`                                                   | All findings in changed files (any gate), regardless of severity                            | No                                         |
| Per-finding `introduced: true \| false`                                                                                                         | Whether each individual finding was introduced by the changeset                             | No (severity is per-rule, not per-finding) |

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

<CodeGroup>
  ```bash Basic usage theme={null}
  # 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
  ```

  ```bash CI integration theme={null}
  # JSON for pipelines (verdict field at top level)
  fallow audit --format json --quiet

  # Environment variables work too (useful when flags can't be passed)
  FALLOW_FORMAT=json FALLOW_QUIET=1 fallow audit

  # Pin the comparison base without a flag (handy for forks and the agent gate)
  FALLOW_AUDIT_BASE=upstream/main fallow audit

  # Fail CI if audit fails
  fallow audit --base main || exit 1

  # SARIF for GitHub Code Scanning
  fallow audit --format sarif > audit.sarif

  # CodeClimate for GitLab CI
  fallow audit --format codeclimate > gl-code-quality-report.json
  ```

  ```bash Scoping theme={null}
  # Only production code
  fallow audit --production

  # Production health only (dead-code and dupes still cover the full tree)
  fallow audit --production-health

  # Single workspace package
  fallow audit --workspace @app/core

  # Explicit base with workspace
  fallow audit --base develop --workspace @app/api
  ```

  ```bash Baselines theme={null}
  # Save baselines once on the default branch
  fallow dead-code --save-baseline fallow-baselines/dead-code.json
  fallow health    --save-baseline fallow-baselines/health.json
  fallow dupes     --save-baseline fallow-baselines/dupes.json

  # Audit only new issues (pre-existing issues on touched files are ignored)
  fallow audit \
    --dead-code-baseline fallow-baselines/dead-code.json \
    --health-baseline    fallow-baselines/health.json \
    --dupes-baseline     fallow-baselines/dupes.json

  # Or set baselines in config and run audit with no flags
  fallow audit
  ```
</CodeGroup>

## Example output

```bash title="$ fallow audit (pass)" theme={null}
Audit scope: 8 changed files vs main (d4a2f91..HEAD)
✓ No issues in 8 changed files (1.18s)
```

```bash title="$ fallow audit (warn)" theme={null}
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`.

```bash title="$ fallow audit (fail)" theme={null}
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](/cli/dead-code), [complexity](/cli/health), [duplication](/cli/dupes).
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

```json title="$ fallow audit --format json" theme={null}
{
  "kind": "audit",
  "schema_version": 11,
  "version": "3.24.1",
  "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

| Field                                        | Type                             | Description                                                                                                                                                                                                                                                                 |
| :------------------------------------------- | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verdict`                                    | `"pass"` \| `"warn"` \| `"fail"` | The audit result. Use this for CI gates.                                                                                                                                                                                                                                    |
| `changed_files_count`                        | integer                          | Number of files changed between base and HEAD                                                                                                                                                                                                                               |
| `base_ref`                                   | string                           | The git ref used for comparison                                                                                                                                                                                                                                             |
| `summary.dead_code_issues`                   | integer                          | Total dead code issues in changed files                                                                                                                                                                                                                                     |
| `summary.dead_code_has_errors`               | boolean                          | Whether any dead code issues have error severity                                                                                                                                                                                                                            |
| `summary.complexity_findings`                | integer                          | Functions exceeding complexity thresholds                                                                                                                                                                                                                                   |
| `summary.max_cyclomatic`                     | integer \| null                  | Highest cyclomatic complexity found (null if none)                                                                                                                                                                                                                          |
| `summary.duplication_clone_groups`           | integer                          | Clone groups involving changed files                                                                                                                                                                                                                                        |
| `attribution.*_introduced`                   | integer                          | Findings whose structural key did not exist at the base ref. With `gate=all`, these stay `0` because audit skips the base-snapshot attribution pass.                                                                                                                        |
| `attribution.*_inherited`                    | integer                          | Findings already present at the base ref. Also `0` under `gate=all`.                                                                                                                                                                                                        |
| `attribution.duplication_demoted`            | integer                          | Clone groups the `new-only` gate demoted from introduced to inherited because no instance overlaps an added line. Always present in audit-family JSON (audit, review brief, MCP `audit`). Demoted groups stay counted in `duplication_inherited`, so this never exceeds it. |
| `dead_code.*[].introduced`                   | boolean                          | Present in audit JSON sub-results when base attribution is available. `true` means the finding is new relative to the base ref.                                                                                                                                             |
| `duplication.clone_groups[].demotion_reason` | string                           | Present only on demoted groups. Kebab-case reason for the demotion, currently `no-added-lines`; further values may be added, so treat an unknown value as "some demotion reason". Never emitted by `fallow dupes --format json`.                                            |
| `complexity.styling_findings[]`              | array                            | Present when CSS analysis is active. Contains first-class styling issues with rule severity and actions. Each item carries optional `introduced` attribution when the base comparison is available.                                                                         |
| `complexity.css_analytics`                   | object                           | Descriptive CSS analytics emitted with CSS analysis: specificity, token usage, duplicate declaration context, and cleanup candidates. Use it as evidence around `styling_findings`, not as a gate by itself.                                                                |

The `dead_code`, `complexity`, and `duplication` sub-objects contain full results in the same format as [`fallow dead-code`](/cli/dead-code#json-output), [`fallow health`](/cli/health#json-output), and [`fallow dupes`](/cli/dupes#json-output) 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`:

```json title="Example request" theme={null}
{
  "tool": "audit",
  "arguments": {
    "base": "main",
    "gate": "new-only",
    "css_deep": true
  }
}
```

When `base` is omitted it resolves as described under [How it works](#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](/integrations/mcp) 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`](/configuration/environment#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>`:

```bash theme={null}
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.

```bash theme={null}
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
```

| Flag                 | Description                                                                                                                                                                                                                                                                                                                                                                                |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dry-run`          | Preview decisions without touching the filesystem: nothing is removed and no lock or age-tracking sidecars are created.                                                                                                                                                                                                                                                                    |
| `--max-age-days <N>` | Age threshold in days for this invocation. Precedence: this flag, then [`FALLOW_AUDIT_CACHE_MAX_AGE_DAYS`](/configuration/environment#fallow_audit_cache_max_age_days), then `audit.cacheMaxAgeDays`, then the 30-day default; the JSON output reports which source won. `0` disables age-based reclaim but still reclaims orphaned entries and entries whose recorded owner root is gone. |

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

```json title="$ fallow audit-cache prune --format json" theme={null}
{
  "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
}
```

| Field                                           | Type            | Description                                                                                                                                                                                                                                                                                                                |
| :---------------------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dry_run`                                       | boolean         | `true` when the run only previewed decisions.                                                                                                                                                                                                                                                                              |
| `max_age_days`, `max_age_source`                | integer, string | The resolved age threshold and which precedence level supplied it (`flag`, `env`, `config`, or `default`)                                                                                                                                                                                                                  |
| `entries[]`                                     | array           | One item per considered cache entry: `path`, `pass` (`owned`, `legacy`, or `foreign`), `disposition` (`removed`, `kept`, `skipped`, or `failed`), a short kebab-case `reason` (e.g. `aged-out`, `fresh`, `owner-live`), `age_days`, `size_bytes`, and `owner_root` (each of the last three is `null` when not measurable). |
| `found`, `removed`, `kept`, `skipped`, `failed` | integer         | Aggregate counts; `removed + kept + skipped + failed` always equals `found`                                                                                                                                                                                                                                                |
| `complete`                                      | boolean         | `true` when nothing was skipped or failed. The field to gate on in scripts; the exit code stays 0 either way.                                                                                                                                                                                                              |
| `reclaimed_bytes`                               | integer         | Bytes removed from disk by this run. On a dry run, the bytes the run would have removed.                                                                                                                                                                                                                                   |

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:

| Job           | What it does                                                                                                                                                                                                     |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **subtract**  | Dead code, complexity, and duplication for the changed files are reported but kept **out** of the judgment loop, so the reviewer is not asked to weigh in on mechanical findings.                                |
| **focus**     | Changed-file units are ranked by a composite attention score, labeled `review-here` or `not-prioritized`, plus a full `deprioritized` list (re-expand the human render with [`--show-deprioritized`](#options)). |
| **structure** | The decision surface: the few consequential structural decisions the change embeds.                                                                                                                              |
| **direct**    | The walkthrough guide for an agent (see [Agent walkthrough loop](#agent-walkthrough-loop)).                                                                                                                      |

### Decision surface

The decision surface is the ranked, capped ([`--max-decisions`](#options)) 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`](/cli/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.

`impact_closure` reports the blast radius as a magnitude, a sample, and a distribution rather than one long list. `affected_count` is the exact number of files the change reaches outside the diff, computed before any capping. `affected_not_shown` is a path-sorted sample of at most ten of them: a prefix of the sorted set, so it clusters in whichever directory sorts first and is meant for jumping into representative files, never for enumerating the reach or inferring its shape. `affected_by_dir` is the shape: `{ dir, count }` rows, heaviest directory first with the directory path breaking ties, at most twenty-five rows, with `affected_by_dir_omitted` counting the lighter directories that did not fit. Every row's count is exact. `coordination_gap` is separate and uncapped, and it is not a subset of the sample: it deliberately skips story and test consumers the affected set counts.

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

```bash theme={null}
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.

```json theme={null}
{
  "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.**

```bash theme={null}
fallow review --base main --walkthrough-file judgment.json --format json
```

Each judgment is sorted into one of these outcomes:

| Outcome                            | Condition                                                                                                                                                                           | Shape                                                                                                           |
| :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| `accepted` (signal)                | The `signal_id` is anchored and the snapshot still matches.                                                                                                                         | Framing fenced `deterministic: false`; `anchor_kind: "signal"` (the strong anchor, a graph finding).            |
| `accepted` (change)                | No `signal_id`, but the `change_anchor` is one fallow emitted and the snapshot still matches.                                                                                       | Framing fenced `deterministic: false`; `anchor_kind: "change"` (the weaker anchor, a changed region only).      |
| `rejected` (unanchored)            | The `signal_id` is not one fallow emitted (a hallucinated id).                                                                                                                      | `reason: "unanchored-signal-id"`.                                                                               |
| `rejected` (unknown change anchor) | The `change_anchor` is not one fallow emitted (a hallucinated region).                                                                                                              | `reason: "unknown-change-anchor"`.                                                                              |
| `rejected` (invalid action)        | The anchor resolved but the `action` is outside the closed vocabulary. A judgment with a hallucinated anchor and a bad label is rejected for the anchor, never as `invalid-action`. | `reason: "invalid-action"`, `invalid_value: "<the offending label>"` so the agent can fix it in one round trip. |
| `rejected` (stale)                 | The echoed graph-snapshot hash no longer matches (the tree moved).                                                                                                                  | `reason: "stale-snapshot"`, `stale: true`. Re-fetch the guide.                                                  |

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

## See also

<CardGroup>
  <Card title="Dead code analysis" icon="skull-crossbones" href="/cli/dead-code">
    Full dead code analysis with issue-type filters.
  </Card>

  <Card title="Health analysis" icon="heart-pulse" href="/cli/health">
    Complexity metrics, file scores, hotspots, and targets.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use fallow tools from AI coding agents.
  </Card>
</CardGroup>


# fallow config
Source: https://docs.fallow.tools/cli/config

Show the resolved fallow config and which file was loaded. Mirrors eslint --print-config and dprint output-resolved-config.

Print the resolved configuration and the path of the config file that was loaded. Useful for debugging "why isn't my config being applied?" in monorepos where multiple `.fallowrc.json` files may be in play.

```bash theme={null}
fallow config
```

By default, prints the loaded config path on the first line followed by the JSON-serialized config (with `extends` resolved):

```text title="$ fallow config" theme={null}
loaded config: /repo/.fallowrc.json
{
  "entry": ["src/main.ts"],
  "ignorePatterns": ["dist/**"],
  "duplicates": {
    "ignoreImports": true
  },
  ...
}
```

## Options

| Flag     | Description                                                                               |
| :------- | :---------------------------------------------------------------------------------------- |
| `--path` | Print only the config file path, one line, no JSON. Easier to consume from shell scripts. |

The global `--config <path>` flag is honored: if you pass it, that path is loaded directly instead of walking the directory tree.

## Exit codes

| Code | Meaning                                                                                                                                  |
| :--- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | The default view succeeded: a config file was found and loaded, or, on a zero-config project, the effective defaults were printed        |
| `2`  | Error (failed to parse, explicit `--config` path missing, etc.)                                                                          |
| `3`  | `--path` mode only, when no config file exists (there is no path to report). The default view prints the defaults and exits `0` instead. |

## Examples

### Verify which config the LSP/CLI picked up

In a monorepo, when running fallow from inside a sub-package:

```bash theme={null}
cd packages/app
fallow config --path
# /repo/.fallowrc.json   (root config inherited, sub-package has none of its own)
```

If a sub-package has its own config, that path is printed instead (first-match-wins).

### Use an explicit config file

```bash theme={null}
fallow --config ./my-config.json config
```

### Pipe to jq for further inspection

```bash theme={null}
fallow config | jq '.duplicates'
```

The `loaded config: ...` disclosure goes to stderr, so stdout is the JSON document alone. See [Loaded config disclosure](/cli/global-flags#loaded-config-disclosure).

### Detect "no config" in scripts

```bash theme={null}
if ! fallow config --path > /tmp/fallow-cfg-path 2>/dev/null; then
  echo "no fallow config found, will use defaults"
fi
```

## Related

* [Configuration overview](/configuration/overview): supported config file names and the full schema
* [Monorepo configuration](/configuration/workspaces): how config discovery works in workspaces


# fallow coverage
Source: https://docs.fallow.tools/cli/coverage

CLI reference for fallow coverage. Run the resumable setup flow, analyze local or cloud runtime coverage, upload source maps, and push static inventory so the dashboard can surface untracked code.

`fallow coverage` groups the paid Runtime Coverage workflow commands:

```bash theme={null}
fallow coverage setup              # resumable first-run flow
fallow coverage analyze --cloud --repo owner/repo
fallow coverage upload-inventory   # push a static function inventory
fallow coverage upload-source-maps           # upload build source maps for bundled code
```

## `setup`

The setup flow is resumable: run it once to bootstrap, follow the generated recipe, then run it again after traffic has been captured. It performs four steps:

1. check license state
2. locate or install `fallow-cov`
3. write a framework-specific collection recipe to `docs/collect-coverage.md`
4. if coverage already exists, hand off directly to `fallow health --runtime-coverage <path>`

```bash theme={null}
fallow coverage setup
fallow coverage setup --non-interactive
fallow coverage setup --yes
fallow coverage setup --yes --json
fallow coverage setup --yes --json --explain
```

### Flags

| Flag                | Description                                                                                                                                                                                                                               |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-y, --yes`         | Accept prompts automatically. Useful for local setup when you want fallow to continue without confirmation prompts.                                                                                                                       |
| `--non-interactive` | Print instructions instead of prompting. Useful in CI, remote shells, or agent workflows.                                                                                                                                                 |
| `--json`            | Emit deterministic agent-readable setup instructions as JSON. Implies `--non-interactive` and does not prompt, write files, install packages, activate a license, or make network calls. See [Agent-readable JSON](#agent-readable-json). |
| `--explain`         | With `--json`, include a `_meta` block with field definitions, enum values, warning semantics, and this docs URL.                                                                                                                         |

## What setup detects automatically

`fallow coverage setup` inspects `package.json`, lockfiles, and scripts to tailor the instructions:

| Detection          | Purpose                                                                                                                                                                                                                                                                                                                                                              |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Framework          | Chooses a recipe for Next.js, NestJS, Nuxt, SvelteKit, Astro, Remix, Vite browser apps, plain Node services, or a generic fallback. When both a Node-server framework (Elysia, Hono, Fastify, Express, Koa, `@trpc/server`) and Vite appear in the same `package.json`, the Node-server framework wins so the recipe targets the API rather than the bundled client. |
| Workspace topology | Walks `workspaces` (npm/pnpm/yarn/bun) and emits one recipe per runtime-bearing member. Library-only workspaces (no `start`/`preview`/`dev` script and no Node-server dependency) are skipped. The top-level `runtime_targets` array is the union (`["node"]`, `["browser"]`, or `["node", "browser"]`) across all members.                                          |
| Package manager    | Uses `packageManager`, lockfiles, or both to choose install commands for npm, pnpm, yarn, or bun.                                                                                                                                                                                                                                                                    |
| Coverage artifact  | Detects existing `coverage/coverage-final.json`, `.nyc_output/coverage-final.json`, or JSON-containing V8 directories.                                                                                                                                                                                                                                               |
| Sidecar binary     | Resolves `FALLOW_COV_BIN`, `FALLOW_COV_BINARY_PATH`, project-local shims, package-manager bin lookups, `~/.fallow/bin/fallow-cov`, and `PATH`.                                                                                                                                                                                                                       |

If the project does not match a built-in framework recipe, fallow still writes a fallback `docs/collect-coverage.md` with a link to the public coverage docs for manual setup.

### Agent-readable JSON

`fallow coverage setup --yes --json` is the agent-driven entry point. The payload is deterministic and stable across reruns; `--explain` adds the optional `_meta` keys without changing `schema_version`.

On a workspace monorepo (Elysia API at root + two Vite browser apps in `dashboard/` and `site/`):

```json theme={null}
{
  "schema_version": "1",
  "framework_detected": "plain_node",
  "package_manager": "bun",
  "runtime_targets": ["node", "browser"],
  "members": [
    {
      "name": "fallow-cloud",
      "path": ".",
      "framework_detected": "plain_node",
      "runtime_targets": ["node"],
      "files_to_edit": [{"path": "src/index.ts", "reason": "..."}],
      "snippets": [{"label": "Node entrypoint", "path": "src/index.ts", "content": "..."}],
      "dockerfile_snippet": "ENV FALLOW_TRANSPORT=fs\nENV FALLOW_WRITE_TO_DIR=/tmp/fallow-coverage",
      "warnings": []
    },
    {
      "name": "fallow-dashboard",
      "path": "dashboard",
      "framework_detected": "vite",
      "runtime_targets": ["browser"],
      "files_to_edit": [{"path": "dashboard/src/main.ts", "reason": "..."}],
      "snippets": [{"label": "Vite browser entry", "path": "dashboard/src/main.ts", "content": "..."}],
      "dockerfile_snippet": null,
      "warnings": []
    }
  ],
  "config_written": null,
  "commands": ["bun add @fallow-cli/beacon", "bun add -d @fallow-cli/fallow-cov"],
  "files_to_edit": [{"path": "src/index.ts", "reason": "..."}],
  "snippets": [{"label": "Node entrypoint", "path": "src/index.ts", "content": "..."}],
  "dockerfile_snippet": "ENV FALLOW_TRANSPORT=fs\nENV FALLOW_WRITE_TO_DIR=/tmp/fallow-coverage",
  "next_steps": [...],
  "warnings": []
}
```

`framework_detected` uses canonical ids (`nextjs`, `nestjs`, `nuxt`, `sveltekit`, `astro`, `remix`, `vite`, `plain_node`, `unknown`). Workspace projects emit one `members[]` entry per runtime-bearing workspace, each with its own `framework_detected`, `runtime_targets`, `files_to_edit`, `snippets`, and `dockerfile_snippet`. Top-level fields mirror the first emitted runtime member (the root when the root itself is a runtime app, otherwise the first runtime workspace), so on a browser-rooted monorepo with a Node child agents should read each member's `dockerfile_snippet` rather than the top-level one. Single-app projects emit a `members` array of length 1 (path `"."`), so consumers can treat `members[]` uniformly.

Aggregator-only repos (workspaces whose only runtime indicator is a Turbo/Nx-style `dev` script delegating to children, plus build-only library packages) are not runtime-bearing and emit an empty payload: `framework_detected: "unknown"`, `runtime_targets: []`, `members: []`, plus a `warnings` entry of `"No runtime workspace members were detected; emitted install commands only."`. Agents can branch on `members.length === 0` (or `framework_detected === "unknown"`) to detect this case and skip the snippet-application step.

## Generated recipe

The generated `docs/collect-coverage.md` recipe typically looks like:

```text theme={null}
1. Remove any old dump directory: rm -rf ./coverage
2. Build the app
3. Start the app with NODE_V8_COVERAGE=./coverage ...
4. Exercise the routes or jobs you care about
5. Stop the app and run: fallow coverage setup
```

Framework-aware script selection means fallow prefers existing `build`, `start`, or `preview` scripts when they exist and falls back to common framework commands otherwise.

## Typical flow

```bash theme={null}
fallow license activate --trial --email you@company.com
fallow coverage setup

# Follow docs/collect-coverage.md, then run setup again.
# With coverage present it hands off to `fallow health --runtime-coverage ./coverage`.
fallow coverage setup
```

## `analyze`

Use local mode when you have a coverage artifact on disk:

```bash theme={null}
fallow coverage analyze --runtime-coverage ./coverage --format json
```

Use cloud mode when you want the latest fallow\.cloud runtime context for a repo:

```bash theme={null}
FALLOW_API_KEY=fallow_live_... \
  fallow coverage analyze --cloud --repo owner/repo --format json
```

`FALLOW_API_KEY` alone never selects cloud mode. You must pass `--cloud`, `--runtime-coverage-cloud`, or set `FALLOW_RUNTIME_COVERAGE_SOURCE=cloud`.

### Analyze flags

| Flag                                  | Description                                                                                                                                                                                                    |
| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--runtime-coverage <PATH>`           | Local V8 directory, V8 JSON file, or Istanbul coverage map. Mutually exclusive with cloud mode.                                                                                                                |
| `--cloud`, `--runtime-coverage-cloud` | Explicitly fetch cloud runtime facts from `/v1/coverage/:repo/runtime-context`.                                                                                                                                |
| `--repo <OWNER/REPO>`                 | Repository to fetch in cloud mode. Falls back to `$FALLOW_REPO`, then parsed `origin`. Slashes are URL-encoded as one route segment.                                                                           |
| `--api-key <KEY>`                     | Fallow cloud bearer token. Falls back to `$FALLOW_API_KEY`, but only after explicit cloud opt-in.                                                                                                              |
| `--api-endpoint <URL>`                | Override the API base URL. Useful for staging and on-prem deployments.                                                                                                                                         |
| `--coverage-period <DAYS>`            | Cloud observation window, 1 through 90 days. Default: 30.                                                                                                                                                      |
| `--project-id <ID>`                   | Optional monorepo/project discriminator.                                                                                                                                                                       |
| `--environment <NAME>`                | Optional cloud environment filter.                                                                                                                                                                             |
| `--commit-sha <SHA>`                  | Optional cloud commit filter.                                                                                                                                                                                  |
| `--top <N>`                           | Show only the top N runtime findings, hot paths, blast-radius entries, and importance entries. Truncation happens before rendering, so it propagates to JSON, human, and cloud-merge output equally.           |
| `--blast-radius`                      | Show the first-class blast-radius section in human output. JSON always includes `runtime_coverage.blast_radius` whenever runtime coverage analysis runs.                                                       |
| `--importance`                        | Show the first-class importance section in human output. JSON always includes `runtime_coverage.importance` whenever runtime coverage analysis runs.                                                           |
| `--production`                        | Run analyze in production mode, matching `fallow health --production`. Filters out test files and dev-only code paths before merging runtime data.                                                             |
| `--min-invocations-hot <N>`           | Hot-path classification threshold. Functions invoked at least N times during the captured window are classified as hot. Default: 100. Mirrors the same flag on `fallow health --runtime-coverage`.             |
| `--min-observation-volume <N>`        | Minimum total trace volume before high-confidence `safe_to_delete` / `review_required` verdicts. Below this the sidecar caps confidence 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`. Decimal form (`0.001` = 0.1%). Default: 0.001.                                                 |
| `--debug-unmatched`                   | List every cloud runtime function with no local counterpart on stderr, highest traffic first. Use it to see what the join dropped without attaching a debugger.                                                |
| `--explain`                           | With `--format json`, attach a top-level `_meta` block with field definitions, enum values (`data_source`, `test_coverage`, `v8_tracking`, `action_type`, etc.), warning-code documentation, and the docs URL. |

Cloud analysis emits the same `runtime_coverage` JSON block as local mode. Its summary includes `data_source: "cloud"`, `last_received_at`, and `capture_quality` derived from the pulled runtime window. Cloud functions that cannot be matched to the local AST/static index are omitted from findings and reported through a `cloud_functions_unmatched` warning.

The join does not require the two sides to spell a function the same way. Stable-id matching runs first. A runtime path such as `/app/src/a.ts` from a containerized service is then rebased onto the local tree by file name plus a segment-wise suffix comparison, and a function whose runtime name disagrees with the static index (an anonymous callback reported as `map`, `then`, or `get`, or an accessor keeping its `get` prefix) is matched on its position within the resolved file. Both tiers refuse an ambiguous answer rather than guess: two local files equally entitled to one runtime path, or two definitions opening on the same line with no end line between them, stay unmatched. Pass `--debug-unmatched` to list whatever is left.

Each finding's `actions[].type` uses the canonical kebab-case vocabulary: `delete-cold-code` is emitted on `verdict=safe_to_delete`, `review-runtime` on `verdict=review_required`. The sidecar may emit additional protocol-specific identifiers, so consumers should treat unknown values as forward-compat extensions rather than schema violations.

## Sidecar installation

If `fallow-cov` is missing, setup tells you exactly what it checked and suggests the correct install command for your package manager, for example:

```bash theme={null}
pnpm add -D @fallow-cli/fallow-cov
```

You can also bypass auto-discovery by setting either explicit-override env var to a binary path. Resolution order is `FALLOW_COV_BIN` first, then `FALLOW_COV_BINARY_PATH`, then project-local auto-discovery. Both fail hard with a clear error if the configured path does not exist (they never silently fall through to the next step). `FALLOW_COV_BINARY_PATH` exists for air-gapped enterprise installs, Linux distro-packaged sidecars, and Docker multi-user setups where `~/.fallow/bin` is not writable.

### Sidecar signature verification

Every sidecar spawn runs an Ed25519 signature check against the compiled-in public key. The sidecar binary must ship with an adjacent `<binary>.sig` file. A missing, wrong-length, or invalid signature fails hard with exit code 4 rather than executing an unverified binary. There is no warn-and-run mode and no opt-out env var. If verification fails, reinstall the signed distribution with the install command above.

## `upload-inventory`

`fallow coverage upload-inventory` walks every JS/TS source in the project and POSTs a static function inventory (one row per declaration, expression, arrow, or method) to fallow cloud. The server computes `inventory − runtime-seen = untracked` for the matching git SHA, which lights up the dashboard's **Untracked** filter.

```bash theme={null}
fallow coverage upload-inventory \
  --api-key $FALLOW_API_KEY \
  --project-id acme/web
```

### Defaults and inference

| Flag             | Default                                                                                                |
| :--------------- | :----------------------------------------------------------------------------------------------------- |
| `--api-key`      | `$FALLOW_API_KEY`                                                                                      |
| `--api-endpoint` | `$FALLOW_API_URL` or `https://api.fallow.cloud`                                                        |
| `--project-id`   | `$GITHUB_REPOSITORY`, then `$CI_PROJECT_PATH`, then `git remote get-url origin` parsed to `owner/repo` |
| `--git-sha`      | `git rev-parse HEAD`                                                                                   |

### Flags

| Flag                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--api-key <KEY>`           | Fallow cloud bearer token. **Prefer `$FALLOW_API_KEY` on shared CI runners**: passing secrets on the command line may be visible to other processes via `ps` and can leak into shell history or process audit logs.                                                                                                                                                                                                                                  |
| `--api-endpoint <URL>`      | Override the base URL. Useful for staging and on-prem deployments.                                                                                                                                                                                                                                                                                                                                                                                   |
| `--project-id <OWNER/REPO>` | Project identifier, `owner/repo` form.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--git-sha <SHA>`           | Commit SHA this inventory is keyed to. Max 64 chars; `[A-Za-z0-9._-]` only.                                                                                                                                                                                                                                                                                                                                                                          |
| `--allow-dirty`             | Silence the warning when the working tree has uncommitted changes.                                                                                                                                                                                                                                                                                                                                                                                   |
| `--exclude-paths <GLOB>`    | Additional globs to skip, applied after the configured fallow ignore rules. Repeatable.                                                                                                                                                                                                                                                                                                                                                              |
| `--path-prefix <PREFIX>`    | Prefix prepended to every emitted `filePath` so the static inventory matches the path shape the runtime beacon reports. Required for containerized deployments: the beacon reports V8's absolute path inside the container (e.g. `/app/src/foo.ts`) while the walker emits repo-relative paths (`src/foo.ts`) by default. Must start with `/` and use POSIX separators. See [Path prefix](#path-prefix-containerized-deployments) for common values. |
| `--with-callers`            | Also upload importer edges (which modules import each declaration) alongside the inventory, so the dashboard can surface caller reach for untracked code. The inventory rows also carry per-function complexity and per-file churn.                                                                                                                                                                                                                  |
| `--dry-run`                 | Print what would be uploaded and exit. No network call.                                                                                                                                                                                                                                                                                                                                                                                              |
| `--ignore-upload-errors`    | Treat upload failures as warnings (exit 0). Validation errors still fail hard.                                                                                                                                                                                                                                                                                                                                                                       |

### Function naming

Inventory entries use names that match `oxc-coverage-instrument` byte-for-byte so the runtime join succeeds. Precedence:

1. Parent context (method key, variable binding, property key, `export default`).
2. The function's own `id` (`function foo() {}`, named function expression).
3. `(anonymous_N)` where `N` is a file-scoped monotonic counter.

TypeScript declaration files (`*.d.ts`, `*.d.mts`, `*.d.cts`, `*.d.tsx`) and overload signatures with no body are intentionally skipped: they have no runtime footprint, so including them would pollute the dashboard with permanently `untracked` entries.

### Path prefix (containerized deployments)

The runtime beacon reports V8's `filePath` as it sees it at runtime. In a container, that is the path inside the image (e.g. `/app/src/foo.ts` when the Dockerfile sets `WORKDIR /app`). The static inventory walker, running in CI against the checkout, emits repo-relative paths (`src/foo.ts`) by default. The server joins runtime and inventory on the exact `(filePath, functionName)` pair; if the two sides don't share a prefix shape, the Untracked filter never lights up and the dashboard surfaces a `mismatched` state.

The fix: pass `--path-prefix` matching your deployed `WORKDIR`:

```bash theme={null}
fallow coverage upload-inventory --path-prefix /app
```

Common values by deployment target:

| Target                                                | Prefix                            |
| :---------------------------------------------------- | :-------------------------------- |
| Docker image with `WORKDIR /app` (most Node services) | `/app`                            |
| Cloud Run / Buildpacks                                | `/workspace`                      |
| Older official Node images                            | `/usr/src/app`                    |
| AWS Lambda                                            | `/var/task`                       |
| GitHub Actions default checkout                       | `/home/runner/work/<repo>/<repo>` |

After upload, the server samples up to 100 recent runtime rows and reports the overlap with the inventory. The CLI prints a yellow warning if overlap \< 50% with an example mismatch, and the dashboard renders a configuration-needed state on the repo detail page until the prefix is corrected.

### Exit codes

| Code | Meaning           | When it fires                                                                                 |
| :--: | :---------------- | :-------------------------------------------------------------------------------------------- |
|  `0` | ok                | Upload succeeded, or `--dry-run`, or `--ignore-upload-errors` downgraded a transient failure. |
|  `7` | network           | DNS, TLS, connect, or transport failure.                                                      |
| `10` | validation        | Missing API key, unresolvable project-id, zero functions in walk.                             |
| `11` | payload too large | Inventory exceeds the server's 200,000-function cap. Scope with `--exclude-paths`.            |
| `12` | auth rejected     | 401 / 403 from the server. Rotate the token or widen its scope.                               |
| `13` | server error      | 5xx after retries, or other non-2xx status.                                                   |

### Example CI job (GitHub Actions)

```yaml theme={null}
- name: Upload function inventory to fallow cloud
  run: |
    npx fallow coverage upload-inventory
  env:
    FALLOW_API_KEY: ${{ secrets.FALLOW_API_KEY }}
```

### Dry-run output

```text theme={null}
fallow coverage upload-inventory (dry run)
  project-id:    acme/web
  git-sha:       a1b2c3d4e5f6...
  functions:     14,280
  endpoint:      https://api.fallow.cloud/v1/coverage/acme/web/inventory

first 5 of 14,280 entries:
  src/index.ts:1   bootstrap
  src/index.ts:12  (anonymous_1)
  src/user.ts:3    createUser
  src/user.ts:18   default
  src/user.ts:42   (anonymous_5)
  ... and 14,275 more
```

## `upload-source-maps`

`fallow coverage upload-source-maps` scans a build output directory for source maps and POSTs each map to fallow cloud under the current repo and git SHA. The production beacon reports coverage against deployed bundles; uploaded source maps let the cloud resolver remap those bundle positions back to original source files.

```bash theme={null}
FALLOW_API_KEY=fallow_live_... \
  fallow coverage upload-source-maps --dir dist --repo my-app --git-sha "$GITHUB_SHA"
```

### Source-map defaults

| Flag                  | Default                                                                                  | Description                                                                                                                                                                                                                   |
| :-------------------- | :--------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dir <PATH>`        | `dist`                                                                                   | Directory scanned recursively. Relative paths resolve from the project root.                                                                                                                                                  |
| `--include <GLOB>`    | `**/*.map`                                                                               | Include glob, matched relative to `--dir`.                                                                                                                                                                                    |
| `--exclude <GLOB>`    | `**/node_modules/**`                                                                     | Exclude glob, repeatable.                                                                                                                                                                                                     |
| `--repo <NAME>`       | `package.json` `repository.url`, then `git remote get-url origin` parsed to `owner/repo` | Repo identifier used in `/v1/coverage/:repo/source-maps`. Must match the beacon's `projectId` (and the `--project-id` passed to `upload-inventory`); pass `--repo <bare-name>` explicitly if your beacon reports a bare name. |
| `--git-sha <SHA>`     | `$GITHUB_SHA`, `$CI_COMMIT_SHA`, `$COMMIT_SHA`, then `git rev-parse HEAD`                | Commit SHA the beacon will report for the deployed build. Must be 7-40 hex chars.                                                                                                                                             |
| `--endpoint <URL>`    | `$FALLOW_API_URL` or `https://api.fallow.cloud`                                          | Override for staging or enterprise deployments.                                                                                                                                                                               |
| `--strip-path <BOOL>` | `true`                                                                                   | Upload only the basename as `fileName`, e.g. `dist/assets/app.js.map` -> `app.js.map`. Set `--strip-path=false` when runtime coverage reports bundle paths with directories, e.g. `assets/app.js`.                            |
| `--dry-run`           | `false`                                                                                  | Print what would upload without reading `FALLOW_API_KEY` or making network calls.                                                                                                                                             |
| `--concurrency <N>`   | `4`                                                                                      | Parallel upload fanout.                                                                                                                                                                                                       |
| `--fail-fast`         | `false`                                                                                  | Stop on the first failed map instead of uploading the rest and reporting a partial-failure summary.                                                                                                                           |

The API key comes only from `FALLOW_API_KEY`; there is intentionally no `--api-key` flag, so secrets do not land in shell history or process lists. Set `FALLOW_CA_BUNDLE=/path/to/bundle.pem` when CI needs a custom PEM trust bundle for fallow cloud. The bundle replaces the default WebPKI roots, so private-CA environments should pass a complete bundle containing public roots plus the private CA. Relative bundle paths resolve from the process working directory.

Uploads retry network failures, HTTP 429, and HTTP 502/503/504 up to three attempts. HTTP 429 honors `Retry-After` delta seconds and HTTP-date values, capped at 60 seconds. Setup or transport failures that prevent every map from uploading exit 7; mixed per-map failures still exit 1.

### Source-map CI snippets

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    - name: Build
      run: npm run build

    - name: Upload source maps to fallow
      run: npx fallow coverage upload-source-maps --dir dist --git-sha "$GITHUB_SHA"
      env:
        FALLOW_API_KEY: ${{ secrets.FALLOW_API_KEY }}
    ```
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    upload_source_maps:
      stage: deploy
      script:
        - npm run build
        - npx fallow coverage upload-source-maps --dir dist --git-sha "$CI_COMMIT_SHA"
      variables:
        FALLOW_API_KEY: $FALLOW_API_KEY
    ```
  </Tab>

  <Tab title="CircleCI">
    ```yaml theme={null}
    - run: npm run build
    - run:
        name: Upload source maps to fallow
        command: npx fallow coverage upload-source-maps --dir dist --git-sha "$CIRCLE_SHA1"
    ```
  </Tab>
</Tabs>

### Source-map failure modes

| Exit | Meaning                                                                                                                                |
| :--: | :------------------------------------------------------------------------------------------------------------------------------------- |
|  `0` | All maps uploaded, or dry-run completed.                                                                                               |
|  `1` | Partial or full upload failure, including invalid JSON maps, auth rejection, rate limits, server errors, or exhausted network retries. |
|  `2` | Bad invocation: missing `FALLOW_API_KEY`, unresolvable repo/SHA, missing directory, or zero maps found.                                |

## See also

<CardGroup>
  <Card title="License commands" icon="key" href="/cli/license">
    Start a trial, refresh a token, or inspect feature status.
  </Card>

  <Card title="Runtime coverage" icon="chart-network" href="/analysis/runtime-coverage">
    Learn what runtime coverage adds and how it differs from static reachability.
  </Card>
</CardGroup>


# fallow dead-code
Source: https://docs.fallow.tools/cli/dead-code

CLI reference for fallow dead-code. Scan entry points, trace reachable exports, and report unused files, exports, dependencies, and types.

Analyze your project for dead code. Fallow scans entry points, traces all reachable exports, and reports anything that isn't used.

<Tip>
  Running bare `fallow` runs **all analyses** (dead code, duplication, and health). Use `fallow dead-code` to run dead code analysis only. `fallow check` remains as a hidden alias for `fallow dead-code`.
</Tip>

```bash theme={null}
fallow dead-code
fallow check      # Hidden alias for fallow dead-code
```

## Options

### 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`                                               |
| `-q, --quiet`           | Suppress progress output                                                                                                                                                                                                                |
| `--fail-on-issues`      | Exit with code 1 if issues are found                                                                                                                                                                                                    |
| `--sarif-file <PATH>`   | Write SARIF output to a file (in addition to `--format`)                                                                                                                                                                                |
| `--ci`                  | CI mode: sets format to SARIF, enables fail-on-issues, suppresses progress. Individual flags can still override.                                                                                                                        |
| `--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.                                                        |
| `--group-by <MODE>`     | Group output by `owner` (CODEOWNERS), `directory` (first path component), `package` (workspace package), or `section` (GitLab CODEOWNERS `[Section]` headers, with `owners` metadata). See [global flags](/cli/global-flags#reference). |
| `--summary`             | Print a one-line summary of issue counts at the end of the run. In JSON format, adds a `summary` counts object.                                                                                                                         |

### Filtering

| Flag                                   | Description                                                                                                                                                                                                  |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--unused-files`                       | Only report unused files                                                                                                                                                                                     |
| `--unused-exports`                     | Only report unused exports                                                                                                                                                                                   |
| `--unused-types`                       | Only report unused types                                                                                                                                                                                     |
| `--private-type-leaks`                 | Opt in to private type leak API hygiene findings and only report that issue type                                                                                                                             |
| `--unused-deps`                        | Only report unused dependencies                                                                                                                                                                              |
| `--unused-optional-deps`               | Only report unused optional dependencies                                                                                                                                                                     |
| `--unused-enum-members`                | Only report unused enum members                                                                                                                                                                              |
| `--unused-class-members`               | Only report unused class members                                                                                                                                                                             |
| `--unused-store-members`               | Only report unused Pinia store members                                                                                                                                                                       |
| `--unresolved-imports`                 | Only report unresolved imports                                                                                                                                                                               |
| `--unlisted-deps`                      | Only report unlisted dependencies                                                                                                                                                                            |
| `--duplicate-exports`                  | Only report duplicate exports                                                                                                                                                                                |
| `--circular-deps`                      | Only report circular dependencies                                                                                                                                                                            |
| `--re-export-cycles`                   | Only report re-export cycles (barrel files re-exporting from each other in a loop, or self-loops). See [explanations/dead-code#re-export-cycles](/explanations/dead-code#re-export-cycles)                   |
| `--boundary-violations`                | Only report boundary violations                                                                                                                                                                              |
| `--policy-violations`                  | Only report rule-pack policy violations (banned calls and banned imports declared via the `rulePacks` config key). See [explanations/dead-code#policy-violations](/explanations/dead-code#policy-violations) |
| `--stale-suppressions`                 | Only report stale suppression comments and `@expected-unused` JSDoc tags                                                                                                                                     |
| `--type-only-deps`                     | Only report type-only dependencies                                                                                                                                                                           |
| `--unused-catalog-entries`             | Only report unused pnpm catalog entries                                                                                                                                                                      |
| `--empty-catalog-groups`               | Only report empty named pnpm catalog groups                                                                                                                                                                  |
| `--unresolved-catalog-references`      | Only report package references to missing pnpm catalog entries                                                                                                                                               |
| `--unused-dependency-overrides`        | Only report unused pnpm dependency overrides                                                                                                                                                                 |
| `--misconfigured-dependency-overrides` | Only report malformed pnpm dependency overrides                                                                                                                                                              |
| `--include-dupes`                      | Also run duplication analysis and cross-reference with dead code                                                                                                                                             |

### Scoping

| Flag                      | Description                                                                                                                                                                                                               |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--file <PATH>`           | Scope output to specific files. Accepts multiple values. Only issues in the specified files are reported. Project-wide dependency issues are suppressed. Warns on non-existent paths. Useful for lint-staged integration. |
| `--include-entry-exports` | Also report unused exports in entry files (package.json `main`/`exports`, framework pages, etc.), which are otherwise assumed to be consumed externally. See [global flags](/cli/global-flags#reference).                 |

### Type-aware TypeScript evidence

| Flag                            | Description                                                                                  |
| :------------------------------ | :------------------------------------------------------------------------------------------- |
| `--type-aware`                  | Add exact checker-backed evidence for Fallow-owned project questions.                        |
| `--type-aware-project <PATH>`   | Select a TypeScript project explicitly. Repeat for multiple projects.                        |
| `--type-aware-require <MODE>`   | Use `best-effort` for advisory partial results or `complete` to fail on incomplete evidence. |
| `--symbol-impact <FILE:EXPORT>` | Return exact consumers, affected files, and targeted tests. Requires `--type-aware`.         |

See [Type-aware TypeScript analysis](/analysis/type-aware) for the safety
contract and the boundary with `tsc` and Oxlint.

### Incremental

| Flag                     | Description                                                  |
| :----------------------- | :----------------------------------------------------------- |
| `--changed-since <REF>`  | Only check files changed since a git ref                     |
| `--baseline <PATH>`      | Compare against a previously saved baseline file             |
| `--save-baseline <PATH>` | Save current results as a baseline file                      |
| `--production`           | Production mode (exclude test/story/dev files)               |
| `--top <N>`              | Show only the top N items per issue category in human output |

### Regression detection

| Flag                                | Description                                                                    |
| :---------------------------------- | :----------------------------------------------------------------------------- |
| `--fail-on-regression`              | Fail if issue count increased beyond tolerance vs a regression baseline        |
| `--tolerance <N>`                   | Allowed increase: `"2%"` (percentage) or `"5"` (absolute). Default: `"0"`      |
| `--regression-baseline <PATH>`      | Path to regression baseline file (default: `.fallow/regression-baseline.json`) |
| `--save-regression-baseline <PATH>` | Save current issue counts as a regression baseline                             |

<Accordion title="Debugging flags">
  | Flag                           | Description                      |
  | :----------------------------- | :------------------------------- |
  | `--trace <FILE:EXPORT>`        | Trace usage of a specific export |
  | `--trace-file <PATH>`          | Show all edges for a file        |
  | `--trace-dependency <PACKAGE>` | Show where a dependency is used  |
  | `--performance`                | Show pipeline timing breakdown   |

  ```bash theme={null}
  # Why is formatDate reported as unused?
  fallow dead-code --trace src/utils.ts:formatDate

  # What imports/exports does this file have?
  fallow dead-code --trace-file src/utils.ts

  # Where is lodash used?
  fallow dead-code --trace-dependency lodash

  # Pipeline performance breakdown
  fallow dead-code --performance
  ```
</Accordion>

## Examples

<CodeGroup>
  ```bash Basic analysis theme={null}
  fallow dead-code
  ```

  ```bash CI integration theme={null}
  # JSON output for CI pipelines
  fallow dead-code --format json

  # SARIF for GitHub Code Scanning
  fallow dead-code --format sarif > results.sarif

  # Markdown for PR comments
  fallow dead-code --format markdown | gh pr comment --body-file -

  # Fail on any issues
  fallow dead-code --fail-on-issues
  ```

  ```bash Incremental workflows theme={null}
  # Only check changed files in a PR
  fallow dead-code --changed-since main

  # Save a baseline, then check against it
  fallow dead-code --save-baseline fallow-baselines/dead-code.json
  fallow dead-code --baseline fallow-baselines/dead-code.json
  ```

  ```bash Production mode theme={null}
  # Exclude test and dev files
  fallow dead-code --production
  ```

  ```bash File scoping theme={null}
  # Only report issues in specific files
  fallow dead-code --file src/utils.ts

  # Multiple files (e.g., from lint-staged)
  fallow dead-code --file src/utils.ts --file src/helpers.ts

  # Catch typos in entry file exports (e.g., meatdata vs metadata)
  fallow dead-code --include-entry-exports
  ```
</CodeGroup>

## Regression detection

Save a regression baseline on your main branch, then compare on subsequent runs (e.g., in PR checks) to prevent issue count from growing.

**Workflow:**

1. Save a regression baseline on `main`:
   ```bash theme={null}
   fallow dead-code --save-regression-baseline
   ```
   This writes issue counts to `.fallow/regression-baseline.json` (or a custom path).

2. On each PR, compare against the baseline:
   ```bash theme={null}
   fallow dead-code --fail-on-regression
   ```
   Exits with code 1 if the total issue count exceeds the baseline plus the configured tolerance.

3. Optionally set a tolerance to allow small fluctuations:
   ```bash theme={null}
   fallow dead-code --fail-on-regression --tolerance 2%   # percentage
   fallow dead-code --fail-on-regression --tolerance 5     # absolute
   ```

When `--fail-on-regression` is used with `--format json`, the output includes an optional `regression` object:

```json theme={null}
{
  "regression": {
    "status": "pass",
    "baseline_total": 42,
    "current_total": 45,
    "delta": 3,
    "tolerance": 2.0,
    "tolerance_kind": "percentage",
    "exceeded": false
  }
}
```

| Field            | Description                                                             |
| :--------------- | :---------------------------------------------------------------------- |
| `status`         | `pass`, `exceeded`, or `skipped`                                        |
| `baseline_total` | Issue count from the baseline file                                      |
| `current_total`  | Issue count from the current run                                        |
| `delta`          | `current_total - baseline_total`                                        |
| `tolerance`      | Configured tolerance value                                              |
| `tolerance_kind` | `percentage` or `absolute`                                              |
| `exceeded`       | Whether the delta exceeds the tolerance                                 |
| `reason`         | Only present when `status` is `skipped` (e.g., baseline file not found) |

<Tip>
  These flags also work with `fallow dupes` and bare `fallow` (all analyses). The regression check compares total issue counts across all enabled analyses.
</Tip>

## Example output

```bash title="$ fallow dead-code --format compact" theme={null}
unused-file:src/server/jobs/worker.ts
unused-file:src/features/savings/hooks/usePotGroups.ts
unused-file:src/server/jobs/cron.ts
unused-export:src/server/jobs/queue.ts:61:enqueueJobDelayed
unused-export:src/server/jobs/queue.ts:206:sweepStuckProcessingJobs
unused-export:src/components/Card/index.ts:1:CardFooter
re-export-cycle:src/api/index.ts:src/api/index.ts <-> src/api/internal/index.ts
re-export-cycle:src/utils/index.ts:src/utils/index.ts (self-loop)
```

Re-export cycles ship under their own field in `--format json` with the cycle's structural shape:

```json title="$ fallow dead-code --format json (excerpt)" theme={null}
{
  "kind": "dead-code",
  "schema_version": 9,
  "re_export_cycles": [
    {
      "files": ["src/api/index.ts", "src/api/internal/index.ts"],
      "kind": "multi-node",
      "actions": [
        {
          "type": "fix",
          "kind": "refactor-re-export-cycle",
          "auto_fixable": false,
          "description": "Remove one `export * from` (or `export { ... } from`) statement on any one member to break the cycle"
        },
        {
          "type": "suppress-file",
          "kind": "suppress-file",
          "auto_fixable": false,
          "comment": "// fallow-ignore-file re-export-cycle"
        }
      ]
    },
    {
      "files": ["src/utils/index.ts"],
      "kind": "self-loop",
      "actions": [...]
    }
  ]
}
```

`files` is sorted lexicographically; the `multi-node` shape carries two or more entries, the `self-loop` shape exactly one. See [explanations/dead-code#re-export-cycles](/explanations/dead-code#re-export-cycles) for the structural rationale.

## Fix suggestions in JSON output

When using `--format json`, every issue includes an `actions` array with machine-actionable fix and suppress hints.

```json theme={null}
{
  "path": "src/utils.ts",
  "export_name": "helperFn",
  "line": 10,
  "actions": [
    {
      "type": "remove-export",
      "auto_fixable": true,
      "description": "Remove the unused export from the public API"
    },
    {
      "type": "suppress-line",
      "auto_fixable": false,
      "description": "Suppress with an inline comment above the line",
      "comment": "// fallow-ignore-next-line unused-export"
    }
  ]
}
```

Each action has:

| Field          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | Fix action type in kebab-case (e.g. `remove-export`, `remove-file`, `suppress-line`, `add-to-config`)                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `auto_fixable` | `true` when `fallow fix` can handle this action automatically. Evaluated **per finding**, not per action type: the same `type` may carry `true` on one finding and `false` on another (e.g. `remove-catalog-entry` flips on `hardcoded_consumers`, the primary dependency action flips between `remove-dependency` / `move-dependency` on `used_in_workspaces`). Filter on this bool of each individual action, not on `type`. See [Auto-fix](/analysis/auto-fix#auto-fixable-is-per-finding-not-per-action-type) for the full list of per-instance flips. |
| `description`  | Human-readable explanation of the action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `comment`      | *(optional)* The inline suppression comment to add                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `note`         | *(optional)* Additional context for non-auto-fixable items                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `config_key`   | *(optional)* The config key to modify, e.g. `"ignoreDependencies"` for dependency issues                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `value`        | *(optional)* Value to write at `config_key`. Scalar for keys like `ignoreDependencies`; array of `{ file, exports }` rule objects for `ignoreExports`                                                                                                                                                                                                                                                                                                                                                                                                      |
| `value_schema` | *(optional)* URL pointing at the JSON Schema fragment that describes `value`. Agents that want to validate the payload before writing it into a user's config can fetch the linked schema and apply it                                                                                                                                                                                                                                                                                                                                                     |
| `scope`        | *(optional)* Present on `duplicate_exports` suppress actions as `"per-location"` since those span multiple files                                                                                                                                                                                                                                                                                                                                                                                                                                           |

<Info>
  Re-export findings include a warning note about public API surface impact. Dependency issues use `add-to-config` suppress (not inline comments) with the concrete package name and `config_key: "ignoreDependencies"`.
</Info>

## Additional JSON fields

When using `--format json`, the output may include these additional top-level objects:

### `entry_points`

Lists all resolved entry point files that root the module graph:

```json theme={null}
{
  "entry_points": [
    "src/index.ts",
    "src/cli.ts",
    "src/workers/sync.ts"
  ]
}
```

### `summary`

When `--summary` is used, a `summary` counts object is included:

```json theme={null}
{
  "summary": {
    "unused_files": 3,
    "unused_exports": 12,
    "unused_types": 2,
    "private_type_leaks": 0,
    "unused_dependencies": 1,
    "unresolved_imports": 0,
    "circular_dependencies": 1,
    "total_issues": 19
  }
}
```

`private_type_leaks` is present in JSON output for schema stability, but the rule is off by default. It is populated only when enabled with `--private-type-leaks` or with `private-type-leaks` set to `warn` or `error` in configuration.

### `used_in_workspaces`

Unused dependency findings can include `used_in_workspaces` when a package is unused in the declaring workspace but imported elsewhere in the monorepo:

```json theme={null}
{
  "unused_dependencies": [
    {
      "package_name": "lodash-es",
      "location": "dependencies",
      "path": "packages/shared/package.json",
      "line": 5,
      "used_in_workspaces": ["packages/consumer"]
    }
  ]
}
```

In human, markdown, GitHub, and GitLab output this appears as "imported in" or an "Imported elsewhere" column. Treat these as workspace placement issues: move the dependency to the consuming workspace instead of auto-removing it.

### `baseline_deltas`

When `--baseline` is used, a `baseline_deltas` object shows changes since the baseline:

```json theme={null}
{
  "baseline_deltas": {
    "added": 3,
    "removed": 5,
    "unchanged": 14
  }
}
```

## Stale suppression detection

Fallow detects `// fallow-ignore` comments and `/** @expected-unused */` JSDoc tags that no longer match any issue. This prevents suppression comments from accumulating after the underlying issues are resolved.

```bash theme={null}
# Only report stale suppressions
fallow dead-code --stale-suppressions

# JSON output includes stale_suppressions array
fallow dead-code --format json --stale-suppressions
```

Two types of staleness are detected:

| Origin                                                 | When it's stale                                                               |
| :----------------------------------------------------- | :---------------------------------------------------------------------------- |
| `// fallow-ignore-next-line` / `// fallow-ignore-file` | The suppression no longer matches any issue on the target line or in the file |
| `/** @expected-unused */` JSDoc tag                    | The tagged export is now imported by another module                           |

The `stale-suppressions` rule defaults to `warn`. Promote to `error` for CI enforcement:

```jsonc theme={null}
{
  "rules": {
    "stale-suppressions": "error"
  }
}
```

When using `--format json`, stale suppressions appear in the `stale_suppressions` array:

```json theme={null}
{
  "stale_suppressions": [
    {
      "path": "src/utils.ts",
      "line": 5,
      "col": 0,
      "origin": {
        "type": "inline_comment",
        "issue_type": "unused-export",
        "is_file_level": false
      }
    },
    {
      "path": "src/lib.ts",
      "line": 10,
      "col": 0,
      "origin": {
        "type": "jsdoc_tag",
        "export_name": "createWidget"
      }
    }
  ]
}
```

<Tip>
  Use `/** @expected-unused */` instead of `// fallow-ignore-next-line` when you want fallow to alert you if a suppressed export later becomes used. Both are tracked for staleness, but `@expected-unused` communicates intent more clearly.
</Tip>

## See also

<CardGroup>
  <Card title="Dead code analysis" icon="skull-crossbones" href="/analysis/dead-code">
    How fallow detects dead code.
  </Card>

  <Card title="Rules configuration" icon="sliders" href="/configuration/rules">
    Configure severity and thresholds per rule.
  </Card>

  <Card title="Production mode" icon="rocket" href="/analysis/production-mode">
    Analyze only shipping code.
  </Card>
</CardGroup>


# fallow decision-surface
Source: https://docs.fallow.tools/cli/decision-surface

CLI reference for fallow decision-surface. Surface only the few consequential structural decisions a change embeds, each as a judgment question with the routed expert to ask. The apex of the review brief, emitted on its own.

Surface only the consequential structural **decisions** a change embeds. Each one is framed as a judgment question, anchored to a deterministic graph-derived `signal_id`, paired with the routed expert to ask, and carries the named trade-off it makes. `decision-surface` is the apex of the [review brief](/cli/audit#review-brief-and-decision-surface), emitted on its own.

```bash theme={null}
fallow decision-surface --base main
fallow decision-surface --base main --format json --quiet
fallow decision-surface --base main --max-decisions 5
```

<Note>
  `fallow decision-surface` **always exits 0**. It is advisory, never a gate: the verdict is carried informationally, unlike [`fallow audit`](/cli/audit), which exits non-zero on a fail verdict. It answers "which one or two things here deserve a human judgment call?", not "will CI block this?".
</Note>

## When to reach for it

Three commands look at changed code; they answer different questions. Pick by the question you have.

| You want to know                                   | Command                                                                                                              | Gates?                                 |
| :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |
| Will CI block this PR?                             | [`fallow audit`](/cli/audit)                                                                                         | Yes (exits non-zero on a fail verdict) |
| Where do I look, across the whole change?          | [`fallow review`](/cli/audit#review-brief-and-decision-surface) (the full brief: subtract, focus, structure, direct) | No (always exits 0)                    |
| Which few decisions deserve a human judgment call? | `fallow decision-surface` (just the structure job)                                                                   | No (always exits 0)                    |

`fallow decision-surface` runs the **same changed-code analysis** as `fallow review` but emits **only** the decisions and discards the rest of the brief (the subtract list, the weighted focus map, the walkthrough contract). Reach for it when you want just the handful of structural choices the diff bakes in.

## What a decision is

A change can touch hundreds of lines and still embed only one or two choices that are expensive to walk back. The decision surface isolates those. Every entry is a **framed judgment question** with the context an agent or reviewer needs to answer it, not a recommendation. fallow never tells you which way to choose.

The surface has exactly three shippable categories:

| Category              | Meaning                                                                                                                                                                                                          |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `coupling-boundary`   | A new cross-zone dependency edge.                                                                                                                                                                                |
| `public-api-contract` | A new exported public-API surface, or a changed contract consumed by modules outside this diff.                                                                                                                  |
| `dependency`          | A new third-party dependency, or a declared one moved across a major version (or a `0.x` minor). One batched decision per manifest per kind, weighted by the graph's in-repo importers of the affected packages. |

Minor and patch bumps and non-numeric ranges (workspace, file, git, tags) are never dependency candidates. The importer count is a union over the batched packages (a module importing two bumped packages counts once). Entries outside `dependencies` are tagged in the question (`dev`, `optional`, `peer`); a package listed in several sections keeps its `dependencies` range and anchor line.

The set is **ranked by consequence** (blast radius x reversibility) and **capped** to a small, working-memory-sized list: 3 to 5 decisions, default 4, via [`--max-decisions`](#options), with no pagination. The cap is the point: a reviewer can hold a handful of structural questions in their head, not a flat wall of findings.

### What each decision carries

| Field                     | Type                                                               | What it is                                                                                                                                                                                                                                                              |
| :------------------------ | :----------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `question`                | string                                                             | The judgment framed as a question, the thing a human should weigh in on.                                                                                                                                                                                                |
| `category`                | `"coupling-boundary"` \| `"public-api-contract"` \| `"dependency"` | The kind of structural choice.                                                                                                                                                                                                                                          |
| `routed_expert`           | string                                                             | Who to ask. The decision points at the person or role whose judgment the category calls for, so the question reaches the right reviewer.                                                                                                                                |
| `signal_id`               | string                                                             | The deterministic, graph-derived anchor for this decision. Stable across runs against the same tree, and the join key for re-attaching review comments.                                                                                                                 |
| `tradeoff`                | string                                                             | The named structural sacrifice, stated as a fact (never a recommendation). For example: `"Couples app to infra; 4 in-repo modules already depend on this anchor"`.                                                                                                      |
| `internal_consumer_count` | integer                                                            | The honest count of in-repo modules **outside the diff** that already depend on the anchor. This is your reversibility signal: the higher the count, the more expensive it is to walk this back. It is the display number, distinct from the ranking-only blast figure. |
| `previous_signal_id`      | string \| null                                                     | Present when the anchor file was renamed: the `signal_id` it had before, so a review surface can re-attach a prior comment across a `git mv`.                                                                                                                           |

The human view shows the question and the trade-off; you read reversibility from the count itself. fallow never labels a decision a one-way or two-way door.

`coupling-boundary` and `public-api-contract` decisions are suppressible with an inline `// fallow-ignore` comment at the decision's anchor, the same way findings are suppressed elsewhere in fallow. A `dependency` decision anchors on `package.json`, which cannot carry a comment, so it has no `suppress` action; `ask-expert` still applies. Suppression removes a decision from the output; it does not change the verdict.

## How an agent consumes it

The decision surface is built for agents.

```bash theme={null}
fallow decision-surface --base main --format json --quiet
```

A typical agent flow:

1. Read `decisions[]` in order.
2. For each decision, surface the **question** and the `routed_expert` to the human, not the raw diff.
3. Use `internal_consumer_count` to decide how loudly to flag it: `0` is a cheap, reversible choice; a high count is a load-bearing anchor that is expensive to undo.
4. Quote the `tradeoff` clause verbatim. It is a fact, so an agent can relay it without editorializing.
5. Anchor any comment to `signal_id`. If the run reports a `previous_signal_id`, re-attach a prior comment across the rename instead of posting a duplicate.

<Tip>
  The digest the decision surface is built from comes from the graph only; PR prose is never folded into it. An agent can trust that the surfaced decisions reflect the actual structural change, not a description of it.
</Tip>

## Picking the comparison point

`decision-surface` scopes to changed code exactly like [`fallow audit`](/cli/audit#options). Use `--base` (or its `--changed-since` alias) to pick what "changed" means.

```bash theme={null}
# Against the merge-base with the default branch (auto-detected)
fallow decision-surface

# Explicit base ref
fallow decision-surface --base main

# Decisions embedded in the last 5 commits
fallow decision-surface --base HEAD~5
```

## Options

| Flag                     | Description                                                                                                                                                                                                                                                                                                          |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--base <REF>`           | Git ref to compare against (e.g. `main`, `HEAD~5`, a commit SHA). Alias for `--changed-since`. When omitted, the base is the `git merge-base` against the branch's upstream or the remote default (`origin/main`); set [`FALLOW_AUDIT_BASE`](/configuration/environment#fallow_audit_base) to pin it without a flag. |
| `--changed-since <REF>`  | Alias for `--base`. Scope the comparison to changes since this git ref.                                                                                                                                                                                                                                              |
| `--max-decisions <N>`    | Cap on the number of consequential structural decisions surfaced (the working-memory limit). Default 4; clamped to a 3 to 5 band. Values outside the band are clamped, not rejected.                                                                                                                                 |
| `-f, --format <FORMAT>`  | Output format: `human` (default) or `json`.                                                                                                                                                                                                                                                                          |
| `-r, --root <PATH>`      | Project root directory.                                                                                                                                                                                                                                                                                              |
| `-c, --config <PATH>`    | Path to a fallow config file.                                                                                                                                                                                                                                                                                        |
| `-w, --workspace <NAME>` | Scope to a single workspace package.                                                                                                                                                                                                                                                                                 |
| `-q, --quiet`            | Suppress progress and status output on stderr.                                                                                                                                                                                                                                                                       |

See [global flags](/cli/global-flags) for the full list.

## Examples

<CodeGroup>
  ```bash Basic usage theme={null}
  # Auto-detect base; render the decisions for a human
  fallow decision-surface

  # Explicit base ref
  fallow decision-surface --base main

  # Raise the cap
  fallow decision-surface --base main --max-decisions 5
  ```

  ```bash Agent / CI theme={null}
  # JSON for an agent to walk decisions[]
  fallow decision-surface --base main --format json --quiet

  # Environment variables work too
  FALLOW_FORMAT=json FALLOW_QUIET=1 fallow decision-surface --base main

  # Scope to one workspace package
  fallow decision-surface --base main --workspace @app/api --format json
  ```
</CodeGroup>

## Example output

```bash title="$ fallow decision-surface --base main" theme={null}
Decision surface: 3 decisions vs main (d4a2f91..HEAD)

● coupling-boundary  (ask: architecture owner)
  src/app/checkout.ts → src/infra/queue.ts
  Should the app zone depend directly on infra here?
  trade-off: Couples app to infra; 4 in-repo modules already depend on this anchor.
  internal consumers: 4

● public-api-contract  (ask: API owner)
  src/lib/client.ts:createClient
  This export is now public surface consumed outside the diff. Is the contract right?
  trade-off: Locks the createClient signature for external callers.
  internal consumers: 2

● dependency  (ask: platform owner)
  package.json → fast-xml-parser
  A new third-party dependency enters the graph. Is it warranted?
  trade-off: Adds a third-party maintenance and supply-chain surface.
  internal consumers: 0
```

## JSON output

`fallow decision-surface --format json` carries the `decisions[]` array; each entry carries the fields listed under [What each decision carries](#what-each-decision-carries). This is the same decision surface [`fallow review --format json`](/cli/audit#json-envelope) carries under its `decisions` key.

```json title="$ fallow decision-surface --base main --format json" theme={null}
{
  "command": "decision-surface",
  "base_ref": "main",
  "head_sha": "d4a2f91",
  "decisions": [
    {
      "signal_id": "coupling:app/checkout->infra/queue",
      "category": "coupling-boundary",
      "question": "Should the app zone depend directly on infra here?",
      "routed_expert": "architecture owner",
      "tradeoff": "Couples app to infra; 4 in-repo modules already depend on this anchor",
      "internal_consumer_count": 4
    },
    {
      "signal_id": "public-api:lib/client:createClient",
      "category": "public-api-contract",
      "question": "This export is now public surface consumed outside the diff. Is the contract right?",
      "routed_expert": "API owner",
      "tradeoff": "Locks the createClient signature for external callers",
      "internal_consumer_count": 2,
      "previous_signal_id": "public-api:lib/old-client:createClient"
    }
  ]
}
```

## MCP tool

The decision surface is also exposed as the [`decision_surface` MCP tool](/integrations/mcp#available-mcp-tools), so an agent gets the same decisions through structured tool calling:

```json title="Example request" theme={null}
{
  "tool": "decision_surface",
  "arguments": {
    "base": "main",
    "max_decisions": 4
  }
}
```

`base` and `max_decisions` map to the CLI flags of the same name. Dependency decisions are included; both routes share the manifest diff. See [MCP integration](/integrations/mcp) for the full tool list and setup.

## See also

<CardGroup>
  <Card title="Audit and review brief" icon="terminal" href="/cli/audit">
    The gating audit, plus the full review brief that the decision surface is the apex of.
  </Card>

  <Card title="Trace a call chain" icon="route" href="/cli/trace">
    Walk the callers and callees of one exported symbol before you change it.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use the `decision_surface` tool from AI coding agents.
  </Card>
</CardGroup>


# fallow doctor
Source: https://docs.fallow.tools/cli/doctor

CLI reference for fallow doctor. Read-only readiness checks for the project root, config resolution, workspace discovery, external plugins, the optional type-aware companion, installed dependencies, and persisted cache compatibility.

Diagnose project readiness without running an analysis. `fallow doctor` checks the things that have to be right before any command produces trustworthy output: whether the root is readable, which config actually resolved, whether workspace discovery found what you expect, whether external plugins load, whether the optional type-aware companion is present, whether dependencies are installed, and whether the persisted caches are compatible with the project.

Every check is a local read, which makes this safe as the very first command on a repository you have never analyzed, and cheap enough to leave in a CI preflight step.

```bash theme={null}
fallow doctor
fallow doctor --format json
```

<Info>
  `doctor` only tells you whether Fallow can see your project properly. Once it reports ready, [`fallow dead-code`](/cli/dead-code) and [`fallow health`](/cli/health) are what actually look at your code.
</Info>

## Checks

| Check          | Category        | Required | What it answers                                                             |
| :------------- | :-------------- | :------- | :-------------------------------------------------------------------------- |
| `root`         | `project`       | Yes      | Is the project root an accessible directory?                                |
| `config`       | `configuration` | Yes      | Which config resolved, or did zero-config defaults apply?                   |
| `workspaces`   | `workspace`     | No       | Did workspace discovery complete, and how many packages did it find?        |
| `plugins`      | `plugin`        | Yes      | Do the configured external plugins load?                                    |
| `type-aware`   | `companion`     | No       | Is the optional type-aware companion enabled and available?                 |
| `dependencies` | `project`       | No       | Is a `node_modules` directory present, or does the project run without one? |
| `cache`        | `cache`         | No       | Can the extraction cache be loaded with the current configuration?          |
| `graph-cache`  | `cache`         | No       | Can the module-graph cache be loaded for this project root?                 |

A check that is not required reports `skipped` when it cannot run, and a skipped check never fails the command. The `type-aware` check is skipped whenever type-aware analysis is off, which is the default.

The last three checks are advisory and cannot fail, so they never change the exit code. `dependencies` warns when the project has no `node_modules` directory and is not a project that runs without one, because package `exports`, plugin activation, and dependency classification all degrade until dependencies are installed. `cache` and `graph-cache` warn when a persisted blob exists but would be discarded, naming the reason and its on-disk size; a project with no cache yet passes, because a first run legitimately has none. A project in one of those states reports the aggregate `warn` and still exits `0`.

The two cache checks are separate because a run reuses the two blobs independently: the extraction cache can be perfectly reusable while the module graph is rebuilt every time. `graph-cache` checks whether the blob loads and belongs to this project root. A successful check does not establish that a run would reuse it, since the reuse decision also compares resolver options, entry points, and per-file content hashes, and computing those means running the discovery and extraction `doctor` deliberately skips.

The cache location follows `FALLOW_CACHE_DIR` when it is nonempty, ahead of the configured cache directory. Relative paths are resolved against the project root, as they are during analysis.

An absent cache is a normal first-run state. An unreadable cache is reported separately with a path-and-permissions hint. A decoding failure may mean an older cache format or damaged data; it does not establish corruption. Rebuilding the cache restores the current format.

## Options

| Flag                | Default           | Description                                          |
| :------------------ | :---------------- | :--------------------------------------------------- |
| `--root <ROOT>`     | current directory | Project root directory.                              |
| `--config <CONFIG>` | discovered        | Path to the Fallow config file.                      |
| `--format <FORMAT>` | `human`           | Output format: `human` or `json`. Alias: `--output`. |
| `--pretty`          | off               | Indent JSON output.                                  |
| `--quiet`           | off               | Suppress progress output.                            |

`doctor` reads and never writes, so `--output-file` is rejected rather than honored: the report goes to stdout, keeping the inputs to a diagnosis immutable. Analysis and gate flags such as `--production` and `--fail-on-issues` are rejected too, instead of being silently ignored on a command that runs no analysis.

## Exit codes

| Code | Meaning                                                          |
| :--- | :--------------------------------------------------------------- |
| `0`  | Every required check passed. Warnings still exit `0`.            |
| `2`  | A required check failed, so the project is not ready to analyze. |

There is no exit `1` here. That code means error-severity findings, and `doctor` looks at your setup rather than your code, so it has no findings to report.

## Human output

```text theme={null}
Fallow doctor (.)
[OK] root: Project root is an accessible directory.
[OK] config: Configuration resolved from .fallowrc.json.
[OK] workspaces: Workspace discovery completed (30 workspace packages).
[OK] plugins: No external plugins are configured; built-in detection remains available.
[-] type-aware: Type-aware analysis is not enabled.
[OK] dependencies: Dependencies are installed, or the project runs without a node_modules directory.
[W] cache: Extraction cache (0.9 MB) would not be reused: cache format version changed. The next run parses every file.
    Action (from project root): fallow dead-code --quiet
[OK] graph-cache: Module-graph cache (0.5 MB) loads; a run reuses it when the analysed files and options are unchanged.
Status: ready with warnings
```

The trailing status line is `ready`, `ready with warnings`, or `not ready`. A check that carries a remediation prints it on an indented `Action` line under the message.

## JSON output

```json theme={null}
{
  "kind": "doctor",
  "schema_version": 2,
  "version": "3.24.1",
  "root": ".",
  "status": "warn",
  "summary": {
    "pass": 6,
    "warn": 1,
    "fail": 0,
    "skipped": 1
  },
  "checks": [
    {
      "id": "root",
      "category": "project",
      "status": "pass",
      "required": true,
      "message": "Project root is an accessible directory."
    },
    {
      "id": "config",
      "category": "configuration",
      "status": "pass",
      "required": true,
      "message": "Configuration resolved from .fallowrc.json."
    },
    {
      "id": "workspaces",
      "category": "workspace",
      "status": "pass",
      "required": false,
      "message": "Workspace discovery completed (30 workspace packages)."
    },
    {
      "id": "plugins",
      "category": "plugin",
      "status": "pass",
      "required": true,
      "message": "No external plugins are configured; built-in detection remains available."
    },
    {
      "id": "type-aware",
      "category": "companion",
      "status": "skipped",
      "required": false,
      "message": "Type-aware analysis is not enabled."
    },
    {
      "id": "dependencies",
      "category": "project",
      "status": "pass",
      "required": false,
      "message": "Dependencies are installed, or the project runs without a node_modules directory."
    },
    {
      "id": "cache",
      "category": "cache",
      "status": "warn",
      "required": false,
      "message": "Extraction cache (0.9 MB) would not be reused: cache format version changed. The next run parses every file.",
      "remediation": {
        "command": "fallow dead-code --quiet",
        "cwd": ".",
        "mutating": false
      }
    },
    {
      "id": "graph-cache",
      "category": "cache",
      "status": "pass",
      "required": false,
      "message": "Module-graph cache (0.5 MB) loads; a run reuses it when the analysed files and options are unchanged."
    }
  ]
}
```

Top-level `status` is `pass`, `warn`, or `fail`; a check's own `status` adds `skipped` to that set.

A check can carry a `remediation` object with `command`, `cwd`, and `mutating`. `cwd` is always the project root, and `mutating` says whether running the command writes anything, so an agent can run the read-only ones without asking. When an explicit `--config` was passed and the path is project-relative and safe to render, the remediation repeats it; for an external or unsafe-to-render config path the command is omitted and the message tells the caller to reuse the same `--config` value.

## For agents

Run `fallow doctor --format json --quiet` before the first analysis on an unfamiliar repository. A clean report and a misconfigured project both come back looking empty, and this is the cheapest way to tell them apart. Branch on the top-level `status`, then read `checks[].message` to report what the user needs to fix.


# fallow dupes
Source: https://docs.fallow.tools/cli/dupes

CLI reference for fallow dupes. Detect duplicated code blocks across your codebase using suffix-array analysis with configurable thresholds.

Detect copy-pasted code blocks across your entire codebase using suffix-array analysis.

```bash theme={null}
fallow dupes
```

## Options

### Detection

| Flag                    | Description                                                                                                                                                                                                                                                                                                                                    |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--mode <MODE>`         | Detection mode: `strict`, `mild` (default), `weak`, `semantic`                                                                                                                                                                                                                                                                                 |
| `--near`                | Include function-scoped near-miss clones with small structural edits. Uses semantic normalization and reports groups with at least 80% all-pairs similarity.                                                                                                                                                                                   |
| `--min-tokens <N>`      | Minimum tokens per clone (default: 50)                                                                                                                                                                                                                                                                                                         |
| `--min-lines <N>`       | Minimum lines per clone (default: 5)                                                                                                                                                                                                                                                                                                           |
| `--min-occurrences <N>` | Minimum number of occurrences before a clone group is reported (default: 2, must be ≥ 2). Raise to skip pair-only clones and focus on widespread copy-paste worth refactoring.                                                                                                                                                                 |
| `--skip-local`          | Only report cross-directory duplicates                                                                                                                                                                                                                                                                                                         |
| `--cross-language`      | Strip TS types for TS to JS matching                                                                                                                                                                                                                                                                                                           |
| `--ignore-imports`      | Exclude module wiring from clone detection (default). ES imports, re-export declarations, and top-level static `require()` binding declarations are stripped from the token stream. Runtime code, local exports, side-effect `require()` calls, nested `require()` calls, dynamic require arguments, and mixed declarations are still counted. |
| `--no-ignore-imports`   | Count module wiring as clone candidates (opt out of the default exclusion). Conflicts with `--ignore-imports`.                                                                                                                                                                                                                                 |

### 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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--top <N>`             | Show only the N highest-ranked clone groups (see [Ranking and JSON fields](#ranking-and-json-fields)). `clone_families[]` is rebuilt from the groups that survive, so it narrows with them. Every `stats` counter keeps describing the whole scoped corpus; `clone_groups_shown` / `clone_groups_omitted` and `clone_families_shown` / `clone_families_omitted` report the split. Refused with exit code `2` alongside `--group-by`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--quiet`               | Suppress progress output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--threshold <N>`       | Fail if duplication exceeds N%                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--group-by <MODE>`     | Partition the report into per-group sections. `MODE`: `owner` (CODEOWNERS), `directory` (first path component), `package` (workspace), or `section` (GitLab `[Section]` headers). Each clone group is attributed to its largest owner (most instances; alphabetical tiebreak), so a group split 2 src / 1 lib appears under `src`. JSON adds `grouped_by` plus a `groups` array of per-bucket dedup-aware `stats`, attributed `clone_groups` (each carrying `primary_owner` and per-instance `owner`), and `clone_families`. SARIF results carry `properties.group` and CodeClimate issues carry a top-level `group` field. Compact and markdown fall back to ungrouped output with a stderr note. Cannot be combined with `--top`: per-bucket stats are computed over every clone group in the bucket, so a global top-N truncation would leave them describing groups the output no longer lists. |
| `--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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--explain-skipped`     | In human/markdown output, show the per-pattern breakdown for files skipped by default duplicates ignores. Machine formats suppress this note.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--summary`             | Print a one-line summary of duplication counts at the end of the run. In JSON format, adds a `summary` counts object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--no-fragments`        | Omit the verbatim source text from `clone_groups[].instances[].fragment` in `--format json`. Each instance still carries `file`, `start_line`, `end_line`, `start_col`, and `end_col`, which address the same code, and the text is most of the payload on a duplicated codebase. Fingerprints, suggested names, refactoring suggestions, and `actions[]` are computed before serialization, so nothing else changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

### Incremental

| Flag                     | Description                                              |
| :----------------------- | :------------------------------------------------------- |
| `--changed-since <REF>`  | Only report duplication in files changed since a git ref |
| `--baseline <PATH>`      | Compare against a previously saved baseline file         |
| `--save-baseline <PATH>` | Save current duplication as a baseline file              |

#### Token cache

For projects with at least `duplicates.minCorpusSizeForTokenCache` source files (default `5000`), `fallow dupes` keeps a per-project tokenized-source cache under `<root>/.fallow/cache/dupes-tokens-vN/` so warm runs skip re-tokenizing unchanged files. The cache writes a sibling `.gitignore` containing `*` on first save, so its contents stay out of `git status`. Pass `--no-cache` to disable the cache for one run, or set a higher `minCorpusSizeForTokenCache` to keep it disabled even on larger projects. Below the threshold the cache stays off because the load/save overhead exceeds the tokenize savings on small corpora.

When `--changed-since` is set on a project at or above `duplicates.minCorpusSizeForShingleFilter` files (default `1024`), the detector additionally drops unchanged files whose k-token shingles do not overlap any changed file before building the suffix array. Both knobs are scoped to `[duplicates]` in `.fallowrc.json` / `.fallowrc.jsonc` / `fallow.toml` / `.fallow.toml`.

#### Default generated-output ignores

`fallow dupes` skips common framework output by default: `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.parcel-cache`, `.vite`, `.cache`, `out`, and `storybook-static`. These defaults merge with `duplicates.ignore`; they do not replace your configured ignores.

Test and mock files are also ignored by default: `*.test.*`, `*.spec.*`, `__tests__/`, and `__mocks__/` paths are skipped, since intentionally repetitive test setup is a common source of first-run noise on hand-coded projects. This is part of the same `ignoreDefaults` set as the generated-output ignores above.

```jsonc theme={null}
{
  "duplicates": {
    "ignoreDefaults": true,
    "ignore": ["**/__generated__/**"]
  }
}
```

Set `ignoreDefaults` to `false` to opt out and use only your `duplicates.ignore` list.

#### Reviewed clone groups

Add an intentional clone group to `duplicates.ignoredClones` without hiding other duplication findings:

```jsonc theme={null}
{
  "duplicates": {
    "ignoredClones": ["dup:6f12ab34:2"]
  }
}
```

The key is `<fingerprint>:<instance_count>`. Copy the fingerprint from the human listing or `clone_groups[].fingerprint` in JSON. Token changes and new occurrences make the group reportable again, while formatting-only edits keep the same fingerprint.

Collision handles use `dup:<16hex>-rN`; ordinary short and widened handles are unchanged. Older `dup:<16hex>-N` handles no longer select or suppress a group. Re-run `fallow dupes` and review the reported group before replacing a saved key, rather than inserting `r` into the old handle. Upgrade all runners before adding `-rN` keys to a shared `ignoredClones` configuration. See [migrating collision handles](/analysis/duplication#migrating-collision-handles) for baseline behavior.

### Monorepo scoping

Both flags retain only clone groups where at least one instance is under a selected workspace root. The full cross-workspace index is still built; reported groups and the `duplication_percentage` stat are recomputed from the scoped slice.

| Flag                         | Description                                                                                                                                                                                                                          |
| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-w, --workspace <PATTERNS>` | Scope output to one or more workspaces. Supports exact package names, globs (`apps/*`, `@scope/*`) matched against both the package name and the workspace path, and `!`-prefixed negation. Comma-separated values or repeated flag. |
| `--changed-workspaces <REF>` | Git-derived monorepo CI scoping: scope to workspaces containing any file changed since `REF` (e.g. `origin/main`). Mutually exclusive with `--workspace`. Missing ref is a hard error (exit 2), not silent full-scope fallback.      |

### Debugging

| Flag                              | Description                                                                                                                                                                                                                                                                                                                                                                                                              |
| :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--trace <FILE:LINE \| dup:<fp>>` | Deep-dive clones. `FILE:LINE` shows all clones at a source location; `dup:<id>` deep-dives a clone group by the stable fingerprint shown in the listing (and on `clone_groups[].fingerprint` in JSON). Fingerprints are usually `dup:<8hex>` and widen only on rare report collisions. The trace shows each group's fingerprint, an extract-function suggestion with estimated savings, and a best-effort proposed name. |
| `--performance`                   | Show pipeline timing breakdown                                                                                                                                                                                                                                                                                                                                                                                           |

## Detection modes

<Accordion title="Detection mode details">
  Each mode progressively normalizes more syntax before comparing, trading precision for recall.

  | Mode         | What it normalizes                                                             | Best for                                 |
  | :----------- | :----------------------------------------------------------------------------- | :--------------------------------------- |
  | **strict**   | Nothing: exact token match                                                     | Finding verbatim copies                  |
  | **mild**     | Currently equivalent to strict (AST tokenization inherently strips whitespace) | General-purpose detection (default)      |
  | **weak**     | + string literal values                                                        | Catching copies with different messages  |
  | **semantic** | + variable names and numeric values                                            | Finding structural clones after renaming |

  As you move from `strict` to `semantic`, you'll find more clones but also more potential false positives. Start with `mild` and increase sensitivity as needed.
</Accordion>

## Ranking and JSON fields

The default report and `--top` multiply duplicated token count by occurrence count, then apply a spread boost. `spread` is the maximum directory-tree distance between instances. Same-file groups count one spread step per 250 lines of separation. The boost is capped at 15%.

Each JSON `clone_groups[]` entry includes:

* `spread`: maximum directory or same-file line distance
* `similarity`: lowest all-pairs similarity for near-miss groups, omitted for exact groups

### Shown versus measured

`stats` always describes the corpus the run measured. A presentation cap such as `--top` truncates the arrays without touching it, and four envelope-level counters report the split:

| Field                    | Meaning                                                          |
| :----------------------- | :--------------------------------------------------------------- |
| `clone_groups_shown`     | Length of `clone_groups[]`.                                      |
| `clone_groups_omitted`   | Groups a presentation cap withheld. `0` on an untruncated run.   |
| `clone_families_shown`   | Length of `clone_families[]`.                                    |
| `clone_families_omitted` | Families a presentation cap withheld. `0` on an untruncated run. |

`clone_groups_shown + clone_groups_omitted` always equals `stats.clone_groups`, and the same identity holds for families against `stats.clone_families`. Read `clone_groups_shown` when you want "how many groups are in this array" and `stats.clone_groups` when you want "how many the project has".

Scope filters are different from presentation caps. `--changed-since`, `--workspace`, and a duplication baseline narrow the corpus itself, so `stats` is recomputed against the narrowed corpus and nothing is reported as omitted.

Human output says the same thing in words. A capped run closes the listing with the counts it withheld:

```text theme={null}
  ... and 63 more clone groups
  ... and 52 more clone families withheld by the same display limit
```

Under `--summary`, the counts block names the corpus totals beside the shown ones, so the four numbers in it can never read as one scope when they are two:

```text theme={null}
       2  Clone families
       2  Clone groups
   2,605  Duplicated lines
    9.5%  Duplication rate
  ... and 63 more clone groups and 52 more clone families withheld by a display limit
  Corpus totals: 65 clone groups, 54 clone families; duplicated lines and rate cover all of it
```

The `stats` object can also include `clone_groups_ignored` when `duplicates.ignoredClones` hides groups, and `near_candidates_skipped` when bounded-work limits skip near-miss comparisons. Zero values are omitted.

## Examples

<CodeGroup>
  ```bash Default analysis theme={null}
  # Mild mode (default)
  fallow dupes
  ```

  ```bash Filtering theme={null}
  # Show only the 10 largest clone groups
  fallow dupes --top 10

  # Top 5 semantic clones, cross-directory only
  fallow dupes --top 5 --mode semantic --skip-local
  ```

  ```bash Advanced detection theme={null}
  # Catch renamed-variable clones
  fallow dupes --mode semantic

  # Include function-scoped clones with small structural edits
  fallow dupes --near

  # Only cross-directory duplicates
  fallow dupes --skip-local

  # TS to JS comparison
  fallow dupes --cross-language

  # Count sorted import blocks as clones (opt out of the default exclusion)
  fallow dupes --no-ignore-imports
  ```

  ```bash CI integration theme={null}
  # Only check duplication in changed files
  fallow dupes --changed-since main

  # Fail CI if duplication exceeds 5%
  fallow dupes --threshold 5

  # SARIF output for GitHub
  fallow dupes --format sarif > dupes.sarif
  ```

  ```bash Debugging theme={null}
  # Trace clones at a specific line
  fallow dupes --trace src/utils.ts:42

  # Deep-dive a clone group by its dup:<id> fingerprint (from the listing or JSON)
  fallow dupes --trace dup:7f3a2c1e

  # Performance breakdown
  fallow dupes --performance
  ```
</CodeGroup>

## Example output

```bash title="$ fallow dupes --top 3" theme={null}
● Duplicates (3 clone groups)

  5,433 lines  2 instances
    deno/lib/types.ts:45-5477
    src/types.ts:45-5477

    914 lines  2 instances
    deno/lib/__tests__/string.test.ts:8-921
    src/__tests__/string.test.ts:7-920

     42 lines  3 instances
    src/features/forecasting/server/procedures/analytics.ts:141-181
    src/features/forecasting/server/procedures/cashflow.ts:153-194
    src/features/forecasting/server/procedures/income.ts:590-631

  Identical code blocks detected via suffix-array analysis, https://docs.fallow.tools/explanations/duplication#clone-groups

✓ 27,255 lines (19.4%) duplicated across 398 files (0.23s)
```

```bash title="$ fallow dupes --threshold 15" theme={null}
● Duplicates (3 clone groups)
  ...

✗ 27,255 lines (19.4%) duplicated across 398 files (0.23s)
Duplication (19.4%) exceeds threshold (15%)
```

## JSON output

### `mirrored_directories`

When fallow detects directory pairs that are largely duplicated (e.g., a `deno/` mirror of `src/`), the JSON output includes a `mirrored_directories` array:

```json theme={null}
{
  "mirrored_directories": [
    {
      "dir_a": "deno/lib",
      "dir_b": "src",
      "shared_files": ["client.ts", "handlers.ts", "types.ts", "utils.ts"],
      "total_lines": 6347
    }
  ]
}
```

Each entry identifies two directories with significant overlap, the shared filenames, and the total duplicated lines across those files.

## See also

<CardGroup>
  <Card title="Duplication analysis" icon="clone" href="/analysis/duplication">
    How fallow's detection engine works.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Set default modes and thresholds in your config.
  </Card>

  <Card title="Migrating from jscpd" icon="right-left" href="/migration/from-jscpd">
    Coming from jscpd? See the migration guide.
  </Card>
</CardGroup>


# fallow explain
Source: https://docs.fallow.tools/cli/explain

CLI reference for fallow explain. Print rule rationale, examples, fix guidance, and docs links for one issue type without running analysis.

Explain one issue type without running analysis. This is useful for agents and CI bots that need a compact rule guide before deciding whether to fix, suppress, or configure a finding.

```bash theme={null}
fallow explain unused-export
fallow explain fallow/code-duplication --format json --quiet
```

## Arguments

| Argument       | Description                                                                                                                                                                                  |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<issue-type>` | Issue type token or rule id, for example `unused-export`, `fallow/unused-dependency`, `high-complexity`, or `code-duplication`. Common plural aliases such as `unused-exports` are accepted. |

## Output

| Format  | Description                                                         |
| :------ | :------------------------------------------------------------------ |
| `human` | Rule id, summary, rationale, example, fix guidance, and docs URL.   |
| `json`  | Machine-readable object with the same fields. Use this from agents. |

```json title="$ fallow explain unused-export --format json --quiet" theme={null}
{
  "id": "fallow/unused-export",
  "name": "Unused Exports",
  "summary": "Export is never imported",
  "rationale": "Named exports that are never imported by any other module in the project. Includes both direct exports and re-exports through barrel files. The export may still be used locally within the same file.",
  "example": "export const formatPrice = ... exists in src/money.ts, but no module imports formatPrice.",
  "how_to_fix": "Remove the export or make it file-local. If it is public API, import it from an entry point or add an intentional suppression with context.",
  "docs": "https://docs.fallow.tools/explanations/dead-code#unused-exports"
}
```

## MCP tool

The `fallow_explain` MCP tool wraps `fallow explain <issue-type> --format json --quiet`:

```json title="Example request" theme={null}
{
  "tool": "fallow_explain",
  "arguments": {
    "issue_type": "unused-export"
  }
}
```

Use it when an agent needs rule-specific context before applying a fix or suppression.


# fallow fix
Source: https://docs.fallow.tools/cli/fix

CLI reference for fallow fix. Automatically remove unused exports and dependencies from source files with dry-run preview and JSON output.

Automatically remove unused exports and dependencies from your codebase. Fallow modifies your source files in place, so treat this like a refactoring tool.

<Warning>
  Always commit your changes before running `fallow fix`. This gives you a clean rollback point if anything unexpected happens.
</Warning>

```bash theme={null}
fallow fix
```

## Options

| Flag                    | Description                                                                                                |
| :---------------------- | :--------------------------------------------------------------------------------------------------------- |
| `--dry-run`             | Preview changes without applying                                                                           |
| `--yes, --force`        | Skip confirmation (required in non-TTY)                                                                    |
| `--no-create-config`    | Refuse to create a new `.fallowrc.json` when none exists. See [Missing config file](#missing-config-file). |
| `-f, --format <FORMAT>` | Output format: `human` (default), `json`                                                                   |

## What gets fixed

* **Unused exports**: the `export` keyword is removed, keeping the declaration. For exported enums where the enum itself is never referenced outside its body in the file, the entire `enum` block is deleted.
* **Unused dependencies**: removed from `package.json` when they are not imported by another workspace
* **Unused enum members**: removed from the enum declaration. When every member of an exported enum is unused, the whole declaration is deleted in one pass instead of leaving behind an empty `export enum X {}` shell. Importers in other files then reference a name that no longer exists, so run your TypeScript build to find and clean them up.
* **Unused pnpm catalog entries**: removed from `pnpm-workspace.yaml`. See [Catalog entries](#catalog-entries).
* **Duplicate exports**: an `ignoreExports` rule is appended to your fallow config file. Common in shadcn / Radix / bits-ui namespace-barrel codebases where dozens of `components/<name>/index.ts` files intentionally re-export the same short names. When no fallow config file exists, one is created; see [Missing config file](#missing-config-file).

Unused files and class members are not auto-fixed. Use `fallow dead-code` to find those.

## Catalog entries

Catalog entries are removed from `pnpm-workspace.yaml` by line-aware deletion. Object-form entries such as `react:\n  specifier: ^18.2.0` are removed as one block. When the last entry of a catalog group is removed, the header is rewritten to `catalog: {}` (or `<name>: {}`) so the file stays installable; bare `catalog:` with no value parses as null and pnpm errors at install time. Other comments and stylistic choices in the file are preserved. After a successful catalog edit fallow reminds you to run `pnpm install` so `pnpm-lock.yaml` stays in sync.

By default, fallow also removes a contiguous YAML comment block immediately above the entry when it clearly belongs to that entry; configure this with [`fix.catalog.deletePrecedingComments`](/configuration/overview) (`"auto"`, `"always"`, or `"never"`). Two escape hatches keep curated comments safe regardless of policy: a `# fallow-keep` marker on any line in the block preserves it (mirrors the inline-suppression convention), and the `auto` policy additionally preserves section-banner blocks whose comment body starts with three or more `=`, `-`, `*`, `_`, `~`, `+`, or `#` characters (e.g. `# === React 18 production pins ===`). The human-mode summary appends `(+M catalog comment lines)` to the fixed-issue count when at least one comment line was absorbed.

Entries whose `hardcoded_consumers` is non-empty (a workspace package still pins a hardcoded version of the same package) are skipped to avoid breaking the next `pnpm install`; the skip is surfaced on stderr and in the JSON output (`{"type": "remove_catalog_entry", "applied": false, "skipped": true, "skip_reason": "hardcoded_consumers", "consumers": [...]}`). The JSON action carries both `line` (first deleted line, the leading comment when policy absorbs one) and `entry_line` (the catalog entry's original 1-based line) so CI annotators can pick whichever anchor they need. The JSON envelope carries a top-level `"skipped"` count alongside `"total_fixed"` for partial-fix gating in CI.

## Missing config file

When `fallow fix` finds duplicate-export issues and no fallow config exists, it creates `.fallowrc.json` automatically, scaffolded the same way as `fallow init` (framework and test-runner detection, `$schema`, `entry`, `ignorePatterns`) with the `ignoreExports` rules layered on top, so the post-fix `fallow dead-code` does not start surfacing new findings. The created file is reported on stderr:

```text theme={null}
Created .fallowrc.json with 2 ignoreExports rule(s). Add it to git.
```

In monorepo subpackages (one of `pnpm-workspace.yaml`, `package.json#workspaces`, `turbo.json`, `lerna.json`, `rush.json` above the invocation directory), the create-fallback refuses to avoid fragmenting one config file across N sub-packages. Instead it emits a directive pointing at the workspace root:

```text theme={null}
Skipped duplicate-export config fix: no fallow config file at packages/ui and the
directory is inside a monorepo (workspace root: /repo). Run `fallow init` at the
workspace root, or invoke `fallow fix` from /repo instead of from a subpackage.
```

For pre-commit hooks, CI bots, and `fallow watch` where silently materialising a new top-level file would surprise the user, pass `--no-create-config`:

```bash theme={null}
# Pre-commit hook
fallow fix --yes --no-create-config

# CI: never create configs as a side effect
fallow fix --yes --no-create-config --format json
```

The duplicate-export config-add path is skipped with an explanatory message; source-file edits (unused exports, dependencies, enum members, catalog entries) proceed normally.

## On-disk drift protection

If a parallel editor save, CI rebase, or other tool changes a source file between analysis and the write, `fallow fix` skips that file instead of applying stale line offsets. The skip is reported on stderr (`Skipping <path>: file content changed since fallow dead-code ran. Re-run fallow fix to refresh the analysis first.`) and in the JSON output (`{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "content_changed"}`). A run with any content-changed skip exits with code 2 so CI does not treat the partial run as a clean no-op. The JSON envelope's top-level `skipped_content_changed: number` (always present) carries the count separately from `skipped` (which tallies catalog / YAML guard skips only).

Each per-file rewrite is staged into a sibling temp file, and every stage is promoted to its final path only after all stages succeed. A stage failure (read-only directory, full disk) leaves every target file at its original content. A rename failure mid-batch (rare; the per-file rename is atomic but POSIX has no atomic multi-rename primitive) reports per-path, so a re-run is safe. `package.json` and `pnpm-workspace.yaml` are re-read at fix time instead, so a dependency or catalog entry that has already disappeared is a no-op.

## Low-confidence export removals

Removing an `export` keyword is only safe when fallow can see every consumer of that symbol. Some consumers are invisible to static analysis: Vitest mock aliases (`test.alias` pointing at a `__mocks__` file), off-workspace end-to-end suites that import shared helpers, and fixture or golden harnesses wired up by a build step. Stripping an export that one of these actually uses turns an analysis false positive into a `tsc` error and a broken build.

`fallow fix` therefore withholds export removals in two low-confidence cases:

* **Off-graph consumer directories.** The file sits under any of `__mocks__`, `__fixtures__`, `fixtures`, `e2e`, `e2e-tests`, `cypress`, `playwright`, `examples`, `evals`, or `golden` (matched on any path segment). Plain test directories (`test`, `tests`, `__tests__`) are intentionally not on the list, because genuinely-dead test helpers are common and should still auto-remove.
* **Files with an unresolved import.** The file itself imports something fallow could not resolve, so its local usage graph is incomplete and the "this export is unused" conclusion is lower confidence.

In both cases the per-file entry is emitted as `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "low_confidence_off_graph"}` (or `"low_confidence_unresolved_imports"`), and the JSON envelope's top-level `skipped_low_confidence_exports: number` (always present) carries the combined count, disjoint from `skipped`. Unlike the drift and encoding skips, this is an intentional, conservative decision rather than a recoverable failure: it does **not** change the exit code. The export is still reported by `fallow dead-code`, so you can confirm it is truly unused and remove it by hand. High-confidence exports in normal source files are removed.

## Incomplete source evidence

Findings with nonempty `reachability_caveats` remain reported, but their removals are not applied automatically. This includes missing references caused by parse errors, unreadable files, and skipped source files. `workspace_diagnostics` identifies the source of the incomplete evidence. Type-aware approval of a class method does not override this guard.

The fix entry has `skipped: true` and `skip_reason: "low_confidence_incomplete_analysis"`. The JSON envelope reports separate counters for `skipped_low_confidence_exports`, `skipped_low_confidence_dependencies`, and `skipped_low_confidence_members`. They are distinct from the general `skipped` counter. These evidence-based skips do not change the exit code; inspect them even when the command succeeds.

## File encoding contract

`fallow fix` is UTF-8 only. Two encoding shapes are handled explicitly:

* **UTF-8 BOM round-trip.** Files with a leading UTF-8 byte-order mark (`EF BB BF`, common on Windows-authored TypeScript when Notepad / older VS settings or some IDE plugins are involved) are read with the BOM stripped before line-offset computation and parsing, so reported line numbers do not shift by the BOM codepoint, and the BOM is re-prepended on write so the file's encoding is preserved on round-trip. fallow neither adds nor removes a BOM; if your input has one, the output has one.

* **Mixed CRLF / LF rejection.** Files containing both `\r\n` and bare-LF line endings (common after cross-platform edits without `core.autocrlf`) are skipped instead of silently rewritten to the wrong offsets. The stderr message names the remediation:

  ```text theme={null}
  Skipping src/mixed.ts: file has mixed CRLF/LF line endings.
  Normalize with `dos2unix` or set `git config core.autocrlf input`, then re-run `fallow fix`.
  ```

  The JSON envelope carries a per-file entry (`{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "mixed_line_endings"}`) and a top-level counter `skipped_mixed_line_endings: number` (always present) disjoint from `skipped_content_changed`. Any non-zero mixed-EOL count exits the run with code 2. **The skip is not self-healing**: re-running `fallow fix` against the same file produces the same skip; you (or your CI / AI agent) must normalize the file's line endings before fallow can act on it. When the same file carries findings for multiple fixers (an unused export AND an unused enum member), the skip is reported once per file, not once per fixer.

## Dry-run config diff

`fallow fix --dry-run` against duplicate-export findings prints the proposed config write as a unified diff so you can audit the exact bytes that would land before passing `--yes`. For the create-fallback case the diff shows the full proposed file (BEFORE is empty):

```diff theme={null}
Would create .fallowrc.json with 2 ignoreExports rule(s):
--- .fallowrc.json (does not exist)
+++ .fallowrc.json (proposed)
@@ -0,0 +1,35 @@
+{
+  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
+  "entry": ["src/index.{ts,tsx,js,jsx}", "src/main.{ts,tsx,js,jsx}"],
+  "ignorePatterns": [".storybook/**"],
+  ...
+  "ignoreExports": [
+    { "file": "src/components/Button/index.ts", "exports": ["*"] },
+    { "file": "src/components/Card/index.ts", "exports": ["*"] }
+  ]
+}
```

For the edit case (existing config), the diff shows context lines around the proposed additions. JSON output (`--dry-run --format json`) includes the same diff under a `proposed_diff` field on the fix entry, plus a `created_files: [".fallowrc.json"]` array on the create-fallback path so agents can detect file-creation side effects programmatically.

## Examples

<CodeGroup>
  ```bash Preview changes theme={null}
  # See what would be removed
  fallow fix --dry-run

  # JSON output for scripting
  fallow fix --dry-run --format json
  ```

  ```bash Apply fixes theme={null}
  # Interactive confirmation
  fallow fix

  # Skip confirmation (CI)
  fallow fix --yes
  ```
</CodeGroup>

## Example output

```bash title="$ fallow fix" theme={null}
Would remove export from src/components/Card/index.ts:1 `CardFooter`
Would remove export from src/providers/trpc-provider/index.tsx:12 `TRPCProvider`
Would remove export from src/server/jobs/queue.ts:61 `enqueueJobDelayed`
Would remove export from src/server/jobs/queue.ts:206 `sweepStuckProcessingJobs`
Would remove export from src/server/jobs/queue.ts:276 `getDeadLetterJobs`
Would remove `@trpc/react-query` from dependencies

6 changes to apply. Proceed? [y/N] y

✓ Applied 6 fixes (5 exports, 1 dependency)
```

## See also

<CardGroup>
  <Card title="Auto-fix" icon="wand-magic-sparkles" href="/analysis/auto-fix">
    Details on what fallow can and cannot auto-fix.
  </Card>

  <Card title="Dead code analysis" icon="skull-crossbones" href="/analysis/dead-code">
    Understand the full range of dead code fallow detects.
  </Card>
</CardGroup>


# fallow flags
Source: https://docs.fallow.tools/cli/flags

CLI reference for fallow flags. Detect feature flag patterns, environment variable gates, SDK calls, and config-based toggles across your codebase.

Detect feature flag patterns in your codebase. Reports flag locations, detection confidence, and cross-references with dead code findings.

```bash theme={null}
fallow flags
```

## Options

### Output

| Flag                    | Description                                                                                                                                                                               |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--top <N>`             | Show only the top N flags                                                                                                                                                                 |
| `-f, --format <FORMAT>` | Output format: `human` (default), `json`, `sarif`, `compact`, `markdown`, `codeclimate`, `gitlab-codequality`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab` |
| `-q, --quiet`           | Suppress progress output                                                                                                                                                                  |
| `--explain`             | Add metric explanations. In JSON format, adds a `_meta` object with descriptions and docs links.                                                                                          |
| `--summary`             | Print a one-line summary of flag counts at the end of the run. In JSON format, adds a `summary` counts object.                                                                            |

### Scoping

| Flag                     | Description                                                                                                 |
| :----------------------- | :---------------------------------------------------------------------------------------------------------- |
| `-r, --root <PATH>`      | Project root directory (default: current working directory)                                                 |
| `-c, --config <PATH>`    | Path to config file (default: auto-detected)                                                                |
| `-w, --workspace <NAME>` | Scope output to a single workspace package                                                                  |
| `--changed-since <REF>`  | Only report flags in files changed since a git ref                                                          |
| `--production`           | Production mode: exclude test/story/dev files                                                               |
| `--no-production`        | Force production mode off, overriding a project config's `production: true` (conflicts with `--production`) |

### Performance

| Flag            | Description                                               |
| :-------------- | :-------------------------------------------------------- |
| `--no-cache`    | Disable incremental caching (force full re-parse)         |
| `--threads <N>` | Number of parser threads (default: available parallelism) |
| `--performance` | Show pipeline timing breakdown                            |

### CI

| Flag                  | Description                                                                                                                                                                                                          |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ci`                | CI mode: equivalent to `--format sarif --fail-on-issues --quiet`                                                                                                                                                     |
| `--fail-on-issues`    | Exit with code 1 if flags are found                                                                                                                                                                                  |
| `--sarif-file <PATH>` | Write SARIF output to a file (in addition to `--format`)                                                                                                                                                             |
| `--group-by <MODE>`   | Group output by `owner` (CODEOWNERS), `directory` (first path component), `package` (workspace package), or `section` (GitLab CODEOWNERS `[Section]` headers). See [global flags](/cli/global-flags#grouped-output). |

### Regression

| Flag                                | Description                                                                    |
| :---------------------------------- | :----------------------------------------------------------------------------- |
| `--baseline <PATH>`                 | Compare against a previously saved baseline file                               |
| `--save-baseline <PATH>`            | Save current results as a baseline file                                        |
| `--fail-on-regression`              | Fail if flag count increased beyond tolerance vs a regression baseline         |
| `--tolerance <N>`                   | Allowed increase: `"2%"` (percentage) or `"5"` (absolute). Default: `"0"`      |
| `--regression-baseline <PATH>`      | Path to regression baseline file (default: `.fallow/regression-baseline.json`) |
| `--save-regression-baseline <PATH>` | Save current flag counts as a regression baseline                              |

## Detection categories

Fallow detects three categories of feature flag patterns:

| Category                       | What it finds                                                                                                                                                         | Examples                                                                                                           |
| :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| **Environment variable flags** | `process.env.*` checks used as feature gates                                                                                                                          | `process.env.FEATURE_NEW_UI`, `process.env.ENABLE_DARK_MODE`                                                       |
| **SDK calls**                  | Feature flag SDK method calls from known providers (LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog, Vercel Flags, ConfigCat, Flagsmith, Optimizely, Eppo) | LaunchDarkly `variation()`, Statsig `checkGate()`, PostHog `useFeatureFlagEnabled()`, Vercel Flags `flag({ key })` |
| **Config object patterns**     | Object property lookups used as boolean guards (opt-in)                                                                                                               | `config.featureX`, `settings.enableNewFlow`                                                                        |

Each detected flag includes a confidence level indicating how certain fallow is that the pattern represents a feature flag.

## Configuration

Fallow ships with built-in detectors for the common providers and env-var conventions, so most projects need no configuration. If `fallow flags` reports `No feature flags detected` but your project does use flags, you are likely on an SDK or env prefix fallow does not recognize by default. Extend detection with the `flags` section in `.fallowrc.json`, `.fallowrc.jsonc`, `fallow.toml`, or `.fallow.toml`.

When you run `fallow flags` on full defaults and nothing is found, the CLI lists the built-in env prefixes and SDKs it scanned for, so you can tell a true negative from a missing detector.

The `flags` fields (`sdkPatterns`, `envPrefixes`, `configObjectHeuristics`) are documented in the [configuration reference](/configuration/overview#flags). Custom `sdkPatterns` and `envPrefixes` are merged with the built-in sets, never replace them.

```json In-house SDK, extra env prefixes, and config heuristics theme={null}
{
  "flags": {
    "sdkPatterns": [
      { "function": "useMyFlag", "nameArg": 0, "provider": "InHouse" }
    ],
    "envPrefixes": ["NEXT_PUBLIC_FEATURE_", "MYAPP_ENABLE_"],
    "configObjectHeuristics": true
  }
}
```

## Examples

<CodeGroup>
  ```bash Basic analysis theme={null}
  # Detect all feature flags
  fallow flags

  # Show only the top 10 flags
  fallow flags --top 10
  ```

  ```bash CI integration theme={null}
  # JSON output for pipelines
  fallow flags --format json --quiet

  # SARIF for GitHub Code Scanning
  fallow flags --format sarif > flags.sarif

  # Compact format (one line per flag)
  fallow flags --format compact

  # Markdown for PR comments
  fallow flags --format markdown | gh pr comment --body-file -

  # CodeClimate for GitLab CI
  fallow flags --format codeclimate > gl-code-quality-report.json
  ```

  ```bash Scoping theme={null}
  # Only flags in changed files
  fallow flags --changed-since main

  # Scope to a workspace package
  fallow flags --workspace @app/core

  # Production code only
  fallow flags --production
  ```
</CodeGroup>

## JSON output

```json title="$ fallow flags --format json" theme={null}
{
  "schema_version": 8,
  "version": "3.24.1",
  "elapsed_ms": 116,
  "feature_flags": [],
  "total_flags": 0
}
```

### Key fields

| Field            | Type    | Description                             |
| :--------------- | :------ | :-------------------------------------- |
| `schema_version` | integer | JSON schema version                     |
| `version`        | string  | Fallow version that produced the output |
| `elapsed_ms`     | integer | Analysis duration in milliseconds       |
| `feature_flags`  | array   | Detected feature flag patterns          |
| `total_flags`    | integer | Total number of detected flags          |

## MCP tool

The `feature_flags` MCP tool wraps `fallow flags --format json --quiet --explain`:

```json title="Example request" theme={null}
{
  "tool": "feature_flags",
  "arguments": {
    "top": 10
  }
}
```

Returns the same JSON envelope as the CLI.

See [MCP integration](/integrations/mcp) for setup instructions.

## See also

<CardGroup>
  <Card title="Dead code analysis" icon="skull-crossbones" href="/cli/dead-code">
    Cross-references feature flags with dead code findings.
  </Card>

  <Card title="Global flags" icon="sliders" href="/cli/global-flags">
    Flags available on every fallow command.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use fallow tools from AI coding agents.
  </Card>
</CardGroup>


# Global flags
Source: https://docs.fallow.tools/cli/global-flags

Global CLI flags available on every fallow command, including root, config, format, cache, threads, workspace, changed-workspaces, score, trend, and snapshot options.

These flags are shared across fallow commands. Some commands reject flags that are not meaningful for that surface.

## Reference

The `--dupes-*` flags apply to combined mode, fall back to the config value when unset, and mirror the standalone [`fallow dupes`](/cli/dupes) flag of the same name.

| Flag                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-r, --root <PATH>`                       | Project root directory (default: current working directory)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `-c, --config <PATH>`                     | Path to config file (default: auto-detected)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `-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`. Alias: `--output`. `--format json` is compact by default; add `--pretty` for indented output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--pretty`                                | Indent `--format json` output for manual inspection. JSON is compact by default so machine and agent consumers get the same schema with less output; this flag restores human-readable indentation. Applies only to JSON output. SARIF, Code Climate, baselines, snapshots, caches, and other persisted JSON keep their existing presentation regardless of this flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `-q, --quiet`                             | Suppress progress bars and status messages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--no-cache`                              | Disable incremental caching (force full re-parse)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--threads <N>`                           | Number of parser threads (default: available parallelism)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--max-file-size <MB>`                    | Skip source files larger than this many megabytes at discovery instead of parsing them (default `5`; `0` disables the guard). Guards against the out-of-memory blowup a single multi-megabyte generated, vendored, or bundled file causes on large repositories, and also skips large one-line minified JS assets while the guard is enabled. Declaration files (`.d.ts`) are always analyzed regardless of size. Skipped files are reported on stderr and in `--format json` under `workspace_diagnostics` (`kind: "skipped-large-file"` or `"skipped-minified-file"`). Also settable via `FALLOW_MAX_FILE_SIZE`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--changed-since <REF>` (alias: `--base`) | Only report issues in files changed since this git ref                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--diff-file <PATH>`                      | Path to a unified diff (e.g. `git diff --unified=0 main...HEAD`) used to narrow source-anchored findings to lines inside an added hunk. Point findings (unused-export, unresolved-import, boundary-violation, etc.) drop when their source line is not in the diff; range findings (complexity hotspots, clone families) drop when their `[start_line, end_line]` does not overlap the diff. Project-level findings (unused deps, catalog entries, dependency overrides) bypass the analysis filter because they anchor at fixed `package.json` / `pnpm-workspace.yaml` lines a PR rarely touches even when it semantically caused them. Sticky PR/MR summaries can set `FALLOW_SUMMARY_SCOPE=diff` to filter those project-level findings too. Also drives line-level scoping of the runtime-coverage `hot-path-touched` verdict. Pass `-` as the path or use `--diff-stdin` to read the diff from stdin (`gh pr diff \| fallow audit --diff-file -`). When combined with `--changed-since`, the diff filter wins for line-level filtering and `--changed-since` still scopes file discovery; a one-line stderr note records the precedence. Falls back to the `FALLOW_DIFF_FILE` env var when omitted. |
| `--diff-stdin`                            | Read the unified diff from stdin instead of a file. Equivalent to `--diff-file -`. Mutually exclusive with a non-stdin `--diff-file PATH` value. Useful for piping `gh pr diff` or `git diff` directly into fallow.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--churn-file <PATH>`                     | Import change history from a `fallow-churn/v1` JSON file instead of `git log`, for projects with no git repository. Affects the churn-backed health signals only. See [`fallow health` › Importing churn from a non-git VCS](/cli/health#importing-churn-from-a-non-git-vcs).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--baseline <PATH>`                       | Compare against a previously saved baseline file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--save-baseline <PATH>`                  | Save the current results as a baseline file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--fail-on-regression`                    | Fail if issue count increased beyond tolerance vs a regression baseline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--tolerance <N>`                         | Allowed increase: `"2%"` (percentage) or `"5"` (absolute). Default: `"0"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--regression-baseline <PATH>`            | Path to regression baseline file (default: `.fallow/regression-baseline.json`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--save-regression-baseline <PATH>`       | Save current issue counts as a regression baseline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--production`                            | Production mode: exclude test/story/dev files, only start/build scripts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--no-production`                         | Force production mode off for every analysis, overriding a project config's `production: true`. Conflicts with `--production`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--production-dead-code`                  | Per-analysis production mode for dead-code in bare combined runs and `fallow audit`. See [Per-analysis production mode](#per-analysis-production-mode).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--production-health`                     | Per-analysis production mode for health in bare combined runs and `fallow audit`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--production-dupes`                      | Per-analysis production mode for duplication in bare combined runs and `fallow audit`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `-w, --workspace <PATTERNS>`              | Scope output to one or more workspaces. Accepts exact names, globs matched against both the package name AND the workspace path (`apps/*`, `@scope/*`), and `!`-prefixed negations (`!apps/legacy`). Values can be comma-separated (`-w web,admin`) or the flag can be repeated. Quote patterns containing `!` or glob chars to avoid shell expansion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--changed-workspaces <REF>`              | Git-derived monorepo CI scoping: scope output to workspaces containing any file changed since `REF` (e.g. `origin/main`, `HEAD~1`). Auto-derives the workspace set from `git diff` so CI jobs don't hand-maintain a `--workspace` list. Mutually exclusive with `--workspace`. A missing ref or non-git directory is a hard error (exit 2), not a silent full-scope fallback. Root-only diffs map to 0 workspaces and exit 0 with no issues.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--performance`                           | Show pipeline timing breakdown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--explain`                               | In human format, prints a `Description:` line under each section header. In JSON format, includes metric definitions in the output `_meta` object. Always enabled for MCP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--ci`                                    | CI mode: equivalent to `--format sarif --fail-on-issues --quiet`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--fail-on-issues`                        | Exit with code 1 if issues are found                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--sarif-file <PATH>`                     | Write SARIF output to a file (in addition to the primary `--format` output)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `-o, --output-file <PATH>`                | Write the report to a file instead of stdout, for any `--format` (no ANSI codes). Useful on large projects where the terminal scrollback truncates the top. Progress and a `Report written to <path>` confirmation stay on stderr (suppressed by `--quiet`). Valid with `dead-code`, `dupes`, `health`, `security`, and bare invocation; composes with `--sarif-file`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--report-path-prefix <PREFIX>`           | Override the repository-root offset prepended to every path in the CI-facing formats; an empty string disables rebasing. See [Repository-root paths in CI formats](#repository-root-paths-in-ci-formats).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--group-by <MODE>`                       | Group output by CODEOWNERS ownership (`owner`), first directory component (`directory`), workspace package (`package`), or GitLab CODEOWNERS section (`section`). When active, all output formats partition issues into labeled groups.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--summary`                               | Print a one-line summary of issue counts at the end of the run. In JSON format, adds a `summary` counts object to the output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--only <check,dupes,health>`             | Run only specific analyses when no subcommand is given                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--skip <check,dupes,health>`             | Skip specific analyses when no subcommand is given                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--coverage <PATH>`                       | Feed Istanbul coverage data to the embedded health analysis in combined mode. Same fallback chain as [`fallow health --coverage`](/cli/health#options).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--coverage-root <PATH>`                  | Absolute prefix to strip from Istanbul coverage paths in combined mode. See [`fallow health --coverage-root`](/cli/health#options).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--dupes-mode <MODE>`                     | Override duplicate detection mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--dupes-near`                            | Include function-scoped near-miss clones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--dupes-threshold <PCT>`                 | Override the duplication percentage failure threshold.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--dupes-min-tokens <N>`                  | Override the minimum token count for clone detection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--dupes-min-lines <N>`                   | Override the minimum line count for clone detection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--dupes-min-occurrences <N>`             | Override the minimum clone occurrences (must be `>= 2`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--dupes-skip-local`                      | Only report cross-directory duplicates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--dupes-cross-language`                  | Enable TypeScript to JavaScript duplicate matching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--dupes-ignore-imports`                  | Exclude module wiring from duplicate detection (default).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--dupes-no-ignore-imports`               | Count module wiring as clone candidates. Conflicts with `--dupes-ignore-imports`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--score`                                 | Compute health score (0-100 with letter grade) in combined mode. Enables the health delta header in PR comments. Also available on [`fallow health`](/cli/health).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--trend`                                 | Compare current health metrics against the most recent saved snapshot. Implies `--score`. Also available on [`fallow health`](/cli/health).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--save-snapshot [PATH]`                  | Save a vital signs snapshot for trend tracking. Default path: `.fallow/snapshots/<timestamp>.json`. Forces file-scores and hotspot computation. Also available on [`fallow health`](/cli/health).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--include-entry-exports`                 | Report unused exports in entry files instead of auto-marking them as used. Catches typos in framework exports (e.g. `meatdata` instead of `metadata`). Also configurable via `includeEntryExports: true` in your fallow config; the CLI flag wins when set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Repository-root paths in CI formats

CI platforms resolve file paths against the repository root: GitHub annotations, CodeClimate reports in GitLab, and inline review comments all reject or misplace paths relative to anything else. When `--root` points at a subdirectory of a git repository (a monorepo package like `packages/app/`), the CI-facing formats (`github-annotations`, `github-summary`, `codeclimate`, `review-github`, `review-gitlab`) therefore emit repository-root-relative paths: fallow detects the offset between `--root` and the git toplevel and prepends it automatically. `--report-path-prefix` overrides the detected offset for containerized or vendored checkouts where the git toplevel does not match the CI workspace; an empty string (`--report-path-prefix ''`) disables rebasing entirely and restores `--root`-relative paths.

Supplied diffs (`--diff-file`, `--diff-stdin`, `FALLOW_DIFF_FILE`) get the same treatment in reverse: fallow detects whether the diff's paths are repository-root-relative or `--root`-relative and filters findings accordingly. A diff that parses but touches no analyzable files (deletion-only, binary-only, or empty) filters the report to zero findings; only a diff whose paths cannot be placed at all falls back to the full-scope report, with a warning saying so.

## Loaded config disclosure

When fallow loads a config file (either auto-discovered or via `--config`), it prints a single line to **stderr**:

```text theme={null}
loaded config: /repo/.fallowrc.json
```

This shows which `.fallowrc.json` is in effect in monorepos where multiple configs exist. The line is suppressed when:

* `--quiet` is set
* `--format` is anything other than `human` (`json`, `sarif`, `compact`, `markdown`, `codeclimate`, `gitlab-codequality`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab`, `badge`)

For deeper inspection (the resolved config with `extends` merged), use the dedicated [`fallow config`](/cli/config) subcommand.

## Examples

```bash theme={null}
# Analyze a project in a different directory
fallow dead-code -r /path/to/project

# Use a specific config file
fallow dead-code -c configs/fallow-strict.json

# JSON output with no progress messages
fallow dead-code -f json --quiet

# Limit parallelism to 4 threads
fallow dead-code --threads 4

# Scope to a single workspace package
fallow dead-code -w @myorg/ui

# Scope to whichever workspaces changed since origin/main (CI primitive)
fallow --changed-workspaces origin/main

# Show timing breakdown
fallow dead-code --performance

# Group issues by CODEOWNERS ownership (see Grouped output below)
fallow dead-code --group-by owner

# Health score in combined mode
fallow --score

# Save a snapshot and track trends
fallow --save-snapshot
fallow --trend
```

## Per-analysis production mode

Bare combined runs (`fallow` with no subcommand) and `fallow audit` accept three per-analysis production flags so you can enable production mode for one analysis without forcing it on the others:

```bash theme={null}
# Treat health as production-only, leave dead-code and dupes in full-tree mode
fallow --production-health

# Audit changed files with production-only health
fallow audit --base main --production-health
```

The matching environment variables `FALLOW_PRODUCTION_DEAD_CODE`, `FALLOW_PRODUCTION_HEALTH`, and `FALLOW_PRODUCTION_DUPES` accept the same set of values as `FALLOW_PRODUCTION` (`true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off`). The `production` config field also accepts a per-analysis object:

```jsonc theme={null}
{
  "production": {
    "deadCode": false,
    "health": true,
    "dupes": false
  }
}
```

**Precedence (highest to lowest)**: CLI flags (`--production`, `--production-{dead-code,health,dupes}`), per-analysis env var (`FALLOW_PRODUCTION_HEALTH`, etc.), global env var (`FALLOW_PRODUCTION`), config (`production: { ... }` or `production: true`). The legacy boolean form (`--production`, `production: true`, `FALLOW_PRODUCTION=true`) is unchanged and still applies to every analysis.

The per-analysis CLI flags are rejected when used with a subcommand other than `audit` (e.g. `fallow dead-code --production-health` errors). Use the bare command or the per-analysis env vars in that case.

## Grouped output

The `--group-by` flag partitions all issues into labeled groups. This works with every output format and every subcommand.

| Mode        | Grouping                                                                                                                                                                                                                                      | Requires                                                            |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ |
| `owner`     | CODEOWNERS file ownership. Auto-probes `CODEOWNERS`, `.github/CODEOWNERS`, `.gitlab/CODEOWNERS`, `docs/CODEOWNERS`. First owner on multi-owner lines wins.                                                                                    | A CODEOWNERS file (or set `codeowners` in config)                   |
| `directory` | First path component (e.g. `src/utils/foo.ts` groups under `src`)                                                                                                                                                                             | Nothing                                                             |
| `package`   | Workspace package name (e.g. `@myorg/ui`). Issues are grouped by the package they belong to.                                                                                                                                                  | A monorepo with workspace packages                                  |
| `section`   | GitLab CODEOWNERS `[Section]` header name. Distinct sections stay in distinct groups even when they share a default reviewer, so teams with one shared lead reviewer across many sections get per-section triage instead of one giant bucket. | A GitLab-style CODEOWNERS file with at least one `[Section]` header |

With `--format json`, the output shape changes to a grouped envelope:

```json theme={null}
{
  "kind": "dead-code-grouped",
  "grouped_by": "owner",
  "total_issues": 12,
  "groups": [
    { "key": "@frontend-team", "total_issues": 8, "unused_files": [], "unused_exports": [] },
    { "key": "@backend-team", "total_issues": 4, "unused_exports": [] }
  ]
}
```

For `--group-by section`, each group also carries an `owners` array with the section's default owners:

```json theme={null}
{
  "kind": "dead-code-grouped",
  "grouped_by": "section",
  "total_issues": 6,
  "groups": [
    {
      "key": "billing",
      "owners": ["@core-reviewers", "@alice", "@bob"],
      "total_issues": 2,
      "unused_exports": []
    },
    {
      "key": "notifications",
      "owners": ["@core-reviewers", "@alice", "@bob"],
      "total_issues": 1,
      "unused_exports": []
    }
  ]
}
```

Section and owner groups are not interchangeable: `owner` collapses all sections that share a lead reviewer into a single bucket, while `section` preserves the `[Section]` headers as stable group keys across reviewer rotation.

<Tip>
  Set a custom CODEOWNERS path via the `codeowners` field in `.fallowrc.json` if your file isn't in a standard location.
</Tip>

## Incremental caching

Fallow caches parsed file data between runs to skip unchanged files. On the second run, only modified files are re-parsed. The rest are loaded from cache.

**How it works:**

1. Each file is hashed with [xxh3](https://github.com/Cyan4973/xxHash) (extremely fast, non-cryptographic)
2. If the hash matches the cached version, parsing is skipped entirely
3. The module graph is rebuilt from cached + freshly-parsed data

<Tip>
  Use `--performance` to see cache hit rates and per-stage timings. This is helpful for diagnosing slow runs.
</Tip>

```bash theme={null}
fallow dead-code --performance
```

```ansi theme={null}
 Discovery     12ms   (142 files)
 Parsing       48ms   (23 parsed, 119 cached)
 Resolution    15ms
 Analysis       8ms
 Total         83ms
```

Use `--no-cache` to force a full re-parse. This is useful after major refactors or when debugging unexpected results.

```bash theme={null}
fallow dead-code --no-cache
```

Set `cache.dir` in the project config or `FALLOW_CACHE_DIR` in the environment to move the persistent cache out of `.fallow/cache.bin`. The env var wins when both are present.

```bash theme={null}
FALLOW_CACHE_DIR=/tmp/fallow-cache fallow dead-code
```

## See also

<CardGroup>
  <Card title="Environment variables" icon="terminal" href="/configuration/environment">
    Set defaults for format and quiet mode via environment variables.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Full config file reference for project-level settings.
  </Card>
</CardGroup>


# fallow guard
Source: https://docs.fallow.tools/cli/guard

CLI reference for fallow guard. Report the architecture rules that apply to a file before you edit it: boundary zone, importable zones, forbidden calls, and rule-pack policies with their suppression tokens.

Report the architecture rules that apply to a set of files, before anything is written. `fallow guard` answers "what am I allowed to do in this file" rather than "what is wrong with this file": it names the file's boundary zone, which zones it may import from, which calls are forbidden there, and every rule-pack policy in scope with the token that suppresses it.

It reads configuration and runs no analysis, so it is fast enough to call on every edit and it works on files that do not exist yet.

```bash theme={null}
fallow guard src/ui/App.ts
fallow guard src/ui/App.ts src/db/query.ts --format json
```

<Info>
  `guard` is the pre-edit question. For violations that already exist in the code, run [`fallow dead-code`](/cli/dead-code) or [`fallow audit`](/cli/audit), which report `boundary-violation` and `policy-violation` findings.
</Info>

## Output

```text theme={null}
src/ui/App.ts (zone: ui)
  note: Same-zone imports are always allowed.
  may import zones: shared, ui (same zone)   type-only: db
  forbidden calls in zone: child_process.*, eval
  policy rules:
    warn  house-rules/no-child-process  banned-call: child_process.*
           suppress: // fallow-ignore-next-line policy-violation:house-rules/no-child-process -- <reason>
  severities: boundary-violation=error  policy-violation=warn
```

## Files that do not exist yet

A path is classified by matching it against the zone patterns, not by reading it, so `guard` answers for a file you are about to create:

```bash theme={null}
fallow guard src/ui/NewScreen.tsx
```

The JSON has `"exists": false` and every rule field populated as usual.

## Paths outside every zone

A path matching no configured zone comes back with `"zone": null` and an empty rule set. That is a normal answer rather than an error, because unzoned files are unrestricted for import rules.

```text theme={null}
src/orphan/thing.ts (zone: none)
  note: Files outside every zone are unrestricted for boundary checks.
  may import zones: none   type-only: none
  forbidden calls in zone: none
  policy rules:
    warn  house-rules/no-moment  banned-import: moment
           suppress: // fallow-ignore-next-line policy-violation:house-rules/no-moment -- <reason>
  severities: boundary-violation=error  policy-violation=warn
```

Being outside every zone silences the import rules, not the policy rules. A rule-pack rule that declares no `zones` applies everywhere, so it still appears here.

When `boundaries.coverage.requireAllFiles` is on and the path is not covered by an `allowUnmatched` glob, the JSON has `"coverage_required": true`: an analysis run will report that file as a `boundary-coverage-violation` for belonging to no zone. The human output does not surface this, and the note it prints covers import rules only, so read `coverage_required` from the JSON on projects that enable coverage.

## Options

| Flag                     | Default           | Description                                                                                |
| :----------------------- | :---------------- | :----------------------------------------------------------------------------------------- |
| `<FILES>...`             | required          | One or more files to report on. Root-relative or absolute; paths are echoed root-relative. |
| `--root <ROOT>`          | current directory | Project root directory.                                                                    |
| `--config <CONFIG>`      | discovered        | Path to the Fallow config file.                                                            |
| `--allow-remote-extends` | off               | Allow trusted config files to extend HTTPS URLs.                                           |
| `--format <FORMAT>`      | `human`           | `human` or `json` only.                                                                    |
| `--pretty`               | off               | Indent JSON output.                                                                        |
| `--quiet`                | off               | Suppress progress output.                                                                  |

`guard` inherits the analysis flags shown in `--help`, but they do not apply: it runs no analysis, so scoping, baseline, and severity-gate flags have no effect. Passing any format other than `human` or `json` exits `2` with `guard supports --format json or human`.

## Exit codes

| Code | Meaning                                                                                               |
| :--- | :---------------------------------------------------------------------------------------------------- |
| `0`  | The rules were reported, including when a path matches no zone or does not exist.                     |
| `2`  | Invalid input or configuration, such as an unsupported `--format` or a rule pack that fails to parse. |

`guard` reports no findings, so it never exits `1`.

## JSON output

```json title="$ fallow guard src/ui/App.ts --format json --pretty" theme={null}
{
  "files": [
    {
      "path": "src/ui/App.ts",
      "exists": true,
      "zone": {
        "name": "ui",
        "patterns": ["src/ui/**"]
      },
      "boundary": {
        "configured": true,
        "unrestricted": false,
        "allowed_zones": ["shared", "ui"],
        "allowed_type_only_zones": ["db"],
        "forbidden_calls": ["child_process.*", "eval"],
        "coverage_required": false
      },
      "policy_rules": [
        {
          "pack": "house-rules",
          "rule_id": "no-child-process",
          "kind": "banned-call",
          "patterns": ["child_process.*"],
          "message": null,
          "severity": "warn",
          "suppress_token": "policy-violation:house-rules/no-child-process"
        }
      ],
      "severities": {
        "boundary_violation": "error",
        "policy_violation": "warn"
      },
      "notes": ["Same-zone imports are always allowed."]
    }
  ],
  "kind": "guard"
}
```

`allowed_zones` always contains the file's own zone, because same-zone imports are never restricted. `unrestricted` is `true` when no import rule constrains the file, either because boundaries are unconfigured or because the path sits outside every zone. `policy_rules` contains only the rules in scope for that file: a rule declaring `zones` appears for files in those zones and nowhere else, and the array is empty when `rules.policy-violation` is `off`.

## Suppression tokens

Every policy rule reports the exact token that silences it, so the comment can be copied straight out of the output:

```ts theme={null}
// fallow-ignore-next-line policy-violation:house-rules/no-moment -- vendored, migrating in Q3
import moment from "moment";
```

The token is `policy-violation:<pack>/<rule-id>`. Rule ids are unique within a pack, so the pair identifies one rule everywhere it appears.

## For agents

Call `guard` on the files you are about to touch, at the point where you still have a choice about what to write. An agent that reads the constraints first can pick an allowed import; one that runs an analysis afterwards can only react to the violation it already committed.

```bash theme={null}
fallow guard --format json --quiet <files>
```

The same contract is exposed as the `guard` MCP tool, described in the [MCP integration guide](/integrations/mcp).


# fallow health
Source: https://docs.fallow.tools/cli/health

CLI reference for fallow health. Analyze function complexity, per-file maintainability, git-churn hotspots, refactoring targets, static coverage gaps, and runtime coverage.

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 `&lt;template&gt;` findings, and a component whose class and template both score emits a `&lt;component&gt;` 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 `&lt;!-- fallow-ignore-file complexity --&gt;` at the top of the template. See [Complexity metrics](/explanations/health#complexity-metrics) for what each shape counts and how to act on it.

```bash theme={null}
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](/explanations/health#crap-score) score before reporting (default: 30.0). Functions meeting or exceeding this score appear alongside complexity findings. Pair with [`--coverage`](#coverage-istanbul) 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`, `maxCrap`, and `maxUnitSize`, 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`](/integrations/badges) |
| `--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.                                                                                                                  |

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:

| 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): specificity hotspots, `!important` density, over-complex selectors, deep nesting, empty rules, design-token sprawl, and cleanup candidates such as unreferenced custom properties, `@keyframes`, `@theme` tokens, and `@font-face` families. Each candidate carries a read-only verification step, because a token can still be used from JavaScript, inline HTML, Tailwind plugins, or external templates. Rule-backed styling issues are emitted separately as `styling_findings`. Opt-in because it reads project stylesheets and cross-checks source files; Sass/Less sources are scanned conservatively. Also derives the descriptive, never-gating `styling_health` grade. See [CSS analysis](/analysis/css-analysis) for the candidate types and the [styling health grade](/analysis/css-analysis#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. 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. Mock-aware; see [With coverage gaps](#with-coverage-gaps). 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; [`fallow audit`](/cli/audit) uses the same chain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--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`; `fallow audit` uses the same chain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--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`).

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

```bash theme={null}
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](/analysis/type-aware).

### 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`. See [Importing churn from a non-git VCS](#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), `anonymized`, legacy `hash`, or `raw`. Implies `--ownership`. See [Email privacy](#email-privacy).                                                                                                                                                                                                                                                                                                                                                            |

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

<Tip>
  `--score`, `--trend`, and `--save-snapshot` also work on bare `fallow` (all analyses combined). See [global flags](/cli/global-flags) for details.
</Tip>

### 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`](/cli/audit).

## 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](/explanations/health#file-health-scores).

Each file score reports these metrics (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](/explanations/health#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 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](/explanations/health#hotspot-metrics).

### 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`  | Whether a shallow clone was detected. Shallow history produces incomplete results; run `git fetch --unshallow` for a full clone. |

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

```bash theme={null}
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`:

```json theme={null}
{
  "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\]`.

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

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

```bash theme={null}
fallow health --hotspots --ownership --churn-file churn.json
```

### The `fallow-churn/v1` contract

```json theme={null}
{
  "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:

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:

```bash theme={null}
# 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.

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

### Snapshot format

```json title="snapshot.json" theme={null}
{
  "snapshot_schema_version": 10,
  "version": "3.24.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 v10)      |
| `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](#vital-signs))   |
| `counts`                  | Raw numerators and denominators behind the percentage metrics |
| `score`                   | Project health score (0-100).                                 |
| `grade`                   | Letter grade (A/B/C/D/F).                                     |

<Tip>
  Store snapshots in CI artifacts or commit them to your repo to build a history of codebase health over time.
</Tip>

## Examples

<CodeGroup>
  ```bash Basic analysis theme={null}
  # Report functions exceeding default thresholds
  fallow health
  ```

  ```bash Top functions theme={null}
  # 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
  ```

  ```bash Health score theme={null}
  # 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
  ```

  ```bash File health scores theme={null}
  # 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
  ```

  ```bash Hotspot analysis theme={null}
  # 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
  ```

  ```bash Refactoring targets theme={null}
  # 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
  ```

  ```bash Custom thresholds theme={null}
  # 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
  ```

  ```bash Workspace scoping theme={null}
  # Scope to a single workspace package
  fallow health --workspace my-app

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

  ```bash Baseline comparison theme={null}
  # 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
  ```

  ```bash CI integration theme={null}
  # 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
  ```

  ```bash Snapshots & trends theme={null}
  # 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
  ```

  ```bash Coverage gaps theme={null}
  # 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
  ```
</CodeGroup>

## Example output

```bash title="$ fallow health --file-scores --top 3" theme={null}
● 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)
```

```bash title="$ fallow health --hotspots --top 3" theme={null}
● 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

```json title="$ fallow health --format json --top 2" theme={null}
{
  "schema_version": 11,
  "version": "3.24.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"
    }
  ]
}
```

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](#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.

| Field                   | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                | `active` (the override matches a finding that still needs the raised ceiling), `stale` (the override is not what keeps the matched unit quiet: it passes the global thresholds on its own, or an inline suppression already covers it), `insufficient` (the override raises a ceiling the matched code still exceeds, so the finding survives), or `no_match` (the entry matches no analyzed file or function). |
| `override_index`        | Position of the entry in the configured `thresholdOverrides` array. Shared by every row the entry produces.                                                                                                                                                                                                                                                                                                     |
| `dimension`             | Threshold dimension this row describes: `complexity` or `crap`.                                                                                                                                                                                                                                                                                                                                                 |
| `outstanding`           | Dimensions the matched unit still breaches despite the override, whether or not the entry configures their ceilings. Omitted when empty.                                                                                                                                                                                                                                                                        |
| `path`, `function`      | Matched file, and matched function for function-scoped entries.                                                                                                                                                                                                                                                                                                                                                 |
| `line`, `col`           | 1-based line and 0-based column of the matched unit. Absent on `no_match` rows. Several units in one file can share a name; the position keeps their rows distinct.                                                                                                                                                                                                                                             |
| `configured_thresholds` | Ceilings the entry itself configures.                                                                                                                                                                                                                                                                                                                                                                           |
| `effective_thresholds`  | Ceilings in effect for the matched unit after applying every matching entry on top of the defaults.                                                                                                                                                                                                                                                                                                             |
| `metrics`               | Current `cyclomatic` and `cognitive` of the matched code, plus `crap` when coverage data exists. Absent on `no_match` rows.                                                                                                                                                                                                                                                                                     |
| `reason`                | The entry's configured `reason`, when set.                                                                                                                                                                                                                                                                                                                                                                      |

```json title="threshold_overrides[] row (crap dimension)" theme={null}
{
  "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:

```json title="$ fallow health --file-scores --format json --top 2" theme={null}
{
  "schema_version": 11,
  "version": "3.24.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
    }
  ]
}
```

<Note>
  `--file-scores` adds the `file_scores` array and the `summary.files_scored` / `summary.average_maintainability` / `summary.coverage_model` fields. 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.
</Note>

### With hotspots

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

```json title="$ fallow health --hotspots --format json --top 2" theme={null}
{
  "schema_version": 11,
  "version": "3.24.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"
    }
  ]
}
```

### With refactoring targets

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

```json title="$ fallow health --targets --format json --top 2" theme={null}
{
  "schema_version": 11,
  "version": "3.24.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. |

### 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](#vital-signs), plus the nested `counts` object. The [snapshot format](#snapshot-format) shows a complete example.

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

### With health score

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

```json title="$ fallow health --score --format json (health_score excerpt)" theme={null}
{
  "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](/explanations/health#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:

```json title="$ fallow health --trend --format json (health_trend)" theme={null}
{
  "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.

<Note>
  `--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.
</Note>

### 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`):

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "rules": {
      "coverage-gaps": "warn"
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [rules]
  coverage-gaps = "warn"
  ```
</CodeGroup>

```json title="$ fallow health --coverage-gaps --format json" theme={null}
{
  "schema_version": 11,
  "version": "3.24.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.

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

```json title="$ fallow health --runtime-coverage ./coverage --format json" theme={null}
{
  "schema_version": 11,
  "version": "3.24.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 `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`](/cli/coverage) for first-run capture instructions; start a trial with [`fallow license`](/cli/license) when you need continuous or multi-capture runtime monitoring. For the conceptual model and trade-offs, see [Runtime coverage](/analysis/runtime-coverage).

## Markdown output

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

```bash theme={null}
fallow health --file-scores --format markdown | gh pr comment --body-file -
```

```markdown title="$ fallow health --file-scores --format markdown --top 2" theme={null}
## 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:

```bash theme={null}
fallow health --format sarif
```

```json title="$ fallow health --format sarif (excerpt)" theme={null}
{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "3.24.1",
  "runs": [{
    "tool": { "driver": { "name": "fallow", "version": "3.24.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:

```yaml theme={null}
- 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:

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "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
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [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"
  ```
</CodeGroup>

See [Configuration](/configuration/overview) for the full config reference.

## Inline suppression

Suppress individual functions from complexity findings with inline comments:

```ts theme={null}
// 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](/configuration/suppression) for all suppressible issue types.

## See also

<CardGroup>
  <Card title="Health metrics explained" icon="chart-line" href="/explanations/health">
    CRAP metric, maintainability index, hotspot scoring, and coverage model details.
  </Card>

  <Card title="Dead code analysis" icon="skull-crossbones" href="/analysis/dead-code">
    Find unused code alongside complexity hotspots.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Set default thresholds in your config file.
  </Card>

  <Card title="CI integration" icon="shield-check" href="/integrations/ci">
    Enforce complexity limits in your pipeline.
  </Card>
</CardGroup>


# fallow impact
Source: https://docs.fallow.tools/cli/impact

CLI reference for fallow impact. A local-only value report: what fallow is surfacing, the trend, commits contained at the gate, and findings resolved over time.

Show what fallow has done for you in this project: how many issues it is surfacing, the trend since the last recorded run, how many commits the pre-commit or agent gate contained (blocked, then cleared after a fix), and how many findings were genuinely resolved over time.

Impact is **opt-in and local-only**. History lives in your user config dir (see [Storage and cleanup](#storage-and-cleanup)): **nothing is ever written into the repo** (no `.fallow/` directory, no `.gitignore` change), nothing is uploaded, and recording never affects exit codes or analysis output. Recording is also skipped in CI.

```bash theme={null}
fallow impact enable        # track this project (overrides the global default)
fallow impact               # render the value report (also prints the store path)
fallow impact status        # tracking state and history size
fallow impact statusline    # print one stable line for a status bar
fallow impact disable       # stop tracking this project (history is retained)
fallow impact default on    # track every project by default (one global opt-in)
fallow impact reset         # delete this project's history (--all wipes every project)
fallow impact --all         # roll up every project: impact across all your repos
```

Enable Impact once for every project with `fallow impact default on`. A per-project `fallow impact enable` or `disable` always wins over the global default, so you can opt one repo out without disabling everywhere.

## Status bars

`fallow impact statusline` prints exactly one path-free plain-text line for shell and editor status bars. It reads the local Impact store only, starts no analysis, never enables recording, and keeps stderr empty on success.

The command intentionally ignores `--format`. Do not parse its output as JSON. Trend output uses only comparable whole-project scans. Older changed-file history is labeled and shown without a trend.

## Across all your repos

`fallow impact --all` aggregates the per-project histories in your config dir into one ranked table plus grand totals, so you can see what fallow has done for you across every project at once. It reads only the stored histories (no analysis), so it works from anywhere, including outside a repo.

```bash theme={null}
fallow impact --all                  # ranked table + grand totals (sorted by most recent)
fallow impact --all --sort resolved  # rank by lifetime findings resolved
fallow impact --all --limit 10       # cap printed rows (totals still cover every project)
```

Sort with `--sort {recent,resolved,contained,name}` (default `recent`). Projects with no recorded history yet are summarized, not listed. Repos are labeled by their folder name; histories recorded by older fallow versions show a short key until their next recorded run. The `--format json` output is a separate `impact-cross-repo` shape (each entry embeds the same per-project report as `fallow impact`, plus a stable `project_key`); like the single-project report, it never includes any filesystem path. As with all of Impact, this reflects local-developer work and is empty in CI.

## What it tracks

| Signal      | Meaning                                                                                                                                                                |
| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Surfacing   | Issue counts from the most recent recorded run                                                                                                                         |
| Trend       | Delta versus the previous recorded run                                                                                                                                 |
| Containment | A gate-marked `fallow audit` that failed, followed by a later run that cleared it: an issue stopped before it landed                                                   |
| Resolved    | Findings that disappeared because code was removed or refactored. Findings silenced with a `fallow-ignore` comment are counted separately as suppressed, never as wins |

History accrues from `fallow audit` runs invoked with a gate marker: the Git pre-commit hook from [`fallow init --hooks`](/cli/init) and the Claude Code agent gate from [`fallow hooks install --target agent`](/integrations/claude-hooks) both pass one. Whole-project surfacing and trend advance on local bare `fallow` runs.

## The weekly digest

When tracking is enabled and has non-zero results, fallow surfaces the headline numbers at most once a week: JSON output carries an `impact-report` entry in the [`next_steps[]` array](/integrations/mcp) (also on otherwise clean runs), and bare `fallow` prints a one-line `Impact:` summary alongside the failure summary. The cadence stamp lives in the impact store, so the digest stays weekly across agents, sessions, and surfaces. Zero results never surface, and CI never sees the digest.

## Storage and cleanup

Each project keeps one small history file in your user config dir (`~/Library/Application Support/fallow/` on macOS, `$XDG_CONFIG_HOME/fallow/` on Linux, `%APPDATA%\fallow\` on Windows), keyed by repository, so running `fallow impact` from any subdirectory or git worktree of a repo shows that repo's history. Concurrent recordings (for example, a pre-commit gate firing in two worktrees at once) are serialized with an advisory lock so neither run loses the other's data.

Stores for repos you delete from disk stay until you reclaim them. Set [`FALLOW_IMPACT_STORE_MAX_AGE_DAYS`](/configuration/environment#fallow_impact_store_max_age_days) to a number of days and a recorded run prunes any store untouched for longer than that. Unset (the default) keeps every store forever. You can also wipe history explicitly with `fallow impact reset` (this project) or `fallow impact reset --all` (every project).

## JSON output

`fallow impact --format json` and `fallow impact status --format json` emit the report shape from the published [output schema](https://github.com/fallow-rs/fallow/blob/main/docs/output-schema.json):

```json theme={null}
{
  "kind": "impact",
  "enabled": true,
  "enabled_source": "project",
  "record_count": 14,
  "containment_count": 3,
  "recent_containment": ["..."],
  "resolved_total": 12,
  "suppressed_total": 2,
  "recent_resolved": ["..."],
  "attribution_active": true,
  "onboarding_declined": false,
  "explicit_decision": true
}
```

Three fields exist for agents that manage opt-ins conversationally:

* `enabled_source`: why tracking is on or off: `project` (an explicit per-repo enable/disable), `user` (the global default), or `default` (off).
* `explicit_decision`: set only by an explicit `impact enable` or `impact disable`, so an agent can distinguish "asked and declined" (`enabled: false`, `explicit_decision: true`) from "never asked" (`enabled: false`, `explicit_decision: false`) and offer the opt-in exactly once.
* `onboarding_declined`: set by [`fallow init --decline`](/cli/init); suppresses fallow's first-contact setup pointer for this project.

## See also

<CardGroup>
  <Card title="fallow init" icon="terminal" href="/cli/init">
    Install the pre-commit hook that passes the gate marker Impact records.
  </Card>

  <Card title="Claude Code hooks" icon="robot" href="/integrations/claude-hooks">
    The agent gate that feeds containment counts.
  </Card>

  <Card title="Environment variables" icon="gear" href="/configuration/environment">
    `FALLOW_IMPACT_STORE_MAX_AGE_DAYS` and the other Impact knobs.
  </Card>
</CardGroup>


# fallow init
Source: https://docs.fallow.tools/cli/init

CLI reference for fallow init. Generate a .fallowrc.json, .fallowrc.jsonc, or fallow.toml configuration file with schema support for editor autocomplete.

Create a configuration file for your project. The generated config includes a `$schema` field so your editor can provide autocomplete and validation.

<Info>
  Most projects don't need a config file. Fallow works out of the box by auto-detecting entry points and frameworks. Only create one if you need custom entry points, rules, or ignore patterns.
</Info>

Fallow's init command auto-detects your project setup and tailors the generated config accordingly:

* **TypeScript**: Detects `tsconfig.json` and enables TypeScript-aware defaults
* **Monorepo**: Detects workspace configurations (npm, yarn, pnpm) and includes workspace patterns
* **Frameworks**: Detects installed frameworks (Next.js, Remix, Vite, etc.) and adds appropriate entry point patterns

```bash theme={null}
fallow init
```

## Options

| Flag             | Description                                                                                                                                                           |
| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--toml`         | Generate `fallow.toml` instead of `.fallowrc.json`                                                                                                                    |
| `--agents`       | Scaffold a starter `AGENTS.md` guide for coding agents, prefilled from detected project info                                                                          |
| `--hooks`        | Scaffold a pre-commit git hook that runs fallow on changed files. Alias for `fallow hooks install --target git`                                                       |
| `--branch <REF>` | Fallback base branch for the hook when no upstream is set (requires `--hooks`, default: `main`)                                                                       |
| `--decline`      | Record that this project deliberately stays unconfigured, so the first-contact setup hint and the `setup` next-step stop appearing. Writes no config file; idempotent |

## Agent guide scaffold

`fallow init --agents` writes a short starter `AGENTS.md` with project-overview, architecture, command, fallow workflow, and agent-rule prompts, plus a task-to-command matrix that routes common agent intents (deleting "unused" code, committing, prioritizing refactors, consolidating duplication) to the right fallow command. The matrix is the same one exposed as `task_matrix` in [`fallow schema`](/cli/schema). It refuses to overwrite an existing `AGENTS.md`, and it is guidance for agents, not a readiness score.

When the project shape is reliably detectable, the scaffold prefills:

* **Install** from the `packageManager` field in `package.json`, or `pnpm install` when `pnpm-workspace.yaml` is present
* **Test** with the detected test framework (Vitest, Jest, or Playwright), but only when exactly one is present
* **Typecheck or lint** with `tsc --noEmit` when `tsconfig.json` exists
* **Module boundaries** with the workspace patterns for monorepos

Anything ambiguous stays blank rather than guessed: fallow never sniffs a package manager from lockfiles, leaves the test line empty when several frameworks are installed, and labels the workspace tool only when the `packageManager` field or `pnpm-workspace.yaml` proves it. Prefilled command lines carry an HTML provenance comment so you know to confirm them.

```bash theme={null}
fallow init --agents
```

[`fallow agent install`](/cli/agent) writes the same guide together with the skill, the MCP registration, and the commit/push gate for every harness it detects.

## Pre-commit hook

Use the hooks namespace to scaffold a git hook that runs `fallow audit` against the base branch before each commit:

```bash theme={null}
fallow hooks install --target git
```

`fallow init --hooks` remains available as a project-initialization shortcut.

Fallow detects your hook manager and writes to the right location:

1. **Husky** -- adds to `.husky/pre-commit`
2. **Lefthook** -- adds to `lefthook.yml`
3. **Bare hooks** -- writes `.git/hooks/pre-commit`

The generated hook:

* Includes a binary guard (`command -v fallow`) so commits still work when fallow isn't installed
* Resolves the base ref at commit time: `git merge-base @{upstream} HEAD` when an upstream is set, falling back to the configured branch (or `main`) otherwise. Feature branches forked from a non-default integration branch (next-release / hotfix / LTS) compare against the right base, not against their own remote tracking branch
* Runs `fallow audit --base "$BASE" --quiet`, which combines dead-code, complexity, and duplication analysis
* Defaults to `gate=new-only`, so inherited findings on touched files do not block the commit; only findings introduced by the changeset fail the gate. Set `[audit] gate = "all"` in `fallow.toml` to fail on every finding in changed files
* Returns exit code 1 on `verdict: "fail"` (default audit semantics); no `--fail-on-issues` is needed
* Prints `git commit --no-verify` as the bypass option in the success message

<Info>
  Want to gate Claude Code or Codex agent commits as well? Use [`fallow hooks install --target agent`](/integrations/claude-hooks) for the agent enforcement path. The two hooks are complementary: `fallow hooks install --target git` catches human commits, `fallow hooks install --target agent` catches agent commits.
</Info>

### Custom base branch

Override the fallback base branch the hook uses when no upstream is set:

```bash theme={null}
fallow hooks install --target git --branch develop
```

## Gitignore

`fallow init` automatically adds `.fallow/` to your project's `.gitignore`. The `.fallow/` directory contains machine-local data (parse cache, regression baselines, snapshots) that should not be committed.

* If `.gitignore` exists and already contains `.fallow/`, nothing changes
* If `.gitignore` exists without it, the entry is appended
* If `.gitignore` doesn't exist, it is created

## Output

By default, creates `.fallowrc.json`:

```jsonc theme={null}
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "rules": {}
}
```

With `--toml`, creates `fallow.toml`.

## See also

<CardGroup>
  <Card title="Configuration overview" icon="gear" href="/configuration/overview">
    Full reference for all configuration options.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Get started with fallow in under a minute.
  </Card>
</CardGroup>


# fallow inspect
Source: https://docs.fallow.tools/cli/inspect

CLI reference for fallow inspect. Compose trace, dead-code, duplication, complexity, and security evidence for one file or exported symbol.

Compose one evidence bundle before editing a file or exported symbol. `inspect` is designed for agents that need the same context as the MCP `inspect_target` tool without starting an MCP session.

```bash theme={null}
fallow inspect --file src/api.ts --format json --quiet
fallow inspect --symbol src/api.ts:fetchUser --format json --quiet
```

## Target

Choose exactly one target form:

| Flag                     | Description                                                                                                                                                                |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file <PATH>`          | Inspect a project-relative file.                                                                                                                                           |
| `--symbol <FILE:EXPORT>` | Inspect one exported symbol, for example `src/api.ts:fetchUser`. Supporting dead-code, duplication, complexity, and security evidence is file-scoped in the first version. |

## Evidence flags

| Flag             | Description                                                                                                                                                                                                                               |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--symbol-chain` | Also attach the best-effort symbol-level call chain (the same data as [`fallow trace`](/cli/trace)) as a `symbol_chain` evidence section. Only meaningful for a symbol target. Default off (best-effort, syntactic, off the ranked path). |

## Output

| Format  | Description                                                                                                                   |
| :------ | :---------------------------------------------------------------------------------------------------------------------------- |
| `human` | Compact target and identity summary.                                                                                          |
| `json`  | Machine-readable `kind: "inspect_target"` bundle with normalized target identity and evidence sections. Use this from agents. |

```json title="$ fallow inspect --file src/api.ts --format json --quiet" theme={null}
{
  "kind": "inspect_target",
  "target": {
    "type": "file",
    "file": "src/api.ts"
  },
  "identity": {
    "file": "src/api.ts",
    "is_reachable": true,
    "is_entry_point": false,
    "export_count": 3,
    "import_count": 2,
    "imported_by_count": 1
  },
  "evidence": {
    "trace_file": { "status": "ok", "scope": "file", "data": {} },
    "dead_code": { "status": "ok", "scope": "file", "data": {} },
    "duplication": { "status": "ok", "scope": "project_filtered_to_file", "data": {} },
    "complexity": { "status": "ok", "scope": "project_filtered_to_file", "data": {} },
    "security": { "status": "ok", "scope": "file", "data": {} }
  },
  "warnings": []
}
```

Each evidence section carries a `status` (`ok` or `error`) and `scope`. Non-fatal child-analysis failures are reported as section-level errors plus a warning, so the caller can still use the rest of the bundle.

`inspect` accepts the project and performance flags (`--root`, `--config`, `--workspace`, `--production`, `--no-cache`, `--threads`). See [global flags](/cli/global-flags) for the full list.

## MCP parity

The MCP `inspect_target` tool uses the same CLI flow and returns the same JSON shape. Prefer the CLI when you are already in a shell or editor command, and MCP when an agent is already connected to the server.

## See also

<CardGroup>
  <Card title="fallow trace" icon="route" href="/cli/trace">
    The call-chain data `--symbol-chain` attaches.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use the `inspect_target` tool from AI coding agents.
  </Card>
</CardGroup>


# fallow license
Source: https://docs.fallow.tools/cli/license

CLI reference for fallow license. Activate a trial or JWT, inspect status, refresh a license, or deactivate the local token for paid runtime coverage.

Manage the local license used for paid runtime-coverage features.

```bash theme={null}
fallow license status
```

Verification is offline against an Ed25519 public key compiled into the binary. Only the trial and refresh flows make network requests to `api.fallow.cloud`.

## Subcommands

### `activate`

Activate a local JWT or start a 30-day email-gated trial.

```bash theme={null}
fallow license activate --trial --email you@company.com
fallow license activate eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
fallow license activate --from-file ./license.jwt
cat ./license.jwt | fallow license activate --stdin
```

JWT input precedence is:

1. positional JWT argument
2. `--from-file <path>`
3. `--stdin`

Whitespace is normalized before verification, so copied multiline tokens still work.

#### Flags

| Flag                 | Description                                                                                                                                                                                                                                           |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--trial`            | Start a 30-day email-gated trial instead of reading a JWT locally. Requires `--email`. Rate-limited to **5 requests per hour per IP**; in CI or behind a shared NAT, start the trial from a developer machine and set `FALLOW_LICENSE` on the runner. |
| `--email <ADDR>`     | Email address for the trial flow. On success, fallow also prints the server-reported `trialEndsAt` ISO timestamp so you do not need to decode the JWT.                                                                                                |
| `--from-file <PATH>` | Read a JWT from a file.                                                                                                                                                                                                                               |
| `--stdin`            | Read a JWT from standard input.                                                                                                                                                                                                                       |

### `status`

Print the current license status, tier, seats, enabled features, and expiry state.

```bash theme={null}
fallow license status
```

Example output:

```text theme={null}
license: VALID, tier=trial seats=1 features=runtime_coverage days_until_expiry=29
  → runtime_coverage: ENABLED
```

If the token is expired but still in the grace window, fallow reports that explicitly and tells you to refresh it. If no token is present, the command suggests starting a trial.

If the JWT includes a `refresh_after` claim (issued at `iat + 15 days` by `api.fallow.cloud`) and that timestamp has already passed, `status` appends a one-line refresh hint. This is a proactive nudge while the license is still valid, not an error.

### `refresh`

Fetch a fresh JWT for the currently active license.

```bash theme={null}
fallow license refresh
```

This is the preferred way to renew a token before the hard-fail window is reached.

### `deactivate`

Remove the local license file.

```bash theme={null}
fallow license deactivate
```

## Storage and precedence

By default, the local token is stored at `~/.fallow/license.jwt`. On Unix, fallow writes the file with mode `0600` (owner read/write only) so other users on the same host cannot read the bearer token. Windows relies on the ACL of the containing directory.

Lookup precedence is:

1. `FALLOW_LICENSE`
2. `FALLOW_LICENSE_PATH`
3. `~/.fallow/license.jwt`

Use `FALLOW_LICENSE` on shared CI runners where writing to a user home directory is not desirable.

## Exit behavior

Common outcomes:

| Situation                                     | Result                                    |
| :-------------------------------------------- | :---------------------------------------- |
| Valid license                                 | exit code `0`                             |
| No license or hard-fail expired license       | non-zero status                           |
| Network failure during `--trial` or `refresh` | exit code `7`                             |
| Malformed or truncated JWT                    | non-zero status with a verification error |

### Actionable error messages

When the backend returns a structured error envelope, fallow maps known `code` values to targeted hints instead of printing the raw HTTP body:

| Operation + code                      | Message                                                                                                                                                                        |
| :------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `refresh` + `token_stale`             | `your stored license is too stale to refresh. Reactivate with: fallow license activate --trial --email <addr>` (fires when the stored JWT is more than 45 days past its `exp`) |
| `refresh` + `invalid_token`           | `your stored license token is missing required claims. Reactivate with: fallow license activate --trial --email <addr>`                                                        |
| `refresh` or `trial` + `unauthorized` | `authentication failed. Reactivate with: fallow license activate --trial --email <addr>`                                                                                       |
| `trial` + `rate_limit_exceeded`       | `trial creation is rate-limited to 5 per hour per IP. Wait an hour or retry from a different network (in CI, start the trial locally and set FALLOW_LICENSE on the runner).`   |

For unknown codes, fallow surfaces the backend's `message` field if present, otherwise the raw body.

## Clock skew

License verification rejects JWTs whose `iat` (issued-at) claim is more than 24 hours in the future relative to the local system clock. The same check catches both directions of skew: a JWT signed against a forward-shifted clock and a local machine whose clock is behind reality. Rejection surfaces as a `license appears to be issued <duration> in the future` error and exits non-zero so paid features fail closed instead of silently honoring a license the local clock cannot validate against.

Common non-user causes:

* CI containers booted without NTP.
* Machines with a dead BIOS battery.
* A laptop's clock drifting after a long sleep.

After confirming the system clock is correct, the default 24h window can be overridden via `FALLOW_LICENSE_SKEW_TOLERANCE_SECONDS=<seconds>` for environments with predictable drift. Parsing is lenient: unset, empty, unparsable, or negative values all fall back to the default so a typo in a runner env block cannot fail license verification on its own.

## See also

<CardGroup>
  <Card title="Runtime coverage" icon="chart-network" href="/analysis/runtime-coverage">
    Understand what the paid runtime-coverage layer adds on top of health analysis.
  </Card>

  <Card title="Coverage setup" icon="wand-magic-sparkles" href="/cli/coverage">
    Guided first-run workflow that bootstraps the sidecar and writes a collection recipe.
  </Card>
</CardGroup>


# fallow list
Source: https://docs.fallow.tools/cli/list

CLI reference for fallow list. Inspect discovered files, entry points, active plugins, and architecture boundary zones to debug configuration and verify project setup.

Inspect what fallow discovered in your project. Use this command to debug configuration issues or verify that the right files, entry points, plugins, and boundary zones are being picked up.

```bash theme={null}
fallow list
```

## Options

| Flag                    | Description                                                                                                                                                                                     |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--files`               | Show all discovered files                                                                                                                                                                       |
| `--entry-points`        | Show entry point files                                                                                                                                                                          |
| `--plugins`             | Show active plugins                                                                                                                                                                             |
| `--boundaries`          | Show architecture boundary zones, rules, and per-zone file counts                                                                                                                               |
| `--workspaces`          | Show monorepo workspaces and workspace-discovery diagnostics (malformed `package.json`, unreachable glob matches, missing tsconfig references). Available as the `fallow workspaces` alias too. |
| `-f, --format <FORMAT>` | Output format: `human` (default), `json`                                                                                                                                                        |

## Examples

<CodeGroup>
  ```bash Inspect plugins theme={null}
  # Show active plugins
  fallow list --plugins

  # JSON output for scripting
  fallow list --plugins --format json
  ```

  ```bash Inspect files theme={null}
  # Show all discovered files
  fallow list --files

  # Show entry points
  fallow list --entry-points
  ```

  ```bash Inspect boundaries theme={null}
  # Show boundary zones and rules (requires boundaries config)
  fallow list --boundaries

  # JSON output with zone file counts
  fallow list --boundaries --format json
  ```

  ```bash Inspect workspaces theme={null}
  # Show monorepo workspaces and any discovery diagnostics
  fallow list --workspaces

  # Same, via the dedicated alias
  fallow workspaces

  # JSON output for scripting (workspace_diagnostics[] is also on
  # `fallow dead-code / dupes / health --format json`)
  fallow list --workspaces --format json
  ```
</CodeGroup>

### Workspace diagnostics

A malformed declared-workspace `package.json`, a workspace glob that matches a directory without `package.json`, or a tsconfig reference pointing at a missing directory all surface as `workspace_diagnostics[]` entries with a `kind` discriminator:

| `kind`                                  | When                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `malformed-package-json`                | A declared workspace's `package.json` failed to parse. Includes the parse error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `glob-matched-no-package-json`          | A workspace glob matched a directory that has no `package.json` (and is not in the conventional skip list or your `ignorePatterns`). Includes the matching pattern.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `malformed-tsconfig`                    | `tsconfig.json` exists but failed to parse as JSONC. Includes the parse error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `tsconfig-reference-dir-missing`        | `tsconfig.json` references a `references[].path` that does not exist.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `undeclared-workspace`                  | A directory contains `package.json` but is not declared as a workspace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `bun-lockb-override-resolution-skipped` | The root `package.json` declares overrides, bun's legacy binary `bun.lockb` sits next to it, and no parseable text lockfile (`bun.lock`, `pnpm-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`) was found to use instead, so the `unused-dependency-overrides` check is skipped and reports nothing. A `yarn.lock` or an unparseable `bun.lock` beside the `bun.lockb` does not prevent the skip. Run `bun install --save-text-lockfile` (bun 1.2 or newer) to write a text `bun.lock`, or delete the stale `bun.lockb` if the repository no longer uses bun. Emitted by the override analysis rather than workspace discovery, so it appears in `dead-code`, `check`, and `health` JSON and as one stderr warning. |

A malformed ROOT `package.json` is treated as a hard config-load error and exits 2 instead of warning; everything else is warn-and-continue so analysis still runs on the remaining workspaces. The same workspace-discovery diagnostics are emitted on `fallow dead-code`, `fallow dupes`, and `fallow health` JSON envelopes (omitted when empty), so CI consumers can gate on discovery problems without a separate command. Those analysis envelopes can also include source-discovery skip diagnostics: `skipped-large-file` and `skipped-minified-file`, each with `size_bytes`.

## Example output

```bash title="$ fallow list --boundaries" theme={null}
Boundaries: 6 zones, 6 rules, 1 logical group

Zones:
  app                  3 files  src/app/**
  features/auth        4 files  src/features/auth/**
  features/billing     5 files  src/features/billing/**
  features             3 files  src/features/**
  shared               8 files  src/components/**, src/hooks/**, src/lib/**, ...
  server               4 files  src/server/**

Rules:
  features/auth        → shared, server
  features/billing     → shared, server
  app                  → features/auth, features/billing, features, shared, server
  features             → shared, server, features/auth, features/billing
  server               → shared
  shared               (isolated, no imports allowed)

Logical groups:
  features             12 files autoDiscover: src/features
    children: features/auth, features/billing
```

The `Logical groups:` section appears whenever the config (or a preset) uses
`autoDiscover` to fan a parent zone out into one zone per child directory.
Each entry shows the user-authored parent name, the exact `autoDiscover` paths
as written, the discovered children, and a summed file count. The human output
puts misconfigured entries (`invalid path`, `empty`) first inside the section
and splits the file count into `N files (X children + Y fallback)` when the
parent has both `patterns` and `autoDiscover` (e.g. the Bulletproof preset).
The `--format json` output mirrors this in a parallel
`boundaries.logical_groups[]` array, with extra fields for round-trip config
tooling: `auto_discover` (verbatim user strings), `source_zone_index` (position
in the pre-expansion `zones[]`), `status` (`ok` / `empty` / `invalid_path`),
`authored_rule` (the pre-expansion rule keyed on the parent), `fallback_zone` (a
back-reference when the parent kept its own `patterns` and stayed in `zones[]`),
`merged_from` (parent zone indices when the same parent name was declared
twice), `original_zone_root` (echo of the parent's `root` subtree scope), and
`child_source_indices` (parallel to `children`, attributing each child to a
specific `auto_discover` entry). The full shape is documented in
[`docs/output-schema.json`](https://github.com/fallow-rs/fallow/blob/main/docs/output-schema.json)
under `ListBoundariesOutput`.

```bash title="$ fallow list --plugins" theme={null}
Active plugins:
  - nextjs
  - vite
  - vitest
  - playwright
  - storybook
  - eslint
  - typescript
  - tailwind
  - drizzle
  - commitlint
  - sentry
```

```bash title="$ fallow list --entry-points" theme={null}
Found 42 entry points
src/app/layout.tsx                   (Plugin: nextjs)
src/app/page.tsx                     (Plugin: nextjs)
src/instrumentation.ts               (Plugin: nextjs)
src/proxy.ts                         (Plugin: nextjs)
src/lib/utils.test.ts                (Plugin: vitest)
e2e/auth.setup.ts                    (Plugin: playwright)
.storybook/main.ts                   (Plugin: storybook)
drizzle.config.ts                    (Plugin: drizzle)
scripts/db-migrate.ts                (PackageJsonScript)
scripts/db-seed.ts                   (PackageJsonScript)
...
```

Each entry point shows how it was discovered. The plugin name tells you which framework detected it.

## See also

<CardGroup>
  <Card title="Built-in plugins" icon="puzzle-piece" href="/frameworks/built-in">
    Full list of fallow's built-in framework plugins.
  </Card>

  <Card title="Custom plugins" icon="plug" href="/frameworks/custom-plugins">
    Create plugins for frameworks fallow doesn't cover yet.
  </Card>
</CardGroup>


# fallow migrate
Source: https://docs.fallow.tools/cli/migrate

CLI reference for fallow migrate. Convert your existing knip, jscpd, or stylelint configuration to fallow's config format.

Migrate your existing knip, jscpd, or stylelint configuration to fallow. The migrate command reads your current config, translates it to fallow's format, and writes a new config file.

<Info>
  If more than one source config exists in your project, fallow merges them into a single config.
</Info>

```bash theme={null}
fallow migrate
```

## Options

| Flag            | Description                                                                                                                                                                                                                                                                |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--toml`        | Output as `fallow.toml` (mutually exclusive with `--jsonc`)                                                                                                                                                                                                                |
| `--jsonc`       | Write to `.fallowrc.jsonc` instead of `.fallowrc.json`. The generated content is the same JSONC (with `//` comments) either way; the `.jsonc` extension lets editors auto-detect JSON-with-comments syntax highlighting and silences linters that flag comments in `.json` |
| `--dry-run`     | Preview the generated config without writing                                                                                                                                                                                                                               |
| `--from <PATH>` | Path to the config file to migrate                                                                                                                                                                                                                                         |

<Tip>
  Without `--jsonc` or `--toml`, fallow auto-mirrors the source extension: a `knip.jsonc` migration writes `.fallowrc.jsonc`, a `knip.json` migration writes `.fallowrc.json`. The fallow config parser accepts comments in both extensions.
</Tip>

## What it detects

Fallow auto-detects:

* `knip.json`, `knip.jsonc`, `.knip.json`, `.knip.jsonc`, `knip.ts`, `knip.config.ts`
* `knip` field in `package.json`

<Info>
  TypeScript config files (`knip.ts`, `knip.config.ts`) are detected but cannot be parsed. Convert to `knip.json` first, then re-run migrate.
</Info>

* `.jscpd.json`
* `jscpd` field in `package.json`

## Examples

<CodeGroup>
  ```bash Auto-detect theme={null}
  # Detect config files and migrate
  fallow migrate

  # Preview without writing
  fallow migrate --dry-run
  ```

  ```bash Output format theme={null}
  # Write as TOML
  fallow migrate --toml

  # Write as JSON (default)
  fallow migrate
  ```

  ```bash Specific file theme={null}
  # Migrate a specific config file
  fallow migrate --from config/knip.json
  ```
</CodeGroup>

Warnings are shown for any config fields that can't be migrated automatically.

## See also

<CardGroup>
  <Card title="Migrating from knip" icon="right-left" href="/migration/from-knip">
    Detailed comparison and migration guide from knip.
  </Card>

  <Card title="Migrating from jscpd" icon="right-left" href="/migration/from-jscpd">
    Detailed comparison and migration guide from jscpd.
  </Card>
</CardGroup>


# fallow plugin-check
Source: https://docs.fallow.tools/cli/plugin-check

CLI reference for fallow plugin-check. A read-only dry-run that reports whether each external plugin activated and, for manifestEntries rules, the manifests matched, entries seeded, and typed warnings.

Dry-run your external plugins without running a full analysis: per plugin, did it activate, and what did each `manifestEntries` rule match and seed. It is read-only, so it is safe to run in a tight loop while you iterate on a `fallow-plugin-*` file.

<Info>
  `plugin-check` is advisory, never a gate: it always exits 0 and rejects the output-gating flags (`--ci`, `--fail-on-issues`, `--output-file`). Reach for it to debug why a plugin activates or seeds nothing, not to fail CI.
</Info>

```bash theme={null}
fallow plugin-check
fallow plugin-check --format json
fallow plugin-check --format json --root packages/app
```

It pairs with [`fallow list --plugins`](/cli/list), which answers whether a plugin is active. `plugin-check` goes further: for active plugins it shows exactly what each `manifestEntries` rule matched and seeded. For the plugin file format, the field reference, and how `manifestEntries` interpolation works, see [Custom plugins](/frameworks/custom-plugins).

## What it reports

For every external plugin discovered from the `plugins` config field, the `.fallow/plugins/` directory, or `fallow-plugin-*` files in the project root:

* `active`, and when inactive an `activation_requirement` string naming the unmet condition, so a plugin whose `detection` fails is no longer silent.
* For active plugins with `manifestEntries`, a structured per-rule report: the manifests matched by the glob (`manifests_matched`), each matched manifest's `when`-gate result (`when_passed`), the entries seeded (each resolved path with a `path_exists` flag), and any `warnings`.

Output is deterministic and sorted, so `--format json` is byte-identical across machines and safe to diff in CI or snapshot in tests.

<Note>
  `path_exists` reports whether a file matches the seeded glob on disk. `false` means the entry is definitely broken. `true` is necessary but not sufficient: it does not prove the entry became reachable, because file discovery still filters gitignored and wrong-extension files.
</Note>

## Warnings

Each `manifestEntries` rule reports typed `warnings[]`. Agents branch on the kebab-case `kind`; each warning carries only the slot relevant to that kind (`glob`, `field_path`, `manifest`, or `entry`). These are the fastest way to debug a rule that seeds nothing.

| `kind`                   | Emitted when                                                                        |
| :----------------------- | :---------------------------------------------------------------------------------- |
| `manifests-matched-none` | The `manifests` glob matched no files.                                              |
| `when-excluded-all`      | The rule's `when` gate excluded every matched manifest.                             |
| `field-path-unresolved`  | A `${dotted.field}` path resolved in none of the gated manifests (likely a typo).   |
| `entries-empty`          | The rule's `entries` list is empty, so it seeds nothing.                            |
| `manifest-parse-failed`  | A matched manifest could not be read or parsed (emitted once per failing manifest). |
| `entry-outside-root`     | A seeded entry resolved outside the project root and was skipped.                   |
| `seeded-paths-missing`   | The rule seeded entries but none of the seeded paths exist on disk.                 |

## Options

| Flag                | Description                                                               |
| :------------------ | :------------------------------------------------------------------------ |
| `--root <ROOT>`     | Project root directory                                                    |
| `--config <CONFIG>` | Path to a config file, which may declare extra plugin paths via `plugins` |
| `--format <FORMAT>` | Output format (`human` default, `json` for agents)                        |
| `--quiet`           | Suppress progress output                                                  |

Global flags such as `--no-cache` and `--threads` still apply; see [global flags](/cli/global-flags).

## JSON output

The example below covers both shapes in one run: an inactive plugin with its `activation_requirement`, and an active plugin whose rule seeded an entry that does not yet exist on disk (`path_exists: false`), raising a `seeded-paths-missing` warning.

```json theme={null}
{
  "kind": "plugin-check",
  "schema_version": "1",
  "note": "path_exists reports whether a file matches the seeded glob on disk. false means the entry is definitely broken; true is necessary but NOT sufficient (it does not prove the entry became reachable, since discovery still filters gitignored and wrong-extension files).",
  "plugins": [
    {
      "name": "acme-framework",
      "active": false,
      "activation_requirement": "no enabler present; requires one of these dependencies: @acme/core"
    },
    {
      "name": "internal-manifests",
      "active": true,
      "manifest_rules": [
        {
          "manifests": "**/service.jsonc",
          "manifests_matched": ["svc/service.jsonc"],
          "matched": [
            {
              "path": "svc/service.jsonc",
              "when_passed": true,
              "seeded": [
                { "path": "svc/src/main.{ts,tsx}", "path_exists": false }
              ]
            }
          ],
          "warnings": [
            { "kind": "seeded-paths-missing", "glob": "**/service.jsonc" }
          ]
        }
      ]
    }
  ]
}
```

A healthy active plugin reports `when_passed: true`, `path_exists: true` for each seeded entry, and an empty `warnings` array.

`plugin-check` is a CLI-only authoring aid; the [MCP server](/integrations/mcp) does not expose it.

## See also

<CardGroup>
  <Card title="Custom plugins" icon="puzzle-piece" href="/frameworks/custom-plugins">
    The plugin file format, the `manifestEntries` rule shape, and `${dotted.field}` interpolation.
  </Card>

  <Card title="fallow list" icon="list" href="/cli/list">
    `fallow list --plugins` shows which plugins are active.
  </Card>

  <Card title="Schemas" icon="file-code" href="/cli/schema">
    `fallow plugin-schema` prints the plugin-file schema for IDE autocomplete.
  </Card>
</CardGroup>


# fallow recommend
Source: https://docs.fallow.tools/cli/recommend

CLI reference for fallow recommend. A read-only, project-tailored config recommendation: what fallow detected, a safe proposed config, and the decisions split into auto, default, and taste.

Recommend a project-tailored config without writing anything. `fallow recommend` inspects the project (frameworks, workspace layout, tooling) and emits three things: what it **detected**, a safe **proposed config**, and the list of **decisions** behind that proposal, so a human or an agent can review the reasoning instead of trusting a generated file.

<Info>
  Zero config is a valid stop: fallow's defaults are strong, so writing no config at all is fully supported. `recommend` exists for the projects that do want one, and for agents that need to author it with the user instead of guessing.
</Info>

```bash theme={null}
fallow recommend
fallow recommend --format json
```

Unlike [`fallow init`](/cli/init), which writes a config file, `recommend` is read-only. The intended flow for agents: run `recommend --format json`, apply the `auto` decisions, disclose the `default` decisions, ask the user about the `taste` decisions, then write the result (or run `init`). When TypeScript is detected, the default decisions point to optional type-aware analysis without adding it to `proposed_config`.

## Decision tiers

Every proposed setting comes with its tier and rationale:

| Tier      | Meaning                                                                                                                                   |
| :-------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `auto`    | Decided from detection (a detected framework, workspace layout, test runner). Safe to apply as-is.                                        |
| `default` | A disclosed, overridable default or optional capability. It changes `proposed_config` only when the proposed config contains its setting. |
| `taste`   | A genuinely subjective choice. Surfaced as an open `question` for the user; not silently decided.                                         |

## Options

`fallow recommend` adds no flags of its own. It reads an existing config passed with
`--config` and takes it into account. [Global flags](/cli/global-flags) such as `--root`,
`--format`, `--quiet`, `--no-cache`, and `--threads` apply.

## JSON output

```json theme={null}
{
  "kind": "recommendation",
  "schema_version": "1",
  "detected": {
    "has_typescript": true,
    "is_monorepo": false,
    "package_manager": "npm",
    "ui_framework": null,
    "test_framework": "vitest"
  },
  "proposed_config": {
    "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
    "entry": ["src/index.{ts,tsx,js,jsx}", "src/main.{ts,tsx,js,jsx}"]
  },
  "decisions": [
    {
      "setting": "entry",
      "value": ["src/index.{ts,tsx,js,jsx}", "src/main.{ts,tsx,js,jsx}"],
      "rationale": "Assumes the src/index or src/main entry convention. Adjust for framework-routed apps or DI-wired entry points (fallow also auto-honors package.json exports/main/module for libraries).",
      "kind": "auto",
      "question": null
    },
    {
      "setting": "typeAware.enabled",
      "value": null,
      "rationale": "Detected TypeScript. Run fallow dead-code --type-aware or set typeAware.enabled to true when cleanup depends on exact TypeScript identity. This starts a slower semantic pass and does not replace tsc or Oxlint. Guide: https://docs.fallow.tools/analysis/type-aware",
      "kind": "default",
      "question": null
    }
  ],
  "note": "proposed_config is the safe, detection-derived baseline; resolve every taste decision with the user before finalizing. For the full set of valid config keys and their shapes, run `fallow config-schema`. Zero config is a valid stop.",
  "config_schema_command": "fallow config-schema"
}
```

The `detected` block also reports monorepo workspace patterns, the workspace tool, Storybook presence, and whether frameworks live in workspace packages rather than the root.

## Related

* [`fallow init`](/cli/init) writes the config file (and can scaffold `AGENTS.md` and git hooks)
* [`fallow config-schema`](/cli/schema) prints the full JSON schema for every config key
* [Type-aware TypeScript analysis](/analysis/type-aware) explains the optional semantic pass
* The MCP server exposes this command as the read-only `recommend` tool; see [MCP integration](/integrations/mcp)


# fallow report
Source: https://docs.fallow.tools/cli/report

CLI reference for fallow report. Render saved JSON results as CI artifacts, summaries, PR comments, or inline-review envelopes without re-running analysis.

Render a saved `--format json` results file in another format without re-running
analysis. Analyze once, retain JSON as the provenance-bearing artifact, then
derive every CI presentation from that same result.

```bash theme={null}
fallow dead-code --type-aware --format json -o results.json
fallow report --from results.json --format github-annotations
fallow report --from results.json --format pr-comment-github > comment.md
fallow report --from results.json --format review-github > review.json
```

The command dispatches on the envelope's `kind`, so any saved fallow result
renders: `dead-code`, `dupes`, `health`, `audit`, `security`, or the bare
combined run. Supported targets are:

* `github-annotations` and `github-summary`
* `codeclimate` and `sarif`
* `pr-comment-github` and `pr-comment-gitlab`
* `review-github` and `review-gitlab`

The PR-comment and review targets preserve the saved audit conclusion, diff
positions, ownership grouping, and repository path prefix. Type-aware `dead-code`
and `audit` results render their final semantically refined findings rather
than the earlier syntactic candidates. When semantic evidence is required but
incomplete, the analysis run fails closed instead of saving an apparently
clean presentation.

GitHub annotations and summaries are log-based, so they work on fork PRs
without a write token. PR-comment and review envelopes still need the provider
posting step described in [CI integration](/integrations/ci).

## Options

| Flag                    | Description                                                                                                                                                  |
| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--from <PATH>`         | Path to a fallow JSON results file produced by `--format json` (required)                                                                                    |
| `-f, --format <FORMAT>` | Target format: `github-annotations`, `github-summary`, `codeclimate`, `sarif`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, or `review-gitlab` |
| `-r, --root <ROOT>`     | Project root directory (used for repository-root path rebasing)                                                                                              |
| `-q, --quiet`           | Suppress progress output on stderr                                                                                                                           |

## Exit code

Rendering is exit-neutral: `fallow report` exits 0 even when the saved file contains findings. Gating belongs to the analysis run that produced the file (`--fail-on-issues`, the audit verdict); use that run's exit code in CI and keep `report` as a pure rendering step.

## See also

<CardGroup>
  <Card title="CI integration" icon="gears" href="/integrations/ci">
    The GitHub Action, GitLab template, and native workflow formats
  </Card>

  <Card title="Global flags" icon="sliders" href="/cli/global-flags">
    Repository-root path rebasing and `--report-path-prefix`
  </Card>
</CardGroup>


# fallow schema
Source: https://docs.fallow.tools/cli/schema

CLI reference for fallow schema. Dump fallow's complete capability manifest (commands, issue types, MCP tools, plugins, environment variables) as machine-readable JSON for agent introspection.

Dump fallow's complete capability manifest as machine-readable JSON. This is the single source of truth an AI agent (or doc generator) can read to learn everything fallow can do: every command and flag, every issue type, every MCP tool, the built-in framework plugins, and the user-facing environment variables.

```bash theme={null}
fallow schema
```

<Note>
  The output is always JSON, regardless of `--format`.
</Note>

The manifest is also the source the agent-skill tables are generated from (the command, issue-type, and MCP-tool tables in the npm package's bundled SKILL.md regenerate from it at release time), and this docs site serves an auto-generated [llms.txt](https://docs.fallow.tools/llms.txt) index alongside it for agent consumption.

## Top-level blocks

| Block                                                                     | Contents                                                                                                                                                                                                                                                                                                                                                |
| :------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `manifest_version`                                                        | Manifest shape discriminator (currently `"1"`). Gate on it when generating docs from the output.                                                                                                                                                                                                                                                        |
| `version`                                                                 | The fallow CLI version that produced the manifest.                                                                                                                                                                                                                                                                                                      |
| `commands`, `global_flags`                                                | Every CLI command and flag with type, default, and description, derived live from the CLI definition.                                                                                                                                                                                                                                                   |
| `issue_types`                                                             | One row per reportable issue type across all analyses (see below).                                                                                                                                                                                                                                                                                      |
| `task_matrix`                                                             | The agent task-to-command cheat sheet: one row per common agent intent (`task`) with the read-only command to run (`command`, may contain `<placeholder>` tokens) and an optional `note`. The same matrix renders into `fallow init --agents`, the managed AGENTS.md block, the root `--help`, and the fallow skill. Rows never name mutating commands. |
| `mcp_tools`                                                               | Every MCP server tool with a `kind` grouping (`analysis`, `trace`, `fix`, `introspection`, `runtime-coverage`, `composition`), a one-line description, `key_params` (a curated subset; the live MCP `list_tools` schemas are authoritative), `license` plus `license_note`, and `read_only`.                                                            |
| `mcp_resources`                                                           | Every MCP resource and resource template (`uri`, `name`, `title`, `description`, `mime_type`, `template`): the read-only reference channel of `fallow-mcp` (tool manifest, issue-type registry, explain index and template, task matrix, JSON Schemas). Same order as `resources/list`.                                                                 |
| `plugins`                                                                 | Built-in framework plugin count and names, derived live from the plugin registry.                                                                                                                                                                                                                                                                       |
| `environment_variables`                                                   | Every user-facing `FALLOW_*` variable with a one-line description.                                                                                                                                                                                                                                                                                      |
| `output_formats`, `exit_codes`, `severity_levels`, `suppression_comments` | Output and exit-code contract reference. Formats include accepted aliases and are derived from the CLI parser; exit codes include the complete public workflow ladder.                                                                                                                                                                                  |

## Issue type rows

Each `issue_types` entry describes one reportable issue type:

| Field                               | Meaning                                                                                                                                                                                                  |
| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                | Bare issue-type identifier (e.g. `unused-file`, `high-crap-score`).                                                                                                                                      |
| `rule_id`                           | The SARIF rule id (e.g. `fallow/unused-file`, `security/sql-injection`).                                                                                                                                 |
| `command`                           | The subcommand that reports it (`dead-code`, `health`, `dupes`, `flags`, `security`).                                                                                                                    |
| `category`                          | Coarse grouping (Dead code, Dependencies, Architecture, Health, Duplication, Security, ...).                                                                                                             |
| `filter_flag`                       | CLI flag that scopes output to this issue type, or `null` when none exists.                                                                                                                              |
| `fixable`                           | Whether `fallow fix` can auto-fix it.                                                                                                                                                                    |
| `suppressible` / `suppress_comment` | Whether an inline suppression comment applies, and the exact copy-pasteable comment. The token is verified to round-trip through fallow's suppression parser, so a copied comment never silently no-ops. |
| `note`                              | Caveats (production-mode-only types, shared filter flags, config prerequisites).                                                                                                                         |
| `license` / `license_note`          | `free` or `freemium`; runtime-coverage rows carry the nuance that a single local capture is free while continuous monitoring requires a license.                                                         |
| `docs_url`                          | Deep link into these docs.                                                                                                                                                                               |

Nullable fields are always present (`null` when not applicable), never absent.

## Examples

<CodeGroup>
  ```bash Quick counts theme={null}
  fallow schema | jq '{
    issue_types: (.issue_types | length),
    mcp_tools: (.mcp_tools.tools | length),
    plugins: .plugins.count
  }'
  ```

  ```bash Suppression comment lookup theme={null}
  # What comment suppresses a finding type?
  fallow schema | jq -r '.issue_types[]
    | select(.id == "unused-export")
    | .suppress_comment'
  ```

  ```bash Fixable issue types theme={null}
  fallow schema | jq -r '.issue_types[]
    | select(.fixable) | .id'
  ```

  ```bash MCP tool selection theme={null}
  # Read-only analysis tools an agent can call safely
  fallow schema | jq -r '.mcp_tools.tools[]
    | select(.read_only and .kind == "analysis") | .name'
  ```
</CodeGroup>

## See also

<CardGroup>
  <Card title="fallow explain" icon="terminal" href="/cli/explain">
    Rationale, examples, and fix guidance for one issue type.
  </Card>

  <Card title="MCP server" icon="robot" href="/integrations/mcp">
    The MCP tools the manifest describes, with full input schemas.
  </Card>

  <Card title="Environment variables" icon="gear" href="/configuration/environment">
    Prose reference for the variables in the manifest.
  </Card>

  <Card title="fallow list" icon="terminal" href="/cli/list">
    Project-specific introspection: discovered files, entry points, active plugins.
  </Card>
</CardGroup>


# fallow security
Source: https://docs.fallow.tools/cli/security

CLI reference for fallow security. Surface opt-in local security candidates for agent or human verification.

Surface local security candidates for verification. Two rule families ship: the graph-structural `client-server-leak` (a `"use client"` file that directly reads, or transitively imports a module that reads, a non-public `process.env` secret), and the data-driven `tainted-sink` catalogue (syntactic dangerous-sink candidates across a catalogue of CWE categories). Both default to `off` and run only under `fallow security`, never under bare `fallow` or the `audit` gate.

<Note>
  Findings are candidates, not confirmed vulnerabilities. Fallow reports a structural trace so an agent or human can verify whether the value can actually reach client-bundled code.
</Note>

```bash theme={null}
fallow security
```

## Options

### Output

| Flag                    | Description                                                          |
| :---------------------- | :------------------------------------------------------------------- |
| `-f, --format <FORMAT>` | Output format: `human` (default), `json`, or `sarif`                 |
| `-q, --quiet`           | Suppress progress output                                             |
| `--summary`             | Show a compact human summary instead of per-finding detail           |
| `--ci`                  | CI mode: equivalent to `--format sarif --fail-on-issues --quiet`     |
| `--surface`             | Include the agent-facing `attack_surface[]` inventory in JSON output |
| `--fail-on-issues`      | Exit with code 1 if security candidates are found                    |
| `--sarif-file <PATH>`   | Write SARIF output to a file in addition to the primary output       |

### Scoping

| Flag                                      | Description                                                                                                                                                                                    |
| :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-r, --root <PATH>`                       | Project root directory (default: current working directory)                                                                                                                                    |
| `-c, --config <PATH>`                     | Path to config file (default: auto-detected)                                                                                                                                                   |
| `--changed-since <REF>` (alias: `--base`) | Only report candidates whose client anchor or trace hops touch files changed since a git ref                                                                                                   |
| `--file <PATH>`                           | Only report candidates whose finding anchor or trace hop matches the selected file. Repeat to select multiple files. The full graph is still analyzed                                          |
| `--diff-file <PATH>`                      | Narrow candidates to added hunks on the client anchor or import trace. Secret-source hops use file-level retention because member-access spans are not yet stored. Use `-` to read from stdin. |
| `--diff-stdin`                            | Read the unified diff from stdin                                                                                                                                                               |
| `-w, --workspace <PATTERNS>`              | Scope output to selected workspace packages                                                                                                                                                    |
| `--changed-workspaces <REF>`              | Scope output to workspace packages touched since the given git ref                                                                                                                             |

### Performance

| Flag            | Description                 |
| :-------------- | :-------------------------- |
| `--no-cache`    | Disable incremental caching |
| `--threads <N>` | Number of parser threads    |

### Regression gate

| Flag                     | Description                                                                                                                                                                                                                                      |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--gate new`             | Fail (exit code **8**) only when the change introduces a NEW security-sink candidate in the changed lines, not on the whole candidate backlog. Requires a diff source (`--changed-since`, `--diff-file`, or `--diff-stdin`).                     |
| `--gate newly-reachable` | Fail (exit code **8**) when a security candidate that already exists in source becomes reachable from project entry points compared with the base ref. Requires `--changed-since <ref>` because it analyzes the base tree, not only a line diff. |

A refactor that merely touches a file already containing a sink passes; a change that adds a
new sink, or wires a new untrusted source into an existing sink, on a changed line fails.
Gated findings stay unverified: the human output says `REVIEW REQUIRED` (not
`FAIL`), SARIF keeps every result at `level: note` with the verdict in
`run.properties.fallowGate`, and `--format json` carries an additive `gate` block
(`mode` / `verdict` / `new_count`). `newly-reachable` ignores unreachable candidates in both
trees; diff-only inputs (`--diff-file` / `--diff-stdin`) exit 2 for this mode.

Exit codes: **8** = a new candidate was introduced in the changed lines; **0** = clean (or a docs-only / empty
diff); **2** = the gate could not compute the diff (an unfetched ref on a shallow clone, a bad
ref, not a git repo), loud rather than a silent pass. Exit 8 is dedicated and stable, so a
pipeline can soft-gate it without allow-listing real errors (GitLab
`allow_failure: exit_codes: [8]`).

<Note>
  On a shallow clone the merge-base may not be fetched. In GitHub Actions set
  `fetch-depth: 0` on `actions/checkout`; in GitLab CI set `GIT_DEPTH: 0`.
</Note>

```bash CI gate on changed lines theme={null}
# GitHub Action / generic CI: gate the PR's committed range
fallow security --gate new --changed-since "$BASE_SHA"

# Gate existing sinks that became entry-point reachable
fallow security --gate newly-reachable --changed-since "$BASE_SHA"

# Pre-commit hook: gate the STAGED content (not committed HEAD)
git diff --cached --unified=0 | fallow security --gate new --diff-stdin
```

## Rule: client-server-leak

The detector starts at files with a top-level `"use client"` directive and walks static imports. It reports a candidate when the client boundary can reach a module that reads a non-public `process.env` value.

Public-by-convention env values are excluded:

| Public prefix   | Example                            |
| :-------------- | :--------------------------------- |
| `NODE_ENV`      | `process.env.NODE_ENV`             |
| `NEXT_PUBLIC_*` | `process.env.NEXT_PUBLIC_API_URL`  |
| `VITE_*`        | `process.env.VITE_API_URL`         |
| `NUXT_PUBLIC_*` | `process.env.NUXT_PUBLIC_SITE_URL` |
| `REACT_APP_*`   | `process.env.REACT_APP_API_URL`    |
| `PUBLIC_*`      | `process.env.PUBLIC_SITE_URL`      |
| `GATSBY_*`      | `process.env.GATSBY_SITE_URL`      |
| `EXPO_PUBLIC_*` | `process.env.EXPO_PUBLIC_API_URL`  |
| `STORYBOOK_*`   | `process.env.STORYBOOK_THEME`      |

Dynamic `import()` edges that the graph cannot follow are counted in the output as unresolved edge files. A clean finding list with a non-zero unresolved count is not a clean bill.

The same client cone is checked against a second sink set, reported as the `server-only-import` category: a `"use client"` file that transitively reaches a server-only module. A module counts as server-only when it carries a `"use server"` directive, imports the `server-only` package, `next/server`, `node:fs` / `node:fs/promises`, or `node:child_process` (the `node:` and bare forms both count), or imports a server-only `next/headers` API (`cookies`, `headers`, `draftMode`). The sink set is intentionally narrow to avoid false positives, and a module pulled in only through `next/dynamic(() => import('./x'), { ssr: false })` (the sanctioned client-only escape hatch) is excluded. Findings in this category are labeled distinctly in human output and use the SARIF rule id `security/server-only-import`; the secret-leak and server-only checks are independent, so a client cone that both reads a secret and reaches server-only code produces a finding for each.

## Rule: tainted-sink (catalogue)

A data-driven catalogue of syntactic sink candidates. Where `client-server-leak` is a graph-reachability rule, `tainted-sink` flags a call, member assignment, or tagged template that reaches a known dangerous sink. Most rows require a **non-literal** argument; narrowly literal-aware rows flag deterministic unsafe literals such as wildcard `postMessage` origins, weak crypto algorithms, disabled TLS validation, and JWT algorithm issues.

All catalogue findings carry `kind: "tainted-sink"` plus a `category` (the catalogue id) and a `cwe` number. The catalogue ships these categories:

| Category                         | CWE  | Sink shape                                                                                                                                                                   |
| :------------------------------- | :--- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dangerous-html`                 | 79   | `innerHTML` / `outerHTML` / `insertAdjacentHTML` / `dangerouslySetInnerHTML`                                                                                                 |
| `template-escape-bypass`         | 79   | template-engine `SafeString(...)` wrapping a non-literal value                                                                                                               |
| `command-injection`              | 78   | `child_process` `exec` / `execSync` / `spawn` / `spawnSync` (import-provenance gated)                                                                                        |
| `code-injection`                 | 94   | `eval` / `vm.runInNewContext`                                                                                                                                                |
| `dynamic-regex`                  | 1333 | `RegExp(...)` / `new RegExp(...)` with a non-literal pattern                                                                                                                 |
| `redos-regex`                    | 1333 | vulnerable regex literals tested with source-backed input                                                                                                                    |
| `resource-amplification`         | 400  | source-backed size into `Array(...)` / `new Array(...)` / `Buffer.alloc*` / `String.prototype.repeat` / `padStart` / `padEnd` (directly `Math.min`-clamped sizes stay quiet) |
| `dynamic-module-load`            | 95   | dynamic `require(...)`                                                                                                                                                       |
| `sql-injection`                  | 89   | `query` / `execute` with concatenation or interpolation, raw escape hatches (`sql.raw`, Prisma unsafe raw, Knex raw, `sequelize.literal`)                                    |
| `ssrf`                           | 918  | `fetch` / `got` / `ky` / `needle` / `request` / `axios` / `superagent` / `undici` / `http(s).request`                                                                        |
| `path-traversal`                 | 22   | `path.join` / `path.resolve` / `node:fs` path methods / route `sendFile`                                                                                                     |
| `header-injection`               | 113  | response `setHeader` / `writeHead`                                                                                                                                           |
| `open-redirect`                  | 601  | `res.redirect` / `location.href` / `location.assign` / `window.open`                                                                                                         |
| `postmessage-wildcard-origin`    | 346  | `postMessage(..., "*")`                                                                                                                                                      |
| `tls-validation-disabled`        | 295  | HTTPS/TLS options with `rejectUnauthorized: false`, plus `NODE_TLS_REJECT_UNAUTHORIZED = "0"`                                                                                |
| `cleartext-transport`            | 319  | cleartext `http://` URLs in fetch-like calls and WebSocket constructors                                                                                                      |
| `electron-unsafe-webpreferences` | 1188 | Electron `webPreferences` with unsafe literal options                                                                                                                        |
| `world-writable-permission`      | 732  | `chmod` / `chmodSync` with world-writable modes                                                                                                                              |
| `insecure-temp-file`             | 377  | predictable temporary file paths in `fs` writes                                                                                                                              |
| `mysql-multiple-statements`      | 89   | MySQL connection options with `multipleStatements: true`                                                                                                                     |
| `permissive-cors`                | 942  | CORS wildcard origin with credentials                                                                                                                                        |
| `insecure-cookie`                | 614  | cookie options missing or disabling `httpOnly` / `secure`                                                                                                                    |
| `mass-assignment`                | 915  | source-backed `Object.assign(target, source)`                                                                                                                                |
| `weak-crypto`                    | 327  | runtime-selectable hash or cipher algorithm                                                                                                                                  |
| `deprecated-cipher`              | 327  | `crypto.createCipher` / `createDecipher` (no IV, MD5-based KDF)                                                                                                              |
| `insecure-randomness`            | 338  | `crypto.pseudoRandomBytes(...)`                                                                                                                                              |
| `unsafe-buffer-alloc`            | 1188 | `Buffer.allocUnsafe` / `allocUnsafeSlow` (uninitialized memory)                                                                                                              |
| `unsafe-deserialization`         | 502  | `js-yaml` `load` / `node-serialize`                                                                                                                                          |
| `prototype-pollution`            | 1321 | `__proto__` writes and recursive merge sources                                                                                                                               |
| `zip-slip`                       | 22   | archive extraction destination paths                                                                                                                                         |
| `nosql-injection`                | 943  | Mongo / Mongoose query object passthrough                                                                                                                                    |
| `ssti`                           | 1336 | template engine compile / render calls                                                                                                                                       |
| `xxe`                            | 611  | XML parse calls                                                                                                                                                              |
| `secret-pii-log`                 | 532  | source-backed secrets or request PII reaching logs                                                                                                                           |
| `hardcoded-secret`               | 798  | provider-prefix credentials and high-entropy literals assigned to secret-shaped identifiers (include-required)                                                               |
| `secret-to-network`              | 201  | a non-public `process.env` / `import.meta.env` secret reaching a network call body (`fetch` / `axios` / `got` / ...) via same-identifier flow (include-required)             |
| `llm-call-injection`             | 1427 | an untrusted source reaching the prompt/messages argument of a known LLM-call sink (taint-path gated, pinned to distinctive LLM SDK call shapes)                             |
| `xpath-injection`                | 643  | `xpath.select` / `select1` with a non-literal expression                                                                                                                     |
| `jwt-alg-none`                   | 347  | JWT signing with algorithm `none`                                                                                                                                            |
| `jwt-verify-missing-algorithms`  | 347  | `jsonwebtoken` verify calls missing an `algorithms` allowlist                                                                                                                |
| `webview-injection`              | 94   | react-native-webview `injectJavaScript(...)` / `injectedJavaScript=` (enabler-gated)                                                                                         |
| `angular-trusted-html`           | 79   | Angular `bypassSecurityTrust*` (enabler-gated)                                                                                                                               |
| `nextjs-open-redirect`           | 601  | Next.js `redirect` / `permanentRedirect` (enabler-gated)                                                                                                                     |
| `dom-document-write`             | 79   | `document.write` / `document.writeln`                                                                                                                                        |
| `jquery-html`                    | 79   | jQuery `.html(value)` (enabler-gated)                                                                                                                                        |
| `route-send-file`                | 22   | Express / Fastify / Hono route `sendFile` (enabler-gated)                                                                                                                    |

<Note>
  These are deliberately conservative candidates: a non-literal argument is a signal to verify, not proof of a vulnerability. Fallow does not prove the value is attacker-controlled or reaches the sink unsanitized. Verification is the agent's job.
</Note>

Sink-shaped nodes whose callee cannot be resolved to a static path (dynamic dispatch, computed members, aliased bindings) are counted in the output as `unresolved_callee_sites`. When emitted, `unresolved_callee_diagnostics` adds bounded sample locations, top files, and reason counts for follow-up review. As with `client-server-leak`, a clean finding list with a non-zero count is not a clean bill.

### Sanitizer-aware suppression

Trusted local sanitizer flows do not report. The detector recognizes syntax-proven local HTML escape helpers, renderer helpers whose dynamic HTML fragments are fully sanitizer-backed, and SQL identifier quoting helpers used in identifier positions. Mixed HTML or SQL templates with unsanitized dynamic fragments still report as candidates, and SQL identifier quoting is not treated as value parameterization.

### Enabling categories

Scope which catalogue categories run with `security.categories` in config:

```json theme={null}
{
  "security": {
    "categories": {
      "include": ["dangerous-html", "command-injection", "hardcoded-secret"],
      "exclude": []
    }
  }
}
```

With both lists empty, ordinary catalogue categories are active. `hardcoded-secret` and `secret-to-network` are intentionally include-required and only run when listed in `security.categories.include`. `secret-to-network` is opt-in because legitimate auth (sending a bearer token to its own provider) is also a secret reaching a network call; each candidate carries the destination (`candidate.network.destination`, the request URL when it is a literal, or absent when the URL is dynamic) so you can tell exfil from intended auth. Public-by-convention env vars (`NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`, ...) are never treated as secrets.

## Suppression

Suppress a known false positive at file level. Each rule has its own token:

```ts theme={null}
// fallow-ignore-file security-client-server-leak
"use client";
```

```ts theme={null}
// fallow-ignore-file security-sink
const el = document.querySelector(".out");
el.innerHTML = render(userInput);
```

One `security-sink` token covers every catalogue category. Use suppression only after verifying that the value cannot reach the sink unsanitized, for example because the input is a trusted constant, server-only, or sanitized upstream.

## JSON output

`--format json` emits a typed root envelope with `kind: "security"`.

```json theme={null}
{
  "kind": "security",
  "schema_version": 8,
  "version": "3.24.1",
  "elapsed_ms": 42,
  "config": {
    "rules": {
      "security_client_server_leak": {
        "configured": "off",
        "effective": "warn"
      },
      "security_sink": {
        "configured": "off",
        "effective": "warn"
      }
    },
    "categories_include": null,
    "categories_exclude": null
  },
  "security_findings": [],
  "unresolved_edge_files": 0,
  "unresolved_callee_sites": 0,
  "unresolved_callee_diagnostics": null
}
```

`fallow security --summary --format json --quiet` emits the same `kind`, `schema_version`, `version`, `elapsed_ms`, and `config` metadata, but replaces candidate arrays with `summary` aggregate counts:

```json title="excerpt" theme={null}
{
  "kind": "security",
  "summary": {
    "security_findings": 0,
    "by_severity": {
      "high": 0,
      "medium": 0,
      "low": 0
    },
    "by_category": {},
    "by_reachability": {
      "entry_reachable": 0,
      "untrusted_source_reachable": 0,
      "arg_level": 0,
      "module_level": 0,
      "crosses_boundary": 0,
      "source_backed": 0
    },
    "by_runtime_state": {
      "runtime_hot": 0,
      "runtime_cold": 0,
      "never_executed": 0,
      "low_traffic": 0,
      "coverage_unavailable": 0,
      "runtime_unknown": 0,
      "not_collected": 0
    },
    "unresolved_edge_files": 0,
    "unresolved_callee_sites": 0,
    "attack_surface_entries": 0
  }
}
```

`attack_surface` is present only when you pass `--surface`. Use it when an agent verifier needs source-to-sink path context and defensive-boundary prompts.

Each finding includes `kind`, `path`, `line`, `col`, `evidence`, `trace`, `actions`, `severity`, and optional `reachability`. `severity` is a review-priority tier (`high`, `medium`, or `low`) derived from reachability, boundary, source-backed, and runtime-hot signals. It is not a verified vulnerability verdict and does not change gate or exit semantics. SARIF maps high and medium candidates to `warning`, and low candidates to `note`. `tainted-sink` findings additionally carry `category` (the catalogue id, for example `"dangerous-html"`) and `cwe` (the category's CWE number); `client-server-leak` findings omit both. `tainted-sink` findings can also include `reachability.untrusted_source_trace` when a module with a known untrusted source imports the sink module. It is ranking and triage context only, not proof that a specific value reaches the sink.

When `reachability.reachable_from_untrusted_source` is set, `reachability.taint_confidence` tiers the association: `"arg-level"` means the sink argument traces back to a source read in the same module, directly or through up to three chained local bindings (the stronger candidate), and `"module-level"` means the sink only lives in a module reachable from a source over the import graph (the weaker candidate). Tier candidates from this field rather than parsing the `evidence` text. For arg-level findings the trace's first hop points at the line of the actual source read; module-level source hops use the role `"module-source"` and never imply a proven value path.

When present, `unresolved_callee_diagnostics` adds bounded unresolved-callee metadata for follow-up review: `sampled[]` rows with `path`, `line`, `col`, `reason`, and `expression_kind`, `top_files[]` counts, `by_reason[]` counts, and the emitted sample/top-file limits. It is blind-spot metadata, not a finding list, and follows the same `--file`, `--workspace`, `--changed-since`, and `--gate new` scoping as security candidates.

### Agent-actionable candidate record

Every finding also carries a `candidate` record, an optional `taint_flow` triple, and a stable `finding_id`, designed for an agent to act on without re-deriving anything from the evidence string.

```json theme={null}
{
  "finding_id": "9a705395d3b50465",
  "kind": "tainted-sink",
  "category": "command-injection",
  "cwe": 78,
  "path": "src/runner.ts",
  "line": 4,
  "col": 2,
  "candidate": {
    "source_kind": null,
    "sink": {
      "path": "src/runner.ts",
      "line": 4,
      "col": 2,
      "category": "command-injection",
      "cwe": 78,
      "callee": "child_process.exec"
    },
    "boundary": { "client_server": false, "cross_module": true }
  },
  "taint_flow": {
    "source": { "path": "src/route.ts", "line": 1, "col": 9 },
    "sink": { "path": "src/runner.ts", "line": 4, "col": 2 },
    "path": { "intra_module": false, "cross_module_hops": 1 }
  }
}
```

The `candidate` record has three slots:

* `source_kind`: the kind of untrusted input that reaches the sink, as a stable catalogue source id such as `"http-request-input"`, `"process-env"`, `"process-argv"`, `"message-event-data"`, or `"location-input"`. Absent when no untrusted source matched (always absent for `client-server-leak`). Treat an unknown id as an untrusted source of unknown kind; never drop a candidate on that basis.
* `sink`: a self-contained description of the sink site (`path`, `line`, `col`, `category`, `cwe`, and the captured `callee`), so you can act on `candidate.sink` without reading the rest of the finding. URL-category sinks (SSRF, open redirect) may add `url_shape` when it is statically visible: `"fixed-origin-dynamic-path"` (fixed origin with dynamic path or query, the lower-alarm shape) or `"dynamic-origin"` (the origin itself is dynamic).
* `boundary`: whether the flow crosses a `client_server` boundary (a `"use client"` file in the trace) or a `cross_module` boundary (the source reaches the sink across one or more import hops), plus an `architecture_zone` (`from`/`to`) when the anchor also participates in a declared architecture-boundary violation.

There is no `impact` field. Deciding exploitability is the verifying agent's job, not fallow's; fallow flags candidates with structural evidence and a severity-based review-priority tier.

`taint_flow` is present only when an untrusted source is import-reachable to the sink. It is the `{ source, sink, path }` shape agent SAST tooling expects. `path` is a compact summary (`intra_module` and `cross_module_hops`); the full ordered hop list lives in `reachability.untrusted_source_trace` and is not duplicated.

`candidate.network` is present only on `secret-to-network` candidates. It carries `destination`: the network call's URL when it is a static string literal (usually intended auth, the credential's own provider) or absent when the destination is dynamic (the higher-signal exfil case). Use it to triage exfil from intended auth without re-reading the code.

`finding_id` is a stable correlation id, identical across runs for the same rule, path, and line, and identical to the finding's SARIF `partialFingerprints` value. Use it to track a candidate across runs (for example after a rebase) and to join JSON and SARIF output.

## Subcommands

Two read-only subcommands support the agent-verification loop. They never re-run analysis assumptions into the candidate output: `survivors` joins existing candidates with an external verifier's verdicts, and `blind-spots` reshapes the unresolved-callee diagnostics fallow already produces. See [Security agent verification](/cli/security-agent-verification) for the end-to-end recipe and the `fallow-security-verdict/v1` verdict schema.

### survivors

Join raw `fallow security --format json` candidate output with a verifier's verdict file and render only the candidates the verifier retained as survivors, without rewriting the original candidate fields.

```bash theme={null}
fallow security --format json --quiet > candidates.json
# (run your verifier, writing verdicts.json keyed by finding_id)
fallow security survivors --candidates candidates.json --verdicts verdicts.json
```

| Flag                                   | Description                                                                                                       |
| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| `--candidates <PATH>`                  | Raw `fallow security --format json` candidate output (required)                                                   |
| `--verdicts <PATH>`                    | Verifier verdict JSON file, one `fallow-security-verdict/v1` entry per `finding_id` (required)                    |
| `--require-verdict-for-each-candidate` | Fail with a structured exit 2 when any candidate has no matching verdict, for CI that must review every candidate |
| `-f, --format <FORMAT>`                | Output format: `human` (default) or `json`                                                                        |
| `-o, --output-file <PATH>`             | Write the report to a file instead of stdout                                                                      |

The output reports `summary.unverdicted` so consumers can distinguish reviewed from unreviewed candidates, and the human renderer separates verifier dispositions from candidates that still need review. Without `--require-verdict-for-each-candidate`, an incomplete verdict file is surfaced (via `summary.unverdicted`) rather than failing.

### blind-spots

Group the unresolved security callees fallow could not resolve (dynamic dispatch, unmodeled framework entry points) into actionable blind-spot output, so a verifier knows where the structural trace stops. `--file` is accepted both before and after the subcommand.

```bash theme={null}
fallow security blind-spots --format json --quiet
```

| Flag                                                         | Description                                                                               |
| :----------------------------------------------------------- | :---------------------------------------------------------------------------------------- |
| `-f, --format <FORMAT>`                                      | Output format: `human` (default) or `json`                                                |
| `--file <PATH>`                                              | Scope diagnostics to selected files (repeatable; accepted before or after the subcommand) |
| `--changed-since <REF>`                                      | Scope to files changed since this git ref                                                 |
| `--diff-file <PATH>` / `--diff-stdin`                        | Unified diff for line-level scoping                                                       |
| `-w, --workspace <WORKSPACE>` / `--changed-workspaces <REF>` | Scope output to selected or recently touched workspaces                                   |
| `-r, --root <ROOT>` / `-c, --config <CONFIG>`                | Project root and config path                                                              |
| `-q, --quiet` / `--no-cache` / `--threads <N>`               | Standard analysis controls                                                                |
| `-o, --output-file <PATH>`                                   | Write the report to a file instead of stdout                                              |

## Examples

<CodeGroup>
  ```bash Basic scan theme={null}
  fallow security
  ```

  ```bash JSON for agents theme={null}
  fallow security --format json --quiet
  ```

  ```bash GitHub Code Scanning theme={null}
  fallow security --ci --sarif-file fallow-security.sarif
  ```

  ```bash PR-scoped scan theme={null}
  git diff --unified=0 origin/main...HEAD | fallow security --diff-file -
  ```
</CodeGroup>

## See also

<CardGroup>
  <Card title="Security agent verification" icon="shield-check" href="/cli/security-agent-verification">
    Hand candidates to a verifier and render the survivors.
  </Card>

  <Card title="Global flags" icon="sliders" href="/cli/global-flags">
    Scoping, output, and performance flags shared by every command.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use fallow tools from AI coding agents.
  </Card>
</CardGroup>


# Security agent verification
Source: https://docs.fallow.tools/cli/security-agent-verification

Turn fallow security candidates into verifier-filtered survivor reports without adding model calls to fallow.

`fallow security` produces deterministic candidates. It does not call a model, decide exploitability, or emit verified vulnerabilities. Use this recipe when an agent or external harness should turn raw candidates into a shorter survivor list.

## Inputs

Use the CLI when you want a standalone JSON file:

```bash theme={null}
fallow security --format json --surface --quiet > fallow-security.json
```

Use MCP when an agent is already in an edit loop:

```json theme={null}
{
  "root": "/path/to/repo",
  "surface": true,
  "paths": ["src/routes/login.ts"]
}
```

`surface: true` forwards `--surface` and includes top-level `attack_surface[]` entries. Set `gate` to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires `changed_since`. `paths` forwards repeated `--file` filters and scopes returned candidates to matching anchors, trace hops, source-trace hops, and unresolved-callee diagnostics.

Each candidate includes `severity`, a review-priority tier (`high`, `medium`, or `low`). It is not a verified vulnerability verdict. When `reachability.taint_confidence` is present, use it to distinguish `arg-level` source association from weaker `module-level` reachability.

## Verifier packet

For each `security_findings[]` item, build one packet from deterministic fallow evidence plus caller-collected source windows:

```json theme={null}
{
  "schema_version": "fallow-security-verifier-input/v1",
  "finding_id": "security:...",
  "severity": "high",
  "candidate": {
    "source_kind": "http-request-input",
    "sink": {},
    "boundary": {}
  },
  "trace": [],
  "taint_flow": null,
  "taint_confidence": "arg-level",
  "reachability_trace": [],
  "attack_surface": null,
  "source_windows": [
    {
      "path": "src/routes/login.ts",
      "start_line": 12,
      "end_line": 52,
      "text": "..."
    }
  ],
  "blind_spots": {
    "unresolved_edge_files": 0,
    "unresolved_callee_sites": 0,
    "unresolved_callee_diagnostics": null
  }
}
```

Collect source windows from disk after the scan. Keep them outside fallow output so the core stays deterministic, compact, and provider-neutral.

`blind_spots.unresolved_callee_diagnostics` can copy the top-level fallow output when a verifier queue wants sample locations for dynamic-dispatch follow-up. It is bounded metadata, not proof of a vulnerability.

## Prompt contract

Ask the verifier to dismiss candidates unless the supplied evidence supports a real exploit path:

```text theme={null}
You are verifying one fallow security candidate.

Fallow is a deterministic candidate producer, not a vulnerability oracle.
Use only the supplied candidate, trace, attack-surface entry, and source windows.
Do not assume data flow beyond the provided code.

Check:
1. Is the input attacker-controlled?
2. Does the value reach the reported sink?
3. Is the reported boundary relevant to exploitability?
4. What concrete impact would remain if the candidate is real?
5. Is there an existing defensive control that dismisses it?

Return only JSON matching fallow-security-verdict/v1.
```

If `attack_surface.defensive_boundary.verification_prompt` is present, include it as an additional question, not as a verdict.

## Verdict schema

Require a compact JSON verdict:

```json theme={null}
{
  "schema_version": "fallow-security-verdict/v1",
  "finding_id": "security:...",
  "verdict": "survivor",
  "reason": "The request query value reaches execSync without validation.",
  "impact": "Command injection through the id query parameter.",
  "evidence_checked": {
    "source": true,
    "sink": true,
    "boundary": true,
    "trace": true,
    "source_window": true
  },
  "dismissal_reason": null,
  "fix_direction": "avoid-shell"
}
```

Allowed verdicts:

* `survivor`: the verifier could not dismiss the candidate from the supplied evidence.
* `dismissed`: the candidate is not exploitable from the supplied evidence.
* `needs-human-review`: the evidence is incomplete, contradictory, or blocked by missing context.

Store verifier output beside the original fallow JSON, keyed by `finding_id`. Do not write verdict fields back into fallow output.

## Render survivors

Join the candidates and the verdict file with [`fallow security survivors`](/cli/security#survivors) to render only the candidates the verifier retained:

```bash theme={null}
fallow security --format json --quiet > candidates.json
# (verifier writes verdicts.json keyed by finding_id)
fallow security survivors --candidates candidates.json --verdicts verdicts.json
```

It reports `summary.unverdicted` so unreviewed candidates stay visible; add `--require-verdict-for-each-candidate` to fail CI when any candidate lacks a verdict. To see where the structural trace stopped (unresolved callees the verifier should inspect by hand), run [`fallow security blind-spots`](/cli/security#blind-spots).

## Caveats

Candidate quality depends on source and trace fidelity. HTTP-input source patterns are receiver-gated to avoid broad `*.query` collisions with unrelated APIs, but framework-specific request aliases can still need verifier judgment. `reachability.taint_confidence` distinguishes `arg-level` from `module-level` source association; use `severity` and `taint_confidence` for triage order, then verify source control, value flow, sink behavior, and defensive controls from source windows before reporting a survivor.

## See also

<CardGroup>
  <Card title="fallow security" icon="shield" href="/cli/security">
    CLI reference for security candidates.
  </Card>

  <Card title="MCP integration" icon="plug" href="/integrations/mcp">
    Agent setup and tool contracts.
  </Card>
</CardGroup>


# fallow suppressions
Source: https://docs.fallow.tools/cli/suppressions

CLI reference for fallow suppressions. A read-only inventory of every active fallow-ignore marker, grouped per file with kind, level, and reason, plus project totals and a stale cross-reference.

List every active `fallow-ignore-next-line` and `fallow-ignore-file` marker in the analyzed files, grouped per file with line, kind, level, and reason, plus project totals and a stale count cross-referenced against this run's stale-suppression findings. A governance surface, not a detector: it always exits 0.

```bash theme={null}
fallow suppressions
```

```text theme={null}
● Suppression inventory (1)
  src/util.ts
    :1 unused-export (file-wide) reason: legacy surface for the v2 SDK migration window

● Totals by kind
  unused-export: 1
```

Markers declare a reason with a `--` separator; the inventory reports markers without one so reason coverage is enforceable:

```typescript theme={null}
// fallow-ignore-file unused-export -- legacy surface for the v2 SDK migration window
```

## Options

| Flag                         | Description                                                 |
| :--------------------------- | :---------------------------------------------------------- |
| `--file <PATH>`              | Only list suppressions in the specified files. Repeatable.  |
| `-w, --workspace <PATTERNS>` | Scope to one or more workspace packages                     |
| `--changed-workspaces <REF>` | Scope to workspaces containing any file changed since `REF` |
| `--changed-since <REF>`      | Scope to files changed since a git ref                      |
| `-f, --format <FORMAT>`      | `human` (default) or `json`                                 |
| `-r, --root <ROOT>`          | Project root directory                                      |
| `-q, --quiet`                | Suppress progress output on stderr                          |

## JSON output

`--format json` emits the `suppression-inventory` envelope (schema version 1). Blanket markers (no kind, suppressing everything) carry `kind: null`; human output reads "blanket".

```json theme={null}
{
  "kind": "suppression-inventory",
  "schema_version": "1",
  "summary": {
    "total": 1,
    "files": 1,
    "without_reason": 0,
    "stale": 0,
    "by_kind": [
      { "kind": "unused-export", "count": 1 }
    ]
  },
  "files": [
    {
      "path": "src/util.ts",
      "suppressions": [
        {
          "line": 1,
          "kind": "unused-export",
          "level": "file",
          "origin": "comment",
          "reason": "legacy surface for the v2 SDK migration window",
          "reason_present": true
        }
      ]
    }
  ]
}
```

The `stale` count is a cross-reference (a join against this run's [stale-suppression findings](/analysis/dead-code#stale-suppressions)), not a new detection: a marker is stale when it no longer matches any issue.

## MCP tool

Agents on the MCP surface reach the same inventory through the `list_suppressions` tool, which returns this envelope verbatim. It runs a full analysis, so raise `FALLOW_TIMEOUT_SECS` on large repositories. See [MCP integration](/integrations/mcp).

## See also

<CardGroup>
  <Card title="Suppression comments" icon="comment-slash" href="/configuration/rules">
    Inline suppression syntax and rule severities
  </Card>

  <Card title="Global flags" icon="sliders" href="/cli/global-flags">
    Flags available on all commands
  </Card>
</CardGroup>


# fallow telemetry
Source: https://docs.fallow.tools/cli/telemetry

CLI reference for fallow telemetry. Opt-in, off-by-default product telemetry for improving agent, CI, MCP, and editor workflows. Inspect the exact payload, enable, disable, or check status.

Manage opt-in product telemetry. Telemetry is **off by default** and exists to improve agent, CI, JSON, MCP, and editor workflows.

```bash theme={null}
fallow telemetry status
```

[Telemetry & privacy](/explanations/telemetry) is the data and privacy contract: what is never collected, what one event contains, and how it is sent. To opt out on one machine, run `fallow telemetry disable`.

## Subcommands

### `status`

Show whether telemetry is on or off, what decided that (admin env var, shell env var, user config, or the default), the config file path, and the commands to change it.

```bash theme={null}
fallow telemetry status
```

### `enable` / `disable`

Turn telemetry on or off in the user-level config file. This requires an explicit human action; agents and wrappers must not enable telemetry automatically.

```bash theme={null}
fallow telemetry enable
fallow telemetry disable
```

Enabling is refused when `DO_NOT_TRACK` or `FALLOW_TELEMETRY_DISABLED` is set.

### `inspect`

Explain inspect mode, or print documented example payloads with field purposes.

```bash theme={null}
fallow telemetry inspect            # explain how to inspect a real run
fallow telemetry inspect --example  # print an example payload + field purposes
```

To see the exact payload a real command would send, **without sending it**, prefix the command with `FALLOW_TELEMETRY=inspect`:

```bash theme={null}
FALLOW_TELEMETRY=inspect fallow audit --format json --quiet
```

The inspected payload is printed to stderr; your command's normal output (including `--format json` on stdout) is untouched.

## Precedence

```text theme={null}
DO_NOT_TRACK / FALLOW_TELEMETRY_DISABLED   (admin/fleet kill switch)
> FALLOW_TELEMETRY_DEBUG                     (forces inspect mode)
> FALLOW_TELEMETRY                           (per-shell override)
> CI: off unless FALLOW_TELEMETRY is set
> user telemetry config                      (fallow telemetry enable/disable)
> default: off
```

In CI, telemetry is off unless `FALLOW_TELEMETRY` is explicitly set in that CI environment. A developer's local `fallow telemetry enable` does not enable organization CI telemetry.

## Environment controls

| Variable                    | Description                                                                                      | Values                                                                           |
| :-------------------------- | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| `FALLOW_TELEMETRY`          | Per-shell mode override                                                                          | `off`/`0`/`false`/`disabled`, `on`/`1`/`true`/`enabled`, `inspect`/`debug`/`log` |
| `FALLOW_TELEMETRY_DISABLED` | Admin/fleet kill switch (top precedence)                                                         | `1`, `true`, `yes`, `on`                                                         |
| `FALLOW_TELEMETRY_DEBUG`    | Forces inspect mode (outranks `FALLOW_TELEMETRY`)                                                | `1`, `true`, `yes`, `on`                                                         |
| `DO_NOT_TRACK`              | Honored as a top-precedence kill switch ([consoledonottrack.com](https://consoledonottrack.com)) | `1`, `true`, `yes`, `on`                                                         |
| `FALLOW_AGENT_SOURCE`       | Declare the calling agent for classification                                                     | see [Agent source](#agent-source)                                                |

## Agent source

If the user has already enabled telemetry, an agent or wrapper can tag the run with its own name, using one value from the fixed list below:

```bash theme={null}
export FALLOW_AGENT_SOURCE=codex
```

Accepted values: `codex`, `claude_code`, `cursor`, `copilot`, `opencode`, `aider`, `roo`, `windsurf`, `gemini` (aliases `gemini_cli` / `antigravity`), `cline`, `continue`, `zed`, `goose`, `other_known`, `unknown`, `none`. Hyphen aliases such as `claude-code` are normalized. Unrecognized values are ignored rather than uploaded. Agents not on the list (for example enterprise IDE assistants) are grouped under `other_known`. **Setting `FALLOW_AGENT_SOURCE` never enables telemetry by itself and uploads no codebase content.**

When more than one agent environment is present at once, Fallow guesses which one is calling, and the guess can depend on the order it checks them. Set `FALLOW_AGENT_SOURCE` to name the agent yourself and get a reliable result.


# fallow trace
Source: https://docs.fallow.tools/cli/trace

CLI reference for fallow trace. Walk the callers and callees of one exported symbol through the module graph, or find the shortest import path between two modules. A standalone, best-effort surface, separate from the ranked review brief.

Walk the symbol-level call chain for one exported symbol: callers **up** (modules that import the symbol) and callees **down** (import-symbol edges plus intra-module call sites), bounded by `--depth`. `trace` is its own surface for following how a symbol connects through the codebase before you change it.

```bash theme={null}
fallow trace src/api.ts:fetchUser --format json --quiet
fallow trace src/api.ts:fetchUser --callers --depth 2
fallow trace --path src/app.ts src/db.ts
```

`--path` answers a different question from the symbol target: which chain of imports carries one module to another. See [Import path between two modules](#import-path-between-two-modules).

<Note>
  `fallow trace` is a standalone, best-effort symbol-level surface. It is **not** folded into the ranked [review brief](/cli/audit#review-brief-and-decision-surface) and is never an input to the focus map or its ranking. Use it when you want to see how a symbol connects, not when you want a prioritized review.
</Note>

## Target

`fallow trace` takes one positional argument in `FILE:SYMBOL` form:

```bash theme={null}
fallow trace src/api.ts:fetchUser
```

`FILE` is a project-relative path and `SYMBOL` is the exported symbol name. Omit it when you pass `--path`, which takes two file paths instead.

## Options

| Flag                 | Description                                                                                                                                                               |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--callers`          | Walk only the callers direction.                                                                                                                                          |
| `--callees`          | Walk only the callees direction.                                                                                                                                          |
| `--depth <N>`        | Bound the walk depth in each requested direction.                                                                                                                         |
| `--path <FROM> <TO>` | Find the shortest import path between two modules instead of walking a symbol. Mutually exclusive with the `FILE:SYMBOL` target, `--callers`, `--callees`, and `--depth`. |

When neither `--callers` nor `--callees` is set, both directions are walked. `trace` also accepts the project, output, and performance [global flags](/cli/global-flags) (`--root`, `--config`, `--format` with `human` or `json`, `--quiet`, `--no-cache`, `--threads`, `--changed-since`).

## How it works

The walk is best-effort and syntactic. Resolved and unresolved callees are reported honestly: an unresolved callee (for example, a dynamic call fallow cannot statically resolve) is surfaced as unresolved rather than silently dropped, so the chain reflects what fallow could and could not follow.

When the same export is referenced in both type and value space, JSON output adds `direct_references_by_namespace` with separate evidence for each lane. `namespace` and `direct_references` keep their existing winning-lane meaning for compatibility. The grouped field is omitted when only one lane has references, so consumers should treat its absence as the common single-namespace case.

## Ambiguous star exports

When two `export *` sources contribute the requested name, the barrel exports
nothing under that name. JSON output reports `symbol_found: false` and adds a
`star_export_ambiguity` object:

```json theme={null}
{
  "symbol_found": false,
  "star_export_ambiguity": {
    "sources": ["src/models/admin.ts", "src/models/customer.ts"],
    "namespaces": ["type"]
  }
}
```

`sources` contains the sorted project-relative declaration origins.
`namespaces` identifies whether the collision is in type space, value space,
or both, with `type` before `value`. This field distinguishes a barrel
collision from an unknown or misspelled symbol. Keep one origin, rename the
others, or replace the star exports with explicit re-exports.

The same best-effort call-chain data is available as opt-in evidence on [`fallow inspect --symbol-chain`](/cli/inspect#evidence-flags) and the `inspect_target` MCP tool's `symbol_chain` option.

## Import path between two modules

`fallow trace --path <FROM> <TO>` reports the shortest chain of imports by which `FROM` reaches `TO`. Both are project-relative file paths. Use it when you want to know how a module ends up depending on another one, rather than how a symbol is called.

Exact project-relative or absolute paths take priority over suffix matches. An abbreviation is accepted only when it identifies one module. A missing or ambiguous endpoint exits with code `2`; use the full project-relative path to disambiguate.

```bash title="$ fallow trace --path pages/report.tsx components/Box.tsx" theme={null}
Shortest import path (syntactic; OFF the ranked path)

  from: pages/report.tsx
  to:   components/Box.tsx
  hops: 3

  [1] pages/report.tsx:20 -> lib/related.transform.ts
  [2] lib/related.transform.ts:1 -> components/RelatedContent.tsx
  [3] components/RelatedContent.tsx:3 -> components/Box.tsx
```

JSON output carries the same walk under `kind: "trace"` with its own `schema_version`:

```json title="$ fallow trace --path pages/report.tsx components/Box.tsx --format json" theme={null}
{
  "kind": "trace",
  "schema_version": "1",
  "from": "pages/report.tsx",
  "to": "components/Box.tsx",
  "reachable": true,
  "hops": 3,
  "path": [
    {
      "from": "pages/report.tsx",
      "to": "lib/related.transform.ts",
      "type_only": false,
      "import_line": 20
    },
    {
      "from": "lib/related.transform.ts",
      "to": "components/RelatedContent.tsx",
      "type_only": false,
      "import_line": 1
    },
    {
      "from": "components/RelatedContent.tsx",
      "to": "components/Box.tsx",
      "type_only": false,
      "import_line": 3
    }
  ],
  "reason": "pages/report.tsx reaches components/Box.tsx in 3 hops"
}
```

Three behaviors are worth relying on. A type-only hop is reported with `type_only: true` rather than skipped, so a path that exists only in type space is visible instead of silently absent. An unreachable pair is a result, not an error: `reachable` is `false`, `path` is empty, `hops` is `0`, and `reason` says no import path was found. The command still exits `0`. And tracing a module to itself answers `reachable: true` with `hops: 0`, so branch on `reachable` rather than on the hop count, which is `0` in both cases.

## See also

<CardGroup>
  <Card title="Inspect a target" icon="search-code" href="/cli/inspect">
    Compose one evidence bundle for a file or exported symbol, with opt-in `--symbol-chain`.
  </Card>

  <Card title="Audit and review brief" icon="terminal" href="/cli/audit">
    Changed-file verdict plus the graph-derived review brief and decision surface.
  </Card>

  <Card title="Resolve a stack trace" icon="bug" href="/cli/trace-error">
    Map runtime stack-trace frames back to the definitions they name.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use fallow tools from AI coding agents.
  </Card>
</CardGroup>


# fallow trace-error
Source: https://docs.fallow.tools/cli/trace-error

CLI reference for fallow trace-error. Resolve the frames of a runtime stack trace to the definitions they name, without reading source maps.

Read a runtime stack trace and ask the module graph which definitions its frames name. `trace-error` classifies reported frames as in-project, inside an installed dependency, or outside the analyzed corpus, then resolves the in-project ones against the definitions fallow already extracted.

```bash theme={null}
fallow trace-error crash.txt
cat crash.txt | fallow trace-error
fallow trace-error - --format json --quiet
```

The trace comes from a file argument, from `-`, or from stdin when no argument is given. A relative path is resolved against the project root, matching `--diff-file`. V8 and Node traces are supported, as are SpiderMonkey and JavaScriptCore traces.

<Note>
  `trace-error` is a standalone, best-effort surface. It is not folded into the ranked [review brief](/cli/audit#review-brief-and-decision-surface) and is never an input to the focus map or its ranking.
</Note>

## What it refuses to do

The command reports what it could not answer instead of guessing.

* A frame matching several definitions reports `ambiguous`. It lists bounded candidates and records additional matches in `candidates_omitted`.
* A frame matching nothing reports `not_found` rather than disappearing from the output.
* A frame the graph was never asked about reports `not_attempted`, with the reason.
* Reported frames stay in `frames[]` in input order. `counts` publishes their per-outcome totals, while `frames_omitted` records frames beyond the report limit.

Exact project-relative or absolute file paths take priority over abbreviated suffix matches. If an abbreviated path matches multiple modules, the result preserves that ambiguity.

No source maps are read. A frame inside generated build output is reported as such, because a stale map rebinds silently to the wrong line and a wrong line is worse than no line.

## Options

`trace-error` takes the project, output, and performance [global flags](/cli/global-flags): `--root`, `--config`, `--format` with `human` or `json`, `--pretty`, `--quiet`, `--no-cache`, and `--threads`.

Input is limited to 1 MiB. The report includes up to 256 frames and up to 10 candidate definitions per frame; omitted counts remain explicit. Oversized input exits with code `2`.

## Human output

```text title="$ fallow trace-error crash.txt" theme={null}
Stack-trace frames (syntactic; OFF the ranked path)

  source: crash.txt
  error:  TypeError: Cannot read properties of undefined (reading 'title')

  [0] Box components/Box.tsx:12 [in-project/not-found]
        no definition named 'Box' is exported from the module this frame points at; a module-local function is not in the graph's definition set
  [1] renderWithHooks node_modules/react-dom/cjs/react-dom.development.js:14985 [node-modules/not-attempted]
        frame is in an installed dependency, not in project source
  [2] Object.<anonymous> /opt/build/generated/chunk-4f2a.js:1 [out-of-corpus/not-attempted]
        '/opt/build/generated/chunk-4f2a.js' is generated build output; resolving it back to source needs a source map, which this command does not read

  frames 3 | resolved 0 | ambiguous 0 | not found 1 | not attempted 2
```

Each frame prints its origin and resolution as a `[origin/resolution]` pair, with the reason on the indented line below.

## JSON output

```json title="$ fallow trace-error crash.txt --format json" theme={null}
{
  "kind": "trace-error",
  "schema_version": "1",
  "source": "crash.txt",
  "header": "TypeError: boom",
  "frames": [
    {
      "index": 0,
      "raw": "at transformCard (lib/card.transform.ts:22:9)",
      "function": "transformCard",
      "file": "lib/card.transform.ts",
      "line": 22,
      "column": 9,
      "origin": "in_project",
      "resolution": "resolved",
      "candidates": [
        {
          "file": "lib/card.transform.ts",
          "symbol": "transformCard",
          "kind": "export",
          "line": 20
        }
      ],
      "candidates_omitted": 0,
      "reason": "'transformCard' names lib/card.transform.ts:transformCard (export)"
    }
  ],
  "counts": {
    "frames": 1,
    "frames_omitted": 0,
    "in_project": 1,
    "node_modules": 0,
    "out_of_corpus": 0,
    "resolved": 1,
    "ambiguous": 0,
    "not_found": 0,
    "not_attempted": 0,
    "unparsed_lines": 0
  },
  "reason": "1 frame: 1 resolved, 0 ambiguous, 0 not found, 0 not attempted"
}
```

### Key fields

| Field                         | Type                                                                | Description                                                                                                                                                        |
| :---------------------------- | :------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`                      | string                                                              | `stdin`, or the path exactly as you wrote it.                                                                                                                      |
| `header`                      | string                                                              | The first non-blank line before any frame, verbatim and unparsed. Omitted when the input began with a frame.                                                       |
| `frames[].index`              | integer                                                             | Position in the input trace. Frames keep input order.                                                                                                              |
| `frames[].raw`                | string                                                              | The frame line as it was read.                                                                                                                                     |
| `frames[].origin`             | `"in_project"` \| `"node_modules"` \| `"out_of_corpus"`             | Where the frame's file sits relative to the analyzed corpus.                                                                                                       |
| `frames[].resolution`         | `"resolved"` \| `"ambiguous"` \| `"not_found"` \| `"not_attempted"` | What the graph could say about the frame.                                                                                                                          |
| `frames[].candidates[]`       | array                                                               | Definitions the frame may name, each with `file`, `symbol`, `kind`, and an optional `line` and `member`. Empty unless the resolution is `resolved` or `ambiguous`. |
| `frames[].candidates_omitted` | integer                                                             | Candidates withheld from the array by a cap. `0` when nothing was withheld.                                                                                        |
| `frames[].line_mismatch`      | boolean                                                             | Set on a `resolved` frame whose line sits far from the declaration it matched, so the runtime may have run a same-named definition elsewhere. Omitted when false.  |
| `frames[].reason`             | string                                                              | Why this frame has the resolution it has.                                                                                                                          |
| `counts.unparsed_lines`       | integer                                                             | Input lines that did not parse as a frame.                                                                                                                         |
| `counts.frames_omitted`       | integer                                                             | Frames withheld from the array by a cap.                                                                                                                           |

`counts.frames` is the number of reported frames. Both `resolved + ambiguous + not_found + not_attempted` and `in_project + node_modules + out_of_corpus` equal that number. Add `counts.frames_omitted` to recover the total number of recognized input frames. A trace that is entirely unrecognised reports zero frames and a non-zero `unparsed_lines`, rather than looking like an empty trace.

## For agents

The `trace_error` MCP tool wraps this command. Feed it the stack trace from a failing test or a production error, then read `frames[].candidates[]` for the files worth opening. A `not_found` result on an in-project frame means the graph could not match its name. The function may be module-local, or the runtime name may differ from the extracted definition.

## See also

<CardGroup>
  <Card title="fallow trace" icon="route" href="/cli/trace">
    Walk a symbol's call chain, or find the shortest import path between two modules.
  </Card>

  <Card title="Inspect a target" icon="search-code" href="/cli/inspect">
    Compose one evidence bundle for a file or exported symbol.
  </Card>

  <Card title="MCP integration" icon="robot" href="/integrations/mcp">
    Use fallow tools from AI coding agents.
  </Card>
</CardGroup>


# fallow viz
Source: https://docs.fallow.tools/cli/viz

CLI reference for fallow viz. Render your codebase as a single self-contained interactive HTML map: a file treemap and an import graph, each recolored by dead-code, duplication, boundaries, and complexity lenses.

Render your codebase as an interactive map. `fallow viz` runs one project analysis and writes a single self-contained HTML file (no server, no external assets) styled like the rest of fallow. It is read-only.

```bash theme={null}
fallow viz                       # writes fallow-viz.html and opens it in your browser
fallow viz --out map.html --no-open
fallow viz --viz-format dot      # emit the import graph as Graphviz DOT
fallow viz --viz-format mermaid  # emit the import graph as a Mermaid diagram
```

## The two views

The HTML report gives you two views over the same project:

* **Treemap** of files sized by bytes, nested by directory.
* **Force-directed import graph** with directory and import-community clustering.

## The four lenses

Both views share four lenses that recolor the same map:

| Lens                    | What it shows                                                                                           |
| :---------------------- | :------------------------------------------------------------------------------------------------------ |
| **Dead code**           | Unused files, unused exports, and entry points                                                          |
| **Duplication**         | Share of duplicated lines per file, with clone previews                                                 |
| **Boundaries**          | Architecture zones from your `boundaries` config, with violating imports drawn in red                   |
| **Complexity hotspots** | Per-function cyclomatic and cognitive scores, including React context such as hook counts and JSX depth |

Click any file to open a detail panel with the evidence behind each finding: unused export names, clone groups and their other locations, boundary crossings, cycle membership, importers and imports as click-through navigation, and a runnable `fallow ... --trace` command to verify the finding yourself.

Search, breadcrumb drill-down, keyboard shortcuts, shareable URL deep links, and dark/light themes are built in. Findings carry a hatch texture and `[E]`/`[W]` prefixes so color is never the only signal, and all motion honors `prefers-reduced-motion`.

## Options

| Flag                    | Description                                                                   |
| :---------------------- | :---------------------------------------------------------------------------- |
| `--out <PATH>`          | Output file path (default: `fallow-viz.html` in the project root)             |
| `--no-open`             | Do not open the output file in the browser                                    |
| `--viz-format <FORMAT>` | Visualization output format: `html` (default), `dot` (Graphviz), or `mermaid` |

[Global flags](/cli/global-flags) such as `--root`, `--config`, `--production`, `--no-cache`, `--changed-since`, `--workspace`, and `--threads` also apply.

## Text formats

`--viz-format dot` and `--viz-format mermaid` emit the import graph as text instead of the HTML map, for piping into other tools:

```bash theme={null}
fallow viz --viz-format dot | dot -Tsvg -o graph.svg
fallow viz --viz-format mermaid > graph.mmd
```

## Related

* [`fallow dead-code`](/cli/dead-code), [`fallow dupes`](/cli/dupes), and [`fallow health`](/cli/health) produce the findings the lenses visualize
* [`fallow trace`](/cli/trace) verifies a single finding from the command line, matching the `--trace` command in each detail panel


# fallow watch
Source: https://docs.fallow.tools/cli/watch

CLI reference for fallow watch. Re-run dead code analysis when files change.

Watch mode re-runs dead code analysis when files change. Saves are debounced. Press `Ctrl+C` to stop.

```bash theme={null}
fallow watch
```

<Info>
  Watch mode supports the [global flags](/cli/global-flags) (like `--format`, `--production`, `--fail-on-issues`, `--include-entry-exports`, `--type-aware`, and the `--dupes-*` family). The `dead-code` issue-type filters like `--unused-exports` are not available.
</Info>

## Examples

<CodeGroup>
  ```bash Filtered watch theme={null}
  # Production mode
  fallow watch --production

  # Compact output
  fallow watch --format compact

  # Silent, only show results
  fallow watch --quiet
  ```
</CodeGroup>

## Example output

```bash title="$ fallow watch" theme={null}
Watching 1,008 files for changes...

[10:23:15] File changed: src/server/jobs/queue.ts
[10:23:15] Re-analyzing...

● Unused exports (2)
  src/server/jobs/queue.ts
    :61  enqueueJobDelayed
    :206 sweepStuckProcessingJobs
  Exported symbols with zero references: https://docs.fallow.tools/explanations/dead-code#unused-exports

✗ 2 issues (0.04s)

[10:23:42] File changed: src/server/jobs/queue.ts
[10:23:42] Re-analyzing...

No issues found (0.03s) ✓
```

## See also

<CardGroup>
  <Card title="Dead code analysis" icon="skull-crossbones" href="/analysis/dead-code">
    How fallow detects dead code.
  </Card>

  <Card title="fallow dead-code" icon="terminal" href="/cli/dead-code">
    The one-shot form of the analysis watch mode re-runs.
  </Card>
</CardGroup>


# Cloud beacon setup
Source: https://docs.fallow.tools/cloud/beacon

Connect a browser or Node service to Fallow Cloud, verify the first ingest, and diagnose a setup that stays empty.

The beacon sends function-level execution counts to Fallow Cloud. HTTP mode needs three values before it can send anything: an API key, a project id, and the Fallow Cloud endpoint.

## Browser setup

Install the beacon and an Istanbul-compatible build instrumenter:

```bash theme={null}
npm install @fallow-cli/beacon
npm install --save-dev oxc-coverage-instrument
```

Configure `oxc-coverage-instrument` in the production build so it populates `window.__coverage__`. Then start the browser beacon from the application entrypoint:

```ts theme={null}
import { createBrowserBeacon } from "@fallow-cli/beacon/browser";

const beacon = createBrowserBeacon({
  apiKey: import.meta.env.VITE_BEACON_API_KEY,
  endpoint: "https://api.fallow.cloud",
  projectId: "your-org/your-repo",
  commitSha: import.meta.env.VITE_GIT_SHA,
  coverageOrigin: "production",
});

beacon.start();
```

Use an ingest-only key with prefix `fallow_pub_k1_` in browser code. It can only call `POST /v1/ingest`. Never embed a full `fallow_live_k1_` key in a browser bundle.

The first browser snapshot can contain only startup code. The beacon intentionally skips that incomplete snapshot. Navigate through at least one real workflow, wait for the 30-second flush, or hide the page to trigger a flush.

## Node setup

Node can read V8 coverage when `NODE_V8_COVERAGE` is present before process startup. The beacon cannot enable V8 coverage after the process has started.

```bash theme={null}
NODE_V8_COVERAGE=./coverage node dist/index.js
```

Start the beacon from server code after boot:

```ts theme={null}
import { createNodeBeacon } from "@fallow-cli/beacon";

const beacon = createNodeBeacon({
  apiKey: process.env.BEACON_API_KEY,
  endpoint: "https://api.fallow.cloud",
  projectId: "your-org/your-repo",
  commitSha: process.env.GIT_SHA,
  coverageOrigin: "production",
});

beacon.start();
```

Use a full `fallow_live_k1_` key and keep it server-side. Bun and Deno need build-time Istanbul instrumentation because their V8 capture path is unavailable or incomplete.

## Verify the first ingest

The beacon is quiet on successful uploads. Verify one of these observable signals:

1. `POST https://api.fallow.cloud/v1/ingest` returns `202 Accepted` in the browser network panel or server proxy logs.
2. The onboarding card at [fallow.cloud](https://fallow.cloud) changes to a repository row after aggregation.
3. The key's `last used` value updates under Settings, API keys.

An accepted ingest is asynchronous. A short delay between the `202` response and the repository row is expected.

## If the dashboard stays empty

Check these in order:

1. `endpoint` is exactly `https://api.fallow.cloud`.
2. Browser code uses an ingest-only key. Server code uses a full key.
3. The configured environment variable exists in the production build or process.
4. `projectId` is stable and different for each repository or service.
5. Browser builds contain Istanbul counters, or Node started with `NODE_V8_COVERAGE`.
6. The app exercised real routes or jobs after the beacon started.
7. The first `/v1/ingest` response is `202`, not `401`, `403`, `402`, `413`, or `429`.

When no coverage source is available, the beacon emits one actionable `onRuntimeMismatch` error and stops. Fix that message before waiting for another batch.

## Add static inventory

Runtime capture tells Fallow what V8 or Istanbul observed. Upload the static inventory in CI to make functions that were never tracked visible as `untracked`:

```bash theme={null}
fallow coverage upload-inventory --api-key "$FALLOW_KEY"
```

For bundled or minified code, also upload source maps from CI. See [`fallow coverage`](/cli/coverage) for the inventory and source-map commands.

## Privacy

The beacon sends function paths, names, positions, hit counts, project metadata, and delivery reports. It does not send arguments, request bodies, environment variables, or source code. See the [network activity disclosure](https://fallow.cloud/coverage/network-activity) for the complete contract.


# Boundaries
Source: https://docs.fallow.tools/configuration/boundaries

Configure architecture boundary zones and rules. Use built-in presets or define custom zones to enforce import direction in your codebase.

Boundaries enforce import direction between architectural zones. A zone groups files by glob pattern; a rule declares which zones may import from which. Violations appear as `boundary-violation` issues in `fallow dead-code` output.

Two optional sections extend zones beyond import direction: [`coverage`](#boundary-coverage) reports source files that fall outside every zone, and [`calls`](#forbidden-calls) bans specific callees per zone.

For preset descriptions, output formats, and suppression, see [Architecture boundaries](/analysis/boundaries).

## Presets

Fallow ships four built-in presets for common architecture patterns:

| Preset           | Zones | Description                                                                                       |
| :--------------- | :---- | :------------------------------------------------------------------------------------------------ |
| `layered`        | 4     | Classic N-tier: presentation, application, domain, infrastructure                                 |
| `hexagonal`      | 3     | Ports and adapters: adapters, ports, domain                                                       |
| `feature-sliced` | 6     | [Feature-Sliced Design](https://fsd.how/): strict downward-only imports                           |
| `bulletproof`    | 4     | [Bulletproof React](https://github.com/alan2207/bulletproof-react): app, features, shared, server |

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "preset": "bulletproof"
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [boundaries]
  preset = "bulletproof"
  ```
</CodeGroup>

## tsconfig rootDir detection

When a preset is active, fallow reads `compilerOptions.rootDir` from `tsconfig.json` to determine the source root for zone patterns. Preset zones become `{rootDir}/{zone}/**`.

The detection logic:

1. Reads `tsconfig.json` from the project root (supports JSONC with comments and trailing commas)
2. Extracts `compilerOptions.rootDir`
3. Strips a leading `./` prefix and any trailing `/`
4. Rejects `.`, `..`, and absolute paths for security
5. Falls back to `src` if the field is missing, the file doesn't exist, or the value is rejected

```jsonc title="tsconfig.json" theme={null}
{
  "compilerOptions": {
    "rootDir": "./lib"
  }
}
```

With the `hexagonal` preset, this produces zones:

```
lib/adapters/**
lib/ports/**
lib/domain/**
```

<Note>
  rootDir detection only applies to presets. Custom zones use patterns exactly as written.
</Note>

## Custom zones

Define zones manually when presets don't match your architecture. Each zone has:

| Field          | Type       | Description                                                                                  |
| :------------- | :--------- | :------------------------------------------------------------------------------------------- |
| `name`         | `string`   | Zone identifier used in rules                                                                |
| `patterns`     | `string[]` | Glob patterns relative to the project root, or relative to `root` when set                   |
| `autoDiscover` | `string[]` | Directories whose immediate child directories become separate zones named `parent/child`     |
| `root`         | `string?`  | Optional subtree scope; patterns and `autoDiscover` paths are resolved relative to this root |

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "zones": [
        { "name": "ui", "patterns": ["src/components/**", "src/pages/**"] },
        { "name": "data", "patterns": ["src/db/**", "src/api/**"] },
        { "name": "shared", "patterns": ["src/lib/**", "src/utils/**"] }
      ]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [[boundaries.zones]]
  name = "ui"
  patterns = ["src/components/**", "src/pages/**"]

  [[boundaries.zones]]
  name = "data"
  patterns = ["src/db/**", "src/api/**"]

  [[boundaries.zones]]
  name = "shared"
  patterns = ["src/lib/**", "src/utils/**"]
  ```
</CodeGroup>

**Zone classification rules:**

* A file belongs to the **first zone** whose pattern matches (first-match wins)
* Files that don't match any zone are **unrestricted** -- they can import from and be imported by any zone
* Zone order matters: place more specific patterns before broader ones

<Warning>
  Fallow warns when a zone matches zero files. This usually means the glob pattern doesn't match your directory structure. Run `fallow list --boundaries` to check file counts per zone.
</Warning>

## Auto-discovered zones

Use `autoDiscover` for feature-module boundaries where every immediate child directory should become its own zone. Rules can still reference the logical parent; fallow expands them to the discovered child zones.

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "zones": [
        { "name": "app", "patterns": ["src/app/**"] },
        { "name": "features", "patterns": ["src/features/**"], "autoDiscover": ["src/features"] },
        { "name": "shared", "patterns": ["src/shared/**"] }
      ],
      "rules": [
        { "from": "app", "allow": ["features", "shared"] },
        { "from": "features", "allow": ["shared"] }
      ]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [[boundaries.zones]]
  name = "app"
  patterns = ["src/app/**"]

  [[boundaries.zones]]
  name = "features"
  patterns = ["src/features/**"]
  autoDiscover = ["src/features"]

  [[boundaries.zones]]
  name = "shared"
  patterns = ["src/shared/**"]

  [[boundaries.rules]]
  from = "app"
  allow = ["features", "shared"]

  [[boundaries.rules]]
  from = "features"
  allow = ["shared"]
  ```
</CodeGroup>

If `src/features/auth` and `src/features/billing` exist, `fallow list --boundaries` shows `features/auth` and `features/billing`, and sibling feature imports are checked as cross-zone imports. Explicit child rules, such as `from: "features/auth"`, override generated parent rules regardless of rule order.

When the zone also has `patterns`, discovered child zones are matched first and top-level files inside the auto-discover directory fall back to the parent zone. The parent fallback rule automatically allows its discovered children, so a `src/features/index.ts` barrel can re-export feature modules without surfacing `features → features/<child>` violations, while non-barrel top-level files such as `src/features/types.ts` still obey the parent `features` rule. Generated child rules keep the original `allow` list exactly, so sibling-feature isolation is preserved. Omit `patterns` from the zone when you want only discovered child directories classified and top-level files left unrestricted.

## Custom rules

Rules define which zones may import from which. Each rule has:

| Field           | Type       | Description                                                                     |
| :-------------- | :--------- | :------------------------------------------------------------------------------ |
| `from`          | `string`   | The importing zone                                                              |
| `allow`         | `string[]` | Zones that `from` may import from                                               |
| `allowTypeOnly` | `string[]` | Zones that `from` may type-only-import from even when not in `allow` (optional) |

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "zones": [
        { "name": "ui", "patterns": ["src/components/**", "src/pages/**"] },
        { "name": "data", "patterns": ["src/db/**", "src/api/**"] },
        { "name": "shared", "patterns": ["src/lib/**", "src/utils/**"] }
      ],
      "rules": [
        { "from": "ui", "allow": ["shared"] },
        { "from": "data", "allow": ["shared"] },
        { "from": "shared", "allow": [] }
      ]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [[boundaries.zones]]
  name = "ui"
  patterns = ["src/components/**", "src/pages/**"]

  [[boundaries.zones]]
  name = "data"
  patterns = ["src/db/**", "src/api/**"]

  [[boundaries.zones]]
  name = "shared"
  patterns = ["src/lib/**", "src/utils/**"]

  [[boundaries.rules]]
  from = "ui"
  allow = ["shared"]

  [[boundaries.rules]]
  from = "data"
  allow = ["shared"]

  [[boundaries.rules]]
  from = "shared"
  allow = []
  ```
</CodeGroup>

**Rule semantics:**

* **Self-imports** are always allowed -- files within the same zone can freely import each other
* **No rule entry** means the zone is unrestricted -- it can import from any zone
* **Empty `allow` list** means the zone is isolated -- no cross-zone imports permitted
* Only zones with an explicit rule entry are constrained

<Tip>
  Start with rules for your lowest-level zones (the ones that should import from nothing) and work upward.
</Tip>

## Type-only imports across boundaries

TypeScript projects sometimes need type-level contracts between modules that must not have runtime dependencies on each other. A plugin system, for example, may declare a contribution interface in one feature that consumers in other features depend on at the type level only:

```ts theme={null}
// features/metrics-panel/extension-api.ts
export interface MetricsPanelContribution { items?: MetricItemProvider[]; }

// features/extra-metrics/index.ts
import type { MetricsPanelContribution } from '#/features/metrics-panel/extension-api';
```

The import is fully erased at compile time, so it carries no runtime coupling. To admit it without opening the full `allow` list to the target zone, add `allowTypeOnly`:

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "rules": [
        {
          "from": "features/extra-metrics",
          "allow": [],
          "allowTypeOnly": ["features/metrics-panel"]
        }
      ]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [[boundaries.rules]]
  from = "features/extra-metrics"
  allow = []
  allowTypeOnly = ["features/metrics-panel"]
  ```
</CodeGroup>

**What `allowTypeOnly` admits:**

* Whole-declaration type imports: `import type { Foo } from '...'`
* Namespace type imports: `import type * as ns from '...'`
* Inline-type imports where every named specifier carries the `type` qualifier: `import { type Foo } from '...'`
* Type-only re-exports: `export type { Foo } from '...'`

**What it does NOT admit:**

* Mixed-specifier imports where at least one specifier is value-typed (`import { type Foo, Bar }`) -- the runtime dependency on `Bar` still fires a violation
* Plain value imports (`import { Foo } from '...'`)
* Side-effect imports (`import '...'`) -- these run the target at runtime

**Semantics:**

* `allowTypeOnly` is independent of `allow`. A type-only edge is admitted if its target zone is in EITHER list.
* The default value is an empty list, so omitting the field preserves pre-feature behavior exactly.
* No preset (Layered, Hexagonal, FeatureSliced, Bulletproof) defaults the field on; type-only crossings are opt-in per rule.

## Merging presets with custom config

When both `preset` and `zones`/`rules` are specified, fallow merges them:

* **Zones** with the same name as a preset zone **replace** the preset zone entirely
* **Rules** with the same `from` as a preset rule **replace** the preset rule
* New zones and rules are **added** on top of the preset

### Example: override a preset zone

Use the hexagonal preset but put your domain code in `src/core` instead of `src/domain`:

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "preset": "hexagonal",
      "zones": [
        { "name": "domain", "patterns": ["src/core/**"] }
      ]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [boundaries]
  preset = "hexagonal"

  [[boundaries.zones]]
  name = "domain"
  patterns = ["src/core/**"]
  ```
</CodeGroup>

This keeps `adapters` and `ports` from the hexagonal preset but replaces the `domain` zone pattern with `src/core/**`. All three rules remain unchanged.

## Boundary coverage

Zones only constrain files they match; anything unmatched is unrestricted. To catch source files that silently fall outside every zone, enable coverage:

| Field             | Type       | Description                                                                                                          |
| :---------------- | :--------- | :------------------------------------------------------------------------------------------------------------------- |
| `requireAllFiles` | `boolean`  | Report every analyzed source file that matches no zone as a `boundary_coverage_violations` finding (default `false`) |
| `allowUnmatched`  | `string[]` | Glob patterns for intentionally unzoned paths; invalid globs are rejected at config load                             |

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "zones": [
        { "name": "domain", "patterns": ["src/domain/**"] }
      ],
      "coverage": {
        "requireAllFiles": true,
        "allowUnmatched": ["src/generated/**"]
      }
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [[boundaries.zones]]
  name = "domain"
  patterns = ["src/domain/**"]

  [boundaries.coverage]
  requireAllFiles = true
  allowUnmatched = ["src/generated/**"]
  ```
</CodeGroup>

**Semantics:**

* Coverage only runs when `requireAllFiles` is `true`; the default keeps unmatched files unrestricted, preserving pre-coverage behavior.
* Findings share the `boundary-violation` rule severity and suppression token.
* Combine with [forbidden calls](#forbidden-calls) so a zone-scoped call policy cannot be bypassed by leaving files unzoned.

Prefer `allowUnmatched` over file-level suppression comments for generated code: the config keeps the exemption in one reviewable place.

## Forbidden calls

To ban specific calls from a zone (for example, keeping a domain layer free of process execution and logging), add a forbidden-call policy:

| Field    | Type                 | Description                                        |
| :------- | :------------------- | :------------------------------------------------- |
| `from`   | `string`             | Zone whose files may not make matching calls       |
| `callee` | `string \| string[]` | Forbidden callee pattern(s), matched segment-aware |

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "boundaries": {
      "zones": [
        { "name": "domain", "patterns": ["src/domain/**"] }
      ],
      "calls": {
        "forbidden": [
          { "from": "domain", "callee": "child_process.*" },
          { "from": "domain", "callee": ["console.*", "process.exit"] }
        ]
      }
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [[boundaries.zones]]
  name = "domain"
  patterns = ["src/domain/**"]

  [[boundaries.calls.forbidden]]
  from = "domain"
  callee = "child_process.*"

  [[boundaries.calls.forbidden]]
  from = "domain"
  callee = ["console.*", "process.exit"]
  ```
</CodeGroup>

Each matching call reports as a `boundary_call_violations` finding naming the written callee, the matched pattern, and the zone.

**Matching semantics:**

* **Segment-aware, not substring or glob**: `fetch` matches only `fetch` (never `myfetch`), a trailing `object.*` matches any member (`child_process.*` matches `child_process.exec`), and a leading `*.member` matches any object (`*.innerHTML` matches `el.innerHTML`).
* **Import provenance**: patterns match through imports, so `child_process.*` covers `import { execSync } from "node:child_process"`, the bare `child_process` specifier, namespace imports, and default imports alike.
* **Direct callee paths only**, optional chaining included (`cp?.exec()` matches like `cp.exec()`). Aliased or re-bound callees (`const run = cp.exec; run()`), computed members, and injected dependencies (`this.client.exec()`) are not followed.
* **Zoned files only**: rules apply only to files classified into a zone; unzoned files are unrestricted. Combine with `coverage.requireAllFiles` to force zoning first.
* **One finding per unique callee path per file**: when several rules could match, the first applicable rule in config order wins. Fixing the first call site surfaces the next occurrence of the same callee on a rerun.
* Inert patterns such as a bare `*` are rejected at config load, and a rule pointing at a zone that matches no files warns at analysis time.

**Severity and suppression:** forbidden-call findings inherit the `boundary-violation` rule (default `error`) and suppression token; the rule-id-shaped `boundary-call-violation` and `boundary-call-violations` tokens are accepted as aliases. Any of these tokens suppresses the whole boundary family on that line or file.

<Tip>
  For a staged rollout, start with `"rules": { "boundary-violation": "warn" }` while you triage existing forbidden calls, then switch back to `"error"` to enforce. Note this also softens import-direction violations, since the boundary family shares one rule.
</Tip>

## Inspecting boundaries

Use `fallow list --boundaries` to see the expanded configuration after preset expansion and merging. This is the fastest way to verify your config is correct.

```bash title="$ fallow list --boundaries" theme={null}
Boundaries: 4 zones, 4 rules

Zones:
  app                  3 files  src/app/**
  features             12 files src/features/**
  shared               8 files  src/components/**, src/hooks/**, src/lib/**, ...
  server               4 files  src/server/**

Rules:
  app                  → features, shared, server
  features             → shared, server
  server               → shared
  shared               (isolated, no imports allowed)
```

For scripting or MCP tools, use JSON output:

```bash theme={null}
fallow list --boundaries --format json --quiet
```

<Tip>
  Run `fallow list --boundaries` first when debugging boundary violations. It shows actual zone patterns, file counts, and resolved rules. Misconfigured globs become obvious before running analysis.
</Tip>

## Common patterns

<Accordion title="Monorepo with per-package boundaries">
  Preset zone patterns are flat (`src/<zone>/**`), which doesn't work when packages have separate source directories. Define zones explicitly for each package:

  <CodeGroup>
    ```jsonc .fallowrc.json theme={null}
    {
      "boundaries": {
        "zones": [
          { "name": "web-ui", "patterns": ["apps/web/src/components/**", "apps/web/src/pages/**"] },
          { "name": "web-data", "patterns": ["apps/web/src/api/**", "apps/web/src/hooks/**"] },
          { "name": "shared-ui", "patterns": ["packages/ui/src/**"] },
          { "name": "shared-utils", "patterns": ["packages/utils/src/**"] }
        ],
        "rules": [
          { "from": "web-ui", "allow": ["web-data", "shared-ui", "shared-utils"] },
          { "from": "web-data", "allow": ["shared-utils"] },
          { "from": "shared-ui", "allow": ["shared-utils"] },
          { "from": "shared-utils", "allow": [] }
        ]
      }
    }
    ```

    ```toml fallow.toml theme={null}
    [[boundaries.zones]]
    name = "web-ui"
    patterns = ["apps/web/src/components/**", "apps/web/src/pages/**"]

    [[boundaries.zones]]
    name = "web-data"
    patterns = ["apps/web/src/api/**", "apps/web/src/hooks/**"]

    [[boundaries.zones]]
    name = "shared-ui"
    patterns = ["packages/ui/src/**"]

    [[boundaries.zones]]
    name = "shared-utils"
    patterns = ["packages/utils/src/**"]

    [[boundaries.rules]]
    from = "web-ui"
    allow = ["web-data", "shared-ui", "shared-utils"]

    [[boundaries.rules]]
    from = "web-data"
    allow = ["shared-utils"]

    [[boundaries.rules]]
    from = "shared-ui"
    allow = ["shared-utils"]

    [[boundaries.rules]]
    from = "shared-utils"
    allow = []
    ```
  </CodeGroup>
</Accordion>

<Accordion title="tRPC apps with server-to-features imports">
  In tRPC apps, the server router typically imports from feature modules to compose sub-routers. With the bulletproof preset, this causes `server -> features` violations.

  The cleanest approach is to suppress the router composition file:

  ```typescript title="src/server/_app.ts" theme={null}
  // fallow-ignore-file boundary-violation
  import { authRouter } from '../features/auth/router'
  import { billingRouter } from '../features/billing/router'

  export const appRouter = router({
    auth: authRouter,
    billing: billingRouter,
  })
  ```

  Alternatively, add `features` to the server rule:

  ```jsonc theme={null}
  {
    "boundaries": {
      "preset": "bulletproof",
      "rules": [
        { "from": "server", "allow": ["shared", "features"] }
      ]
    }
  }
  ```

  <Warning>
    Widening the server rule allows all server files to import from features, not just the router. Prefer inline suppression for surgical exceptions.
  </Warning>
</Accordion>

<Accordion title="Adding a test zone alongside a preset">
  Test files often need to import from any zone. Add a `test` zone that sits above the preset layers:

  <CodeGroup>
    ```jsonc .fallowrc.json theme={null}
    {
      "boundaries": {
        "preset": "bulletproof",
        "zones": [
          { "name": "test", "patterns": ["src/**/*.test.ts", "src/**/*.spec.ts", "src/__tests__/**"] }
        ],
        "rules": [
          { "from": "test", "allow": ["app", "features", "shared", "server"] }
        ]
      }
    }
    ```

    ```toml fallow.toml theme={null}
    [boundaries]
    preset = "bulletproof"

    [[boundaries.zones]]
    name = "test"
    patterns = ["src/**/*.test.ts", "src/**/*.spec.ts", "src/__tests__/**"]

    [[boundaries.rules]]
    from = "test"
    allow = ["app", "features", "shared", "server"]
    ```
  </CodeGroup>

  Since zones use first-match classification, place more specific patterns (like test file globs) before broader zone patterns. When using a preset with custom zones, custom zones are appended after preset zones. If your test files live inside zone directories (e.g., `src/features/auth/auth.test.ts`), the preset's `features` zone pattern will match first. Move the test patterns into an explicit zone list that comes before the preset zones, or use `ignorePatterns` to exclude test files from boundary analysis entirely.
</Accordion>

## See also

<CardGroup>
  <Card title="Architecture boundaries" icon="layer-group" href="/analysis/boundaries">
    Presets, output formats, and inline suppression for boundary violations.
  </Card>

  <Card title="Rules & Severity" icon="scale-balanced" href="/configuration/rules">
    Set `boundary-violation` to error, warn, or off.
  </Card>

  <Card title="Inline Suppression" icon="comment-slash" href="/configuration/suppression">
    Suppress individual findings in source code.
  </Card>
</CardGroup>


# Environment variables
Source: https://docs.fallow.tools/configuration/environment

Override fallow defaults with environment variables like FALLOW_FORMAT and FALLOW_QUIET. Useful for CI pipelines, editor integrations, and MCP.

Fallow reads a small set of environment variables to override default behavior. These are useful for CI pipelines, editor integrations, and the MCP server.

| Variable                           | Description                                                                                                                                                                                                                                                                 | Values                                                                                                                                                                                                                                           |
| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FALLOW_FORMAT`                    | Default output format                                                                                                                                                                                                                                                       | `human`, `json`, `sarif`, `compact`, `markdown` (`md`), `codeclimate`, `gitlab-codequality` (`gitlab-code-quality`), `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab`, `badge`, `github-annotations`, `github-summary` |
| `FALLOW_QUIET`                     | Suppress progress output                                                                                                                                                                                                                                                    | `1` or `true`                                                                                                                                                                                                                                    |
| `FALLOW_BIN`                       | Path to the fallow binary                                                                                                                                                                                                                                                   | Any valid path                                                                                                                                                                                                                                   |
| `FALLOW_EXTENDS_TIMEOUT_SECS`      | Timeout for fetching URL extends                                                                                                                                                                                                                                            | Seconds (default: `5`)                                                                                                                                                                                                                           |
| `FALLOW_PRODUCTION`                | Global production-mode override for every analysis                                                                                                                                                                                                                          | `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`                                                                                                                                                                                                     |
| `FALLOW_PRODUCTION_DEAD_CODE`      | Per-analysis production override for dead-code (combined runs and `fallow audit`)                                                                                                                                                                                           | Same values as `FALLOW_PRODUCTION`                                                                                                                                                                                                               |
| `FALLOW_PRODUCTION_HEALTH`         | Per-analysis production override for health                                                                                                                                                                                                                                 | Same values as `FALLOW_PRODUCTION`                                                                                                                                                                                                               |
| `FALLOW_PRODUCTION_DUPES`          | Per-analysis production override for duplication                                                                                                                                                                                                                            | Same values as `FALLOW_PRODUCTION`                                                                                                                                                                                                               |
| `FALLOW_REVIEW_GUIDANCE`           | Add collapsed "What to do" blocks to `review-github` / `review-gitlab` inline comments                                                                                                                                                                                      | `1`, `true`, `yes`, `on`                                                                                                                                                                                                                         |
| `FALLOW_SUMMARY_SCOPE`             | Sticky PR/MR summary scope for `pr-comment-github` / `pr-comment-gitlab`. `all` keeps project-level dependency/catalog/override findings outside the diff; `diff` applies the diff filter to those findings too. Inline review comments are unaffected                      | `all` (default), `diff`                                                                                                                                                                                                                          |
| `FALLOW_PR_COMMENT_LAYOUT`         | Sticky PR/MR summary layout for `pr-comment-github` / `pr-comment-gitlab`. Use `gate-only` when a native Check Run or Code Quality widget is the primary surface                                                                                                            | `default`, `compact`, `gate-only`, `details`                                                                                                                                                                                                     |
| `FALLOW_CACHE_DIR`                 | Override the extraction cache directory                                                                                                                                                                                                                                     | Any valid path                                                                                                                                                                                                                                   |
| `FALLOW_AUDIT_BASE`                | Pin the `fallow audit` comparison base when `--base` / `--changed-since` is unset (escape hatch for the agent gate and forks)                                                                                                                                               | Any git ref (e.g. `origin/main`, `upstream/main`)                                                                                                                                                                                                |
| `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS`  | Max age of persistent reusable `fallow audit` base-snapshot worktree caches                                                                                                                                                                                                 | Whole days (default `30`; `0` disables)                                                                                                                                                                                                          |
| `FALLOW_IMPACT_STORE_MAX_AGE_DAYS` | Reclaim per-project [`fallow impact`](/cli/impact) stores older than this; a recorded run sweeps stale stores (e.g. from deleted repos)                                                                                                                                     | Whole days (unset / `0` keeps every store forever)                                                                                                                                                                                               |
| `FALLOW_CLOCK_EPOCH`               | Pin the single reference instant a run measures churn recency, hotspot ranking, and ownership staleness against, so two runs over one commit produce the same churn-derived numbers. Read the value a run resolved from `hotspot_summary.clock.epoch_secs` and pass it back | Unix epoch seconds                                                                                                                                                                                                                               |
| `FALLOW_MAX_FILE_SIZE`             | Skip source files larger than this many megabytes at discovery and skip large one-line minified JS assets while the guard is enabled (mirrors `--max-file-size`; `.d.ts` always analyzed)                                                                                   | Whole megabytes (default `5`; `0` disables)                                                                                                                                                                                                      |
| `FALLOW_UPDATE_CHECK`              | Disable the local human-TTY upgrade nudge and background latest-version check                                                                                                                                                                                               | `off`, `0`, `false`, `disabled`, `no`                                                                                                                                                                                                            |
| `FALLOW_SUGGESTIONS`               | Suppress the `next_steps[]` array of read-only follow-up commands in JSON output and the human `Next:` line                                                                                                                                                                 | `off`, `0`, `false`, `no`, `disabled` (default on)                                                                                                                                                                                               |
| `FALLOW_TELEMETRY`                 | Opt-in [telemetry](/cli/telemetry) mode, off by default (see [what it collects](/explanations/telemetry))                                                                                                                                                                   | `off`/`on`/`inspect` (plus `0`/`1`/`true`/`false`/`disabled`/`enabled`/`debug`/`log`)                                                                                                                                                            |
| `FALLOW_TELEMETRY_DISABLED`        | Admin/fleet telemetry kill switch (top precedence)                                                                                                                                                                                                                          | `1`, `true`, `yes`, `on`                                                                                                                                                                                                                         |
| `FALLOW_TELEMETRY_DEBUG`           | Forces inspect mode (outranks `FALLOW_TELEMETRY`)                                                                                                                                                                                                                           | `1`, `true`, `yes`, `on`                                                                                                                                                                                                                         |
| `DO_NOT_TRACK`                     | Honored as a top-precedence telemetry kill switch                                                                                                                                                                                                                           | `1`, `true`, `yes`, `on`                                                                                                                                                                                                                         |
| `FALLOW_AGENT_SOURCE`              | Declare the calling agent for [telemetry](/cli/telemetry#agent-source) classification (never enables telemetry)                                                                                                                                                             | `codex`, `claude_code`, `cursor`, `copilot`, `opencode`, `aider`, `roo`, `windsurf`, `gemini` (aliases `gemini_cli`/`antigravity`), `cline`, `continue`, `zed`, `goose`, `other_known`, `unknown`, `none`                                        |
| `FALLOW_INTEGRATION_SURFACE`       | Declare the [telemetry](/explanations/telemetry) integration surface (set by the MCP server on the CLI it invokes; never enables telemetry)                                                                                                                                 | `mcp`, `lsp`, `vscode`, `napi`, `programmatic`                                                                                                                                                                                                   |
| `FALLOW_MCP_TOOL`                  | Declare the MCP tool name for the [telemetry](/explanations/telemetry) `mcp_tool` dimension (set by the MCP server; validated against a fixed allowlist, otherwise dropped; never enables telemetry)                                                                        | An allowlisted MCP tool name (for example `find_dupes`, `audit`)                                                                                                                                                                                 |

## FALLOW\_FORMAT

Set the default output format so you don't need to pass `--format` every time.

```bash theme={null}
export FALLOW_FORMAT=json
fallow dead-code   # Outputs JSON without --format flag
```

The `--format` CLI flag takes precedence over `FALLOW_FORMAT` when both are set.

## FALLOW\_QUIET

Suppress progress bars and status messages. Useful in CI environments or when piping output.

```bash theme={null}
export FALLOW_QUIET=1
fallow dead-code   # No progress output, only results
```

Equivalent to passing `--quiet` on every command.

## FALLOW\_BIN

Path to the fallow binary. Used by the MCP server (`fallow-mcp`) to locate the fallow CLI.

```bash theme={null}
export FALLOW_BIN=/usr/local/bin/fallow
fallow-mcp   # MCP server uses the specified binary
```

Defaults to `fallow` on `PATH` when not set.

## FALLOW\_EXTENDS\_TIMEOUT\_SECS

Timeout in seconds for fetching remote configs via `https://` URLs in the [`extends`](/configuration/overview#extends) field.

```bash theme={null}
export FALLOW_EXTENDS_TIMEOUT_SECS=10
fallow dead-code   # URL extends have 10s to respond
```

Defaults to `5` seconds when not set.

## FALLOW\_CACHE\_DIR

Directory for the persistent extraction cache. Wins over the `cache.dir` config field when both are set.

```bash theme={null}
export FALLOW_CACHE_DIR=/tmp/fallow-cache
fallow dead-code   # cache files are stored under /tmp/fallow-cache
```

By default, fallow stores the cache in `.fallow/cache.bin` under the project root. Use this env var when the project checkout is read-only, when CI has a dedicated cache volume, or when multiple workspace copies should share a stable cache location.

`--no-cache` disables the cache entirely; this env var is then irrelevant.

## FALLOW\_CACHE\_MAX\_SIZE

Maximum on-disk extraction cache (`.fallow/cache.bin`) size in megabytes. Wins over the `cache.maxSizeMb` config field when both are set.

```bash theme={null}
export FALLOW_CACHE_MAX_SIZE=64
fallow dead-code   # cache capped at 64 MB
```

Defaults to `256` (MB) when not set. The cache triggers LRU eviction when its serialized size crosses 80% of the cap and evicts down to 60%. Intended for CI runners with disk quotas; local dev machines on full-size disks rarely need to touch this knob.

`--no-cache` disables the cache entirely; this env var is then irrelevant.

## FALLOW\_AUDIT\_BASE

Pins the `fallow audit` comparison base. It takes effect only when neither `--base` nor `--changed-since` is passed, so the precedence is `--base` flag, then `FALLOW_AUDIT_BASE`, then auto-detection.

```bash theme={null}
export FALLOW_AUDIT_BASE=upstream/main
fallow audit   # compares against upstream/main instead of the auto-detected base
```

When unset, `fallow audit` auto-detects the base as the `git merge-base` (fork point) against the branch's upstream or the remote default (`origin/HEAD`, then `origin/main`, then `origin/master`). That is the right answer for most repositories, but two cases want an explicit pin:

* **Forks.** On a fork, `origin` is your fork (which can lag the real upstream), so set `FALLOW_AUDIT_BASE=upstream/main` to compare against the true upstream.
* **The agent gate.** `fallow hooks install --target agent` generates a hook that runs bare `fallow audit`. If your team works entirely in `git worktree`s and never updates the local default branch, the env var lets you pin the base without editing the generated script (which is regenerated on reinstall).

A malformed value (a ref with disallowed characters) fails the audit with exit code `2` rather than being silently ignored, so a typo surfaces immediately.

## FALLOW\_AUDIT\_CACHE\_MAX\_AGE\_DAYS

Maximum age (in whole days, since last reuse or fresh create) of a persistent reusable `fallow audit` base-snapshot worktree cache. Older entries are removed at the top of the next `fallow audit` invocation. Wins over the `audit.cacheMaxAgeDays` config field when both are set; during [`fallow audit-cache prune`](/cli/audit#audit-cache-prune), the `--max-age-days` flag wins over this variable.

```bash theme={null}
export FALLOW_AUDIT_CACHE_MAX_AGE_DAYS=7
fallow audit --base origin/main   # caches older than 7 days are reclaimed
```

Defaults to `30` days when not set. Setting the value to `0` disables the GC entirely (escape hatch for CI runners that prune `/tmp` out-of-band). Invalid values (non-integer, negative) silently fall back to the config field / default; a typo in a runner env var does not fail audits.

The sweep runs once per `fallow audit` invocation, walks fallow-owned base-snapshot cache entries only (never unrelated temp-directory content), and never removes a cache entry that another in-flight `fallow audit` is using (per-entry kernel `flock(2)` guard). On reclaim, fallow writes a single `fallow: reclaimed N stale base-snapshot caches` line to stderr (unless `--quiet` is set) so the disk-space recovery is observable. To apply the same GC policy on demand and see every per-entry decision, use [`fallow audit-cache prune`](/cli/audit#audit-cache-prune).

## FALLOW\_IMPACT\_STORE\_MAX\_AGE\_DAYS

Reclaim per-project [`fallow impact`](/cli/impact) stores that have not been touched in this many whole days. Impact keeps one small history file per project in your user config directory; over time, projects you delete from disk leave their stores behind. Set this so a recorded run prunes them.

```bash theme={null}
export FALLOW_IMPACT_STORE_MAX_AGE_DAYS=90
fallow audit --base origin/main   # impact stores untouched for 90+ days are reclaimed
```

Unset (the default) keeps every store forever; `0` and invalid values are treated the same way (no sweep), so a typo never deletes history. Age is the store file's modification time, and any recorded run rewrites the file, so an actively-tracked project never ages out. The sweep never touches the project you just recorded, never deletes the advisory `.lock` sidecars, and never the global `impact.json` opt-in toggle. Because impact only records on developer machines (never in CI), this is purely local housekeeping.

## FALLOW\_UPDATE\_CHECK

Local human runs can show a one-line upgrade hint when a cached latest-version check says the installed fallow is stale. The hint is suppressed for machine formats, CI, quiet runs, and non-TTY agent paths. Set `FALLOW_UPDATE_CHECK=off` to disable both the hint and the background latest-version check on that machine. `DO_NOT_TRACK` and `FALLOW_TELEMETRY_DISABLED` also suppress it.

## FALLOW\_SUGGESTIONS

`dead-code`, `health`, `dupes`, bare `fallow`, and `audit` add a top-level `next_steps[]` array of read-only follow-up commands to their `--format json` output (and a one-line `Next:` hint to bare `fallow`'s human output on a TTY), computed from the run's findings. Set `FALLOW_SUGGESTIONS=off` (or `0`/`false`/`no`/`disabled`) to suppress it; this is the escape hatch for CI consumers that snapshot-diff raw JSON output. The variable is inherited by the MCP-spawned CLI, so it also disables `next_steps` on MCP responses.

## FALLOW\_PRODUCTION and per-analysis overrides

`FALLOW_PRODUCTION` mirrors the `--production` CLI flag and turns production mode on for every analysis. The per-analysis vars (`FALLOW_PRODUCTION_DEAD_CODE`, `FALLOW_PRODUCTION_HEALTH`, `FALLOW_PRODUCTION_DUPES`) target a single analysis when running bare combined mode (`fallow` with no subcommand) or `fallow audit`.

```bash theme={null}
# Run combined mode with production-only health, full-tree dead-code and dupes
export FALLOW_PRODUCTION_HEALTH=true
fallow --format json --quiet
```

Precedence (highest to lowest):

1. CLI flags (`--production`, `--production-{dead-code,health,dupes}`)
2. Per-analysis env var (`FALLOW_PRODUCTION_HEALTH`, etc.)
3. Global env var (`FALLOW_PRODUCTION`)
4. Config (`production: true` legacy form, or `production: { health: true, ... }` per-analysis form)

Per-analysis env beats global env, so `FALLOW_PRODUCTION=false FALLOW_PRODUCTION_HEALTH=true` runs health in production mode and the other analyses in non-production mode. Single-subcommand runs (e.g. `fallow health`) still respect `FALLOW_PRODUCTION_HEALTH` even though the per-analysis CLI flag is rejected with a subcommand: pass `--production` or set the per-analysis env var.

<Tip>
  Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in CI pipelines for clean machine-readable output.
</Tip>

## FALLOW\_COVERAGE

Path to Istanbul coverage data (`coverage-final.json`) used for accurate per-function CRAP scores in `fallow health`, `fallow audit`, and bare `fallow`. An explicit CLI flag or MCP tool parameter wins when set. CLI and typed MCP routes then read this variable before falling back to `health.coverage` from config.

```bash theme={null}
export FALLOW_COVERAGE=./coverage/coverage-final.json
fallow health
```

## FALLOW\_COVERAGE\_ROOT

Absolute prefix to strip from Istanbul coverage paths before matching files. Use it when coverage was generated in a different checkout root, such as CI or Docker. An explicit CLI flag or MCP tool parameter wins when set. CLI and typed MCP routes then read this variable before falling back to `health.coverageRoot` from config.

## FALLOW\_MAX\_FILE\_SIZE

Per-file size ceiling in megabytes for source discovery (default `5`; `0` = no limit). Source files strictly larger are skipped before parsing, guarding against out-of-memory blowups from a single multi-megabyte generated or bundled file. The `--max-file-size` CLI flag wins when both are set. Declaration files (`.d.ts`) are always analyzed.

## Review and PR-comment formats

These variables tune the `review-github` / `review-gitlab` / `pr-comment-github` / `pr-comment-gitlab` output formats. The bundled GitHub Action and GitLab CI template set them for you; set them yourself only when rendering these formats outside the bundled integrations.

| Variable                   | Effect                                                                                                                                                                                                                     |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FALLOW_ROOT`              | Project root the review renderers read source from for suggestion blocks. Set alongside `--root`.                                                                                                                          |
| `FALLOW_REVIEW_GUIDANCE`   | Set to `true` to append collapsed per-finding guidance blocks to review inline comment bodies.                                                                                                                             |
| `FALLOW_SUMMARY_SCOPE`     | `all` (default) keeps project-level dependency/catalog/override findings outside the diff filter in PR-comment summaries; `diff` applies the diff filter to them too.                                                      |
| `FALLOW_PR_COMMENT_LAYOUT` | Sticky PR/MR summary layout for `pr-comment-github` / `pr-comment-gitlab`. Values: `default`, `compact`, `gate-only`, or `details`. Use `gate-only` when a native Check Run or Code Quality widget is the primary surface. |
| `FALLOW_DIFF_CONTEXT`      | Line radius around changed diff lines when scoping findings to a diff (default `3`).                                                                                                                                       |
| `FALLOW_BOT_LOGIN`         | Bot or token username treated as fallow's own when reconciling existing PR/MR comments. Required when posting with a personal access token.                                                                                |
| `FALLOW_API_RETRIES`       | Maximum HTTP attempts for review-comment reconciliation API calls (default `3`).                                                                                                                                           |
| `FALLOW_API_RETRY_DELAY`   | Floor delay in seconds between HTTP retries (default `2`); a server-supplied `Retry-After` overrides it on 429 responses.                                                                                                  |

## License and cloud

These variables configure the paid runtime intelligence layer and fallow cloud connectivity. See [fallow license](/cli/license) and [fallow coverage](/cli/coverage).

| Variable                                | Effect                                                                                                                                                   |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FALLOW_LICENSE`                        | License JWT (full string); intended for shared CI runners.                                                                                               |
| `FALLOW_LICENSE_PATH`                   | File path containing the license JWT.                                                                                                                    |
| `FALLOW_LICENSE_SKEW_TOLERANCE_SECONDS` | Clock-skew tolerance applied to the license JWT's `iat` claim (default `86400`).                                                                         |
| `FALLOW_COV_BIN`                        | Explicit path override for the `fallow-cov` runtime-coverage sidecar binary.                                                                             |
| `FALLOW_COV_BINARY_PATH`                | Secondary sidecar path override, checked after `FALLOW_COV_BIN` (air-gapped installs, distro-packaged sidecars).                                         |
| `FALLOW_RUNTIME_COVERAGE_SOURCE`        | Set to `cloud` to select cloud runtime coverage in `fallow coverage analyze` without passing `--cloud`.                                                  |
| `FALLOW_REPO`                           | `owner/repo` fallback for `fallow coverage analyze --cloud` when `--repo` is not passed.                                                                 |
| `FALLOW_API_URL`                        | Base URL override for fallow cloud API calls (staging / local-dev).                                                                                      |
| `FALLOW_API_KEY`                        | fallow cloud bearer token for coverage upload commands.                                                                                                  |
| `FALLOW_CA_BUNDLE`                      | Path to a PEM certificate bundle for fallow cloud and provider HTTP calls (replaces the default WebPKI roots; include public roots plus any private CA). |

## MCP server

Set these in the MCP server's `env` block; the spawned CLI inherits them. Full reference: [MCP integration](/integrations/mcp).

| Variable                     | Effect                                                                                          |
| :--------------------------- | :---------------------------------------------------------------------------------------------- |
| `FALLOW_TIMEOUT_SECS`        | Per-tool-call CLI subprocess timeout in seconds (default `120`).                                |
| `FALLOW_DIFF_FILE`           | Path to a unified diff that scopes all findings by changed line.                                |
| `FALLOW_CHANGED_SINCE`       | Git ref that scopes file discovery for analysis tools.                                          |
| `FALLOW_INTEGRATION_SURFACE` | Telemetry surface override for non-CLI surfaces; set by the MCP server on the CLI it spawns.    |
| `FALLOW_MCP_TOOL`            | Telemetry per-tool dimension; set by the MCP server alongside `FALLOW_INTEGRATION_SURFACE=mcp`. |

<Note>
  The complete machine-readable list ships in the `environment_variables` block of `fallow schema`.
</Note>

## See also

<CardGroup>
  <Card title="MCP server" icon="robot" href="/integrations/mcp">
    AI agent integration using the Model Context Protocol.
  </Card>

  <Card title="fallow dead-code" icon="terminal" href="/cli/dead-code">
    Full CLI reference including all output format options.
  </Card>
</CardGroup>


# Configuration
Source: https://docs.fallow.tools/configuration/overview

Configure fallow with .fallowrc.json, .fallowrc.jsonc, or fallow.toml. Customize entry points, ignore patterns, rules, and plugin settings for your project.

Fallow works out of the box with zero configuration. To customize entry points, rules, or ignore patterns, create a config file:

```bash theme={null}
fallow init          # Creates .fallowrc.json
fallow init --toml   # Creates fallow.toml
```

## Config file formats

Fallow searches for config files in this order:

1. `.fallowrc.json` (JSONC, comments allowed)
2. `.fallowrc.jsonc` (same JSONC parser, lets editors auto-detect JSON-with-comments syntax highlighting)
3. `fallow.toml`
4. `.fallow.toml`

Discovery is first-match-wins per directory, walking up to the workspace root. `.fallowrc.json` and `.fallowrc.jsonc` are identical in behavior; the `.jsonc` extension only signals to editors that comments are expected. If more than one of these files coexists in the same directory, fallow loads the higher-precedence one and prints a warning on stderr naming the file it ignored, so a stale config left over from a migration cannot silently win.

## Full example

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
    "entry": ["src/workers/*.ts", "scripts/*.ts"],
    "ignorePatterns": ["**/*.generated.ts", "**/*.d.ts"],
    "ignoreDependencies": ["autoprefixer", "@types/node"],
    "ignoreExports": [
      { "file": "src/public-api.ts", "exports": ["*"] }
    ],
    "ignoreExportsUsedInFile": true,
    "publicPackages": ["@myorg/sdk"],
    "dynamicallyLoaded": ["src/plugins/**/*.ts"],
    "rules": {
      "unused-files": "error",
      "unused-exports": "warn",
      "unused-types": "off",
      // Opt-in API hygiene check; default is "off"
      "private-type-leaks": "warn",
      "unresolved-imports": "error"
    },
    "duplicates": {
      "mode": "mild",
      "minTokens": 50,
      "minLines": 5,
      "threshold": 10
    },
    "similarCode": {
      "threshold": 0.8,
      "minLines": 3,
      "ignore": ["src/generated/**"]
    },
    "health": {
      "maxCyclomatic": 20,
      "maxCognitive": 15,
      "ignore": ["**/*.generated.ts"],
      "thresholdOverrides": [
        {
          "files": ["src/legacy/**"],
          "functions": ["parseLegacy"],
          "maxCyclomatic": 40,
          "maxCognitive": 35,
          "reason": "Queued legacy parser cleanup"
        }
      ]
    },
    "audit": {
      "gate": "new-only"
    },
    "security": {
      "requestReceivers": ["h", "httpReq"]
    },
    "boundaries": {
      "preset": "bulletproof"
    },
    "production": false
  }
  ```

  ```toml fallow.toml theme={null}
  entry = ["src/workers/*.ts", "scripts/*.ts"]
  ignorePatterns = ["**/*.generated.ts", "**/*.d.ts"]
  ignoreDependencies = ["autoprefixer", "@types/node"]
  ignoreExportsUsedInFile = true
  publicPackages = ["@myorg/sdk"]
  dynamicallyLoaded = ["src/plugins/**/*.ts"]
  production = false

  [rules]
  unused-files = "error"
  unused-exports = "warn"
  unused-types = "off"
  # Opt-in API hygiene check; default is "off"
  private-type-leaks = "warn"
  unresolved-imports = "error"

  [duplicates]
  mode = "mild"
  minTokens = 50
  minLines = 5
  threshold = 10

  [similarCode]
  threshold = 0.8
  minLines = 3
  ignore = ["src/generated/**"]

  [health]
  maxCyclomatic = 20
  maxCognitive = 15
  ignore = ["**/*.generated.ts"]

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

  [audit]
  gate = "new-only"

  [security]
  requestReceivers = ["h", "httpReq"]

  [boundaries]
  preset = "bulletproof"
  ```
</CodeGroup>

## Config fields

<Accordion title="entry">
  Additional entry point glob patterns. Fallow auto-detects entry points from `package.json` (`main`, `module`, `bin`, `exports`) and framework plugins. Add files here that aren't auto-detected.

  ```jsonc theme={null}
  {
    "entry": ["src/workers/*.ts", "scripts/*.ts", "src/cli.ts"]
  }
  ```
</Accordion>

<Accordion title="Entry point auto-detection">
  Even without an `entry` config, fallow discovers entry points from your `package.json` fields. These files are the roots of the module graph. Anything reachable from them is considered "used."

  Fallow reads the following `package.json` fields:

  | Field               | Description                                                                                       |
  | :------------------ | :------------------------------------------------------------------------------------------------ |
  | `main`              | CJS entry point                                                                                   |
  | `module`            | ESM entry point                                                                                   |
  | `types` / `typings` | TypeScript declaration entry point                                                                |
  | `source`            | Unbuilt source entry point (common convention for dev tooling)                                    |
  | `browser`           | Browser-specific entry (string or object with per-path overrides)                                 |
  | `bin`               | CLI binaries (string for single binary, object for multiple)                                      |
  | `exports`           | Modern entry point map (resolved recursively, including conditional exports and subpath patterns) |

  The `exports` field is resolved recursively. Nested conditions like `"import"`, `"require"`, `"types"`, and `"default"` are all followed to their target files. Subpath exports (e.g., `"./utils"`) are included too.

  Output directories (`dist/`, `build/`, `out/`, `esm/`, `cjs/`) referenced in these fields are mapped back to `src/` equivalents with source extension fallback. Fallow ignores output directories by default.

  On top of `package.json` fields, framework plugins add their own entry points (e.g., Next.js adds `pages/**`, `app/**/page.tsx`; Vitest adds `**/*.test.ts`). Run `fallow list` to see all detected entry points.
</Accordion>

<Accordion title="ignorePatterns">
  Glob patterns for files to exclude from analysis entirely.

  ```jsonc theme={null}
  {
    "ignorePatterns": ["**/*.generated.ts", "**/*.d.ts", "legacy/**"]
  }
  ```
</Accordion>

<Accordion title="ignoreFindings">
  Glob patterns for files whose dead-code findings should not be reported. Matching files are still discovered, parsed, and kept in the module graph, so anything they import stays reachable. Use `ignorePatterns` when you want the files out of analysis entirely.

  ```jsonc theme={null}
  {
    "ignoreFindings": [
      "vitest.config.ts",
      "src/generated/**",
      // a leading ! keeps matching paths reportable
      "!src/generated/keep.ts"
    ]
  }
  ```

  Patterns are project-root-relative and use `/` on every platform, including Windows. Matching is case sensitive, and `*` and `?` cross `/`, so `src/*` covers the whole `src` subtree. Absolute paths, `..` segments, and a bare `"!"` are rejected at load time.

  Order does not matter: a negation wins over any positive match wherever it sits in the array. An array of negations alone hides every path except the ones a negation matches.

  Findings are hidden before rules, severities, and `--fail-on-issues` are applied, so a hidden finding cannot fail a run or reach any output format. A finding with several owning files (circular dependency, re-export cycle, duplicate export, prop drilling chain, and an unlisted dependency, owned by its import sites) is hidden only when every owner matches.

  Dependency findings owned by a manifest (unused, dev, optional, type-only, test-only, catalog, override), architecture boundary and policy violations, stale suppressions, framework correctness findings such as client/server directives and route collisions, and security candidates stay visible even when their path matches.

  Human output prints a stderr note naming patterns that matched no finding, which catches typos; `--quiet` and the machine formats leave it out.
</Accordion>

<Accordion title="ignoreDependencies">
  Package names that should always be considered used and always considered available.
  Listed dependencies are excluded from both unused dependency and unlisted dependency detection.
  Useful for runtime-provided packages like `bun:sqlite` or implicitly available dependencies.

  ```jsonc theme={null}
  {
    "ignoreDependencies": ["autoprefixer", "@types/node", "bun:sqlite"]
  }
  ```
</Accordion>

<Accordion title="ignoreCatalogReferences">
  Rules that suppress `unresolved-catalog-reference` findings: a `catalog:` dependency pointing at a catalog that does not declare the package. These findings sit in `package.json` rather than source files, and JSON has no comment syntax, so `// fallow-ignore-next-line` never reaches them and a config entry is the only suppression.

  ```jsonc theme={null}
  {
    "ignoreCatalogReferences": [
      // Placeholder package; the `upcoming` catalog lands in a later change.
      {
        "package": "future-dep",
        "catalog": "upcoming",
        "consumer": "packages/placeholder/package.json"
      },
      // Staged migration: any catalog, every workspace package.
      { "package": "old-react", "consumer": "packages/**/package.json" }
    ]
  }
  ```

  `package` is required and matched by exact, case-sensitive string equality against the dependency key, so `"@scope/*"` matches nothing. `catalog` and `consumer` are optional; omitting one matches any value.

  `catalog` is matched against the normalized catalog name: `"react": "catalog:"` and `"react": "catalog:default"` are both `default`, and `"catalog:react17"` is `react17`. `consumer` is a project-root-relative glob over the consuming `package.json` path, with `/` on every platform (`package.json` for the root manifest, `packages/app/package.json` for a workspace member); matching is anchored to the whole path, and `*` and `?` cross `/`. Every field of one entry must match, and any matching entry in the array suppresses the finding.

  Every `unresolved-catalog-reference` finding in `fallow dead-code --format json` output carries an `add-to-config` action with `package`, `catalog`, and `consumer` already filled in.

  Only `unresolved-catalog-reference` is affected; `unused-catalog-entries` and `empty-catalog-groups` are untouched. To turn the rule off for a path, use `overrides` with `"unresolved-catalog-references": "off"`; to turn it off everywhere, set `rules.unresolved-catalog-references` to `"off"`. `ignoreFindings` does not apply here: manifest-owned findings stay visible even when their path matches. A `consumer` value with invalid glob syntax, an absolute path, or a `..` segment fails config load.
</Accordion>

<Accordion title="ignoreDependencyOverrides">
  Package-manager override entries that should not be reported. Suppresses `unused-dependency-override` and `misconfigured-dependency-override` for matching entries in `overrides` (`pnpm-workspace.yaml`), `pnpm.overrides`, npm `overrides`, and bun `resolutions`. These findings sit in manifests rather than source files, so `// fallow-ignore-next-line` never reaches them and a config entry is the only suppression (a CVE pin that must stay, for example).

  ```jsonc theme={null}
  {
    "ignoreDependencyOverrides": [
      // overrides: { "lodash": "^4.17.21" } in pnpm-workspace.yaml
      // No source filter, so the entry matches in either file
      { "package": "lodash" },
      // pnpm.overrides: { "@scope/legacy-pkg": "^1.0.0" } in package.json
      { "package": "@scope/legacy-pkg", "source": "package.json" },
      // resolutions: { "**/trim-newlines": "^3.0.1" } in a bun package.json
      { "package": "trim-newlines", "source": "package.json" }
    ]
  }
  ```

  `package` is an exact, case-sensitive string match against the override's target package, not a glob and not the raw key: write `react-dom` for `"react>react-dom"` and `@types/react` for `"@types/react@<18"`. Bun `resolutions` keys drop their `**` path segments, so `"**/trim-newlines"` is matched as `trim-newlines`; a `**/` prefix in an `overrides` key is not stripped. A key fallow cannot parse is matched verbatim instead, so `"react>"` needs `{ "package": "react>" }`.

  `source` is the declaring file's label, `"pnpm-workspace.yaml"` or `"package.json"`, not a path; omit it to match both. Any other value loads without complaint and never matches. `pnpm.overrides`, npm `overrides`, and bun `resolutions` all report `"package.json"`, so `source` cannot separate them. A bun project's `resolutions` are read only when the root manifest declares no `overrides` key; alongside `overrides` they are shadowed and never reported, so an entry for them matches nothing. Both fields must match, and any matching entry in the array suppresses the finding.

  Both findings carry an `add-to-config` action in JSON output, with `package` and `source` already filled in. An entry that matches nothing produces no warning. To drop either finding entirely, set `rules.unused-dependency-overrides` or `rules.misconfigured-dependency-overrides` to `"off"`. `ignoreFindings` does not apply here: manifest-owned findings stay visible even when their path matches.
</Accordion>

<Accordion title="ignoreUnresolvedImports">
  Glob patterns matched against the raw import specifier text, not against a file path. A matching specifier is never reported as `unresolved-import`. Useful for imports fallow cannot resolve on disk: code generated later in the build, a package whose `exports` map points at build artifacts that are not in the checkout, or a bundler alias fallow does not model.

  ```jsonc theme={null}
  {
    "ignoreUnresolvedImports": [
      "@example/icons",     // the bare specifier
      "@example/icons/**",  // its subpaths, not the bare name
      "../generated/**"     // parent-relative codegen output
    ]
  }
  ```

  Matching is case-sensitive and anchored to the whole specifier. `*` and `?` cross `/`, but a trailing `/**` requires the separator, so list the bare package name alongside the subpath pattern when you want both. A leading `./` is stripped from each pattern, and every specifier is tried with and without its own, so `"./generated/x.js"` and `"generated/x.js"` cover the same imports.

  A `..` segment is allowed here, unlike in the file-path glob fields, because these are specifiers rather than paths. There is no negation syntax and no ordering: a specifier is silenced if any pattern matches. A pattern with invalid glob syntax fails config load, with a message naming the field and the offending pattern.

  The field covers static imports, dynamic imports, and re-export sources, for both value and type-only imports. Resolution and the module graph still run as before, and dependency usage accounting is untouched, so `unlisted-dependency` is unaffected (that is `ignoreDependencies`, which matches package names by exact string).

  Every `unresolved-import` finding in JSON output carries an `add-to-config` action pointing at this field with the reported specifier. When moving an import here from an inline `// fallow-ignore-next-line unresolved-import` comment, delete the comment: the config check runs first, so the comment is then reported as `stale-suppression`.
</Accordion>

<Accordion title="ignoreExports">
  Rules for ignoring specific exports. Useful for public API packages and for namespace-barrel UI libraries (shadcn / Radix / bits-ui) where many `components/ui/<name>/index.ts` files intentionally export the same short names.

  `ignoreExports` suppresses both `unused-export` findings AND `duplicate-export` grouping for matching files. Use `exports: ["*"]` to exclude every export from the matched files; use a name list to exclude only those names.

  ```jsonc theme={null}
  {
    "ignoreExports": [
      { "file": "src/index.ts", "exports": ["*"] },
      { "file": "src/utils/*.ts", "exports": ["default"] },
      // shadcn / Radix / bits-ui barrels
      { "file": "src/lib/components/ui/**", "exports": ["*"] }
    ]
  }
  ```

  Note: per-file `overrides.rules.duplicate-exports = "off"` has no effect because the rule spans multiple files (a duplicate-export finding groups N locations across N files). Fallow emits a load-time warning when this override shape is detected and points at `ignoreExports` as the working escape hatch.
</Accordion>

<Accordion title="ignoreExportsUsedInFile">
  Suppress unused-export findings when the exported symbol is referenced inside the file that declares it. Exports with no references at all are still reported. Mirrors knip's [`ignoreExportsUsedInFile`](https://knip.dev/reference/configuration#ignoreexportsusedinfile).

  ```jsonc theme={null}
  {
    "ignoreExportsUsedInFile": true
  }
  ```

  A fine-grained object form is also accepted for knip parity:

  ```jsonc theme={null}
  {
    "ignoreExportsUsedInFile": { "type": true, "interface": true }
  }
  ```

  Fallow groups type aliases and interfaces under the same `unused-types` issue, so `{ "type": true }`, `{ "interface": true }`, and `{ "type": true, "interface": true }` all behave identically: any type export referenced in the same file is suppressed. The two fields exist only for knip-config compatibility.

  References inside the export specifier itself (`export { foo }`, `export { foo as bar }`, `export default foo`) do not count as same-file uses; those exports are still reported when no other file or no other in-file expression references the binding.
</Accordion>

<Accordion title="includeEntryExports">
  Report unused exports in entry files (package.json `main`/`exports`, framework pages, etc.) instead of auto-marking them as used. Catches typos in framework-convention exports like `meatdata` instead of `metadata`.

  ```jsonc theme={null}
  {
    "includeEntryExports": true
  }
  ```

  The same behaviour is also available as the global CLI flag `--include-entry-exports`. The CLI flag wins when both are set.
</Accordion>

<Accordion title="typeAware">
  Enable optional checker-backed TypeScript evidence for exact symbol use, class
  contracts, cross-file private type leaks, affected tests, and public-signature
  coupling. The default is disabled so the normal analysis stays fast and
  independent of the TypeScript companion.

  ```jsonc theme={null}
  {
    "typeAware": {
      "enabled": true,
      "projects": ["tsconfig.json"],
      "require": "best-effort"
    }
  }
  ```

  `projects` is optional and accepts tsconfig paths relative to the project root.
  An empty list uses automatic project discovery. Start with `best-effort`, which
  keeps conservative findings when semantic evidence is partial or unavailable.
  Choose `complete` only when an incomplete semantic pass must fail the run.

  This does not replace `tsc` or Oxlint. See
  [Type-aware TypeScript analysis](/analysis/type-aware) for installation,
  performance, safety, and library-consumer boundaries.
</Accordion>

<Accordion title="security">
  Configure `fallow security` catalogue behavior. `security.categories` scopes which candidate categories run, and `security.requestReceivers` adds project-local HTTP request object names to the built-in `req`, `request`, `ctx`, `context`, and `event` receiver allowlist.

  `requestReceivers` is additive only. Values are trimmed and matched case-insensitively for `*.query`, `*.params`, and `*.body` source reads. It does not replace the built-ins and does not gate `*.searchParams`.

  ```jsonc theme={null}
  {
    "security": {
      "requestReceivers": ["h", "httpReq"],
      "categories": {
        "include": ["command-injection"],
        "exclude": ["dynamic-regex"]
      }
    }
  }
  ```
</Accordion>

<Accordion title="autoImports">
  Resolve framework convention auto-imports (Nuxt components) as real module-graph edges. Frameworks like Nuxt expose components to templates by filesystem convention (`<Card001 />` resolving to `components/Card001.vue`) with no `import` statement.

  ```jsonc theme={null}
  {
    "autoImports": true
  }
  ```

  Edges for these tag references are always synthesized, so a component's default export consumed via a `<Card />` tag is credited under `includeEntryExports`. Setting `autoImports: true` additionally drops the Nuxt component entry patterns so a genuinely-unreferenced component is reported as `unused-file` instead of being kept alive as an entry point.

  The flag is conservative: if your `nuxt.config` declares a `components:` key (custom `prefix`, `pathPrefix`, or `dirs`), the entry patterns are kept, since those custom layouts are not yet modeled. Defaults to `false`. Composable, util, and Pinia store auto-imports are tracked separately.
</Accordion>

<Accordion title="ignoreDecorators">
  Decorator names that fallow should NOT treat as evidence of reflective use. Members carrying only listed decorators are checked for usage like undecorated members. Members carrying any decorator NOT in the list stay skipped, so framework defaults (NestJS, Angular, TypeORM) are unchanged.

  Use this when your codebase carries utility decorators that do not imply runtime reflection: Playwright's `@step("label")`, internal labeling decorators like `@measure`, `@log`, `@retry`, or any custom decorator that wraps a method for logging or tracing.

  ```jsonc theme={null}
  {
    "ignoreDecorators": ["@step"]
  }
  ```

  Conservative semantics: a method decorated with both `@step` and `@Inject` stays skipped because `@Inject` is not in the ignore list. Only methods whose every decorator is in the list become subject to the standard usage check.

  ### Matching

  * **Bare entries** (`"step"` or `"decorators"`) match the leftmost segment of the decorator path. A single bare `"decorators"` entry collapses every `@decorators.*` decorator, useful when an internal namespace exposes many utility decorators that should all be treated as non-reflective.
  * **Dotted entries** (`"decorators.log"`) match the full dotted path exactly. Sibling `@decorators.audit` decorators stay skipped unless you also list `"decorators.audit"` or use the bare `"decorators"` form.
  * Both `"@step"` and `"step"` round-trip equivalently; a leading `@` is stripped before matching.

  ### Unmatched-entry warning

  Entries that never match any decorator in the analyzed codebase produce a one-time warning at end of run, mirroring `usedClassMembers`'s warn-on-unmatched-pattern behavior. Treat unmatched entries as dead config and remove them.

  The default empty list preserves today's skip-all-decorated behavior, so existing NestJS / Angular / TypeORM projects see no change. The first run after enabling this option will surface new `unused-class-members` findings on members previously hidden by the unconditional skip.
</Accordion>

<Accordion title="unusedComponentProps">
  Options for the `unused-component-props` rule. Set `ignorePattern` to a regex that exempts component props whose local destructure binding name matches, so a prop accepted for public-API stability but intentionally unused internally is not reported.

  This honors the leading-underscore "accepted-but-intentionally-unused" convention, mirroring TypeScript's `noUnusedParameters` and ESLint's `@typescript-eslint/no-unused-vars` `varsIgnorePattern` / `argsIgnorePattern`:

  ```jsonc theme={null}
  {
    "rules": { "unused-component-props": "warn" },
    "unusedComponentProps": {
      "ignorePattern": "^_"
    }
  }
  ```

  ```svelte theme={null}
  <script lang="ts">
    interface Props { stage: string; variant?: string }
    // `_stage` is exempted by `^_`; `variant` is still reported if unused.
    let { stage: _stage, variant }: Props = $props();
  </script>
  ```

  Applies to Vue, Svelte, Astro, and React/Preact props. Default behavior is unchanged: with no `ignorePattern`, every unused prop is reported.

  ### Matching

  * The regex is matched against the **local destructure binding name** (`_stage` in `let { stage: _stage } = $props()`), not the public prop name the finding reports (`stage`). When a prop is declared without an alias, the local name equals the public name.
  * Matching is **unanchored** (like ESLint's `RegExp.test`), so `_` with no anchor matches any prop containing an underscore (`on_click`, `aria_label`). Anchor with `^_` to match a leading underscore.
  * An invalid regex fails config load with a clear error.

  When at least one prop is exempted, fallow prints a one-line note reporting how many, so a pattern that matches nothing (often a typo) is not silently inert.

  The Angular `unused-component-input` / `unused-component-output` rules are not affected (their declarations are class fields, not destructured locals).
</Accordion>

<Accordion title="usedClassMembers">
  Class member method/property names that should never be reported as unused. Extends fallow's built-in Angular and React lifecycle allowlist with framework-invoked names from third-party libraries.

  Use this when a library calls methods on your class at runtime via an interface or contract pattern. Common examples include ag-Grid (`agInit`, `refresh`), TypeORM migrations (`up`, `down`), and Web Components (`connectedCallback`, `disconnectedCallback`, `attributeChangedCallback`).

  Each entry is either a plain member name (global suppression) or a scoped object that only matches classes whose heritage clause includes the configured `extends` or `implements` identifier. Strings can be exact names or glob patterns:

  ```jsonc theme={null}
  {
    "usedClassMembers": [
      "agInit",
      { "implements": "ICellRendererAngularComp", "members": ["refresh"] },
      { "extends": "BaseCommand", "members": ["execute"] },
      { "implements": "CanActivate", "members": ["canActivate"] },
      { "extends": "GrammarBaseListener", "members": ["enter*", "exit*"] }
    ]
  }
  ```

  Plain names like `agInit` are unique enough to suppress globally. Common names like `refresh` or `execute` would produce false negatives across unrelated classes, so scope them with `implements` or `extends`. A scoped rule requires at least one of `extends` or `implements`; an unconstrained object rule (`{ "members": [...] }` with no heritage field) is rejected at load time.

  Heritage matching is syntactic: the identifier in the source's `extends Foo` or `implements IBar` clause is compared against the rule's string. Re-aliased imports (`import { IBar as IBaz }`) use whatever identifier appears in the class declaration.

  ### Glob patterns

  Member strings containing `*` or `?` are treated as glob patterns; existing exact strings keep their current meaning. `"*"` matches every member declared on a matching class, `"enter*"` matches any member whose name starts with `enter`, `"*Handler"` matches any member ending with `Handler`, and `"on*Event"` combines prefix and suffix. Useful for parser-generator listeners (ANTLR), code-generated bridges, and abstract framework bases that dispatch on a member-name prefix instead of an exhaustive list.

  Glob patterns that match zero members across the codebase emit a `WARN` at the end of the run so dead allowlist entries surface. Exact-string entries do not emit this warning (they are common boilerplate that may legitimately match in some configurations but not others).

  The allowlist only applies to class methods and properties. Enum members with the same names are still checked.

  For library-specific allowlists that should only activate when the library is installed, prefer a plugin file with the `usedClassMembers` field. See [Custom plugins](/frameworks/custom-plugins) for the plugin format.
</Accordion>

<Accordion title="publicPackages">
  Workspace packages whose exported API surface should be considered public. Exports, exported enum members, and exported class members from these packages are never reported as unused, even if no internal consumer imports them. Useful for library packages that are consumed externally.

  ```jsonc theme={null}
  {
    "publicPackages": ["@myorg/sdk", "@myorg/types"]
  }
  ```
</Accordion>

<Accordion title="dynamicallyLoaded">
  Glob patterns for files that are loaded dynamically at runtime (e.g., via `import()`, lazy routes, or plugin systems). These files are treated as entry points and will not be reported as unused.

  ```jsonc theme={null}
  {
    "dynamicallyLoaded": ["src/plugins/**/*.ts", "src/routes/**/page.tsx"]
  }
  ```
</Accordion>

<Accordion title="duplicates">
  Configuration for `fallow dupes`:

  | Field                           | Type                                               | Default  | Description                                                                                                                                                                                                                                                                                                                                   |
  | :------------------------------ | :------------------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `mode`                          | `"strict"` \| `"mild"` \| `"weak"` \| `"semantic"` | `"mild"` | Detection mode. `strict`/`mild` match exact tokens. `weak` blinds string literal values. `semantic` blinds identifiers and all literal values for structural (Type-2) detection.                                                                                                                                                              |
  | `near`                          | `boolean`                                          | `false`  | Include function-scoped near-miss clones with small structural edits alongside exact clones.                                                                                                                                                                                                                                                  |
  | `minTokens`                     | `number`                                           | `50`     | Minimum token count for a code block to be considered a clone                                                                                                                                                                                                                                                                                 |
  | `minLines`                      | `number`                                           | `5`      | Minimum line count for a clone group                                                                                                                                                                                                                                                                                                          |
  | `minOccurrences`                | `number`                                           | `2`      | Minimum occurrences before a clone group is reported. Must be at least `2`.                                                                                                                                                                                                                                                                   |
  | `threshold`                     | `number`                                           | `0`      | Maximum allowed duplication percentage before failing (exit code 1). `0` disables the limit.                                                                                                                                                                                                                                                  |
  | `enabled`                       | `boolean`                                          | `true`   | Toggle duplication detection on/off                                                                                                                                                                                                                                                                                                           |
  | `ignore`                        | `string[]`                                         | `[]`     | Glob patterns to exclude from duplication analysis. Merged with the built-in defaults below unless `ignoreDefaults` is `false`.                                                                                                                                                                                                               |
  | `ignoredClones`                 | `string[]`                                         | `[]`     | Reviewed clone groups to omit. Each key uses `<fingerprint>:<instance_count>`, for example `dup:6f12ab34:2`. A token or occurrence-count change makes the group reportable again.                                                                                                                                                             |
  | `ignoreDefaults`                | `boolean`                                          | `true`   | Merge built-in generated-output ignores (`**/.next/**`, `**/.nuxt/**`, `**/.svelte-kit/**`, `**/.turbo/**`, `**/.parcel-cache/**`, `**/.vite/**`, `**/.cache/**`, `**/out/**`, `**/storybook-static/**`) with `ignore`. Set to `false` to use only your configured `ignore` list.                                                             |
  | `skipLocal`                     | `boolean`                                          | `false`  | Only report cross-directory duplicates, skip file-internal clones                                                                                                                                                                                                                                                                             |
  | `crossLanguage`                 | `boolean`                                          | `false`  | Enable cross-language clone detection between `.ts` and `.js` files by stripping TypeScript type annotations                                                                                                                                                                                                                                  |
  | `ignoreImports`                 | `boolean`                                          | `true`   | Exclude module wiring from clone detection. ES imports, re-export declarations, and top-level static `require()` binding declarations are excluded by default; set to `false` to count them again. Runtime code, local exports, side-effect or nested `require()` calls, dynamic require arguments, and mixed declarations are still counted. |
  | `normalization`                 | `object`                                           | none     | Fine-grained normalization overrides: `ignoreIdentifiers`, `ignoreStringValues`, `ignoreNumericValues`                                                                                                                                                                                                                                        |
  | `minCorpusSizeForShingleFilter` | `number`                                           | `1024`   | Tokenized file count above which focused-mode duplication (driven by `--changed-since` or `audit`) prefilters unchanged files via k-token shingles. Below this threshold the prefilter is skipped because building the shingle index outweighs the savings.                                                                                   |
  | `minCorpusSizeForTokenCache`    | `number`                                           | `5000`   | Source file count above which the persistent duplication token cache activates under `<root>/.fallow/cache/dupes-tokens-vN/`. Below this threshold the cache load/save overhead exceeds the tokenize savings, so the cache stays disabled even without `--no-cache`.                                                                          |

  ```jsonc theme={null}
  {
    "duplicates": {
      "mode": "mild",
      "near": true,
      "minTokens": 50,
      "minLines": 5,
      "minOccurrences": 2,
      "threshold": 5,
      "ignore": ["**/*.generated.ts"],
      "ignoredClones": ["dup:6f12ab34:2"],
      "skipLocal": true,
      "ignoreImports": true
    }
  }
  ```
</Accordion>

<Accordion title="similarCode">
  Project-owned calibration for the separate `fallow similar-code` workflow:

  | Field       | Type                 | Default | Description                                                                       |
  | :---------- | :------------------- | :------ | :-------------------------------------------------------------------------------- |
  | `threshold` | `number` from 0 to 1 | `0.8`   | Model-specific cutoff for unverified candidates. It is not a probability or gate. |
  | `minLines`  | positive `number`    | `3`     | Exclude functions shorter than this source-line count.                            |
  | `ignore`    | `string[]`           | `[]`    | Additional root-relative globs excluded only from similar-code extraction.        |

  ```jsonc theme={null}
  {
    "similarCode": {
      "threshold": 0.8,
      "minLines": 3,
      "ignore": ["src/generated/**"]
    }
  }
  ```

  Config cannot select the provider, model, executable, download, or credential.
  Model setup always needs a separate explicit user action. See
  [Semantic similar code](/analysis/similar-code) for the discovery, inspect, and
  verdict flow.
</Accordion>

<Accordion title="health">
  Configuration for `fallow health`:

  | Field                      | Type       | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
  | :------------------------- | :--------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `maxCyclomatic`            | `number`   | `20`    | Maximum cyclomatic complexity before reporting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  | `maxCognitive`             | `number`   | `15`    | Maximum cognitive complexity before reporting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
  | `maxCrap`                  | `number`   | `30`    | Maximum CRAP score before reporting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | `maxUnitSize`              | `number`   | `60`    | Maximum function length in lines of code before it is reported as an oversized "large function". Raise it to relax the unit-size check for generated or test files (where a `describe()` block spans hundreds of lines) without disabling complexity checks.                                                                                                                                                                                                                                                                                                                                                                                                                           |
  | `crapRefactorBand`         | `number`   | `5`     | Band below `maxCyclomatic` where CRAP-only findings also receive a secondary `refactor-function` action when cognitive complexity is at least half of `maxCognitive`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
  | `ignore`                   | `string[]` | `[]`    | Glob patterns for files to exclude from complexity analysis                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
  | `thresholdOverrides`       | `array`    | `[]`    | Per-file threshold exceptions. Each entry has `files` globs, optional exact `functions`, one or more of `maxCyclomatic`, `maxCognitive`, `maxCrap`, `maxUnitSize`, and optional `reason`. Leave `functions` empty to relax every function in the matching files (which covers both a `describe()` wrapper and its `it()` blocks). JSON health output reports override state in `threshold_overrides`: one row per threshold dimension (`complexity` for the cyclomatic, cognitive, and unit-size ceilings; `crap` for `maxCrap`) with `active`, `stale`, `insufficient`, or `no_match` status; rows from one entry share `override_index`, so group on it to count configured entries. |
  | `suggestInlineSuppression` | `boolean`  | `true`  | Emit `suppress-line` action hints on health findings in JSON output. Auto-omitted when `--baseline`/`--save-baseline` is active regardless of this setting. Set to `false` to opt out across the project when you do not want CI-driven inline suppression hints.                                                                                                                                                                                                                                                                                                                                                                                                                      |

  ```jsonc theme={null}
  {
    "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"
        },
        {
          "files": ["**/*.test.*", "**/*.spec.*"],
          "maxUnitSize": 500,
          "reason": "Test suites: describe/it blocks are long by design"
        }
      ],
      "suggestInlineSuppression": true
    }
  }
  ```
</Accordion>

<Accordion title="audit">
  Configuration for `fallow audit`, the changed-file review command:

  | Field             | Type                    | Default      | Description                                                                                                                                                                                                                                                                                                                                                          |
  | :---------------- | :---------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `gate`            | `"new-only"` \| `"all"` | `"new-only"` | Which findings affect the audit verdict. `new-only` fails only on issues introduced by the current changeset while keeping inherited findings visible as context. `all` gates every finding in changed files and skips the extra base-snapshot attribution pass.                                                                                                     |
  | `css`             | `boolean`               | `true`       | Include styling analytics in `fallow audit`. Set to `false` to match `--no-css`.                                                                                                                                                                                                                                                                                     |
  | `cssDeep`         | `boolean`               | `true`       | Include project-wide styling reachability checks in `fallow audit`. Set to `false` to match `--no-css-deep`; set to `true` to force the same behavior as `--css-deep`.                                                                                                                                                                                               |
  | `cacheMaxAgeDays` | `number`                | `30`         | Max age (in days since last reuse or fresh create) of a persistent reusable base-snapshot worktree cache. Older entries are reclaimed at the top of the next `fallow audit`. `0` disables the GC. Overridable per-run via the [`FALLOW_AUDIT_CACHE_MAX_AGE_DAYS`](/configuration/environment#fallow_audit_cache_max_age_days) env var, which wins when both are set. |

  ```jsonc theme={null}
  {
    "audit": {
      "gate": "new-only",
      "css": true,
      "cssDeep": true,
      "cacheMaxAgeDays": 14
    }
  }
  ```

  ```toml theme={null}
  [audit]
  gate = "all"
  css = true
  cssDeep = true
  cacheMaxAgeDays = 14
  ```
</Accordion>

<Accordion title="fix">
  Configure `fallow fix` behavior.

  | Field                             | Type                            | Default  | Description                                                                             |
  | :-------------------------------- | :------------------------------ | :------- | :-------------------------------------------------------------------------------------- |
  | `catalog.deletePrecedingComments` | `"auto" \| "always" \| "never"` | `"auto"` | Controls contiguous YAML comment blocks immediately above removed pnpm catalog entries. |

  ```jsonc theme={null}
  {
    "fix": {
      "catalog": {
        "deletePrecedingComments": "auto"
      }
    }
  }
  ```

  `auto` removes a leading comment block when it clearly belongs to the deleted catalog entry: the block directly follows the parent `catalog:` / `catalogs.<name>:` header, or follows a blank separator. Use `always` to remove every adjacent leading comment block, or `never` to keep leading comments in place for manual review.

  Two escape hatches keep curated comments safe regardless of policy:

  * Add `# fallow-keep` to any line in a comment block to preserve the entire block even under `always`. Mirrors the existing `fallow-ignore-next-line` / `fallow-ignore-file` inline-suppression convention:

    ```yaml theme={null}
    catalog:
      # fallow-keep: audit trail, CVE-2024-XXXX
      react: ^18.2.0
    ```

  * Under `auto`, section-banner blocks are automatically preserved. A banner is any comment whose body (after `#` and optional whitespace) starts with three or more repeats of `=`, `-`, `*`, `_`, `~`, `+`, or `#`:

    ```yaml theme={null}
    catalog:
      # === React 18 production pins ===
      react: ^18.2.0
    ```

    Under `always` the banner heuristic does not apply; use `# fallow-keep` to protect banners when running with `always`.

  The JSON action emitted to `fixes[N]` carries both `line` (1-based first deleted line, the leading comment when `auto` / `always` absorb one) and `entry_line` (the catalog entry's original 1-based line). CI annotators and dedup caches that key on the entry position should use `entry_line` for a stable anchor; tools that want to point at the actual file edit should use `line`.
</Accordion>

<Accordion title="production">
  Enable [production mode](/analysis/production-mode) to focus on code that ships to users. Accepts the legacy boolean form (applies to every analysis) or a per-analysis object so you can run, for example, production-only health while keeping dead-code and duplication on the full tree:

  ```jsonc theme={null}
  {
    "production": true
  }
  ```

  ```jsonc theme={null}
  {
    "production": {
      "deadCode": false,
      "health": true,
      "dupes": false
    }
  }
  ```

  The CLI flags `--production`, `--production-dead-code`, `--production-health`, and `--production-dupes` (bare combined runs and `fallow audit`) override config. The matching env vars `FALLOW_PRODUCTION`, `FALLOW_PRODUCTION_DEAD_CODE`, `FALLOW_PRODUCTION_HEALTH`, `FALLOW_PRODUCTION_DUPES` follow the same precedence ladder, with per-analysis env beating global env. See [global flags](/cli/global-flags#per-analysis-production-mode) for the full ladder.
</Accordion>

<Accordion title="workspaces">
  Additional workspace patterns beyond what's detected from `package.json` or `pnpm-workspace.yaml`:

  ```jsonc theme={null}
  {
    "workspaces": {
      "patterns": ["tools/*", "shared/*"]
    }
  }
  ```
</Accordion>

<Accordion title="extends">
  Inherit from one or more base config files. Handy for sharing config across projects or keeping a base config with per-project overrides.

  ```jsonc theme={null}
  {
    "extends": ["./configs/base.json", "./configs/strict.json"]
  }
  ```

  ```toml theme={null}
  extends = ["./configs/base.json", "./configs/strict.toml"]
  ```

  The `extends` field supports three source types:

  | Source        | Example                                  | Description                                        |
  | :------------ | :--------------------------------------- | :------------------------------------------------- |
  | Relative path | `"./configs/base.json"`                  | Local file, resolved relative to the config file   |
  | npm package   | `"npm:@my-org/fallow-config"`            | Reads the package's main entry from `node_modules` |
  | HTTPS URL     | `"https://example.com/fallow-base.json"` | Fetched remotely over HTTPS                        |

  ```jsonc theme={null}
  {
    "extends": [
      "./configs/local-overrides.json",
      "npm:@my-org/fallow-config",
      "https://example.com/shared/fallow-base.json"
    ]
  }
  ```

  Key behaviors:

  * **Deep merge:** Object fields (like `rules`) are deep-merged. The child config overrides the base, but unspecified fields are inherited.
  * **Array replacement:** Array fields (like `entry`, `ignorePatterns`) are replaced entirely, not concatenated. If the child specifies `entry`, it overrides the base `entry`.
  * **Cross-format support:** A JSON config can extend a TOML config and vice versa.
  * **Circular detection:** Fallow detects circular extends chains and reports an error.
  * **Max depth:** Extends chains are limited to 10 levels to prevent accidental deep nesting.
  * **String shorthand:** A single path can be passed as a string instead of an array: `"extends": "./base.json"`.

  Paths are resolved relative to the config file that contains the `extends` field.

  ### URL extends

  URL sources must use `https://` (plain HTTP is rejected). Fallow fetches the config on every run with no caching.

  * **Timeout:** 5 seconds by default, configurable via `FALLOW_EXTENDS_TIMEOUT_SECS`
  * **Body limit:** 1 MB maximum response size
  * **Chaining:** A URL-sourced config can extend other URLs or `npm:` packages, but not relative paths (there is no filesystem context to resolve against)

  <Warning>
    URL extends fetch on every run. If the remote server is slow or unavailable, your analysis will fail. Pin critical shared configs to a versioned URL or use `npm:` packages for reliability.
  </Warning>
</Accordion>

<Accordion title="minimumVersion">
  The lowest fallow version this config is written for, as `MAJOR.MINOR.PATCH`.

  An unrecognized config key fails the run with exit 2. That is what catches an `ignorePaths` written where `ignorePatterns` was meant, but it also makes every new config field a coordinated upgrade: the day a team commits a field introduced in a newer version, every runner still on the old one breaks, on the commit that adds the field rather than on the upgrade that would explain it, with an error naming the field so the first guess is a typo.

  Declaring a floor turns that into a clear message.

  ```jsonc theme={null}
  {
    "minimumVersion": "3.21.0",
    "entry": ["src/main.ts"]
  }
  ```

  A binary below the floor stops before it reports any field it does not recognize:

  ```
  fallow.json requires fallow 3.21.0 or newer, running 3.19.0.
  Upgrade fallow, or remove minimumVersion and the fields that need it.
  ```

  Key behaviors:

  * **Inherited through `extends`:** a monorepo base config declares it once and every config that extends it inherits the floor.
  * **Checked before unknown keys:** the version message replaces the misleading field-name error, not just precedes it.
  * **Gates nothing on its own:** at or above the floor an unknown key still fails, because there it really is a typo.
  * **Optional:** unset by default. Absent, nothing changes.
  * **Validated:** a value that is not `MAJOR.MINOR.PATCH` (for example `v3.21`) is itself a config error.

  <Tip>
    Set it in the same change that adds a field introduced in a newer version, not preemptively. A floor that is higher than anything the config actually uses only blocks runners for no reason.
  </Tip>
</Accordion>

<Accordion title="overrides">
  Apply different rules to specific file patterns. For example, relax rules in test files or tighten them in critical paths.

  ```jsonc theme={null}
  {
    "overrides": [
      {
        "files": ["*.test.ts", "*.spec.ts"],
        "rules": {
          "unused-exports": "off"
        }
      },
      {
        "files": ["src/core/**/*.ts"],
        "rules": {
          "unused-exports": "error",
          "unused-types": "error"
        }
      }
    ]
  }
  ```

  ```toml theme={null}
  [[overrides]]
  files = ["*.test.ts", "*.spec.ts"]

  [overrides.rules]
  unused-exports = "off"

  [[overrides]]
  files = ["src/core/**/*.ts"]

  [overrides.rules]
  unused-exports = "error"
  unused-types = "error"
  ```

  Each override object has:

  * **`files`**: Array of glob patterns matched against project-relative paths.
  * **`rules`**: Rule severity overrides that apply to files matching the patterns.

  When multiple overrides match the same file, later overrides take precedence.
</Accordion>

<Accordion title="sealed">
  Mark a config as **sealed** to guarantee it cannot be modified by ancestor configs being injected via `extends`. When `sealed: true`:

  * `extends` paths must be file-relative
  * `extends` paths must resolve **within** the config's own directory (no `../` escapes)
  * `npm:` and `https:` extends are rejected with a clear error

  ```jsonc theme={null}
  {
    "sealed": true,
    "extends": ["./base.json"]
  }
  ```

  ```toml theme={null}
  sealed = true
  extends = ["./base.json"]
  ```

  Use cases:

  * **Library publishers** shipping a `.fallowrc.json` as part of an npm package can guarantee the config is self-contained
  * **Monorepo sub-packages** (e.g., a shared component library used by multiple apps) that intentionally do not inherit from the monorepo root config

  `sealed: true` does **not** affect config discovery. Fallow's first-match-wins walk already stops at the nearest config in the directory tree. This option only constrains what `extends` can reference.
</Accordion>

<Accordion title="boundaries">
  Define architecture boundary zones and import rules. Use a built-in preset or define custom zones.

  ```jsonc theme={null}
  {
    "boundaries": {
      "preset": "bulletproof"
    }
  }
  ```

  Available presets: `layered`, `hexagonal`, `feature-sliced`, `bulletproof`. Or define custom zones and rules for full control.

  See [Architecture boundaries](/analysis/boundaries) for presets, custom zones, examples, and output formats.
</Accordion>

<Accordion title="rulePacks">
  List declarative rule packs: standalone JSON or JSONC files of `banned-call`, `banned-import`, and `banned-effect` rules, loaded as pure data (no project code ever executes). Paths are project-root-relative. Matches report as `policy-violation` findings identified by `<pack>/<rule-id>`.

  ```jsonc theme={null}
  {
    "rulePacks": ["./rule-packs/team-policy.jsonc"]
  }
  ```

  A pack file declares `version: 1`, a unique `name`, and a non-empty `rules` array. Pack names and rule ids must use ASCII letters, digits, `.`, `_`, or `-` so scoped suppression comments can name them unambiguously. `banned-call` rules match callee paths segment-aware and import-resolved (`child_process.*` covers named, namespace, and default imports from `child_process` and `node:child_process`); `banned-import` rules match raw import specifiers segment-aware (`moment` covers `moment/locale/nl`, never `moment-timezone`). Rules scope with optional `files` / `exclude` globs, skip type-only imports with `"ignoreTypeOnly": true`, and carry an optional per-rule `severity` overriding the `rules."policy-violation"` master (default `warn`). Suppress one rule with `// fallow-ignore-next-line policy-violation:<pack>/<rule-id>` or the file-level form; bare `policy-violation` remains the broad family token.

  Run `fallow rule-pack-schema` to print the pack JSON Schema for editor autocomplete, or point `$schema` at `https://raw.githubusercontent.com/fallow-rs/fallow/main/rule-pack-schema.json`. Invalid or missing packs fail config load with exit code 2 instead of silently enforcing nothing. Keep pack files in a committed directory such as `rule-packs/`; `.fallow/` is the gitignored cache directory, so packs stored there vanish from teammates' checkouts.

  See [Policy violations](/explanations/dead-code#policy-violations) for the issue type details.
</Accordion>

<Accordion title="rules">
  Per-issue-type severity rules: `error` (default, fails CI with exit code 1), `warn` (reports but exits 0), or `off` (skip detection entirely).

  ```jsonc theme={null}
  {
    "rules": {
      "unused-files": "warn",
      "unused-exports": "error",
      "circular-dependency": "off",
      "css-token-drift": "warn",
      "css-duplicate-block": "warn",
      "css-selector-complexity": "warn",
      "css-dead-surface": "warn",
      "css-broken-reference": "warn"
    }
  }
  ```

  Styling audit findings use the same severity map. The styling rules are `css-token-drift`, `css-duplicate-block`, `css-selector-complexity`, `css-dead-surface`, and `css-broken-reference`. They default to `warn`, so they stay visible and verdict-neutral unless you set them to `error` or `off`.

  See [Rules and severity](/configuration/rules) for the full list of issue types, including pnpm catalog hygiene such as `unused-catalog-entries` and `empty-catalog-groups`, default severities, and per-glob overrides via the `overrides` field.
</Accordion>

<Accordion title="flags">
  Customize feature flag detection. Add SDK call patterns beyond the built-ins (LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog, Vercel Flags, ConfigCat, Flagsmith, Optimizely, Eppo), declare environment variable prefixes, or enable opt-in heuristic detection.

  | Field                    | Type           | Default | Description                                                                                                                                                                                                                                                       |
  | :----------------------- | :------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `sdkPatterns`            | `SdkPattern[]` | `[]`    | Additional SDK call patterns to detect as feature flags. Merged with built-ins. Each entry: `function` (function name to match), `nameArg` (zero-based index of the argument containing the flag name, default `0`), `provider` (optional label shown in output). |
  | `envPrefixes`            | `string[]`     | `[]`    | Environment variable prefixes that indicate feature flags. Merged with built-ins. Only `process.env.*` accesses matching these prefixes are reported.                                                                                                             |
  | `configObjectHeuristics` | `boolean`      | `false` | Enable heuristic detection: property accesses on objects whose name contains "feature", "flag", or "toggle" are reported as low-confidence flags. Opt-in due to higher false-positive rate.                                                                       |

  ```jsonc theme={null}
  {
    "flags": {
      "sdkPatterns": [
        { "function": "useFlag", "nameArg": 0, "provider": "LaunchDarkly" },
        { "function": "client.getFeatureValue", "nameArg": 0 }
      ],
      "envPrefixes": ["FEATURE_", "NEXT_PUBLIC_ENABLE_"],
      "configObjectHeuristics": false
    }
  }
  ```

  See [`fallow flags`](/cli/flags) for the command that consumes this configuration.
</Accordion>

<Accordion title="resolve">
  Module resolver configuration. Controls how fallow matches `package.json` `exports` and `imports` maps.

  | Field        | Type       | Default | Description                                                                                                                                                                                                                                                                                                                      |
  | :----------- | :--------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `conditions` | `string[]` | `[]`    | Additional export / import condition names to honor during resolution. Merged with fallow's built-in set: `development`, `import`, `require`, `default`, `types`, `node` (plus `react-native` and `browser` when the React Native or Expo plugin is active). User conditions are matched with higher priority than the baseline. |

  Use this to honor community-defined conditions like `worker`, `edge-light`, `deno`, or any custom condition your bundler uses. The built-in `development` condition already ships in the baseline, so packages that declare a `development` branch (common in monorepos where `development` points at source and `import` points at compiled output) resolve to source without any config.

  ```jsonc theme={null}
  {
    "resolve": {
      "conditions": ["worker", "edge-light"]
    }
  }
  ```

  With this config, a `package.json` like:

  ```jsonc theme={null}
  {
    "exports": {
      "./api": {
        "worker": "./src/api.worker.ts",
        "import": "./dist/api.js"
      }
    }
  }
  ```

  resolves `./api` to `src/api.worker.ts` instead of `dist/api.js`.

  See the [Node.js community conditions reference](https://nodejs.org/api/packages.html#community-conditions-definitions) for the full list of established condition names.
</Accordion>

<Accordion title="codeowners">
  Path to a CODEOWNERS file for `--group-by owner`. When unset, fallow auto-probes `CODEOWNERS`, `.github/CODEOWNERS`, `.gitlab/CODEOWNERS`, and `docs/CODEOWNERS`. Set this to use a non-standard location.

  ```jsonc theme={null}
  {
    "codeowners": ".github/CODEOWNERS"
  }
  ```
</Accordion>

<Accordion title="framework">
  Inline framework plugin definitions. Define custom entry points, ignored files, or test patterns without a separate plugin file.

  ```jsonc theme={null}
  {
    "framework": [
      {
        "name": "my-framework",
        "entry": ["src/server.ts"],
        "ignore": ["**/*.internal.ts"]
      }
    ]
  }
  ```
</Accordion>

<Accordion title="plugins">
  Paths to external plugin files or directories. In addition to these explicit paths, fallow automatically discovers `*.toml`, `*.json`, `*.jsonc` files in `.fallow/plugins/` and `fallow-plugin-*.{toml,json,jsonc}` in the project root.

  ```jsonc theme={null}
  {
    "plugins": ["./my-plugins/custom.toml", "./plugins/"]
  }
  ```
</Accordion>

<Accordion title="cache">
  Incremental cache tuning. Use `dir` to relocate the extraction cache and `maxSizeMb` to cap its serialized size and trigger LRU eviction during save.

  ```jsonc theme={null}
  {
    "cache": {
      "dir": "/tmp/fallow-cache",
      "maxSizeMb": 64
    }
  }
  ```

  Default cache file: `.fallow/cache.bin` under the project root. When `cache.dir` is set, fallow stores the cache file under that directory. The env var `FALLOW_CACHE_DIR` overrides `cache.dir` when both are set.

  Default cap: 256 MB. The cap is the size of the serialized extraction cache; saves that cross 80% of the cap evict the oldest entries down to 60%. The env var `FALLOW_CACHE_MAX_SIZE` overrides `cache.maxSizeMb` when both are set. Both size values are interpreted as whole megabytes.

  The cache invalidates automatically when extraction-affecting config changes
  (currently active plugin names and inline framework definition names).
  Detection-only fields such as `entry`, `ignorePatterns`, and severity overrides
  do not bust the extraction cache.

  `--no-cache` disables the cache entirely; this section is then irrelevant.
</Accordion>

<Accordion title="regression">
  Regression detection baseline embedded in config. Stores issue counts from a known-good state for CI regression checks. Populated by `--save-regression-baseline` (no path argument), read by `--fail-on-regression`.

  ```jsonc theme={null}
  {
    "regression": {
      "baseline": {
        "unused_files": 11,
        "unused_exports": 48,
        "unused_types": 5,
        "unused_dependencies": 3,
        "circular_dependencies": 1
      }
    }
  }
  ```
</Accordion>

## JSON Schema

The `$schema` field enables autocomplete and validation in your editor:

```jsonc theme={null}
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json"
}
```

Generate it locally:

```bash theme={null}
fallow config-schema > schema.json
```

## See also

<CardGroup>
  <Card title="Rules & Severity" icon="scale-balanced" href="/configuration/rules">
    Control issue severity for incremental CI adoption.
  </Card>

  <Card title="Inline Suppression" icon="comment-slash" href="/configuration/suppression">
    Suppress individual findings directly in source code.
  </Card>

  <Card title="Custom Plugins" icon="puzzle-piece" href="/frameworks/custom-plugins">
    Extend fallow with framework-specific entry point detection.
  </Card>
</CardGroup>


# Rules & severity
Source: https://docs.fallow.tools/configuration/rules

Configure fallow rules to set issue severity as error, warning, or off. Use rules for incremental CI adoption and granular dead code reporting.

Rules control the severity of each issue type, making it easy to adopt fallow incrementally in CI.

<Tip>
  Start with all rules as `warn`, then promote to `error` one type at a time as the codebase cleans up.
</Tip>

## Severity levels

| Level   | Behavior                                |
| :------ | :-------------------------------------- |
| `error` | Report and fail CI (non-zero exit code) |
| `warn`  | Report but exit 0                       |
| `off`   | Don't detect or report                  |

Most issue types default to `error` when not configured. The exceptions are `private-type-leaks`, `coverage-gaps`, `prop-drilling`, `thin-wrapper`, `duplicate-prop-shape`, and `require-suppression-reason` (default `off`), plus `stale-suppressions` and `policy-violation` (default `warn`).

## Configuration

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "rules": {
      "unused-files": "error",
      "unused-exports": "warn",
      "unused-types": "off",
      "private-type-leaks": "off",
      "unused-dependencies": "error",
      "unused-dev-dependencies": "warn",
      "unused-optional-dependencies": "warn",
      "unused-enum-members": "warn",
      "unused-class-members": "off",
      "unresolved-imports": "error",
      "unlisted-dependencies": "error",
      "duplicate-exports": "warn",
      "circular-dependencies": "error",
      "re-export-cycle": "warn",
      "boundary-violation": "error",
      "type-only-dependencies": "error",
      "test-only-dependencies": "warn",
      "dev-dependencies-in-production": "warn",
      "coverage-gaps": "off",
      "stale-suppressions": "warn"
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [rules]
  unused-files = "error"
  unused-exports = "warn"
  unused-types = "off"
  private-type-leaks = "off"
  unused-dependencies = "error"
  unused-dev-dependencies = "warn"
  unused-optional-dependencies = "warn"
  unused-enum-members = "warn"
  unused-class-members = "off"
  unresolved-imports = "error"
  unlisted-dependencies = "error"
  duplicate-exports = "warn"
  circular-dependencies = "error"
  re-export-cycle = "warn"
  boundary-violation = "error"
  type-only-dependencies = "error"
  test-only-dependencies = "warn"
  dev-dependencies-in-production = "warn"
  coverage-gaps = "off"
  stale-suppressions = "warn"
  ```
</CodeGroup>

## Available rule names

| Rule                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unused-files`                       | Files not reachable from any entry point                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `unused-exports`                     | Exported symbols never imported                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `unused-types`                       | Type aliases and interfaces never referenced                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `private-type-leaks`                 | Opt-in API hygiene check for exported signatures that reference same-file private types (default `off`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `unused-dependencies`                | Packages in `dependencies` never used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `unused-dev-dependencies`            | Packages in `devDependencies` never used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `unused-optional-dependencies`       | Packages in `optionalDependencies` never used                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `unused-enum-members`                | Enum values never referenced                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `unused-class-members`               | Class members never referenced                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `unused-store-members`               | Pinia store members (state / getter / action) never accessed by any consumer; runs only when `pinia` / `@pinia/nuxt` is a dependency (default `warn`)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `unused-catalog-entries`             | Entries in `pnpm-workspace.yaml`'s `catalog:` / `catalogs:` maps that no workspace package references via the `catalog:` protocol (default `warn`)                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `empty-catalog-groups`               | Named `catalogs.<name>:` groups in `pnpm-workspace.yaml` that contain no package entries (default `warn`; top-level `catalog:` placeholders are ignored)                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `unresolved-catalog-references`      | `package.json` references to `catalog:` / `catalog:<name>` whose catalog does not declare the package (default `error`; `pnpm install` would fail)                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `unused-dependency-overrides`        | `pnpm-workspace.yaml#overrides` / `package.json#pnpm.overrides` entries whose target package is not declared by any workspace package and is not present in `pnpm-lock.yaml` (default `warn`; when the lockfile is missing the check degrades to manifest-only and the `hint` field flags those conservative cases)                                                                                                                                                                                                                                                                      |
| `misconfigured-dependency-overrides` | `pnpm.overrides` entries whose key is unparsable or value is missing (default `error`; `pnpm install` would fail)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `unresolved-imports`                 | Imports that can't be resolved                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `unlisted-dependencies`              | Imported packages not in `package.json`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `duplicate-exports`                  | Same symbol exported from multiple files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `circular-dependencies`              | Modules that import each other, directly or transitively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `re-export-cycle`                    | Barrel files re-exporting from each other in a loop (`kind: "multi-node"`), or a single barrel re-exporting from itself (`kind: "self-loop"`). Distinct from `circular-dependencies` (which describes runtime import loops); re-export cycles are structurally a no-op and almost always bugs. Default `warn`. Per-file `overrides.rules.re-export-cycle` is a no-op because the cycle spans multiple files; use the project-wide `rules` block or `// fallow-ignore-file re-export-cycle` on any member. Aliases: `re-export-cycles`, `reexport-cycle`, `reexport-cycles` all accepted. |
| `boundary-violation`                 | Imports that cross user-defined architecture zone boundaries                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `policy-violation`                   | Calls, imports, or catalogue-derived effects banned by a rule pack (the `rulePacks` config key). Default `warn` so a new pack never hard-fails CI on its first run; a per-rule `severity` in the pack overrides this master per finding, and the exit-code gate reads the effective per-finding severity. `off` is a kill switch for the whole evaluator.                                                                                                                                                                                                                                |
| `type-only-dependencies`             | Production dependencies only imported via `import type`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `test-only-dependencies`             | Production dependencies only imported by test files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `dev-dependencies-in-production`     | Packages in `devDependencies` imported by production code with a runtime import; they should be promoted to `dependencies` (default `warn`)                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `coverage-gaps`                      | Runtime files and exports not reached by any test dependency path (default `off`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `stale-suppressions`                 | `fallow-ignore` comments or `@expected-unused` JSDoc tags that no longer match any issue (default `warn`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `require-suppression-reason`         | Opt-in suppression hygiene check: when enabled, every `fallow-ignore-*` comment and `@expected-unused` tag must carry a trailing `-- <reason>`; a suppression without one reports as `missing-suppression-reason` (default `off`)                                                                                                                                                                                                                                                                                                                                                        |

<Note>
  `circular-dependencies` and `circular-dependency` are interchangeable. Both forms are accepted in `rules`, `overrides[].rules`, and inline directives, so the singular/plural slug doesn't matter.
</Note>

<Accordion title="Incremental adoption strategy">
  Adopting fallow in an existing codebase works best gradually:

  1. **Start permissive.** Set all rules to `warn` so you see issues without blocking CI.
  2. **Fix high-confidence rules first.** Promote `unresolved-imports` and `unlisted-dependencies` to `error`. These are almost never false positives.
  3. **Tackle unused files.** Promote `unused-files` to `error`. Unreachable files are safe to remove.
  4. **Address unused exports.** Usually the largest category. Promote to `error` once the count is manageable.
  5. **Enable remaining rules.** Promote `unused-types`, `unused-enum-members`, and `unused-class-members` as you clean up each category. Enable `private-type-leaks` only for packages where public API or declaration hygiene matters.

  Use [baselines](/analysis/dead-code#baseline-comparison) to avoid blocking CI on pre-existing issues while enforcing rules on new code.
</Accordion>

<Info>
  Use `--fail-on-issues` in CI to temporarily treat all warnings as errors without changing the config file. Good for pre-merge gates on critical branches.
</Info>

```bash theme={null}
fallow dead-code --fail-on-issues
```

## Exit codes

| Code | Meaning                                     |
| :--- | :------------------------------------------ |
| `0`  | No error-severity issues                    |
| `1`  | Error-severity issues found                 |
| `2`  | Fatal error (invalid config, parse failure) |

## See also

<CardGroup>
  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Full config file reference with all available fields.
  </Card>

  <Card title="CI Integration" icon="circle-check" href="/integrations/ci">
    Set up fallow in GitHub Actions, GitLab CI, and more.
  </Card>
</CardGroup>


# Inline suppression
Source: https://docs.fallow.tools/configuration/suppression

Suppress fallow findings with inline fallow-ignore comments, JSDoc visibility tags (@public, @internal, @beta, @alpha), and @expected-unused. Handle false positives, library exports, and intentional exceptions.

Suppress specific findings with inline comments or JSDoc tags. Useful for false positives or intentional exceptions.

<Tip>
  Prefer config-level rules for broad patterns. Use inline suppression sparingly for individual exceptions. For library exports consumed externally, use [JSDoc visibility tags](#jsdoc-visibility-tags) (`@public`, `@internal`, `@beta`, `@alpha`) instead of suppression comments.
</Tip>

## JSDoc visibility tags

Exports annotated with JSDoc visibility tags are never reported as unused. Fallow recognizes `@public`, `@internal`, `@beta`, and `@alpha`. Use these for library APIs consumed by external projects, or exports intentionally reserved for specific audiences. They have zero internal references but are intentionally part of your API surface.

```ts theme={null}
/** @public */
export function createClient() {
  // Not imported anywhere in this repo, but consumed by users of the library
}

/**
 * Configuration options for the client.
 * @public
 */
export interface ClientOptions {
  baseUrl: string;
  timeout?: number;
}

/** @internal */
export function resetState() {
  // Used by sibling packages in the monorepo, not public API
}

/** @beta */
export function experimentalFeature() {
  // Available to early adopters, not yet stable
}

/** @alpha */
export function unstableApi() {
  // Early-stage API, subject to breaking changes
}

/** @api public */
export type UserId = string; // TSDoc @api convention also supported
```

The tags work with all export types: named, default, classes, interfaces, enums, type aliases, and multi-specifier exports (`export { foo, bar }`).

<Note>
  Only `/** */` JSDoc block comments are recognized. Line comments (`// @public`) and regular block comments (`/* @public */`) have no effect.
</Note>

## `@expected-unused` JSDoc tag

Mark exports as intentionally unused with `/** @expected-unused */`. Unlike visibility tags (`@public`, `@internal`), this tag is tracked for staleness. If the export later becomes imported by another module, fallow reports the tag as a stale suppression.

```ts theme={null}
/** @expected-unused */
export const deprecatedHelper = () => {
  // Intentionally kept but not used anywhere
};
```

Use `@expected-unused` when you want to:

* Suppress an unused export finding
* Be notified if the export becomes used again (via the `stale-suppressions` rule)

The `stale-suppressions` rule (default: `warn`) controls the severity of stale `@expected-unused` tags. See [dead code explained](/explanations/dead-code#stale-suppressions) for details.

## Comment syntax

```ts theme={null}
// Suppress all issues on the next line
// fallow-ignore-next-line
export const keepThis = 1;

// Suppress a specific issue type
// fallow-ignore-next-line unused-export
export const keepThisToo = 2;

// Suppress all issues in the entire file
// fallow-ignore-file

// Suppress a specific issue type file-wide
// fallow-ignore-file unused-export
```

### Suppressing complexity findings

Suppress individual functions from the health command's complexity report. Both cyclomatic and cognitive metrics are suppressed together.

```ts theme={null}
// fallow-ignore-next-line complexity
function* parseCsv(text) {
  // intentionally complex parser, not worth refactoring
  // ...
}

function processRow(row) {
  // this function is NOT suppressed, still appears in health output
  // ...
}
```

File-level suppression excludes all functions in the file from complexity findings (file health scores are unaffected):

```ts theme={null}
// fallow-ignore-file complexity
```

## Reference

| Comment                                     | Scope                                                             |
| :------------------------------------------ | :---------------------------------------------------------------- |
| `// fallow-ignore-next-line`                | All issues on the next line                                       |
| `// fallow-ignore-next-line <type>`         | Specific issue on the next line                                   |
| `// fallow-ignore-next-line <type>, <type>` | Multiple issue types on the next line (comma- or space-separated) |
| `// fallow-ignore-file`                     | All issues in the file                                            |
| `// fallow-ignore-file <type>`              | Specific issue type for the file                                  |

### Multi-kind markers and typos

A marker can list more than one token. When one of the tokens does not match a known issue kind (typo, or a kind renamed in a newer fallow release), the recognized tokens still apply and each unknown token surfaces as a `stale-suppression` finding. fallow includes a "Did you mean ...?" Levenshtein hint when a known kind is within edit distance 2, so an upgrade across a rename never silently breaks the entire marker.

```ts theme={null}
// Recognized + unknown on the same marker:
// fallow-ignore-next-line unused-export, complexity-typo
export const foo = 1;
// `unused-export` still suppresses `foo`; `complexity-typo` surfaces as a stale
// suppression so you can fix the typo or drop the unknown token.
```

JSON consumers can distinguish unknown-kind tokens from stale-but-known tokens via the additive `origin.kind_known` field on `stale_suppressions[].origin` (present and `false` only in the unknown-kind case; absent when the kind is recognized).

## Documenting suppressions with a reason

Every suppression comment and `@expected-unused` tag can carry a trailing `-- <reason>` explaining why it is there:

```ts theme={null}
// fallow-ignore-next-line unused-export -- public compatibility export
export const legacyHelper = () => {};

// fallow-ignore-file -- generated route map

/** @expected-unused -- kept for the v3 migration */
export const oldApi = () => {};
```

By default the reason is optional and recorded in suppression hygiene output. Enable the opt-in `require-suppression-reason` rule (default `off`) to enforce that every suppression documents itself:

```jsonc .fallowrc.json theme={null}
{ "rules": { "require-suppression-reason": "warn" } }
```

With the rule at `warn` (or `error` to fail CI), any `fallow-ignore-*` comment or `@expected-unused` tag without a `-- <reason>` reports as a `missing-suppression-reason` finding, so you can find and backfill undocumented suppressions across the codebase. See [Rules & Severity](/configuration/rules#available-rule-names) for the rule reference.

## Issue type tokens

Use these tokens with suppression comments. The **Scope** column shows whether each type supports line-level (`// fallow-ignore-next-line`), file-level (`// fallow-ignore-file`), or both.

| Token                               | Issue                                                                                                                                                                         | Scope |
| :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---- |
| `unused-file`                       | Unused file                                                                                                                                                                   | file  |
| `unused-export`                     | Unused export                                                                                                                                                                 | both  |
| `unused-type`                       | Unused type export                                                                                                                                                            | both  |
| `unused-dependency`                 | Unused dependency                                                                                                                                                             | file  |
| `unused-dev-dependency`             | Unused devDependency                                                                                                                                                          | file  |
| `unused-enum-member`                | Unused enum member                                                                                                                                                            | both  |
| `unused-class-member`               | Unused class member                                                                                                                                                           | both  |
| `unresolved-import`                 | Unresolved import                                                                                                                                                             | both  |
| `unlisted-dependency`               | Unlisted dependency                                                                                                                                                           | both  |
| `duplicate-export`                  | Duplicate export                                                                                                                                                              | both  |
| `code-duplication`                  | Code duplication                                                                                                                                                              | file  |
| `circular-dependency`               | Circular dependency                                                                                                                                                           | both  |
| `boundary-violation`                | Boundary violation (covers the whole family: import direction, zone coverage, forbidden calls; `boundary-call-violation` and `boundary-call-violations` are accepted aliases) | both  |
| `policy-violation:<pack>/<rule-id>` | One rule-pack policy violation. Bare `policy-violation` still covers every rule-pack rule on the line or file                                                                 | both  |
| `type-only-dependency`              | Type-only dependency                                                                                                                                                          | file  |
| `test-only-dependency`              | Test-only dependency                                                                                                                                                          | file  |
| `complexity`                        | Function exceeding complexity threshold                                                                                                                                       | both  |
| `coverage-gaps`                     | File with no test dependency path                                                                                                                                             | file  |
| `feature-flag`                      | Detected feature flag pattern                                                                                                                                                 | both  |

<Accordion title="Tokens grouped by command">
  **`fallow dead-code`** (dead code analysis):
  `unused-file`, `unused-export`, `unused-type`, `unused-dependency`, `unused-dev-dependency`, `unused-enum-member`, `unused-class-member`, `unresolved-import`, `unlisted-dependency`, `duplicate-export`, `circular-dependency`, `boundary-violation`, `policy-violation`, `policy-violation:<pack>/<rule-id>`, `type-only-dependency`, `test-only-dependency`

  **`fallow health`** (complexity and coverage):
  `complexity`, `coverage-gaps`

  **`fallow dupes`** (code duplication):
  `code-duplication`

  **`fallow flags`** (feature flag detection):
  `feature-flag`
</Accordion>

<Note>
  The `circular-dependency` and `circular-dependencies` slugs are interchangeable wherever rule slugs are accepted (inline directives, config `rules`, `overrides[].rules`). The singular form is canonical for inline directives, the plural form is canonical for `rules` config; both are accepted on either surface as aliases.
</Note>

## When to use suppression

Prefer config-level solutions ([rules](/configuration/rules), [ignoreExports](/configuration/overview#ignoreexports)) for broad patterns. Use inline suppression for:

* Individual false positives
* Temporary suppression during migration

<Warning>
  Don't suppress systemic issues. If a pattern affects many files, configure it at the project level instead.
</Warning>

## Config-level vs inline suppression

<CodeGroup>
  ```ts Bad: many inline suppressions theme={null}
  // src/components/Button.tsx
  // fallow-ignore-next-line unused-export
  export const Button = () => { /* ... */ };

  // src/components/Input.tsx
  // fallow-ignore-next-line unused-export
  export const Input = () => { /* ... */ };

  // src/components/Modal.tsx
  // fallow-ignore-next-line unused-export
  export const Modal = () => { /* ... */ };

  // Repeated across dozens of component files...
  ```

  ```jsonc Good: config-level ignoreExports theme={null}
  // .fallowrc.json
  {
    "ignoreExports": [
      {
        "file": "src/components/**/*.tsx",
        "exports": ["*"]
      }
    ]
  }
  ```
</CodeGroup>

## See also

<CardGroup>
  <Card title="Rules & Severity" icon="scale-balanced" href="/configuration/rules">
    Control issue severity at the project level.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Full config file reference including ignoreExports and ignorePatterns.
  </Card>
</CardGroup>


# Workspaces
Source: https://docs.fallow.tools/configuration/workspaces

Fallow automatically detects monorepo workspaces for npm, yarn, pnpm, and Deno. Resolves cross-package imports and supports per-package configuration.

Fallow detects and analyzes monorepo workspaces automatically. It understands npm, yarn, pnpm, and Deno workspace protocols, resolves cross-package imports through `node_modules` symlinks or Deno import maps, and supports scoping output to a single package.

<Info>
  Workspace detection is automatic. If your repo has a `workspaces` field in `package.json`, a `pnpm-workspace.yaml` file, or a `workspace` field in a root `deno.json` / `deno.jsonc`, fallow will find and analyze all packages.
</Info>

## Workspace auto-detection

Fallow detects workspaces from these sources:

| Source                                       | Example                              |
| :------------------------------------------- | :----------------------------------- |
| `package.json` `workspaces` field            | `"workspaces": ["packages/*"]`       |
| `pnpm-workspace.yaml`                        | `packages: ["packages/*", "apps/*"]` |
| `deno.json` / `deno.jsonc` `workspace` field | `"workspace": ["./packages/*"]`      |

<CodeGroup>
  ```json package.json (npm / yarn) theme={null}
  {
    "workspaces": [
      "packages/*",
      "apps/*"
    ]
  }
  ```

  ```yaml pnpm-workspace.yaml theme={null}
  packages:
    - "packages/*"
    - "apps/*"
  ```
</CodeGroup>

## Deno workspaces

A root `deno.json` or `deno.jsonc` drives workspace discovery the same way `package.json` does for npm. The `workspace` field lists member globs and accepts both the bare array form and the object form:

<CodeGroup>
  ```jsonc deno.json (array form) theme={null}
  {
    "workspace": ["./apps/*", "./packages/*"]
  }
  ```

  ```jsonc deno.json (object form) theme={null}
  {
    "workspace": {
      "members": ["./apps/*", "./packages/*"]
    }
  }
  ```
</CodeGroup>

Each member's `name` and `exports` are read like their `package.json` equivalents, so `@scope/lib` with `"exports": { ".": "./mod.ts" }` resolves exactly like an npm package export map. When a member directory contains both a `package.json` and a `deno.json`, the `package.json` wins for package identity.

Import maps (`imports` in root or member configs) resolve per package: an exact specifier match wins, otherwise the longest matching slash-prefix entry applies. Deno workspace member names count as listed dependencies, so importing a sibling package by name is not reported as an unlisted dependency.

A pure Deno root (no root `package.json`) does not warn about a missing `node_modules` directory. A malformed root `deno.json` / `deno.jsonc` is an explicit analysis error (exit 2) rather than a silently empty workspace list.

## Cross-workspace imports

When `apps/web` imports from `@myorg/ui`, fallow resolves the import through the `node_modules` symlink back to the workspace source files. Symlinked paths are canonicalized, so usage is tracked against the real source location, not the `node_modules` copy.

```ts apps/web/src/App.tsx theme={null}
// Resolves to packages/ui/src/Button.tsx via node_modules symlink
import { Button } from '@myorg/ui'
```

### Pnpm content-addressable store

Pnpm uses a content-addressable store with a `.pnpm` virtual store inside `node_modules`. Fallow detects these paths and maps them back to the original workspace source files. Cross-package usage is tracked correctly even with pnpm's strict isolation mode.

## Package exports resolution

Fallow resolves the `exports` field in each package's `package.json`, including subpath patterns:

```json packages/ui/package.json theme={null}
{
  "name": "@myorg/ui",
  "exports": {
    ".": "./src/index.ts",
    "./icons": "./src/icons/index.ts",
    "./theme/*": "./src/theme/*.ts"
  }
}
```

An import of `@myorg/ui/icons` resolves to `packages/ui/src/icons/index.ts`.

## Output directory mapping

When a package's `exports` or `main` points to a build output directory (`dist`, `build`, `out`, `esm`, `cjs`), fallow maps it back to the corresponding source file. It tries the same relative path under `src/` with source extensions (`.ts`, `.tsx`, `.js`, `.jsx`).

```json packages/utils/package.json theme={null}
{
  "main": "dist/index.js"
}
```

Fallow maps `dist/index.js` back to `src/index.ts` (or `.js`, `.tsx`, etc.) if the source file exists.

## Per-package tsconfig.json

Fallow discovers `tsconfig.json` files in each workspace package automatically. Path aliases from each package's `tsconfig.json` are used when resolving imports within that package.

```json packages/ui/tsconfig.json theme={null}
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

## Scoping output to workspaces

Use `-w` / `--workspace` to focus on one or more workspaces. Fallow still analyzes the full monorepo graph; only the reported issues are scoped.

Patterns support three forms:

* **Exact package name** or **workspace path**: `web`, `@myorg/ui`, `apps/web`
* **Glob** matched against BOTH the package name AND the workspace path relative to the repo root: `apps/*`, `@scope/*`
* **Negation** with a `!` prefix: `!apps/legacy`

Values can be comma-separated or the flag repeated. Quote patterns containing `!` or glob characters so your shell doesn't expand them.

```bash theme={null}
# Single package (back-compat with earlier fallow versions)
fallow dead-code -w @myorg/ui

# Multiple packages (comma-separated or repeated)
fallow dead-code -w web,admin
fallow dead-code -w web -w admin

# Glob: all apps, all scoped packages
fallow dead-code -w 'apps/*'
fallow dead-code -w '@myorg/*'

# Everything under apps/ except legacy
fallow dead-code -w 'apps/*,!apps/legacy'

# Everything except a workspace (negation only)
fallow dead-code -w '!apps/legacy'
```

```bash title="$ fallow dead-code -w 'apps/*,!apps/legacy'" theme={null}
● Unused exports (2)
  apps/web/src/Button.tsx
    :15 ButtonVariant
  apps/admin/src/Modal.tsx
    :8  ModalContext
  Exported symbols with zero references

✗ 2 issues (31ms, 1,247 files)
```

<Tip>
  For CI matrix jobs, combine `--workspace` with `--changed-since`: fallow intersects the two filters so you analyze only changed files inside the matched workspaces.
</Tip>

## Additional workspace patterns

If fallow doesn't detect all your workspace packages automatically, add extra patterns in your config:

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "workspaces": {
      "patterns": ["tools/*", "shared/*"]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [workspaces]
  patterns = ["tools/*", "shared/*"]
  ```
</CodeGroup>

These patterns are additive. They extend whatever fallow already detects from `package.json`, `pnpm-workspace.yaml`, or a root Deno config.

## See also

<CardGroup>
  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Full config file reference including all available fields.
  </Card>

  <Card title="fallow dead-code" icon="terminal" href="/cli/dead-code">
    CLI reference for running analysis across workspaces.
  </Card>
</CardGroup>


# Dead code explained
Source: https://docs.fallow.tools/explanations/dead-code

What each issue type in fallow's dead-code output means, how to interpret the results, and when to act. Covers unused class members with inheritance tracking, circular dependency detection with no depth limits, and CSS/SCSS import resolution.

This page covers what `fallow dead-code` reports, how to prioritize findings, and when to act.

## Issue types

Fallow reports multiple dead-code issue types. Each type has a default severity that determines whether it causes a non-zero exit code with `--fail-on-issues`.

### Unused files

Files not reachable from any entry point. No module in the project imports them, and they are not matched by any framework plugin or entry point pattern.

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

**When to act:** Almost always. Unused files add to IDE indexing time and confuse search results.

**Common false positives:**

* **Scripts run directly** (e.g., `node scripts/seed.ts`): Add to `entry` in config, or ensure the script is in a `package.json` script field (fallow parses those).
* **Files loaded by tools fallow doesn't know about**: Add to `entry` or the relevant plugin config.

### Unused exports

Exported symbols never imported by any other module. The export exists but nothing references it.

A TypeScript namespace declared without the `export` keyword (`namespace Foo { export const inner = 1 }`, also `declare namespace` and the legacy `module Foo {}` form) is a local binding: its inner `export` declarations are members of that namespace, not exports of the file, so fallow never reports them here or under unused types. Only `export namespace Foo { ... }` contributes a file-level export (`Foo` itself).

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

**When to act:** Most unused exports should be removed or unexported. They inflate the public API surface and confuse consumers about what the module does.

**When it's OK to keep:**

* **Library public API**: Exports consumed by external users fallow can't see. Mark them with [`/** @public */`](/configuration/suppression#jsdoc-visibility-tags) (or `@internal`, `@beta`, `@alpha`) JSDoc tags, add the library entry point to [`entry`](/configuration/overview), or use [`ignoreExports`](/configuration/overview#ignoreexports) for broad patterns.
* **Convention-based exports**: Exports consumed by frameworks via naming conventions (e.g., Next.js `getStaticProps`). Fallow's framework plugins handle most of these. If one is missed, configure the plugin or add an ignore pattern.

### Unused types

Type aliases and interfaces never referenced by any module.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**When to act:** Remove unused types. They add noise to auto-import suggestions and inflate the public type surface.

**When it's OK to keep:**

* **Shared type packages**: Types exported for external consumers. Mark the package entry point in `entry`.

### Private type leaks

Exported values, functions, classes, and types whose public TypeScript signature references a same-file type declaration that is NOT itself exported. Consumers may see the private type's name in generated declarations or API docs but cannot import it, so they end up retyping it or using `Parameters<typeof X>[0]` / `ReturnType<typeof X>` workarounds.

This is an opt-in API hygiene check, not a default dead-code finding. It is most useful for packages that publish TypeScript declarations or maintain a public API surface. For app-internal exports, private `Props`, `Options`, and `State` helper types are often intentional and should not be exported just to satisfy this rule.

| Severity | Default |
| :------- | :------ |
| Off      | Yes     |

**Example:**

```typescript theme={null}
type Props = { label: string; }; // private to the module

export function Component(p: Props): void {} // public, but Props leaks
```

**When to act:** Enable this check for publishable packages or declaration-emitting modules. For findings on that API surface, export the backing type alongside the exported symbol, or restructure the public signature so it doesn't reference the private type:

```typescript theme={null}
export type Props = { label: string; };
export function Component(p: Props): void {}
```

**Interaction with unused types:** when you export the backing type to fix a leak, fallow does not turn around and report the new export as `unused-types` even if no other module imports it. Any type whose name is referenced from a public signature in the same file is treated as load-bearing for the public API and is excluded from the unused-types check.

**Skipped patterns:**

* **ECMAScript `#field` private members and TypeScript `private` accessibility**: these are not part of the public signature, so types they reference do not leak. `class Service { #state: InternalState; }` does not flag `InternalState`.
* **Storybook story files**: `*.stories.{ts,tsx,js,jsx,mts,cts,mjs,cjs}` and `*.story.*` variants are skipped because the canonical `type Story = StoryObj<typeof X>; export const Default: Story = ...` pattern would otherwise generate one finding per story.
* **Framework routing conventions**: route files where the framework forces multiple exports per file to share a private `Props` / `Params` / `LoaderArgs` type. Coverage:

  * **Next.js App Router**: `app/**/{page,layout,template,loading,error,not-found,route,default,global-error,forbidden,unauthorized}.{ts,tsx,js,jsx}` plus the metadata files (`opengraph-image`, `twitter-image`, `icon`, `apple-icon`, `manifest`, `sitemap`, `robots`).
  * **Next.js Pages Router**: any file under `pages/`.
  * **Gatsby**: pages and templates.
  * **Remix v2 + TanStack Router**: top-level files in `app/routes/` and folder-route entries (`route.tsx`, `_layout.tsx`, `_index.tsx`, `index.tsx`, `__root.tsx`). Subdirectories under `app/routes/<segment>/` are still checked because users co-locate non-route helpers there.
  * **Expo Router**: `_layout.tsx` and `+*.tsx` special files.

  Patterns match anywhere in the path so monorepo subpackages (`packages/web/src/app/blog/[slug]/page.tsx`) are skipped too.

**Enable:** run `fallow dead-code --private-type-leaks`, or set `private-type-leaks: "warn"` / `"error"` in [`rules`](/configuration/rules).

**Suppression:** add `// fallow-ignore-next-line private-type-leak` above the affected export, or keep `private-type-leaks: "off"` in [`rules`](/configuration/rules).

**Prior art:** Rust's `unreachable_pub` lint, TypeScript's TS4023 / TS4060 errors emitted with `--declaration`. ESLint has no equivalent rule today.

### Unused dependencies

Packages listed in `dependencies` that are never imported in source code and not used as script binaries in `package.json`.

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

**When to act:** Remove from `package.json` when nothing imports it. If the finding says the package is imported in another workspace, move the dependency to that consuming workspace instead. Unused dependencies slow down `npm install`, increase `node_modules` size, and expand the attack surface for supply chain vulnerabilities.

**Internal workspace packages count too:** in monorepos, workspace package names (e.g., `@repo/ui`) listed in another workspace's `dependencies` are checked the same way as external npm packages. If a workspace declares `@repo/ui` but never imports it, the dependency is reported as unused. A workspace package's own name does not need to be self-listed.

**Common false positives:**

* **Uninstalled peer dependencies of other packages**: Fallow credits required peers when the package is installed under `node_modules`. If a peer is required only by an environment outside the analyzed install tree, check whether removing it breaks that runtime.
* **Runtime-only packages** (polyfills, CSS frameworks loaded via `@import`): Add to `ignoreDependencies` in config.

### Unused devDependencies

Same as unused dependencies, but for packages in `devDependencies`.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

### Unused optionalDependencies

Same as unused dependencies, but for packages in `optionalDependencies`. Only reported when the `--unused-optional-deps` flag is passed.

| Severity | Default     |
| :------- | :---------- |
| Warning  | No (opt-in) |

### Unused enum members

Enum values declared but never referenced.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**When to act:** Remove the unused member. Unused enum members inflate serialized values and can cause confusion about which values are valid.

### Unused class members

Class methods and properties never referenced outside their class body.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**What it detects:** Public methods and properties that are never accessed by any module other than the class itself. Internal `this.member` accesses within the class body are tracked separately and do not count as external usage.

**Inheritance awareness:** Fallow builds an inheritance map from `extends` clauses and propagates member accesses through the hierarchy. If a parent class method calls `this.getArea()`, that access credits child class overrides (`Circle.getArea()`, `Rectangle.getArea()`). External member accesses on a parent type also propagate to child implementations. This prevents false positives on abstract-like patterns where a base class defines a contract that subclasses fulfill.

**Decorator exclusion:** Members with decorators (e.g., `@Get()`, `@Column()`, `@Input()`, `@Inject()`) are automatically excluded from detection. Decorators indicate runtime wiring that static analysis cannot trace, so decorated members are never flagged. The one exception is a Lit `@state()` reactive property on a direct `LitElement` / `ReactiveElement` subclass (when `lit` is a declared dependency): `@state` is internal component state with no external surface, so a `@state` field read nowhere via `this.<name>` (in a method or the `html` template) is flagged as an unused class member. The public `@property()` decorator stays excluded (it is the element's attribute API, settable from HTML, a parent binding, `setAttribute`, or CSS).

**Lifecycle method allowlists:** Framework lifecycle methods are never flagged. Fallow has built-in allowlists for React (`componentDidMount`, `render`, `shouldComponentUpdate`, etc.) and Angular (`ngOnInit`, `ngOnDestroy`, `canActivate`, `validate`, etc.). For other frameworks (Web Components, ag-Grid, etc.), the `usedClassMembers` config option lets you extend the allowlist.

**Whole-object use heuristics:** Patterns like `Object.values(instance)`, `Object.keys(instance)`, rest destructuring (`const { foo, ...rest } = instance`), and `for (const key in obj)` conservatively mark all members as used.

```typescript theme={null}
class UserService {
  // Used: called in app.ts
  async getUser(id: string) { ... }

  // Unused: never called outside this class
  private formatName(user: User) { ... }

  // Excluded: has decorator (runtime wiring)
  @Get('/users')
  handleGetUsers() { ... }

  // Excluded: React lifecycle method
  componentDidMount() { ... }
}
```

**When to act:** Remove or mark as `private`. An unreferenced public method is either dead functionality or wired at runtime. Both are worth investigating.

**Configuration:** The `usedClassMembers` config option marks specific member names as always-used. This is useful for convention-based methods called by DI frameworks or third-party libraries that invoke methods reflectively (e.g., `agInit`, `connectedCallback`). Plugins can also contribute to this allowlist via the `usedClassMembers` field in custom plugin definitions.

### Unused store members

A Pinia store member (a `state` / `getters` / `actions` key, or a setup-store returned key) that is declared but accessed by no consumer anywhere in the project.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**What it detects:** The store binding is imported (so the module is reachable), yet a specific state property, getter, or action is never read. This is the cross-graph "declared but never used by any file" direction that single-file linters (eslint-plugin-vue, eslint-plugin-svelte, eslint-plugin-pinia) and type-checkers (vue-tsc, svelte-check) do not cover. Defaults to `warn`, not `error` like the closed-set class and enum member rules: a store has an open declaration surface (plugins, dynamic dispatch), so confidence is lower.

**Activation:** Runs only when `pinia` or `@pinia/nuxt` is a declared dependency, so it never fires on an unrelated `defineStore`-named helper in a non-Pinia project.

**Consumption it credits:** `const s = useStore(); s.member`, destructures (`const { count } = useStore()`, `const { count } = storeToRefs(store)`), template `store.member` in `.vue` / `.svelte` files, and intra-store `this.member` usage between getters and actions.

**Abstain heuristics (false-positive safe):** Whole-object usage (`{ ...store }`, `Object.keys(store)`, dynamic `store[key]`) and the Options-API `mapState` / `mapGetters` / `mapActions` helpers conservatively mark the whole store as used, so no member is flagged. The Pinia `$`-prefixed API (`$patch`, `$reset`, `$subscribe`, etc.) is never reported, and a setup store whose returned object spreads (`return { ...base, x }`) abstains entirely.

```typescript theme={null}
export const useCartStore = defineStore('cart', {
  state: () => ({
    items: [],        // Used: read in CartView.vue
    legacyTotal: 0,   // Unused: no component or store ever reads it
  }),
  getters: {
    total: (s) => s.items.length,  // Used: rendered in the template
  },
  actions: {
    add() { /* ... */ },           // Used: called on click
    deprecatedReset() { /* ... */ }, // Unused: never dispatched
  },
})
```

**When to act:** Remove the unused state property, getter, or action. There is no auto-fix, because a store member can be accessed reflectively through a Pinia plugin or dynamic dispatch; suppress with `// fallow-ignore-next-line unused-store-member` if a member is consumed in a way fallow cannot see.

**Scope:** Pinia only. Svelte stores and Vuex are not yet covered (a Svelte `writable` is opaque and its value shape is reshaped at runtime, so member-level detection would be false-positive-prone; an entirely unused store export is already caught by the unused-export check).

### Unresolved imports

Import specifiers that cannot be resolved to a file on disk or a `node_modules` package.

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

**When to act:** Always investigate. An unresolved import usually means the code will fail at runtime. Common causes:

* Typo in the import path
* Missing dependency (not installed or not in `package.json`)
* Path alias not configured in `tsconfig.json` paths

### Unlisted dependencies

Packages imported in source code but not declared in `package.json`.

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

**When to act:** Add the package to `dependencies` or `devDependencies`. Unlisted dependencies work by accident (hoisted from another package) and will break in environments with strict `node_modules` resolution (pnpm, Yarn Plug'n'Play).

**Internal workspace packages count too:** in monorepos, importing a workspace package (e.g., `import { x } from '@repo/utils'`) from a workspace whose own `package.json` does not list `@repo/utils` is reported as unlisted. Add the workspace package to that workspace's `dependencies` (or move the import). Self-references stay allowed without requiring a package to depend on itself.

### Duplicate exports

The same symbol name exported from multiple modules. This causes ambiguous auto-imports and makes it unclear which module is the canonical source.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**When to act:** Consolidate to a single canonical export. Re-export from one location if multiple modules need to expose it.

### Circular dependencies

Modules that import each other directly or transitively, forming a cycle.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**Detection during graph construction:** Circular dependencies are detected as a natural byproduct of building the module graph using Tarjan's strongly connected components algorithm (O(V + E)). There is no separate analysis pass, so cycle detection adds zero meaningful cost to the analysis.

**No depth limits:** Fallow detects cycles of any length. The graph algorithm processes all strongly connected components regardless of size, then enumerates individual elementary cycles within each component. There is no cap on cycle depth.

**Type-only cycle filtering:** Cycles where every edge consists exclusively of `import type` imports are filtered out automatically. Type imports are erased at compile time and cannot cause runtime initialization issues. Fallow distinguishes these from runtime cycles by tracking the `is_type_only` flag on each import symbol through the graph.

**Cycle path reporting:** Fallow reports the full path of each cycle, so you can see exactly which files are involved:

```
src/auth.ts → src/user.ts → src/permissions.ts → src/auth.ts
```

This makes it straightforward to identify the weakest edge to break.

**Why circular dependencies are risky:**

* Module evaluation order becomes unpredictable. JavaScript evaluates modules depth-first, and a cycle forces at least one module to receive an incomplete namespace object.
* Accessing an export before the module finishes evaluating returns `undefined`, causing subtle runtime errors that are hard to trace.
* Bundlers may produce incorrect output or larger bundles when they cannot determine a clean evaluation order.
* Refactoring becomes dangerous because moving code between cycle members can break initialization order in ways that only manifest at runtime.

| Cycle length | Risk                             | Action                                  |
| :----------- | :------------------------------- | :-------------------------------------- |
| 2 (A ↔ B)    | Moderate, usually a design issue | Extract shared code into a third module |
| 3-5          | Higher, harder to trace          | Break the cycle at the weakest edge     |
| 5+           | Architectural issue              | Refactor module boundaries              |

**When it's OK to keep:**

* **Type-only cycles**: If the cycle only involves `import type`, there is no runtime initialization risk. These are filtered from circular dependency reports automatically.

### Re-export cycles

Two or more barrel files that re-export from each other in a loop, or a single barrel file that re-exports from itself. Distinct from circular dependencies: circular deps describe runtime import loops; re-export cycles describe **declarative** loops in the `export * from` graph where chain propagation has no terminating module to resolve names against.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**Why this is its own category:** Circular dependencies in the runtime import graph are sometimes intentional (mutual recursion between application modules). Re-export cycles are essentially always bugs. When `src/api/index.ts` does `export * from './internal'` and `src/api/internal/index.ts` does `export * from '../index'`, neither file actually declares anything; the chain has no terminating source. Any consumer doing `import { foo } from './api'` is asking the chain to resolve `foo` against a graph with no leaf, and the import silently comes up `undefined` at runtime.

**Two structural shapes:**

* **`multi-node`** -- a strongly connected component of two or more files in the re-export edge subgraph. Example: `barrel-a.ts` re-exports from `barrel-b.ts` and `barrel-b.ts` re-exports back from `barrel-a.ts`.
* **`self-loop`** -- a single file that re-exports from itself. Almost always a rename leftover where `barrel.ts` ended up doing `export * from './'` or `export * from './barrel'`. Surfaces under the same rule with a distinct `kind` discriminator so consumers can tell the two shapes apart.

**Type-only cycles still fire:** `export type * from './b'` paired symmetrically with `export type * from './a'` is also a re-export cycle. Chain propagation through a type-only loop is the same no-op as through a value loop; the cycle is reported regardless.

**Human output:**

```
Re-Export Cycles (Architecture)

  src/api/index.ts
    Cycle (2 files):
      - src/api/index.ts
      - src/api/internal/index.ts
    To fix: remove one `export * from` statement on any member file.

  src/utils/index.ts
    Self-loop (1 file):
      - src/utils/index.ts
    To fix: remove the `export * from './'` (or equivalent) inside this file.
```

**How to fix it:**

1. Pick any one file in the loop.
2. Remove the `export * from` (or `export { ... } from`) statement that points back into the cycle.
3. Any single removal breaks the cycle and restores working re-exports. You do not need to touch every member.

For a self-loop, the fix is unambiguous: open the offending file and delete the stray `export * from './'` (or `export * from './<this-file>'` after a rename).

**Suppression:** the finding is file-scoped (the cycle spans multiple files; there is no single line to anchor at). Suppress with a file-level comment on any member:

```ts theme={null}
// fallow-ignore-file re-export-cycle
export * from "./internal";
```

The four spellings `re-export-cycle`, `re-export-cycles`, `reexport-cycle`, and `reexport-cycles` are all accepted. Per-file `overrides.rules.re-export-cycle` is a **no-op** because the rule's severity is project-wide and the finding spans multiple files; configure it at the top-level `rules` block instead, or use the file-level `fallow-ignore-file` suppression above.

**When to keep it as a warning:** legacy projects with hand-written barrels predating ESM strictness may have benign-looking cycles that no consumer actually relies on. Leaving the rule at `warn` keeps the diagnostic visible without breaking CI; promote to `error` once the cycles are cleaned up. On upgrade, expect `total_issues` to step up on the first run because cycles that existed before this rule shipped now appear as findings.

### Boundary violations

Imports that cross user-defined architecture zone boundaries. Zones are defined in the `boundaries` config section and map file path patterns to named architecture zones. A boundary violation occurs when a file in one zone imports from a file in another zone that the boundary rules disallow.

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

**When to act:** Always. Boundary violations indicate that code is breaking the intended architecture. Fix by restructuring imports to respect zone boundaries, or update the boundary config to allow the import if it's an accepted exception.

**Common false positives:**

* **Shared utilities**: Code in a shared/common zone may need to be accessible from multiple zones. Adjust boundary rules to allow these imports.
* **Newly created zones**: When introducing boundaries to an existing codebase, expect violations. Use `warn` severity initially.

### Policy violations

Calls, imports, or catalogue-derived effects matching a `banned-call`, `banned-import`, or `banned-effect` rule from a configured rule pack (the `rulePacks` config key). Rule packs are standalone JSON or JSONC files of pure declarative policy data; loading a pack never executes project code. Findings are identified as `<pack>/<rule-id>` across every output format.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

The `rules."policy-violation"` master defaults to `warn` so a new pack never hard-fails CI on its first run. A per-rule `severity` in the pack overrides the master per finding, and the exit-code gate reads the effective per-finding severity, so one `error` rule fails the run even under a warn master. `off` on the master is a kill switch for the whole evaluator. Invalid or missing packs fail config load with exit code 2 instead of silently enforcing nothing.

**When to act:** Replace the banned call or import with the alternative named in the rule's message. Scope a rule with `files` / `exclude` globs if it fires in directories where the usage is sanctioned, or suppress one rule with `// fallow-ignore-next-line policy-violation:<pack>/<rule-id>`. Use bare `policy-violation` only when you intend to suppress every rule-pack finding at that line or file scope.

**Limitations:** Matching is syntactic. `banned-call` does not follow aliased or re-bound callees (`const run = cp.exec; run()`), and `banned-import` matches the raw specifier only, so rewritten forms such as `npm:moment` are not matched; `require()` calls and dynamic `import()` are not checked.

Run `fallow rule-pack-schema` to print the pack JSON Schema for editor autocomplete. See the [`rulePacks` config key](/configuration/overview#config-fields) for the pack file format.

### Invalid client exports

A file carrying the `"use client"` directive that also exports a Next.js server-only or route-segment-config name. Next.js rejects these at build time: a client module cannot export `metadata`, `generateMetadata`, `viewport`, `generateViewport`, `generateStaticParams`, `dynamic`, `dynamicParams`, `revalidate`, `fetchCache`, `runtime`, `preferredRegion`, `maxDuration`, the Pages Router data functions (`getServerSideProps`, `getStaticProps`, `getStaticPaths`), or a route HTTP method handler (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`). fallow catches it statically, before a build, in the same pass as the rest of dead-code analysis. The component's `default` export is never flagged.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

The rule only runs when `next` is a declared dependency, so it cannot false-positive on non-Next projects. There is no auto-fix, because removing a legitimate client export would break the component.

**When to act:** Move the offending export out of the `"use client"` file into a server module (or a shared module without the directive). Suppress with `// fallow-ignore-next-line invalid-client-export` if the export is intentional and you handle the boundary another way.

### Mixed client/server barrels

A barrel file (one with at least one `export ... from` re-export) that re-exports both a `"use client"` module and a server-only module. Importing any single name from such a barrel can drag the other origin's directive context across the React Server Components boundary, a common Next.js App Router footgun that surfaces as confusing build or hydration errors far from the barrel.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

A module counts as server-only when it carries a `"use server"` directive, imports the `server-only` package, `next/server`, `node:fs`, or `node:child_process` (the `node:` and bare forms both count), or imports a server-only `next/headers` API (`cookies`, `headers`, `draftMode`). The check classifies only direct re-export origins (it does not walk transitive chains), skips type-only re-exports (which carry no runtime directive context), and never flags a barrel that mixes a client module with an ordinary utility, so it stays false-positive-safe. It runs only when `next` is a declared dependency.

**When to act:** Split the barrel so client and server-only modules are re-exported from separate entry points. There is no auto-fix (splitting a barrel is a design decision); suppress with `// fallow-ignore-next-line mixed-client-server-barrel` if the grouping is intentional.

### Misplaced directives

A `"use client"` or `"use server"` directive written as a bare string-literal statement below an import (or any other statement) instead of at the very top of the file. A directive is only honored in the file's leading prologue; once any statement precedes it, the parser treats the string as an ordinary expression and the bundler silently ignores it, so a file you intended as a client component is treated as a server module. Nothing errors, which is what makes it dangerous.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

The fix is always the same: move the directive above every `import`. The rule runs only when `next` is a declared dependency. There is no auto-fix (fallow does not reorder your source); the finding points at the misplaced directive so you can move it by hand.

**When to act:** Move the `"use client"` / `"use server"` line to the top of the file, before all imports. Suppress with `// fallow-ignore-next-line misplaced-directive` only if the bare string is intentional and not meant as a directive (rare).

### Route collisions

Two or more App Router route files (a `page` or a `route` handler) that resolve to the same URL within one app-root. Route groups `(name)` and parallel slots `@name` do not change the URL, so `app/(marketing)/about/page.tsx` and `app/(shop)/about/page.tsx` both own `/about`. Next.js fails the build with "You cannot have two parallel pages that resolve to the same path" because a URL can have at most one owner, whether a Page or a Route Handler. fallow catches it statically, before a build, and surfaces every colliding file at once (the build error names only one and aborts).

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

It defaults to `error` because it mirrors a `next build` failure: a project hitting it was already red, so erroring aligns fallow's exit code with the build it mirrors.

Collision buckets are scoped per app-root using your workspace package roots, so a monorepo with several independent Next apps that happen to share a path (`apps/web/app/about` and `apps/admin/app/about`) is not flagged. Files under a private `_folder` and files under an intercepting marker (`(.)`, `(..)`, `(...)`) are excluded. Two dynamic segments that differ only by name (`[id]` vs `[slug]`) are reported by [dynamic segment name conflicts](#dynamic-segment-name-conflicts), not here. The rule runs only when `next` is a declared dependency.

**When to act:** Move or merge one of the colliding files so each URL has a single owner. Suppressing a guaranteed build error does not make the build pass, so the primary action is the fix; `// fallow-ignore-file route-collision` exists only as an escape hatch.

### Dynamic segment name conflicts

Two or more sibling dynamic route segments at the same App Router tree position using different param spellings (`[id]` vs `[slug]`, or a catch-all `[...x]` vs an optional catch-all `[[...x]]`). Next.js throws "You cannot use different slug names for the same dynamic path" at dev and production runtime when the position is hit, because one position must resolve to a single param name. Note that `next build` does NOT catch this (the build succeeds), so CI stays green while the route crashes the first time it is requested; fallow's static catch closes that gap. Route groups are transparent to the position and parallel slots fork it, so only genuinely-sibling segments conflict.

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

It defaults to `error` because it is a deterministic runtime crash on first request that `next build` lets through, so fallow is the only gate that fails on it. The detector is pure path arithmetic on the same primitive as `route-collision`, so there is no heuristic to misfire.

The rule runs only when `next` is a declared dependency.

**When to act:** Rename the dynamic segments at the position to one consistent slug name (pick `[id]` or `[slug]` for both). Suppress with `// fallow-ignore-file dynamic-segment-name-conflict` only as an escape hatch.

### Unused server actions

A Next.js Server Action (an export of a `"use server"` file) that no code in the project references: no import-and-call, no `action={fn}` binding, and no `<form action={fn}>`. This is the cross-graph "exported but wired to nothing" direction, exactly where dead server actions accumulate as a page is refactored, and `eslint-plugin-next` cannot see it because it is single-file. It does not mean the endpoint is unreachable: Next still registers a generated action id, so it stays POST-able; it means no project code calls it, so it is a strong delete candidate.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

This is a more specific re-classification of `unused-export` for `"use server"` files. It reuses fallow's whole-project reference graph, so the `action={fn}` and `<form action={fn}>` bindings, plain import-and-call, and component-prop forwarding all count as real uses, and wrapped action factories (`authenticatedActionClient.action(...)`, `withAuditLogging(...)`) are credited by the wrapped const's references; only a genuinely orphaned action is flagged. The rule runs only when `next` is a declared dependency. Inline `"use server"` body directives (`export async function f() { "use server" }` in a non-`"use server"` file) are not covered yet; such dead actions still surface as `unused-export`.

**When to act:** Wire the action to a consumer or delete it. There is no auto-fix. Suppress with `// fallow-ignore-next-line unused-server-action`, or set the rule to `off`. If you gate CI on dead server actions, note the action now reports as `unused-server-action` (default `warn`) instead of `unused-export` (default `error`); set this rule to `error` to keep failing on it, and re-save any `--save-baseline` snapshot once.

### Unprovided injects

A Vue `inject(KEY)` or Svelte `getContext(KEY)` whose symbol key is `provide()` / `setContext()`'d nowhere in the project. At runtime a dead inject silently returns `undefined`, surfaced only when the affected path renders; no static tool in the Vue / Svelte / Nuxt ecosystems catches it (Vue and Nuxt emit a runtime-only warning, Svelte's eslint proposal is unimplemented).

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

The key must be a symbol with cross-file identity (an imported const or a module-local symbol), which makes the check false-positive-safe by construction: a key imported from a package abstains (the provider may live inside that package), a key bound to a string literal abstains (string identity, a literal provider matches it), a key that is part of your package's public API abstains (a "bring-your-own-provider" library exports the key for the consumer to provide), and any dynamic-keyed provide (`keys.forEach(k => provide(k))`) abstains project-wide. App-level `app.provide(KEY, value)` is credited, and a provide imported directly while the inject reaches the same key through a barrel re-export are matched. The rule runs only when `vue`, `@vue/runtime-core`, or `svelte` is a declared dependency. Nuxt's string-keyed `nuxtApp.provide` / `$x` API and the inverse provided-never-injected direction are not covered yet.

**When to act:** Provide the key (`provide(KEY, value)` / `setContext(KEY, value)` in an ancestor) or remove the dead inject. There is no auto-fix. Suppress with `// fallow-ignore-next-line unprovided-inject`, or set the rule to `off`.

### Unrendered components

A single-file component (the default export of a `.vue` / `.svelte` / `.astro` file) that is kept reachable by a barrel re-export but instantiated by no file in the project: no `<Tag>`, no `:is` / `this=` binding, no `components` / `app.component` registration, no `h()` / Nuxt auto-import, and no script value-read. This is the common rot where a component is refactored out of every template but its barrel re-export keeps it alive, so `unused-file` (the file is reachable) and `unused-export` (the re-export counts as a use) both miss it; `eslint`'s `vue/no-unused-components` is single-file and cannot see a barrel-reexported component rendered by a sibling.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

The render set is built liberally across barrel chains, Nuxt auto-imports, and dynamic / side-effect imports, so over-crediting only suppresses a finding (never creates one). A component that is itself an entry point (route page, layout, `App.vue`, Nuxt `app.vue` / `error.vue`) and a component re-exported through any chain from a non-private package entry point (a library exporting components for its consumers to render) are both abstained, so component libraries are not false-flagged. The rule runs only when `vue` / `@vue/runtime-core` / `nuxt` (for `.vue`), `svelte` / `@sveltejs/kit` (for `.svelte`), or `astro` (for `.astro`) is a declared dependency.

The same rule has two non-SFC arms. An **Angular arm** (`framework: "angular"`, gated on `@angular/core`) flags an `@Component` whose element selector appears in no template project-wide, with route / `bootstrapApplication` / lazy-`loadComponent` and dynamic-render (`ViewContainerRef.createComponent`, `*ngComponentOutlet`) abstains. A **Lit arm** (`framework: "lit"`, gated on `lit` / `lit-element` / `@lit/reactive-element`) flags a registered custom element (`@customElement('x-foo')`, or `customElements.define('x-foo', C)` on any receiver) whose tag is rendered in no `html` template, no standalone `.html` document, and via no imperative `createElement` / `customElements.get` / `whenDefined`; it abstains on published elements (public API) and on elements defined under a docs / dev / demo directory (rendered by site or dev tooling that fallow cannot parse).

**When to act:** Render the component where it belongs, or delete it and its barrel re-export. There is no auto-fix (a component can be rendered reflectively through a dynamic `<component :is>` resolved from a non-literal value, or a Lit element created from a computed tag). Suppress with `// fallow-ignore-next-line unrendered-component`, or set the rule to `off`.

### Unused component props

A Vue `<script setup>` `defineProps` declared prop that is referenced by no code in its own single-file component, neither in `<script>` nor in `<template>`. This is the in-component dead-input direction that `vue-tsc` / Volar do not cover (they check caller-side prop correctness, not "this declared prop is wired to nothing"); eslint's `vue/no-unused-properties` is opt-in, off by default, and historically unreliable on `<script setup>` reactive destructure.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

Prop names are harvested from the inline TS form (`defineProps<{ foo: T }>()`), the runtime object form (`defineProps({ foo: {...} })`), and `withDefaults(...)`; usage is credited from both script (the destructured binding or `props.foo`) and template (`{{ foo }}`, `:x="foo"`, `props.foo`, `$props.foo`). It stays false-positive-safe by abstaining on the whole component when it cannot see all consumption: a `v-bind="$attrs"` / `v-bind="props"` fallthrough, a whole-object props use (`toRefs(props)`, `{...props}`), a `defineExpose` or `defineModel` call, or a prop type from an imported alias (`defineProps<ImportedProps>()`, names not statically resolvable). The rule runs only when `vue` / `@vue/runtime-core` / `nuxt` is a declared dependency and covers Vue `<script setup>` and Options API props.

A **React / Preact arm** shares this rule key and emits the same finding for a prop that is destructured from a component's first parameter and read nowhere in the component body. It is dep-gated on `react` / `react-dom` / `next` / `preact`, covers inline-destructured literal props, and stays false-positive-safe by abstaining on rest spread (`{...rest}`), props forwarded by spread, props passed wholesale to a hook, a `forwardRef` / `memo` component whose props come from an imported interface (not statically resolvable), and exported public-API component props.

An **Astro arm** shares this rule key for a `.astro` `interface Props` (or `type Props`) field read nowhere: not through an `Astro.props` destructure (including a nested destructure such as `const { post: { id } } = Astro.props`), not via `Astro.props.<name>`, not in a `{expr}` template position, and not through a `<style>` / `<script>` `define:vars={{ prop }}` binding. It is dep-gated on `astro` and abstains on the whole component for a `{...Astro.props}` template spread, a whole-object `Astro.props` use, an `interface Props extends ...` or imported-type alias (names not statically resolvable), or an array destructure of `Astro.props`.

**When to act:** Wire the prop where it is meant to be used, or remove it from `defineProps` (Vue) / the destructure (React). There is no auto-fix. Suppress with `// fallow-ignore-next-line unused-component-prop`, or set the rule to `off`.

### Unused component emits

A Vue `<script setup>` `defineEmits` declared event that is emitted by no code in its own single-file component, neither through `emit('name')` in `<script>` nor `emit('name')` / `$emit('name')` in `<template>`. This is the emit-side sibling of unused component props: the in-component dead-output direction that `vue-tsc` / Volar do not cover (they check caller-side listener correctness, not "this declared event is never emitted").

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

Event names are harvested from the array form (`defineEmits(['save', 'close'])`), the type / object form (`defineEmits<{ save: [] }>()`), and the bound form (`const emit = defineEmits(...)`, tracking the actual local binding name so a renamed `const notify = defineEmits(...)` is still credited); usage is credited from both the script call walk and the template (`@click="$emit('save')"`). It stays false-positive-safe by abstaining on the whole component when it cannot see all emission: a dynamic `emit(eventName)` whose event name is not a literal, the emit function passed or returned or spread elsewhere, a `defineModel` call (which generates implicit `update:x` emits), or an emit type from an imported alias (`defineEmits<ImportedEmits>()`, names not statically resolvable). The rule runs only when `vue` / `@vue/runtime-core` / `nuxt` is a declared dependency and covers Vue `<script setup>` and Options API emits.

**When to act:** Emit the event where it is meant to fire, or remove it from `defineEmits`. There is no auto-fix (removing an emit can break a deliberately-stable public component API). Suppress with `// fallow-ignore-next-line unused-component-emit`, or set the rule to `off`.

### Unused Svelte events

A Svelte component dispatches a custom event through `createEventDispatcher`, but no reachable Svelte consumer listens for that event name.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

Event names are harvested from literal dispatcher calls such as `dispatch('save')` after tracking the local binding returned by `createEventDispatcher()`. Listeners are credited from Svelte component usage with `on:event` syntax and forwarded listener attributes. The rule stays false-positive-safe by abstaining from dynamic event names, dispatcher values that escape the component, and projects without a declared Svelte dependency.

**When to act:** Add the intended listener, forward the event intentionally, or remove the dispatch. There is no auto-fix. Suppress with `// fallow-ignore-next-line unused-svelte-event`, or set the rule to `off`.

### Unused component inputs

An Angular component input (`@Input()`, the signal `input()` / `input.required()`, or `model()`) declared on a component that is read by no code in its own component, neither in the class body nor in its template (inline `template` or an external `templateUrl` file). This is the Angular analogue of unused component props: the in-component dead-input direction that no Angular tooling covers. There is no `@angular-eslint` rule for it, and the Angular compiler only checks caller-side binding correctness (that a parent's `[input]="..."` matches a declared input), never "this declared input is wired to nothing inside the component." An input consumed only by a parent's template binding but read nowhere in its own component IS flagged, because the parent binding is satisfied while the component never uses the value.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

Input names are harvested from the decorator form (`@Input() foo`, including the aliased `@Input('alias')` and the metadata `inputs: ['foo']` on the `@Component` decorator) and the signal form (`foo = input<T>()`, `input.required<T>()`, `model<T>()`); `model()` is treated as input-only (its two-way write half is not an emit). Usage is credited from the class body (`this.foo`) and from the component's template (interpolation, property and attribute bindings, structural directives, and template references). It stays false-positive-safe by abstaining on the whole component whenever it cannot see all consumption: any `extends` clause (an inherited template or base class may read the input), a `{...this}` spread, a JS-reserved-word input name, an accessor input (a `get` / `set` pair, where the setter side effect is the consumption), and `host:` decorator-metadata members are credited as used. The rule runs only when `@angular/core` is a declared dependency.

**When to act:** Read the input where it is meant to be used, or remove the `@Input()` / `input()` / `model()` declaration. There is no auto-fix. Suppress with `// fallow-ignore-next-line unused-component-input`, or set the rule to `off`.

### Unused component outputs

An Angular component output (`@Output()` or the signal `output()`) that is emitted (`.emit(...)`) by no code in its own component. This is the emit-side sibling of unused component inputs: the in-component dead-output direction that no Angular tooling covers (the compiler checks caller-side listener correctness, that a parent's `(output)="..."` matches a declared output, never "this declared output is never emitted").

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

Output names are harvested from the decorator form (`@Output() saved = new EventEmitter()`, including the aliased `@Output('alias')` and the metadata `outputs: ['saved']` on the `@Component` decorator) and the signal form (`saved = output<T>()`); only `new EventEmitter()` initializers are harvested, so an observable-stream `@Output` (one wired to a `Subject` / `Observable` whose emissions fallow cannot follow) is left alone. Usage is credited from any `this.saved.emit(...)` call in the component. It stays false-positive-safe by abstaining on the whole component whenever it cannot see all emission: any `extends` clause, a `{...this}` spread, or a JS-reserved-word output name. The rule runs only when `@angular/core` is a declared dependency.

**When to act:** Emit the output where it is meant to fire, or remove the `@Output()` / `output()` declaration. There is no auto-fix (removing an output can break a deliberately-stable public component API). Suppress with `// fallow-ignore-next-line unused-component-output`, or set the rule to `off`.

### Prop drilling

A React / Preact prop that is forwarded unused through two or more intermediate components before a component finally consumes it. "Forwarded unused" means a receiving component reads the prop's identifier only as the root of a child-JSX attribute value (so `<Child userName={user.name} />` counts: the `user` prop is projected straight through), never substantively. This is a cross-file graph signal that per-file linters (eslint-plugin-react) structurally cannot see.

| Severity     | Default |
| :----------- | :------ |
| Off (opt-in) | Yes     |

This rule is off by default; enable it with `prop-drilling: "warn"` (or `"error"`) under `rules`. When enabled it reports one located chain per drilled prop, with the source component that owns the value, each pass-through hop, and the consumer, each with file, line, and component name, so you or an agent can act. It stays false-positive-safe by abstaining on the whole chain whenever it cannot prove a clean pass-through: any `{...props}` / `{...rest}` spread, a `cloneElement` call, a component passed as a prop or render prop or function-as-children, a matching context `*.Provider` in the subtree (where drilling may be a deliberate choice), or any dynamic or unresolvable hop. The rule runs only when `react` / `react-dom` / `next` / `preact` is a declared dependency. When enabled it also contributes a small, capped penalty to the health score (one point per chain, capped at five); with the rule off the health score is unchanged.

**When to act:** Colocate the consumer with the data, lift the value to a React context / provider at a mid-chain hop, or compose the components so the intermediates no longer thread the prop. There is no auto-fix (the right refactor is a design choice). Suppress an individual chain with `// fallow-ignore-next-line prop-drilling`, or set the rule to `off`.

### Thin wrapper

A React / Preact component whose entire body is `return <Child {...props} />`: it renders a single child component, forwards all of its props through a spread, and adds no markup, no hooks, and no logic of its own. It is pure structural indirection: every call site could render the child directly. This is a cross-component graph signal that per-file linters cannot see.

| Severity     | Default |
| :----------- | :------ |
| Off (opt-in) | Yes     |

This rule is off by default; enable it with `thin-wrapper: "warn"` (or `"error"`) under `rules`. It reports the wrapper component (at its definition) and the child it forwards to. It stays false-positive-safe by abstaining on wrappers that are intentional indirection: a `forwardRef` or `memo` wrapper (the sanctioned way to make a child ref-able or to set a perf boundary), an exported (public-API) component (a library re-branding a child under its own name), a context-provider wrapper, a `cloneElement` call, a render-prop / function-as-children, or any wrapper whose body is more than the single spread-forwarded child (a host element, sibling, hook, or branch). The rule runs only when `react` / `react-dom` / `next` / `preact` is a declared dependency.

**When to act:** Inline the wrapper at its call sites and delete it, or give it a real responsibility (markup, defaults, logic). There is no auto-fix. Suppress with `// fallow-ignore-next-line thin-wrapper`, or set the rule to `off`.

### Duplicate prop shape

Three or more React / Preact components, across two or more files, that declare an identical set of prop names, suggesting a shared `Props` type (or a base component) should be extracted. Cross-graph, which per-file linters cannot see.

| Severity     | Default |
| :----------- | :------ |
| Off (opt-in) | Yes     |

This rule is off by default; enable it with `duplicate-prop-shape: "warn"` (or `"error"`) under `rules`. It reports one finding per member of a group, naming the other components that share the shape. It stays noise-free by requiring an exact full-set match (a superset or subset does not group), a minimum of four significant prop names after stripping ubiquitous DOM-passthrough names (`id`, `className`, `children`, `style`, ...), and at least three components in at least two files, so two buttons that merely share `{label, onClick}` are never grouped. The rule runs only when `react` / `react-dom` / `next` / `preact` is a declared dependency, and abstains on components whose props are not statically harvestable (rest spread, imported-interface generics).

**When to act:** Extract a shared `Props` type or a base component the group can reuse. There is no auto-fix (the right abstraction is a design choice). Suppress with `// fallow-ignore-next-line duplicate-prop-shape`, or set the rule to `off`.

### Unused load data keys

A SvelteKit `load()` return-object key (in `+page.ts` / `+page.server.ts` and the `.js` variants) that is read by no consumer: not the sibling `+page.svelte`'s `data.<key>`, and not any project-wide `page.data.<key>` (Svelte 5 `$app/state`) or `$page.data.<key>` (Svelte 4 `$app/stores`). A dead returned key still runs its real server-side fetch / DB cost on every request for data nothing renders, and no other static tool catches it: `svelte-check` types `data` through the generated `$types` but never flags an unread returned key (the unused-input direction).

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

It stays false-positive-safe by abstaining whenever it cannot see all consumption: an unharvestable `load` body (a spread return, a non-literal or multi-branch return, a computed key, a wrapped / re-exported `load`), a sibling component that passes the whole `data` object opaquely (`data={data}`, `{...data}`, `fn(data)`, `const x = data`), a `+page.server.ts` whose universal `+page.ts` sibling reads or forwards its `data` param, and any project-wide reflective whole-object read of the page-data store (`Object.values(page.data)`), which abstains every route. Page-load data reaches only the sibling `+page.svelte`, so a `data.<key>` read in a `+layout.svelte` (which receives layout-load data, not page-load data) does not credit a page key. The rule runs only when `@sveltejs/kit` is a declared dependency. Layout loads (`+layout.ts` / `+layout.server.ts`) are not covered yet.

**When to act:** Read the key where the data is meant to be used, or remove it from the `load()` return (and drop the fetch that produced it if nothing else needs it). There is no auto-fix (a load fetch can have side effects, so removing a key is a human decision). Suppress with `// fallow-ignore-next-line unused-load-data-key`, or set the rule to `off`.

### Type-only dependencies

Production dependencies (`dependencies`) that are only ever imported via `import type`. Since type imports are erased at compile time, these packages are never loaded at runtime and should be moved to `devDependencies`.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**When to act:** Move to `devDependencies`. This reduces the production install size and clearly communicates that the package is only needed for type checking.

### Test-only dependencies

Production dependencies (`dependencies`) that are only ever imported by test files (files matching test patterns like `*.test.ts`, `*.spec.ts`, test directories). Since they are never used in production code, they should be moved to `devDependencies`.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**When to act:** Move to `devDependencies`. This reduces the production install size and makes it clear the package is only needed for testing.

### Dev dependencies in production

A package in `devDependencies` that is imported by production source code via a runtime (value) import. This is the promote-side mirror of `type-only-dependencies` and `test-only-dependencies`: where those rules demote a production dependency that only tests or types need, this rule catches the opposite drift. A production-only install (`npm install --omit=dev`, `pnpm install --prod`, `yarn workspaces focus --production`) omits `devDependencies`, so the import breaks at runtime; the package belongs in `dependencies`.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**What counts as a production import.** An import is production evidence only when all of the following hold:

* The importing file is reachable from a runtime entry point. Repo tooling that is not part of the shipped artifact (`scripts/`, benchmarks, playgrounds, files reachable only through a config-file chain such as a Rollup config importing helpers) does not count.
* The importing file is not a test, story, or fixture file (patterns like `*.test.*`, `*.spec.*`, `*.e2e.*`, `*.bench.*`, `*.stories.*`, `__tests__/`, `__mocks__/`, `test/`, `tests/`, the same exclusion set `--production` mode uses) and not a config file.
* The import is a runtime (value) import. A production file that imports the package only via `import type` does not trigger the rule, because type imports are erased at build time; this mirrors the import-kind analysis behind `type-only-dependencies`.

**What is never flagged.** A `devDependency` is skipped when another manifest section already provides it at runtime (it is also listed in `dependencies`, `peerDependencies`, or `optionalDependencies`), when it is a workspace package, when it is known dev tooling (`@types/*`, `typescript`, and similar), or when it is listed in `ignoreDependencies`. The rule currently checks the root `package.json` against the project-wide import graph; imports from files owned by a workspace package are skipped because the workspace's own manifest governs their runtime resolution (per-workspace detection is a shared follow-up with the sibling dependency rules).

**Interaction with `--production` mode.** Unlike `test-only-dependencies`, which needs test files in the graph to answer its question, this rule stays on in `--production` mode. Production mode only makes the signal cleaner: every discovered file is production code, and a production CI run is exactly where a prod-only install breakage matters.

**Known limitation.** A file referenced from a `package.json` `scripts` command counts as a runtime entry point, so a dev-only helper script that value-imports a `devDependency` can still be flagged. Suppress such a package via `ignoreDependencies`.

**Configuration and suppression.** The config key is `dev-dependencies-in-production` under `rules`; set it to `"error"`, `"warn"` (the default), or `"off"`:

```json fallow.json theme={null}
{
  "rules": {
    "dev-dependencies-in-production": "off"
  }
}
```

There is no inline suppression comment for this rule (`suppressible: false` in the capability manifest). That is intentional: the finding anchors on the package's line in `package.json`, and JSON cannot carry comments. To silence a specific package, add it to `ignoreDependencies`; to silence the rule entirely, set it to `off`.

**When to act:** Move the package from `devDependencies` to `dependencies`. If the flagged import is genuinely dev-only tooling (the script-entry limitation above), add the package to `ignoreDependencies` instead.

### Unused pnpm catalog entries

Packages declared in `pnpm-workspace.yaml` under `catalog:` or `catalogs.<name>:` that no workspace `package.json` references with the `catalog:` protocol.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**When to act:** Remove the catalog entry, or switch consumers that still pin a hardcoded version to `catalog:` first.

### Empty pnpm catalog groups

Named `catalogs.<name>:` groups in `pnpm-workspace.yaml` that contain no package entries. The top-level `catalog:` map is not reported when empty because it can be a harmless default-catalog placeholder.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**When to act:** Remove the empty named group header.

### Unresolved pnpm catalog references

Workspace `package.json` dependencies using `catalog:` or `catalog:<name>` where the selected catalog does not declare the requested package.

| Severity | Default |
| :------- | :------ |
| Error    | Yes     |

**When to act:** Add the package to the selected catalog, switch to a catalog that declares it, or pin a direct version.

### pnpm dependency overrides

`unused-dependency-overrides` reports override entries whose target package is not declared by any workspace `package.json` and is not present in the lockfile (`pnpm-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`, or bun's text `bun.lock`). Overrides that target transitive dependencies resolved in the lockfile (the common CVE-pin pattern) are treated as used. When no lockfile is present, fallow falls back to a package.json-only check and keeps a `hint` on each finding so transitive pins can be reviewed before removal. When the only lockfile next to the root `package.json` is bun's legacy binary `bun.lockb` (no parseable text lockfile beside it; a `yarn.lock` is never consulted), resolution ground truth is unreadable, so the check is skipped rather than degraded, and fallow says so through the `bun-lockb-override-resolution-skipped` workspace diagnostic, which names the lockfiles it looked for and hints `bun install --save-text-lockfile` (bun 1.2 or newer) or deleting a stale `bun.lockb`. `misconfigured-dependency-overrides` reports malformed override keys or empty values that pnpm rejects.

### Stale suppressions

`// fallow-ignore` comments and `/** @expected-unused */` JSDoc tags that no longer match any issue. Suppression comments accumulate as codebases evolve. A suppression that once silenced a real finding may become stale when the underlying issue is fixed, the code is moved, or another module starts importing a previously unused export.

| Severity | Default |
| :------- | :------ |
| Warning  | Yes     |

**Two origins are tracked:**

* **Inline comments** (`// fallow-ignore-next-line`, `// fallow-ignore-file`): reported as stale when the target line or file no longer has a matching issue.
* **`@expected-unused` JSDoc tags**: reported as stale when the tagged export is now imported by another module. Use `/** @expected-unused */` to mark exports that are intentionally dead code but should be flagged if they become used again.

```typescript theme={null}
// STALE: this suppression no longer matches any issue
// fallow-ignore-next-line unused-export
export const helper = () => {};  // now imported in app.ts

// @expected-unused marks intentional dead code
/** @expected-unused */
export const deprecatedApi = () => {};
// ^ reported as stale if something starts importing deprecatedApi
```

**Unknown issue-kind tokens (typos, obsolete names):** fallow accepts the recognized tokens on a multi-kind marker even when one of the tokens does not match any known issue kind, and reports each unknown token as a stale suppression. This guards against the silent-failure case where a typo (`unused_export` instead of `unused-export`) or a kind renamed in a newer release would otherwise discard every suppression on the same line. The diagnostic's explanation surfaces the verbatim token plus a "Did you mean ...?" suggestion when a known kind is within Levenshtein distance 2.

```typescript theme={null}
// Recognized + unknown on the same marker:
// fallow-ignore-next-line unused-export, complexity-typo
export const foo = 1;
// `unused-export` still suppresses `foo`; `complexity-typo` surfaces as a stale
// suppression so you can fix the typo or drop the unknown token.
```

JSON consumers can distinguish unknown-kind tokens from stale-but-known tokens via the additive `origin.kind_known` field on `stale_suppressions[].origin` (present and `false` only in the unknown-kind case; absent when the kind is recognized).

**When to act:** Remove the stale suppression comment or JSDoc tag. For unknown-kind reports, fix the typo or drop the unknown token; the rest of the marker continues to apply. Stale suppressions add noise and may hide future issues if the code changes again.

**Configuration:**

```jsonc theme={null}
{
  "rules": {
    "stale-suppressions": "error"  // default: "warn"
  }
}
```

Use `--stale-suppressions` as a filter flag to show only stale suppression findings.

## Prioritizing findings

Not all findings are equally important. Use this priority order:

1. **Unresolved imports**: potential runtime failures
2. **Unlisted dependencies**: breaks in strict environments
3. **Boundary violations**: architecture enforcement
4. **Unused files**: entire modules to delete
5. **Unused dependencies**: security and install time
6. **Unused exports**: API surface cleanup
7. **Circular dependencies**: initialization bugs
8. **Type-only dependencies**: install size optimization
9. **Test-only dependencies**: install size optimization
10. **Duplicate exports**: developer experience
11. **Stale suppressions**: suppression hygiene
12. **Unused types / enum members / class members**: code hygiene

<Info>
  The first two categories indicate correctness issues that may cause runtime failures. Everything else is maintenance and hygiene.
</Info>

## Incremental adoption

Most projects have existing dead code. Baselines, `--changed-since`, and enabling one issue type at a time let you adopt gradually; see [Adopting fallow](/adoption).

## Common false positive patterns

Fallow auto-detects frameworks and tools via `package.json` and config files, so most convention-based exports (Next.js pages, Storybook stories, Jest configs, tap suites, tsd declaration tests, and Contentlayer content roots) are handled out of the box. Run `fallow list` to see which plugins are active and what entry points they add.

False positives that do occur are typically in these categories:

| Pattern                                       | Why fallow flags it                       | Fix                                                                              |
| :-------------------------------------------- | :---------------------------------------- | :------------------------------------------------------------------------------- |
| Scripts run directly (`node scripts/seed.ts`) | Not imported by any module                | Add to `entry` in config, or add a `package.json` script                         |
| Dependency injection / runtime wiring         | Registered via DI container, not `import` | Add to `entry` or use `/** @public */` (or `@internal`, `@beta`, `@alpha`)       |
| Dynamic `require()` with variables            | Path not statically resolvable            | Add the directory to `entry`                                                     |
| Environment-specific files                    | Only imported behind `process.env` checks | Add to `entry` if always needed                                                  |
| Unsupported framework conventions             | Plugin doesn't exist for this framework   | Add entry points manually or [write a custom plugin](/frameworks/custom-plugins) |

<Warning>
  Before acting on a finding, verify with `--trace`. A finding is only as good as fallow's module graph. If an export is used via a dynamic pattern fallow can't resolve, use `--trace` to confirm.
</Warning>

```bash theme={null}
# Verify a specific export
fallow dead-code --trace src/utils.ts:formatDate

# See all edges for a file
fallow dead-code --trace-file src/utils.ts

# Check where a dependency is used
fallow dead-code --trace-dependency lodash
```

## Limitations

* **Fully runtime-computed paths**: `import(variable)` or `require(variable)` where the argument has no static structure cannot be resolved. Template literals with partial paths (``import(`./locales/${lang}.json`)``) and `import.meta.glob` *are* resolved. Only completely opaque variables are a limitation. Mark those directories in `entry`.
* **Syntactic analysis only**: fallow doesn't invoke the TypeScript compiler. Conditional types or dead code behind generic constraints require type resolution to detect. See [known limitations](/analysis/limitations) for details.
* **Side-effect imports** (`import './polyfill'`) are tracked as file-level edges. The imported file won't be flagged as unused, but individual exports within it are still analyzed.

<Info>
  Monorepo workspaces, framework conventions (Next.js, NestJS, Angular, etc.), and decorator-driven wiring are handled automatically via [auto-detected plugins](/frameworks/built-in) and [workspace detection](/configuration/workspaces). See [known limitations](/analysis/limitations) for edge cases.
</Info>

## JSON `_meta` object

When `--explain` is passed (or via MCP), the JSON output includes a `_meta` object:

```json theme={null}
{
  "schema_version": 9,
  "_meta": {
    "docs": "https://docs.fallow.tools/explanations/dead-code",
    "issue_types": {
      "unused_file": {
        "name": "Unused file",
        "description": "File not reachable from any entry point",
        "severity": "error",
        "action": "Delete the file or add it as an entry point"
      },
      "unused_export": {
        "name": "Unused export",
        "description": "Exported symbol never imported by another module",
        "severity": "error",
        "action": "Remove the export keyword or delete the symbol"
      },
      "circular_dependency": {
        "name": "Circular dependency",
        "description": "Modules that import each other directly or transitively",
        "severity": "warning",
        "action": "Extract shared code into a separate module"
      },
      "boundary_violation": {
        "name": "Boundary violation",
        "description": "Import crosses a user-defined architecture zone boundary",
        "severity": "error",
        "action": "Restructure the import to respect zone boundaries"
      }
    }
  }
}
```

AI agents and CI systems can use this to interpret issue types without consulting external documentation.


# Duplication explained
Source: https://docs.fallow.tools/explanations/duplication

What fallow's duplication output means, how clone detection works, and how to interpret and act on the results.

This page covers what `fallow dupes` reports, how to read the output, and when to act.

## Clone types

Fallow classifies clones using the standard taxonomy from clone detection research.

| Clone type | What matches                                                 | Detection mode     |
| :--------- | :----------------------------------------------------------- | :----------------- |
| **Type-1** | Exact token sequences (whitespace/comments already stripped) | `strict`, `mild`   |
| **Type-2** | Same structure, but identifiers and/or literals differ       | `weak`, `semantic` |

As you move from `strict` to `semantic`, recall increases (more clones found) but precision decreases (more potential false positives).

<Accordion title="Research: clone taxonomy">
  The Type-1 through Type-4 clone taxonomy was surveyed by [Roy, Cordy, and Koschke (2009)](https://doi.org/10.1016/j.scico.2009.02.007). Fallow detects Type-1 and Type-2 clones. Type-3 (gapped clones with inserted/deleted statements) and Type-4 (semantically equivalent but syntactically different) require analysis beyond token comparison and are not currently supported.
</Accordion>

### Detection modes in detail

| Mode       | What is normalized                                                         | Trade-off                                             |
| :--------- | :------------------------------------------------------------------------- | :---------------------------------------------------- |
| `strict`   | Nothing -- exact token match                                               | Highest precision, lowest recall                      |
| `mild`     | Equivalent to strict (AST tokenization already strips whitespace/comments) | Default, good starting point                          |
| `weak`     | + string literal values abstracted                                         | Catches copies with different messages/URLs           |
| `semantic` | + identifiers + numeric literals + type annotations stripped               | Catches renamed-variable clones, most false positives |

```text fallow dupes --mode semantic theme={null}
● Clone group (196 lines, 2 instances) [semantic match]
  src/lib/dutch-holidays.ts:193-388
  src/lib/dutch-holidays.ts:389-584
  Renamed: holidays2024→holidays2025, year2024→year2025
```

## Key metrics

### Duplication percentage

Fraction of total source tokens that appear in at least one clone group. Computed over the full analyzed file set, not just the groups shown by `--top`.

| Range  | Interpretation  | Action                                                |
| :----- | :-------------- | :---------------------------------------------------- |
| 0–5%   | Low duplication | No action needed                                      |
| 5–15%  | Moderate        | Review the largest clone families                     |
| 15–30% | High            | Prioritize extraction of shared modules               |
| 30%+   | Very high       | Likely structural issue; look for copy-pasted modules |

<Info>
  Duplication percentage is mode-dependent. Running with `semantic` mode will always report a higher percentage than `strict` because more normalization means more matches. Compare percentages only across runs using the same mode.
</Info>

### Token count and line count

Each clone group reports both token count and line count.

* **Tokens** are language-aware units (keywords, identifiers, operators, literals). This is what the detection engine matches on.
* **Lines** are the source lines spanned by the clone. Useful for estimating refactoring effort.

Larger clones have higher refactoring value. A 200-line clone group is worth extracting; a 6-line one probably isn't.

### Instance count

The number of locations where the same code appears. A clone group with 5 instances means the same block was copied to 5 places. Fixing a bug in the logic requires updating all 5.

| Instances | Risk                     | Action                                                |
| :-------- | :----------------------- | :---------------------------------------------------- |
| 2         | Normal, often acceptable | Extract if the code is complex or likely to change    |
| 3–5       | Bug risk increases       | Extract into a shared function or module              |
| 5+        | High maintenance burden  | Extract urgently; divergence between copies is likely |

## Clone groups and families

### Clone groups

A **clone group** is a single duplicated code block found at 2+ locations. Each location is an **instance**.

```text theme={null}
● Clone group 1 (8 lines, 2 instances)
  src/validators/userValidator.ts:12-19
  src/validators/orderValidator.ts:8-15
```

This means one block of 8 lines appears in both files. Here's what it looks like:

<CodeGroup>
  ```typescript userValidator.ts:12-19 theme={null}
  const errors: string[] = [];
  for (const [key, rule] of Object.entries(rules)) {
    const value = data[key];
    if (rule.required && (value === undefined || value === null)) {
      errors.push(`${key} is required`);
    }
  }
  return errors;
  ```

  ```typescript orderValidator.ts:8-15 theme={null}
  const errors: string[] = [];
  for (const [key, rule] of Object.entries(rules)) {
    const value = data[key];
    if (rule.required && (value === undefined || value === null)) {
      errors.push(`${key} is required`);
    }
  }
  return errors;
  ```
</CodeGroup>

One clone group = one duplicated block. But the same two files may share more than one block:

```text theme={null}
● Clone group 2 (6 lines, 2 instances)
  src/validators/userValidator.ts:24-29
  src/validators/orderValidator.ts:20-25

● Clone group 3 (5 lines, 2 instances)
  src/validators/userValidator.ts:35-39
  src/validators/orderValidator.ts:31-35
```

Three separate clone groups, all between the same two files. That pattern is a **clone family**.

### Clone families

A **clone family** is when multiple clone groups involve the same files. Those files share multiple distinct clones and were probably copy-pasted from each other.

```text theme={null}
Family: src/validators/userValidator.ts ↔ src/validators/orderValidator.ts
  3 clone groups, 19 duplicated lines
  → Extract shared validation module
```

This changes the refactoring approach. Individual clone groups suggest extracting a function. A clone family suggests the files themselves need to be merged or restructured.

| Pattern                   | What it tells you          | Refactoring strategy                                |
| :------------------------ | :------------------------- | :-------------------------------------------------- |
| Single clone group        | One block was copied       | Extract that block into a shared function           |
| Family within one file    | Multiple self-clones       | Extract the repeated pattern into a helper          |
| Family across 2 files     | Files were copy-pasted     | Merge into a shared module with configuration       |
| Family across a directory | Template-based duplication | Replace the template with a parameterized generator |

## When duplication is acceptable

Not all duplication should be eliminated. Context matters.

* **Test files**: Test cases often repeat setup code intentionally. Abstracting test setup makes tests harder to read and debug. Use [`--production`](/cli/global-flags) to exclude test/story/dev files entirely, or use `dupes.ignore` patterns for more granular control.
* **Generated code**: Codegen output (GraphQL, Prisma, OpenAPI) is inherently duplicative. Exclude with `dupes.ignore`.
* **Small clones (\< 10 lines)**: Very small clones are often idiomatic patterns (error handling, guard clauses) rather than meaningful duplication.
* **Cross-language ports**: If you maintain both `.ts` and `.js` versions intentionally, use `--skip-local` to focus on cross-directory duplicates instead.

<Warning>
  Premature abstraction is worse than duplication. If the duplicated code isn't changing and isn't causing bugs, leave it. Extract clones that are both **large** and **in actively changing files**. Use [`fallow health --hotspots`](/cli/health) to cross-reference.
</Warning>

## Interpreting `--threshold` results

The `--threshold` flag sets a maximum allowed duplication percentage. If the project exceeds the threshold, fallow exits with code 1.

```text fallow dupes --threshold 15 theme={null}
Duplication: 19.4% (27,255 duplicated lines across 398 files, exceeds 15% threshold)
Found 1,184 clone groups, 2,959 instances (0.23s) ✗
```

Start with a threshold above your current level, then ratchet it down over time. Combine with `--baseline` for even more gradual adoption.

## How suffix-array detection works

Fallow concatenates all token streams into one sequence, builds a <Tooltip>suffix array</Tooltip> with <Tooltip>LCP array</Tooltip>, and scans for repeated subsequences above the minimum length. This runs in O(n log n) time, no pairwise file comparison needed.

<Accordion title="Research: suffix-array clone detection">
  Token-based clone detection was pioneered by [Baker (1995)](https://doi.org/10.1109/WCRE.1995.514697). Suffix-array approaches for scalable clone detection were developed by [Li et al. (2006)](https://doi.org/10.1145/1137983.1138012). Fallow's approach is closest to the suffix-array method, with normalization levels corresponding to clone types.
</Accordion>

## Limitations

* **Type-3 clones** (gapped clones with inserted/deleted lines) are not detected by default. Add `--near` to find function-scoped near-miss clones with small structural edits. Near-miss detection uses semantic normalization and requires at least 80% shingle similarity between every pair in a group.
* **Type-4 clones** (semantically equivalent but syntactically different) are not detected. Two functions that do the same thing but are written differently will not be flagged.
* **Cross-file-type detection** only works between `.ts` and `.js` files (via `--cross-language`). Other language pairs are not supported.
* **Minimum size thresholds** mean very small clones (below `--min-tokens` / `--min-lines`) are invisible. This is intentional: small clones are usually idiomatic patterns.
* **Semantic mode false positives**: Normalizing identifiers and literals can match code that is structurally similar but semantically unrelated. Review semantic-mode results before acting.

## JSON `_meta` object

When `--explain` is passed (or via MCP), the JSON output includes a `_meta` object:

```json theme={null}
{
  "schema_version": 10,
  "_meta": {
    "docs": "https://docs.fallow.tools/cli/dupes",
    "metrics": {
      "duplication_percentage": {
        "name": "Duplication Percentage",
        "description": "Percentage of source lines that overlap at least one reported clone instance. Computed over the full analyzed file set.",
        "range": "[0, 100]",
        "interpretation": "lower is better"
      },
      "clone_groups": {
        "name": "Clone Groups",
        "description": "A set of code fragments with identical or near-identical normalized token sequences. Each group has 2+ instances across different locations.",
        "interpretation": "each group is a single refactoring opportunity"
      },
      "clone_families": {
        "name": "Clone Families",
        "description": "Groups of clone groups that share the same set of files. Indicates systematic duplication patterns (e.g., mirrored directory structures).",
        "interpretation": "families suggest extract-module refactoring opportunities"
      }
    }
  }
}
```

This is an excerpt. `_meta` carries an entry for every metric the report can emit, plus a `field_definitions` block describing shared wire fields such as `actions[]`.

AI agents and CI systems can use this to interpret results without consulting external documentation.


# Fallow vs linters
Source: https://docs.fallow.tools/explanations/fallow-vs-linters

Why fallow and linters (ESLint, Biome, oxlint) are complementary, not competing. Linters work at the file level. Fallow is codebase intelligence that works at the project graph level. They find fundamentally different things.

Linters check files. TypeScript checks types. Fallow checks the codebase.

* **Formatter**: "Does this file look consistent?"
* **Linter**: "Does this file follow the rules?"
* **Fallow**: "Is this codebase structurally sound?"

What fallow provides is graph-level codebase intelligence: static by default, with an optional runtime intelligence layer (see [static vs runtime](/explanations/static-vs-runtime)) for teams that want to ground dead code decisions in production evidence.

This page explains the conceptual difference, what each tool category finds, and how to combine them in CI.

## Three pillars of code quality

<CardGroup>
  <Card title="Formatter" icon="paintbrush">
    Prettier, Biome, dprint. Enforces consistent formatting across all files: indentation, quotes, trailing commas. Works on a single file. No understanding of imports or project structure.
  </Card>

  <Card title="Linter" icon="list-check">
    ESLint, Biome, oxlint. Enforces coding rules and detects local code smells: undefined variables, missing dependencies in `useEffect`, suspicious patterns. Works on a single file, with optional type context from `tsc`.
  </Card>

  <Card title="Codebase intelligence" icon="diagram-project">
    Fallow. Finds issues that only exist at the project level: unused files, orphaned exports, circular dependencies, dependency graph violations. Requires building and traversing the full module graph.
  </Card>
</CardGroup>

The key distinction: **linters read files**. Fallow **builds the import graph** across the entire project and reasons about relationships between modules.

## What each tool finds

| Issue                                      |   ESLint  |     Biome    |  oxlint  | Fallow |
| :----------------------------------------- | :-------: | :----------: | :------: | :----: |
| Unused variable within a file              |    Yes    |      Yes     |    Yes   |   No   |
| Missing `useEffect` dependency             |    Yes    |      Yes     |    Yes   |   No   |
| Suspicious `==` vs `===`                   |    Yes    |      Yes     |    Yes   |   No   |
| Code style violations                      |    Yes    |      Yes     |    Yes   |   No   |
| Exported symbol never imported             | Slow \[1] |      No      |    No    |   Yes  |
| File not reachable from entry point        |     No    |      No      |    No    |   Yes  |
| Circular import chain across N files       | Slow \[2] |   Yes \[2]   | Yes \[2] |   Yes  |
| Package in deps but never imported         |  No \[3]  |    No \[3]   |    No    |   Yes  |
| Import of package not in package.json      |    Yes    |      Yes     |    No    |   Yes  |
| Architecture boundary enforcement          |  Yes \[4] | Limited \[4] |    No    |   Yes  |
| Duplicated logic blocks across modules     |     No    |      No      |    No    |   Yes  |
| Per-function cyclomatic complexity         |    Yes    |      No      |    Yes   |   Yes  |
| Per-function cognitive complexity          |     No    |      Yes     |    No    |   Yes  |
| Complexity + git churn hotspot correlation |     No    |      No      |    No    |   Yes  |

**\[1] Unused exports.** `eslint-plugin-import/no-unused-modules` rebuilds the full import graph on every lint run. On projects with 20-30K LOC this adds \~320 seconds to total lint time ([#1487](https://github.com/import-js/eslint-plugin-import/issues/1487)). Produces incorrect results with `import { name as alias }` ([#1339](https://github.com/import-js/eslint-plugin-import/issues/1339)). Does not follow barrel file re-export chains. Neither Biome nor oxlint have an equivalent rule.

**\[2] Circular imports.** ESLint: `eslint-plugin-import/no-cycle` takes 45-305 seconds on large projects with known OOM failures ([#2348](https://github.com/import-js/eslint-plugin-import/issues/2348), [#2076](https://github.com/import-js/eslint-plugin-import/issues/2076)). Teams commonly set `maxDepth: 1` to stay fast, missing longer cycles. Only covers ES `import`, not `require()`. Biome v2: `noImportCycles` is Rust-based and graph-aware, but Biome documents it as computationally expensive. oxlint: `no-cycle` in Rust, faster than the JS version. Fallow: builds and caches the graph once, no depth cap, covers both `import` and `require()`.

**\[3] Unused vs unlisted deps.** `no-extraneous-dependencies` (ESLint) and `noUndeclaredDependencies` (Biome) catch imports of packages missing from `package.json`. That is the opposite problem. No linter detects packages listed in `package.json` that are never imported. Fallow finds both.

**\[4] Boundaries.** ESLint: `eslint-plugin-boundaries` enforces import rules between element types with capture groups and templates. `no-restricted-paths` enforces directory-level restrictions but requires enumerating every forbidden pair. Neither follows re-export chains, so a boundary can be bypassed via a barrel file. Biome: `noRestrictedImports` accepts plain string paths only, no globs or patterns. oxlint: no boundary rules. Fallow: [zone presets](/configuration/boundaries) (`bulletproof`, `layered`, `hexagonal`, `feature-sliced`) with re-export chain tracking.

## Detailed comparison

### Unused exports

Fallow builds a persistent module graph, resolves re-export chains iteratively, and handles TypeScript path aliases.

<Info>
  If you're building a library, your public API exports are intentionally consumed externally. Mark them with `/** @public */` (or `@internal`, `@beta`, `@alpha`) JSDoc tags or configure your [entry points](/configuration/overview#entry) so fallow doesn't flag them.
</Info>

```bash theme={null}
fallow dead-code --unused-exports
```

```text theme={null}
● Unused exports (3)
  src/components/Card/index.ts
    :1  CardFooter
  src/utils/format.ts
    :14 formatCurrency
    :28 formatDate
```

### Unused files

`no-unused-modules` detects exports with no importers, but does not detect files that are never imported at all. A file with no exports and no importers (an orphaned utility, a deleted component's leftover test file) does not trigger any ESLint rule.

Detecting unreachable files requires starting from entry points and walking the full import graph. ESLint has no concept of entry points. It lints files; it does not traverse graphs from roots. Fallow reads entry points from `package.json` fields and framework conventions (Next.js pages, Vite entry, etc.), then marks every file not reachable from those roots.

### Circular dependencies

```text theme={null}
src/auth.ts → src/user.ts → src/permissions.ts → src/auth.ts
```

Not all cycles are bugs. Dependency injection frameworks (NestJS, InversifyJS) create intentional cycles. Use `// fallow-ignore-next-line circular-dep` to suppress them, the same way you'd use an ESLint disable comment. No tool automatically distinguishes intentional from accidental cycles.

### Architecture boundary violations

Fallow tracks re-export chains when evaluating boundaries. If `shared/index.ts` re-exports a symbol from `core/`, an import of that symbol is attributed to `core/`, not `shared/`, when checking boundary rules. [Zone presets](/configuration/boundaries) (`bulletproof`, `layered`, `hexagonal`, `feature-sliced`) cover common architecture patterns. Zones use glob patterns, and rules are expressed as allowlists ("this zone can only import from these zones") rather than enumerating forbidden paths.

```jsonc theme={null}
{
  "boundaries": {
    "zones": [
      { "name": "ui", "include": ["src/components/**"] },
      { "name": "api", "include": ["src/api/**"] }
    ],
    "rules": [
      { "from": "ui", "disallow": ["api"] }
    ]
  }
}
```

## Recommended CI pipeline

Run all three in parallel. Some linter plugins (`no-cycle`, `no-unused-modules`) overlap with fallow on a subset of issues. If you already have those enabled, fallow covers the same ground faster and adds the issues linters cannot detect (unused files, unused deps, duplication, churn hotspots). If you don't have them enabled, fallow covers everything in one pass:

```yaml theme={null}
jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx prettier --check .          # or: npx biome check --only=format

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx eslint .                    # or: npx biome lint / npx oxlint

  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: fallow-rs/fallow@v3
```

<Info>
  Fallow's GitHub Action automatically uploads SARIF results to GitHub Code Scanning, giving you inline annotations on PR diffs. Linter results typically appear via separate status checks or linter-review actions. For GitLab CI and other runners, see [CI integration](/integrations/ci).
</Info>

## What to use when

| Situation                                              | Tool                                                                                                                    |
| :----------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
| Variable used in wrong scope                           | Linter                                                                                                                  |
| Missing React hook dependency                          | Linter                                                                                                                  |
| Inconsistent code style                                | Formatter                                                                                                               |
| Exported function nobody imports                       | Fallow                                                                                                                  |
| File that was left behind after a refactor             | Fallow                                                                                                                  |
| `lodash` in `package.json` but never imported          | Fallow                                                                                                                  |
| 8-file circular dependency chain                       | Fallow                                                                                                                  |
| Feature module importing directly from core internals  | Fallow                                                                                                                  |
| Growing codebase, want to prevent new dead code in PRs | Fallow (`--changed-since`)                                                                                              |
| Library export consumed by external consumers          | Fallow (configure [entry points](/configuration/overview#entry) or `/** @public */` / `@internal` / `@beta` / `@alpha`) |

<Tip>
  Existing codebase already has unused exports and files? Use `--save-baseline` to snapshot current issues, then run CI with `--baseline` to fail only on regressions. See the [CI integration guide](/integrations/ci) for incremental adoption.
</Tip>

<Info>
  For a comparison with knip, which operates at the same graph level as fallow, see [Fallow vs Knip](/migration/comparison).
</Info>

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Add fallow to your project in under a minute.
  </Card>

  <Card title="CI Integration" icon="shield-check" href="/integrations/ci">
    Full guide for GitHub Actions, GitLab CI, and other pipelines.
  </Card>

  <Card title="Dead code explained" icon="skull-crossbones" href="/explanations/dead-code">
    Fallow's dead code and dependency findings, with examples.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Entry points, ignore patterns, severity rules.
  </Card>
</CardGroup>


# Health explained
Source: https://docs.fallow.tools/explanations/health

What each metric in fallow's health output means, how it's computed, and how to interpret the values. Complexity analysis, hotspot detection, and refactoring targets integrated with dead-code and duplication findings.

Codebase health analysis goes beyond finding dead code. While unused exports and unreachable files tell you what to delete, health metrics tell you what to fix: which functions are too complex, which files change too often, and where untested complexity creates the most risk.

This page covers what `fallow health` reports, when to act on the numbers, and where the research comes from.

## Complexity metrics

These metrics appear in [`fallow health`](/cli/health) output, both per-function (findings) and per-file (file scores).

### Cyclomatic complexity

The number of linearly independent paths through a function's control flow graph. For structured programs (like JS/TS), this simplifies to 1 + the number of decision points (`if`/`else`, `switch` cases, loops, ternary `?:`, logical `&&`/`||`, `catch`).

| Range | Interpretation                              | Action                       |
| :---- | :------------------------------------------ | :--------------------------- |
| 1–10  | Simple, easy to test exhaustively           | No action needed             |
| 11–20 | Moderate, most functions should stay here   | Review if growing            |
| 21–50 | High, hard to test all paths                | Split into smaller functions |
| 50+   | Very high, testing all paths is impractical | Refactor urgently            |

**Default threshold:** 20

Project-wide cyclomatic averages, percentiles, and critical shares include authored functions, module-scope branching, and template units. `vital_signs.cyclomatic_population` reports `count`, `sum`, and `max` for each group. Add the sums and divide by the total count to reconstruct the mean, rounded to one decimal place. An empty group has a `null` maximum; older saved reports omit the population field.

Module-scope units contribute to these aggregates without producing function findings. `summary.functions_analyzed` counts functions and template units checked for findings, excluding module scopes. For example, one function with complexity 1 and a module scope with complexity 31 produce an average of 16 even when the function has no finding. The population fields make that difference explicit.

Compact output appends population rows after the unchanged `vital-signs` line, in functions, modules, then templates order. For the example above:

```text theme={null}
cyclomatic-population:functions:count=1,sum=1,max=1
cyclomatic-population:modules:count=1,sum=31,max=31
cyclomatic-population:templates:count=0,sum=0,max=null
```

Older reports or results without population data omit all three rows.

<Accordion title="Research">
  Introduced by Thomas McCabe in ["A Complexity Measure" (1976)](https://doi.org/10.1109/TSE.1976.233837). The practical upper bound of 20 comes from [NIST SP 500-235](https://www.nist.gov/publications/structured-testing-testing-methodology-using-cyclomatic-complexity-metric) (Watson & McCabe, 1996).
</Accordion>

### Cognitive complexity

How hard a function is to understand when reading top-to-bottom. Unlike cyclomatic complexity (which counts paths for *testing*), cognitive complexity measures *comprehension difficulty*. It penalizes nesting depth, `break`/`continue` to labels, recursion, and sequences of logical operators.

| Range | Interpretation                         | Action                                    |
| :---- | :------------------------------------- | :---------------------------------------- |
| 0–7   | Easy to understand at a glance         | No action needed                          |
| 8–15  | Moderate, may benefit from extraction  | Extract helpers if growing                |
| 15+   | Hard to follow, likely mixing concerns | Refactor: extract, simplify, or decompose |

**Default threshold:** 15 (matches SonarSource's default rule). The 0–7 "easy" range is fallow's guideline based on common industry practice.

<Accordion title="Research">
  Developed by G. Ann Campbell at SonarSource. Full specification: [SonarSource white paper](https://www.sonarsource.com/resources/cognitive-complexity/).
</Accordion>

### Complexity density

Total cyclomatic complexity divided by lines of code. Normalizing by file size lets you compare fairly: a 500-line file with complexity 50 (density 0.1) vs. a 10-line file with complexity 10 (density 1.0).

| Value   | Interpretation                                    | Action                                       |
| :------ | :------------------------------------------------ | :------------------------------------------- |
| \< 0.3  | Low, data files, configs, simple modules          | No action needed                             |
| 0.3–1.0 | Moderate, normal application code                 | Review the densest functions                 |
| > 1.0   | Very dense, nearly every line is a decision point | Refactor: extract logic, simplify conditions |

### Cyclomatic vs cognitive: a code example

These two functions illustrate why both metrics matter:

<CodeGroup>
  ```typescript High cyclomatic, low cognitive theme={null}
  // Cyclomatic: 6 (one per case)
  // Cognitive: 1 (flat switch is easy to read)
  function getStatusLabel(status: string): string {
    switch (status) {
      case "pending": return "Pending";
      case "active": return "Active";
      case "paused": return "Paused";
      case "cancelled": return "Cancelled";
      case "completed": return "Done";
      default: return "Unknown";
    }
  }
  ```

  ```typescript Low cyclomatic, high cognitive theme={null}
  // Cyclomatic: 4 (one per if)
  // Cognitive: 9 (nesting adds +2, +3 increments)
  function processOrder(order: Order): string {
    if (order.items.length > 0) {            // +1
      if (order.customer.verified) {          // +2 (nesting)
        if (order.total > order.limit) {      // +3 (nesting)
          return "requires_approval";
        }
      } else {                                // +1
        return "unverified";
      }
    }
    return "empty";
  }
  ```
</CodeGroup>

The `switch` has higher cyclomatic complexity (more paths to test) but is trivially readable. The nested `if` chain has lower cyclomatic complexity but is harder to follow. Cognitive complexity captures that difference.

### Synthetic `<template>` and `<component>` findings

Angular components render their work across two surfaces: a TypeScript class (methods, getters, lifecycle hooks) and a template (HTML control flow, bindings, interpolations). Fallow flags both, but the per-half findings would understate the total complexity an agent or developer is responsible for. Two synthetic finding shapes close that gap:

| Finding `name` | Path                                                             | What `cyclomatic` and `cognitive` count                                                                                                                                                                                                                                                                |
| :------------- | :--------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<template>`   | The `.html` file or the `.ts` file containing the inline literal | Cyclomatic: template control-flow blocks (`@if`, `@else if`, `@for`, `@case`, `@defer (when ...)`, legacy `*ngIf`/`*ngFor`) plus ternary and logical operators inside bound attributes and `{{ }}` interpolations. Cognitive: the same plus nesting penalties on stacked `@if`/`@for`/`@switch` blocks |
| `<component>`  | The `.ts` file declaring the `@Component`                        | Worst class method's score plus the template's score, for each metric. Ranking and `--targets` use the rollup totals; the per-half breakdown lives under `component_rollup` (`class_cyclomatic`, `class_cognitive`, `template_cyclomatic`, `template_cognitive`)                                       |

Both shapes route to the same rule ids as function findings: `fallow/high-cyclomatic-complexity`, `fallow/high-cognitive-complexity`, and `fallow/high-complexity`. They use the same thresholds (`max_cyclomatic`, `max_cognitive`) and the same severity bands. Templates that exceed the configured threshold are surfaced individually; if both a `<template>` and at least one class method on the same component file exceed thresholds, a `<component>` rollup is added alongside them.

Acting on these findings differs from function findings:

* **`<template>` findings** are easiest to address by splitting into child components, hoisting derived data into the class as computed signals (`computed(...)`), or replacing nested control flow with a flatter structure.
* **`<component>` rollup findings** point to a component whose two halves together exceed the budget. Attack the larger half first: the `component_rollup.class_*` and `component_rollup.template_*` fields show which side contributes more.

CRAP scoring on `<template>` findings inherits from the owning component class: the `templateUrl` edge means a template is reachable iff its class is reachable, and tests that exercise the class also exercise the template. The `inherited_from` field on a `<template>` finding's payload names the `.component.ts` file whose coverage drove the score, so the `increase-coverage` action targets the testable surface (the class) rather than the structurally untestable `.html`.

## File health scores

Per-file scores from [`fallow health --file-scores`](/cli/health). Zero-function files (barrel files, re-export files) are excluded.

### Maintainability Index (MI)

Fallow uses a **simplified Maintainability Index** adapted for JavaScript/TypeScript module graphs.

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

| Range  | Interpretation       | Action                                    |
| :----- | :------------------- | :---------------------------------------- |
| 70–100 | Good maintainability | Monitor                                   |
| 40–70  | Moderate             | Review periodically, address if declining |
| 0–40   | Poor                 | Prioritize for refactoring                |

```text fallow health --file-scores --top 5 theme={null}
● File health scores (3 files) · sorted by triage concern

   57.5    src/helpers/errorUtil.ts                         structure
             48 LOC    1 fan-in    0 fan-out  100% dead  0.75 density  18.0 risk

   76.2    src/helpers/util.ts                              risk
            320 LOC   35 fan-in    0 fan-out   86% dead  0.22 density  42.0 risk

   90.5    src/types.ts                                     structure
            154 LOC   42 fan-in    3 fan-out    0% dead  0.20 density   4.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
```

<Accordion title="How fallow's MI relates to the classic Maintainability Index">
  The original MI from [Oman and Hagemeister (1992)](https://doi.org/10.1109/ICSM.1992.242525) combines Halstead Volume, cyclomatic complexity, lines of code, and comment percentage. [Microsoft adapted it](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning) to a 0–100 scale for Visual Studio.

  Fallow's variant makes three changes for the JS/TS ecosystem:

  1. **Replaces Halstead Volume with complexity density.** Halstead metrics require full type resolution, which fallow doesn't have (syntactic analysis only). Complexity density captures the same "how complex per unit of code" signal.
  2. **Adds dead code ratio.** Unused exports are a JS/TS-specific maintenance burden that the classic MI doesn't account for.
  3. **Adds fan-out coupling penalty.** High import counts are a strong signal of maintenance difficulty in module-based codebases. The penalty uses logarithmic scaling (`ln(fan_out + 1) × 4`, capped at 15 points), reflecting diminishing marginal risk per additional import.

  Because the formula differs, fallow's MI scores are **not directly comparable** to Visual Studio or SonarQube MI scores.
</Accordion>

### Fan-in, fan-out, and dead code ratio

**Fan-in**: number of files that import this file. High fan-in = high blast radius when changed.

**Fan-out**: number of files this file imports. High fan-out = high coupling and change propagation risk.

**Dead code ratio**: fraction of value exports with zero references (0-1). Type-only exports (interfaces, type aliases) are excluded.

| Metric          | Signal                         | Action                                  |
| :-------------- | :----------------------------- | :-------------------------------------- |
| Fan-in > 20     | Many dependents, critical file | Extra review before changes             |
| Fan-out > 15    | Many imports, high coupling    | Consider splitting into smaller modules |
| Dead code = 0   | All exports used               | No action needed                        |
| Dead code > 0.3 | Significant unused code        | Run `fallow fix` to auto-remove         |

<Accordion title="Research: fan-in/fan-out">
  Fan-in/fan-out coupling metrics originate from [Henry and Kafura (1981)](https://doi.org/10.1109/TSE.1981.231113). Later refined in the [Chidamber & Kemerer OO metrics suite (1994)](https://doi.org/10.1109/32.295895), where Coupling Between Objects (CBO) captures the same idea for class-level dependencies.
</Accordion>

### Coupling concentration

Two vital signs metrics summarize coupling at the project level:

| Metric              | Description                                                   |
| :------------------ | :------------------------------------------------------------ |
| `p95_fan_in`        | 95th percentile fan-in across all files                       |
| `coupling_high_pct` | Percentage of files with fan-in above the effective threshold |

The effective threshold is `max(p95_fan_in, 10)`. The floor of 10 prevents false positives in small projects where even moderate fan-in is normal.

### Risk profiles

Risk profiles show what percentage of functions fall into each risk bin. Two profiles are reported as vital signs:

**Unit size** (function length in lines of code):

| Bin            | LOC range |
| :------------- | :-------- |
| Low risk       | 1–15      |
| Medium risk    | 16–30     |
| High risk      | 31–60     |
| Very high risk | > 60      |

**Unit interfacing** (function parameter count):

| Bin            | Parameters |
| :------------- | :--------- |
| Low risk       | 0–2        |
| Medium risk    | 3–4        |
| High risk      | 5–6        |
| Very high risk | 7+         |

Both profiles appear as `unit_size_profile` and `unit_interfacing_profile` in the vital signs JSON, each containing `low_risk`, `medium_risk`, `high_risk`, and `very_high_risk` percentage values.

When the unit size profile shows >= 3% of functions in the very-high-risk bin (> 60 LOC), the human output includes a **Large functions** drill-down listing the specific oversized functions with file path, function name, line number, and LOC count. In JSON output, these appear as a `large_functions` array on the health report.

The 60-LOC threshold is configurable via `health.maxUnitSize` (globally) or a per-file `health.thresholdOverrides[].maxUnitSize` entry. Raising it for a glob (e.g. `**/*.test.*`) removes those functions from the **Large functions** list while keeping complexity, cognitive, and CRAP checks on the same files, which is the recommended way to stop test suites (long `describe()` / `it()` blocks) from dominating the list. Like the other overrides, `maxUnitSize` filters the reported list; the descriptive `unit_size_profile` and the unit-size score still reflect raw sizes, so use `health.ignore` if you want a file out of the score entirely.

<Accordion title="Research: SIG quality model">
  Risk profiles follow the [SIG/TÜViT quality model](https://www.softwareimprovementgroup.com/wp-content/uploads/SIG-TUViT-Evaluation-Criteria-Trusted-Product-Maintainability-Guidance-for-producers.pdf), which benchmarks codebases by the distribution of code across risk categories rather than by averages. A codebase where 95% of functions are low-risk is healthier than one with the same average complexity but a fat tail of very-high-risk functions.
</Accordion>

## Untested complexity risk

Complex code without test coverage is the most likely source of production bugs. Fallow quantifies this risk per function using a score based on the CRAP metric (Change Risk Anti-Patterns), originally developed by Alberto Savoia and Bob Evans at Agitar Labs in 2007.

The score appears in [`fallow health --file-scores`](/cli/health) output and JSON.

### How the score is computed

Fallow uses the canonical CRAP formula:

```
score = CC^2 × (1 - cov/100)^3 + CC
```

Where `cov` is per-function coverage (0–100). Fallow obtains that value in one of three ways:

| Model (`coverage_model`) | When                                                                                                             | How `cov` is determined                                                                                                               |
| :----------------------- | :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `static_estimated`       | Default                                                                                                          | Graph-based per-function estimate: directly test-referenced = 85%, transitively test-reachable = 40%, not test-reachable = 0%.        |
| `istanbul`               | `--coverage <coverage-final.json>` (auto-detected from `coverage/` and `.nyc_output/`, or via `FALLOW_COVERAGE`) | Real per-function statement coverage produced by Jest, Vitest, c8, or nyc.                                                            |
| `static_binary`          | Legacy, snapshot/JSON compatibility only                                                                         | Whole-file binary: test-reachable file = 100% (score = CC), untested file = 0% (score = CC^2 + CC). Superseded by `static_estimated`. |

For untested code the quadratic term makes complexity hurt fast. Under the default `static_estimated` model, a not-test-reachable function with cyclomatic complexity 5 scores 5^2 × 1 + 5 = 30, which is exactly the default flag threshold.

For execution evidence from real traffic (hot/cold paths, runtime-weighted dead-code verdicts), see [Runtime coverage](/analysis/runtime-coverage). Runtime coverage is a paid Fallow Runtime feature and accepts V8 or Istanbul runtime data via `--runtime-coverage`; it merges on top of whichever static `coverage_model` is active.

**Default threshold:** 30 (functions scoring at or above this value are flagged)

### Interpreting the numbers

| Score   | Interpretation                             | Action                                                              |
| :------ | :----------------------------------------- | :------------------------------------------------------------------ |
| \< 30   | Acceptable risk                            | No action needed                                                    |
| 30-99   | Moderate risk, complex untested code       | Add test coverage or reduce complexity                              |
| 100-999 | High risk                                  | Prioritize: add tests, then simplify                                |
| > 999   | Extreme risk (shown as ">999" in terminal) | Refactor urgently, this code is both complex and invisible to tests |

In human output, scores above 999 are capped to `>999` for readability. JSON output always contains the exact value.

### File-level aggregation

Each file reports two aggregated values:

| Field                  | Meaning                                |
| :--------------------- | :------------------------------------- |
| `crap_max`             | Highest per-function score in the file |
| `crap_above_threshold` | Count of functions scoring >= 30       |

The active model is reported as `coverage_model` on the health summary (`static_estimated`, `istanbul`, or the legacy `static_binary`).

### Refactoring targets

The `add_test_coverage` refactoring target (label `untested risk`) fires when both conditions are true:

* `crap_above_threshold` >= 2 (multiple risky functions, not just one outlier)
* `complexity_density` > 0.3 (the file is genuinely complex, not just large)

This combination identifies files where adding test coverage will reduce the most risk per effort spent.

### Suppression

To exclude a file from untested complexity risk reporting:

```typescript theme={null}
// fallow-ignore-file coverage-gaps
```

This suppresses all coverage-related findings for the file, including the CRAP-based scores.

To suppress individual functions from complexity findings (cyclomatic and cognitive thresholds):

```typescript theme={null}
// fallow-ignore-next-line complexity
function* parseCsv(text) { /* ... */ }
```

See [Inline suppression](/configuration/suppression) for all suppressible issue types.

<Accordion title="Static estimation vs. real coverage">
  A fully tested function (cov = 100) always scores exactly CC, regardless of complexity. A completely untested function (cov = 0) scores CC^2 + CC.

  The default `static_estimated` model is an approximation of test coverage:

  * **False negatives**: A file imported by tests but with functions that are never actually exercised will score lower (look healthier) than it should.
  * **False positives**: A file referenced only from non-test code can score worse than it deserves if it is in fact unit-tested through indirect paths.
</Accordion>

<Accordion title="Research">
  The CRAP metric was introduced by Alberto Savoia and Bob Evans at Agitar Labs. Original presentation: ["CRAP4J" (2007)](http://www.artima.com/weblogs/viewpost.jsp?thread=215899). The core insight is that complexity alone is not dangerous if the code is well-tested, and simple code is low-risk even without tests. Risk concentrates where complexity and missing coverage overlap.
</Accordion>

## Hotspot metrics

Hotspots are files that are both **complex** and **frequently changing**. Bugs concentrate at this intersection, and refactoring here yields the highest return. Available via [`fallow health --hotspots`](/cli/health).

<Info>
  **The core insight:** Complex code that never changes is stable. Simple code that changes often is manageable. Complex code that changes often is where defects concentrate.
</Info>

### Hotspot score

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

The multiplicative relationship means a file needs **both** high churn AND high complexity to score highly. Either dimension alone produces a low score.

| Score  | Interpretation   | Action                                |
| :----- | :--------------- | :------------------------------------ |
| 70–100 | Critical hotspot | Prioritize refactoring in next sprint |
| 40–70  | Moderate hotspot | Schedule review, reduce complexity    |
| 0–40   | Low risk         | Monitor                               |

```text fallow health --hotspots --top 3 theme={null}
● Hotspots (3 files, since 6 months)

   72.1 ▲  src/types.ts
           47 commits   2739 churn  0.20 density  42 fan-in  ▲ accelerating

   38.4 ─  src/helpers/util.ts
           23 commits    610 churn  0.22 density  35 fan-in  ─ stable

   12.7 ▼  src/locales/en.ts
            8 commits    177 churn  0.35 density   2 fan-in  ▼ cooling

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

### Weighted commits

Recency-weighted commit count using exponential decay with a 90-day half-life:

* A commit **yesterday** contributes \~1.0
* A commit **90 days ago** contributes \~0.5
* A commit **180 days ago** contributes \~0.25

<Accordion title="Research">
  Recency-weighted change metrics were introduced by [Graves et al. (2000)](https://doi.org/10.1109/32.859533). The empirical link between churn and defect density was established by [Nagappan and Ball (2005)](https://doi.org/10.1145/1062455.1062514) at Microsoft.
</Accordion>

### Churn trend

Compares commit frequency in the first half vs second half of the analysis window:

| Trend          | Meaning                    | Action                                   |
| :------------- | :------------------------- | :--------------------------------------- |
| `accelerating` | Recent > 1.5× older half   | High priority if complexity is also high |
| `stable`       | Balanced frequency         | Normal, monitor score                    |
| `cooling`      | Recent \< 0.67× older half | Lower priority, stabilizing              |

<Accordion title="Research: churn × complexity methodology">
  Pioneered by Michael Feathers and systematized by Adam Tornhill in [*Your Code as a Crime Scene*](https://pragprog.com/titles/atcrime/your-code-as-a-crime-scene/) (2015) and [*Software Design X-Rays*](https://pragprog.com/titles/atevol/software-design-x-rays/) (2018).
</Accordion>

## Refactoring targets

Refactoring targets are ranked, actionable recommendations produced by [`fallow health --targets`](/cli/health). They rank files by refactoring priority using the metrics above.

<Tip>
  **Quick start**: Run `fallow health --targets` for a prioritized refactoring list. Filter by `effort: low` for the fastest improvements. Save a baseline with `--save-baseline` and pass `--baseline` in CI to block new regressions. Update the baseline as you fix targets.
</Tip>

<Info>
  **Targets are synthesis, not data.** The other sections show measurements. Targets tell you what to do about them.
</Info>

### Priority score

```
priority = min(complexity_density, 1) × 30
         + hotspot_boost × 25            (hotspot_score / 100 if in hotspots, else 0)
         + dead_code_ratio × 20
         + min(fan_in / 20, 1) × 15
         + min(fan_out / 30, 1) × 10
```

All inputs are normalized to \[0, 1] so each weight is a true percentage share. The formula intentionally avoids the Maintainability Index to prevent double-counting (MI already incorporates density and dead code).

| Score  | Interpretation | Action                             |
| :----- | :------------- | :--------------------------------- |
| 70–100 | High priority  | Address in the current sprint      |
| 40–70  | Moderate       | Schedule for upcoming work         |
| 0–40   | Lower priority | Monitor, address opportunistically |

### Effort estimation

Every target includes an effort estimate (`low`, `medium`, or `high`) based on three file-level signals:

| Effort     | Criteria                                                                       |
| :--------- | :----------------------------------------------------------------------------- |
| **low**    | \< 100 lines AND ≤ 3 functions AND fan-in \< P25 percentile                    |
| **high**   | ≥ 500 lines, OR fan-in ≥ P95 percentile, OR (≥ 15 functions AND density > 0.5) |
| **medium** | Everything else                                                                |

Effort uses OR-semantics for "high" (any single criterion triggers it) and AND-semantics for "low" (all three must be true). The fan-in percentiles are computed from the project's file-score distribution (P25 floor 2, P95 floor 5), so a small file whose fan-in sits at or above the project's P95 is still "high" because changes ripple widely.

In human output, effort appears after the category label separated by `·`:

```text theme={null}
dead code · low    Remove 12 unused exports...
complexity · high  Extract 3 functions with cognitive complexity > 30...
```

### Evidence

For three recommendation categories, fallow provides structured evidence linking the target back to specific analysis data. This lets agents and scripts act on recommendations without a second tool call.

| Category                    | Evidence fields                                        | Example                                                   |
| :-------------------------- | :----------------------------------------------------- | :-------------------------------------------------------- |
| `remove_dead_code`          | `unused_exports`: list of export names                 | `["assertEqual", "assertIs", "assertNever"]`              |
| `extract_complex_functions` | `complex_functions`: list of `{name, line, cognitive}` | `[{"name": "processData", "line": 45, "cognitive": 113}]` |
| `break_circular_dependency` | `cycle_path`: list of file paths forming the cycle     | `["src/a.ts", "src/b.ts", "src/c.ts"]`                    |
| All other categories        | `evidence` omitted from JSON                           | —                                                         |

Evidence is designed for machine consumption. In human output, the recommendation text already incorporates the key evidence (e.g., "Remove 12 unused exports" or "Extract processData (cognitive: 113)").

### Baselines

Use `--save-baseline` and `--baseline` with the health command to track refactoring progress over time. When a baseline is active, only *new* targets (not present in the baseline) are reported.

```bash theme={null}
# Save current targets as the baseline
fallow health --targets --save-baseline fallow-baselines/health.json

# On subsequent runs, only show new targets
fallow health --targets --baseline fallow-baselines/health.json
```

Baseline keys use the format `relative_path:category_label` (e.g., `src/utils.ts:dead code`). A target is considered "known" if the same file + category combination exists in the baseline, regardless of whether its priority score or effort level has changed.

This is useful in CI to prevent new tech debt from landing while allowing existing targets to be addressed incrementally.

### Recommendation categories

Each target is assigned a category based on which rule matches first (evaluated in priority order):

| Category                  | Display label      | Trigger                                                    | What it means                                                   |
| :------------------------ | :----------------- | :--------------------------------------------------------- | :-------------------------------------------------------------- |
| Urgent churn + complexity | `churn+complexity` | Hotspot score ≥ 50, accelerating trend, density > 0.5      | Actively-changing file with growing complexity, highest urgency |
| Break circular dependency | `circular dep`     | File in an import cycle with fan-in ≥ 5                    | Changes cascade through the cycle to many dependents            |
| Split high-impact file    | `high impact`      | Fan-in ≥ 20 (or ≥ 10 with ≥ 5 functions) and density > 0.3 | High blast radius amplifies every bug introduced                |
| Remove dead code          | `dead code`        | Dead code ratio ≥ 0.5 with ≥ 3 value exports               | Majority of exports are unused; reduce surface area             |
| Extract complex functions | `complexity`       | Top cognitive complexity ≥ 30                              | Contains functions that are very hard to understand             |
| Reduce coupling           | `coupling`         | Fan-out ≥ 15 and MI \< 60 (excluding entry points)         | Too many imports reduce testability                             |
| Add test coverage         | `untested risk`    | `crap_above_threshold` ≥ 2 and density > 0.3               | Multiple complex functions lack a test dependency path          |

A file can trigger multiple rules, but only the highest-priority match determines the category. All contributing factors are still collected and shown in JSON output.

```text fallow health --targets --top 5 theme={null}
● Refactoring targets (5)

  92.3    src/core/processor.ts
          churn+complexity · high  Actively-changing file with growing complexity, stabilize before adding features

  71.2    src/utils/helpers.ts
          high impact · high  Split high-impact file, 15 dependents amplify every change

  55.8    src/legacy/old-api.ts
          dead code · low  Remove 8 unused exports to reduce surface area (73% dead)

  52.0    src/graph/resolver.ts
          circular dep · medium  Break import cycle, 8 files depend on this, changes cascade through the cycle

  41.8    src/components/Dashboard.tsx
          complexity · high  Extract renderMetrics (cognitive: 45) and renderFilters (cognitive: 32) into smaller functions

  Prioritized refactoring recommendations based on complexity, churn, and coupling signals: https://docs.fallow.tools/explanations/health#refactoring-targets
```

### JSON structure

With `--format json`, each target includes structured data for programmatic consumption:

```json theme={null}
{
  "targets": [
    {
      "path": "src/core/processor.ts",
      "priority": 92.3,
      "recommendation": "Actively-changing file with growing complexity, stabilize before adding features",
      "category": "urgent_churn_complexity",
      "effort": "high",
      "factors": [
        {
          "metric": "complexity_density",
          "value": 0.67,
          "threshold": 0.3,
          "detail": "density 0.67 exceeds 0.3"
        },
        {
          "metric": "fan_in",
          "value": 12,
          "threshold": 10,
          "detail": "12 files depend on this"
        }
      ]
    },
    {
      "path": "src/helpers/util.ts",
      "priority": 38.8,
      "recommendation": "Remove 12 unused exports to reduce surface area (86% dead)",
      "category": "remove_dead_code",
      "effort": "low",
      "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", "oldConfig", "legacyHelper"]
      }
    }
  ]
}
```

Each factor includes raw `value` and `threshold` for programmatic use. The `evidence` field provides actionable detail for categories that support it. AI agents can use `evidence.unused_exports` to generate removal PRs without a second tool call. Categories without evidence omit the field entirely.

## Health score

The health score is a single 0–100 number summarizing overall codebase quality. Available via [`fallow health --score`](/cli/health).

```
score = 100 - sum(penalties)
```

Clamped to \[0, 100]. Each penalty targets a different quality dimension:

| Penalty         | Formula                                                                                      | Max |
| :-------------- | :------------------------------------------------------------------------------------------- | --: |
| Dead files      | `min(dead_file_pct × 0.2, 15)`                                                               |  15 |
| Dead exports    | `min(dead_export_pct × 0.2, 15)`                                                             |  15 |
| Complexity      | `min(critical_complexity_pct × 4, 20)`                                                       |  20 |
| P90 complexity  | `0` for formula v2 runs; older snapshots fall back to `min(max(0, p90_cyclomatic − 10), 10)` |  10 |
| Maintainability | `min(maintainability_low_pct × 1.5, 15)`                                                     |  15 |
| Hotspots        | `min(hotspot_top_pct_count / ceil(total_files × 0.01) × 10, 10)`                             |  10 |
| Unused deps     | `min(unused_deps_per_k_files × 0.5, 25)`                                                     |  25 |
| Circular deps   | `min(circular_deps_per_k_files × 0.5, 25)`                                                   |  25 |
| Unit size       | `min(functions_over_60_loc_per_k × 0.5, 10)`                                                 |  10 |
| Coupling        | `min(coupling_high_pct × 0.5, 5)`                                                            |   5 |
| Duplication     | `min(max(0, duplication_pct − 5) × 1.0, 10)`                                                 |  10 |

`health_score.formula_version` identifies the formula used. Version 2 uses scale-invariant density and tail metrics so large monorepos are not diluted by many healthy files. Older snapshots that lack the v2 fields fall back to the previous average, p90, and raw-count aggregators.

**Letter grades:** A (score >= 85), B (70–84), C (55–69), D (40–54), F (below 40).

Penalty fields are `null` in JSON when the corresponding analysis 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.

## Limitations

<Warning>
  Metrics are signals, not verdicts. Be aware of these edge cases.
</Warning>

* **Generated files** (GraphQL codegen, Prisma client, OpenAPI types) may have high complexity density but shouldn't be refactored. Use `health.ignore` patterns to exclude them.
* **Test files** with many `it()`/`test()` blocks can have high cyclomatic complexity. This is usually fine. Test suites *should* cover many paths.
* **Config files** (Webpack, ESLint) may appear as hotspots due to frequent changes during setup. Their churn typically cools after initial configuration.
* **MI scores are not portable.** Fallow's formula differs from Visual Studio and SonarQube, so scores are not directly comparable across tools.
* **Hotspot scores are project-relative.** A score of 80 means "worst in your project," not "objectively bad." A well-maintained project may have a top score of 30.
* **Fan-in/out counts modules, not imports.** `import { a, b, c } from './utils'` counts as 1 edge, not 3.

## JSON `_meta` object

When `--explain` is passed (or via MCP), each command's JSON output includes a `_meta` object:

```json theme={null}
{
  "schema_version": 11,
  "_meta": {
    "docs": "https://docs.fallow.tools/explanations/health",
    "metrics": {
      "maintainability_index": {
        "name": "Maintainability Index",
        "description": "Composite score: 100 - (complexity_density × 30) - ...",
        "range": "[0, 100]",
        "interpretation": "higher is better; <40 poor, 40–70 moderate, >70 good"
      }
    }
  }
}
```

AI agents and CI systems can use this to interpret metric values without consulting external documentation.


# Explanations
Source: https://docs.fallow.tools/explanations/index

Mental models for how Fallow works and how to use it well. Static vs runtime intelligence, Fallow vs linters, health, duplication, and dead code explained.

These pages explain the model behind the tool.

<CardGroup>
  <Card title="Static vs runtime intelligence" icon="chart-network" href="/explanations/static-vs-runtime">
    Static answers "what is connected". Runtime answers "what actually ran".
  </Card>

  <Card title="Fallow vs linters" icon="scale-balanced" href="/explanations/fallow-vs-linters">
    Why project-wide analysis catches what file-local tools cannot.
  </Card>

  <Card title="Health explained" icon="heart-pulse" href="/explanations/health">
    How health, maintainability, and refactor targets are computed.
  </Card>

  <Card title="Duplication explained" icon="clone" href="/explanations/duplication">
    The four detection modes and when to use each.
  </Card>

  <Card title="Dead code explained" icon="skull-crossbones" href="/explanations/dead-code">
    What Fallow considers reachable and why.
  </Card>
</CardGroup>

If you are new to Fallow, start with **Static vs runtime intelligence** and **Fallow vs linters**.


# Static vs runtime intelligence
Source: https://docs.fallow.tools/explanations/static-vs-runtime

Static analysis answers 'what is connected to what?'. Runtime intelligence answers 'what actually ran?'. Both are necessary, neither replaces the other, and they meet in fallow health.

Fallow answers two different questions about your codebase. Static analysis answers "what is connected to what?". Runtime intelligence answers "what actually ran?". Both are necessary. Neither replaces the other.

This page explains where each layer stops, what the other layer adds, and why `fallow health` is where they converge.

## What static intelligence sees

Static analysis builds a module graph from your source. Every file, every import, every export, every re-export chain, every dynamic `import()` it can resolve. From that graph, Fallow derives:

* **Reachability.** Which files are reachable from an entry point and which are not.
* **Exports with zero importers.** A public API surface that nothing consumes.
* **Import cycles.** Tight cycles and long ones, without a depth cap.
* **Duplicated blocks.** Structural clones across modules, including clones with renamed identifiers.
* **Complexity hotspots.** Per-function cyclomatic and cognitive complexity, maintainability scores, churn correlation.
* **Architecture boundaries.** Layered, hexagonal, feature-sliced, or custom zones, with re-export chain tracking.
* **Feature flag definitions.** Where flags are declared, where they're branched on, which branches exist.

Concrete examples of what static analysis flags with confidence:

* An `export function computeTax` that no file imports, directly or through a barrel.
* A file at `src/server/jobs/worker.ts` that isn't reached from any entry point, script, or test.
* A tight cycle: `a.ts -> b.ts -> c.ts -> a.ts`.
* A 60-LOC function with cyclomatic 28 and cognitive 34, colocated with a file that has churned 40 times in the last 90 days.

All of that is deterministic. Every finding traces back to a path through the graph.

## What static intelligence cannot see

The graph is a model of the code, not a recording of the program. Some things live below the model:

* **Dynamic dispatch.** Handlers registered by string key, plugins loaded from an array, methods resolved via `obj[name]()`.
* **Conditional imports.** `if (process.env.FOO) { await import("./bar") }` may or may not execute in production.
* **Feature flag branches.** Static sees both branches. It cannot tell you which branch users actually hit this month.
* **Traffic-weighted importance.** A 5-line helper called 200 million times a day and a 5-line helper called once at startup look identical in the graph.
* **Reachable but unused.** A function that is imported and could run, but hasn't been called in 30 days.

Static reachability says "this could run". It does not say "this did run".

## What runtime intelligence adds

Runtime intelligence is the evidence layer. It records which code actually executed, then merges that evidence back into the same analyses you already run:

* **Hot functions.** The functions that carry production traffic. Changes there deserve extra review.
* **Cold functions.** Reachable in the graph, silent in reality. High-confidence candidates for removal.
* **Flag branches observed vs. not observed.** Concrete evidence that a flag is stale, not a guess.
* **Runtime-weighted health.** Complexity alone is a signal, complexity on a hot path is an alarm.

Runtime coverage is the collection mechanism. Runtime intelligence is what you get from it. The CLI surfaces everything through a single flag: `fallow health --runtime-coverage ./.fallow/runtime.json`. See the [runtime coverage analysis page](/analysis/runtime-coverage) for the collection setup.

## Where they meet: fallow health

`fallow health` is the surface where static findings and runtime evidence merge into a single verdict.

Examples:

* A file with cyclomatic complexity 24, dead code ratio 0.7, and zero runtime hits over 30 days. Static alone would call it complex and partly unused. Runtime alone would call it cold. Together, Fallow calls it a confident deletion candidate.
* A function that just dropped from cognitive 12 to cognitive 26 in this PR, sitting on a hot path with 40M calls a day. Static alone would flag the complexity bump. Runtime adds the review escalation.
* A feature flag with both branches statically defined, where only the `true` branch has been observed in 60 days. Static alone would see two branches. Runtime retires the other one.

<Info>
  Runtime evidence never overrides static findings, it refines them. A function with zero runtime hits is still only a candidate if static says it's reachable. An unreferenced export is already dead; runtime cannot make it deader.
</Info>

## Mental model

| Question                            | Answered by           |
| :---------------------------------- | :-------------------- |
| What is connected to what?          | Static                |
| What imports this file?             | Static                |
| What files nothing imports?         | Static                |
| What code changed in this PR?       | Static (graph + diff) |
| What actually ran in production?    | Runtime               |
| Which functions are hot?            | Runtime               |
| Did this branch execute this month? | Runtime               |
| Is this code safe to delete?        | Both                  |
| Does this PR touch hot code?        | Both                  |

## Free vs paid layer

Static intelligence is free and open source (MIT). You can run every static analysis on any project, today, with `npx fallow`. Runtime intelligence is the paid team layer, and `runtime coverage` is the collection engine that feeds it. Pricing, tiers, and what's included at each level live at [fallow.tools/pricing](https://fallow.tools/pricing).

<Tip>
  Start with static. It's free and already cleans up most dead code a typical codebase accumulates. Add runtime once you care about hot-path review, runtime-weighted health, or deletion confidence backed by production evidence.
</Tip>


# Telemetry & privacy
Source: https://docs.fallow.tools/explanations/telemetry

What fallow's opt-in telemetry collects and, more importantly, what it never collects. Off by default, no identifiers, inspect it before you consent.

Fallow telemetry is **opt-in** and **off by default**. It exists to improve agent, CI, JSON, MCP, and editor workflows, not to track individuals or codebases. For the commands and environment controls, see [`fallow telemetry`](/cli/telemetry).

To keep telemetry off everywhere, set `FALLOW_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`. See [Disabling everywhere](#disabling-everywhere).

## What is never collected

Fallow telemetry never includes:

* repository, organization, project, branch, or git remote names
* file paths, import specifiers, source snippets, or stack traces
* package, dependency, workspace, or framework package names
* raw command-line arguments
* config contents or config values
* environment variable names or values
* raw errors, logs, or serialized exceptions
* machine, user, project, or repository identifiers

Hashing these values is not used as a workaround.

The one exception is an anonymous install grouping token: a freshly random value, never derived from your machine, user account, repository, project, file paths, or environment. It is created only when you explicitly opt in (`fallow telemetry enable`, or the first upload after `FALLOW_TELEMETRY=on`), deleted when you run `fallow telemetry disable`, and sent only as a private transport header (`X-Fallow-Install`) for server-side grouping, never as a field inside the event itself. It exists so aggregate dashboards can count distinct workflows per install instead of per run. `fallow telemetry status` reports only whether the token is present, never the token itself.

## Inspect what is sent

Do not take the list on trust. You can print the exact payload any real command would send, without sending it:

```bash theme={null}
FALLOW_TELEMETRY=inspect fallow audit --format json --quiet
```

The payload prints to stderr; your command's normal output is untouched.

## What is collected

When you enable telemetry, Fallow sends one small, high-level event per analysis run:

```json theme={null}
{
  "schema_version": 1,
  "event": "workflow_completed",
  "fallow_version": "3.24.1",
  "workflow": "audit",
  "integration_surface": "mcp",
  "invocation_context": "agent",
  "agent_source": "codex",
  "output_format": "json",
  "quiet": true,
  "ci": false,
  "tty": false,
  "os": "linux",
  "arch": "x86_64",
  "duration_bucket_ms": "500-2000",
  "outcome": "issues_found",
  "exit_code_bucket": "1",
  "findings_present": true,
  "mcp_tool": "find_dupes",
  "parent_run": "tmp_8x7p4k"
}
```

`agent_source`, `findings_present`, `mcp_tool`, and `parent_run` are optional. `agent_source` appears only on agent-driven runs. `findings_present` is omitted by commands that run no analysis (and by older binaries). `mcp_tool` appears only when a run came through the MCP server. `parent_run` appears only when a run is explicitly correlated to a previous one. All are omitted otherwise.

| Field                          | Purpose                                                                                                                                                                                  |
| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow`                     | Prioritize the audit, dead-code, health, duplication, CI, runtime-coverage setup, impact, security, fix, and explain workflows.                                                          |
| `integration_surface`          | Understand whether Fallow is used through human CLI, CLI JSON, MCP, CI, editor, or as a library.                                                                                         |
| `invocation_context`           | Separate human, CI, editor, and agent-driven use without uploading detection evidence.                                                                                                   |
| `agent_source`                 | Improve compatibility with specific agent integrations using a documented allowlist.                                                                                                     |
| `output_format` / `quiet`      | Protect the output contracts that users and agents rely on most.                                                                                                                         |
| `duration_bucket_ms`           | Find slow workflow classes without collecting exact timings.                                                                                                                             |
| `outcome` / `exit_code_bucket` | Measure clean runs, findings, and failures without uploading raw error text.                                                                                                             |
| `findings_present`             | Whether the analysis surfaced any findings, decoupled from the exit-code gate (so informational analyses like default-config `dupes`, which never exits non-zero, are still measurable). |
| `mcp_tool`                     | Attribute MCP usage to a specific tool, from a fixed allowlist of tool names.                                                                                                            |
| `parent_run`                   | Link explicit agent follow-up runs using a short allowlisted token, never a path or free-form string.                                                                                    |

When Fallow runs through the MCP server, the server tags the CLI process it invokes so the single emitted event is attributed to the `mcp` surface and the specific tool, instead of looking like a plain `cli_json` run. Code Mode snippets can make several read-only host calls; those spawned CLI events are attributed to `code_execute`, not to free-form code text or nested helper names. No extra event is sent and the privacy posture is unchanged. The LSP server, editor extension, and library embeddings run in-process and currently emit no telemetry.

The `schema_version` field increments if the collected fields ever change, and this page is updated before any new field ships.

## Agent source

When telemetry is enabled and a run is classified as agent-driven, Fallow may emit one normalized `agent_source` value from a fixed allowlist:

```text theme={null}
none codex claude_code cursor copilot opencode aider roo
windsurf gemini cline continue zed goose other_known unknown
```

`none` appears in the list because it is the internal default before a run is classified, but it is never sent: Fallow only sends `agent_source` for runs it identifies as agent-driven, and those are never `none`. Agents not on the list (for example enterprise IDE assistants) are grouped under `other_known`. Hyphen aliases such as `claude-code`, and CLI aliases such as `gemini_cli` and `antigravity` (both map to `gemini`), are normalized.

Fallow does not upload raw MCP client info, process names, parent process paths, editor or extension identifiers, environment variable names, model names, account or organization IDs, prompts, versions, or free-form vendor strings. Agent wrappers should set `FALLOW_AGENT_SOURCE=<allowlisted-value>`; ambiguous sources emit `unknown`. **Setting `FALLOW_AGENT_SOURCE` never enables telemetry by itself and uploads no codebase content.** When more than one agent environment is present at once, attribution is best-effort and can depend on check order; set `FALLOW_AGENT_SOURCE` to name the agent yourself.

## Transport and server privacy

* requests are HTTPS POST JSON to `https://api.fallow.cloud/v1/telemetry/events` (override the host with `FALLOW_API_URL`)
* no cookies are used and no authentication token is sent
* the upload runs on a background thread, so it does not slow down your command
* Fallow does not wait for the upload, so the fastest runs and runs on slow networks often drop their event; counts are a rough, biased sample, not an exact usage count
* network errors are ignored and never affect command output or exit code
* telemetry is never written to stdout
* server-side handling does not enrich telemetry with customer, repository, organization, git, package-registry, or license data
* IP addresses are dropped or truncated as early as practical
* raw events are retained only for a short window, then deleted

Public reporting uses only coarse aggregate trends after privacy review.

## Disabling everywhere

The `DO_NOT_TRACK` and `FALLOW_TELEMETRY_DISABLED` environment variables are top-precedence kill switches: when either is truthy, telemetry stays off and `fallow telemetry enable` is refused. Use `FALLOW_TELEMETRY_DISABLED=1` as the fleet-wide switch in managed and CI environments.


# Built-in plugins
Source: https://docs.fallow.tools/frameworks/built-in

Built-in plugins for Next.js, Vite, Jest, Tailwind, ESLint, and more. Auto-detected framework conventions for accurate analysis.

Fallow ships with built-in plugins for popular TypeScript and JavaScript tools. Each plugin teaches fallow about framework-specific conventions: entry points, config files, used exports, and tooling dependencies. Analysis is accurate out of the box.

<Info>
  Most plugins activate automatically when the relevant package is in your `package.json`. Some plugins (ESLint, Vitest) also activate when a config file is present in the workspace root, even without the package. This covers monorepos where the tool is installed at the root but workspace packages have their own config files.
</Info>

<Tabs>
  <Tab title="Frameworks">
    | Plugin                  | Enabler packages                                                                                                                     |
    | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
    | **Next.js**             | `next`                                                                                                                               |
    | **Nuxt**                | `nuxt`, `nuxt3`                                                                                                                      |
    | **Remix**               | `@remix-run/dev`                                                                                                                     |
    | **SvelteKit**           | `@sveltejs/kit`                                                                                                                      |
    | **Gatsby**              | `gatsby`                                                                                                                             |
    | **Astro**               | `astro`                                                                                                                              |
    | **Angular**             | `@angular/core`, `ng-packagr`                                                                                                        |
    | **React Router**        | `react-router`, `@react-router/dev`                                                                                                  |
    | **RedwoodSDK**          | `rwsdk` (keeps `src/worker.{ts,tsx,js,jsx,mts,mjs}` reachable in `rwsdk/vite` apps)                                                  |
    | **TanStack Router**     | `@tanstack/react-router`, `@tanstack/start`, `@tanstack/react-start`                                                                 |
    | **React Native**        | `react-native`                                                                                                                       |
    | **Expo**                | `expo`                                                                                                                               |
    | **NestJS**              | `@nestjs/core`                                                                                                                       |
    | **AdonisJS**            | `@adonisjs/core`                                                                                                                     |
    | **Docusaurus**          | `@docusaurus/core`                                                                                                                   |
    | **Nitro**               | `nitropack`                                                                                                                          |
    | **Capacitor**           | `@capacitor/core`, `@capacitor/cli`                                                                                                  |
    | **Sanity**              | `sanity`, `@sanity/`                                                                                                                 |
    | **VitePress**           | `vitepress`                                                                                                                          |
    | **next-intl**           | `next-intl`                                                                                                                          |
    | **Relay**               | `relay-runtime`, `react-relay`, `relay-compiler`                                                                                     |
    | **Electron**            | `electron`, `electron-builder`, `@electron-forge/cli`, `electron-vite`                                                               |
    | **Qwik**                | `@builder.io/qwik`, `@builder.io/qwik-city`, `@qwik.dev/core`, `@qwik.dev/router`                                                    |
    | **i18next**             | `i18next`, `react-i18next`, `vue-i18n`                                                                                               |
    | **Wuchale**             | `wuchale`, `@wuchale/vite-plugin`, or `wuchale.config.js`                                                                            |
    | **Convex**              | `convex`; the safe in-project directory from `convex.json#functions` becomes the functions entry root when configured                |
    | **Lit**                 | `lit`, `lit-element`, `lit-html` (also activates for native Custom Elements without a Lit dependency)                                |
    | **Lexical**             | `lexical`, `@lexical/` (credits custom node lifecycle methods on `DecoratorNode`, `ElementNode`, `TextNode` subclasses)              |
    | **Ember**               | `ember-source`, `ember-cli`, `@embroider/core`, `@glimmer/component`                                                                 |
    | **Expo Router**         | `expo-router`                                                                                                                        |
    | **Supabase**            | `supabase`, or `supabase/config.toml` / `supabase/functions/` present (treats `supabase/functions/*/index.*` as runtime entry roots) |
    | **Content Collections** | `@content-collections/core`, `@content-collections/vite`, `@content-collections/next`                                                |
    | **Contentlayer**        | `contentlayer`, `contentlayer2`, `next-contentlayer`, `next-contentlayer2`, or `contentlayer.config.{ts,js,mts,mjs}` present         |
    | **Fumadocs**            | `fumadocs-mdx`, `fumadocs-core`, `fumadocs-ui`, or `source.config.*` present                                                         |
    | **Mintlify**            | `mint`, `mintlify`, or `docs.json` / `mint.json` present                                                                             |
    | **Velite**              | `velite`, or `velite.config.{ts,mts,cts,js,mjs,cjs}` present                                                                         |
    | **rspress**             | `rspress`, `@rspress/` (credits the `@theme` / `@theme-original` virtual modules)                                                    |
  </Tab>

  <Tab title="Bundlers">
    | Plugin        | Enabler packages     |
    | :------------ | :------------------- |
    | **Vite**      | `vite`               |
    | **Webpack**   | `webpack`            |
    | **Rspack**    | `@rspack/core`       |
    | **Rsbuild**   | `@rsbuild/core`      |
    | **Rollup**    | `rollup`             |
    | **Rolldown**  | `rolldown`           |
    | **Tsup**      | `tsup`               |
    | **Tsdown**    | `tsdown`             |
    | **pkg-utils** | `@sanity/pkg-utils`  |
    | **Parcel**    | `parcel`, `@parcel/` |
  </Tab>

  <Tab title="Testing">
    | Plugin          | Enabler packages                                           |
    | :-------------- | :--------------------------------------------------------- |
    | **Vitest**      | `vitest` or config file present                            |
    | **Jest**        | `jest`                                                     |
    | **Playwright**  | `@playwright/test`                                         |
    | **Cypress**     | `cypress`                                                  |
    | **Mocha**       | `mocha`                                                    |
    | **Ava**         | `ava`                                                      |
    | **tap**         | `tap`                                                      |
    | **tsd**         | `tsd`                                                      |
    | **Storybook**   | `storybook`, `@storybook/react`                            |
    | **Karma**       | `karma`                                                    |
    | **Cucumber**    | `@cucumber/cucumber`                                       |
    | **WebdriverIO** | `webdriverio`, `@wdio/`                                    |
    | **k6**          | `k6`, or `*.k6.{js,ts,mjs,cjs,mts,cts}` files present      |
    | **Stryker**     | `@stryker-mutator/core`, `stryker`, or config file present |
  </Tab>

  <Tab title="Linting & Formatting">
    | Plugin           | Enabler packages                                        |
    | :--------------- | :------------------------------------------------------ |
    | **ESLint**       | `eslint` or config file present                         |
    | **Biome**        | `@biomejs/biome`                                        |
    | **Stylelint**    | `stylelint`                                             |
    | **Prettier**     | `prettier`                                              |
    | **Oxlint**       | `oxlint`                                                |
    | **markdownlint** | `markdownlint`, `markdownlint-cli`, `markdownlint-cli2` |
    | **CSpell**       | `cspell`                                                |
    | **Remark**       | `remark`, `remark-cli`                                  |
  </Tab>

  <Tab title="Transpilation">
    | Plugin         | Enabler packages        |
    | :------------- | :---------------------- |
    | **TypeScript** | `typescript`            |
    | **Babel**      | `@babel/core`           |
    | **SWC**        | `@swc/core`, `@swc/cli` |
  </Tab>

  <Tab title="CSS">
    | Plugin       | Enabler packages      |
    | :----------- | :-------------------- |
    | **Tailwind** | `tailwindcss`         |
    | **PostCSS**  | `postcss`             |
    | **UnoCSS**   | `unocss`, `@unocss/*` |
    | **PandaCSS** | `@pandacss/dev`       |
  </Tab>

  <Tab title="Database">
    | Plugin      | Enabler packages           |
    | :---------- | :------------------------- |
    | **Prisma**  | `prisma`, `@prisma/client` |
    | **Drizzle** | `drizzle-orm`              |
    | **Knex**    | `knex`                     |
    | **TypeORM** | `typeorm`                  |
    | **Kysely**  | `kysely`, `kysely-ctl`     |
  </Tab>

  <Tab title="Monorepo">
    | Plugin         | Enabler packages                                  |
    | :------------- | :------------------------------------------------ |
    | **Turborepo**  | `turbo`                                           |
    | **Nx**         | `nx`                                              |
    | **Changesets** | `@changesets/cli`                                 |
    | **Syncpack**   | `syncpack`                                        |
    | **pnpm**       | `pnpm-workspace.yaml` or `pnpm-lock.yaml` present |
  </Tab>

  <Tab title="CI/CD & Release">
    | Plugin               | Enabler packages   |
    | :------------------- | :----------------- |
    | **semantic-release** | `semantic-release` |
    | **Commitlint**       | `@commitlint/cli`  |
    | **Commitizen**       | `commitizen`       |
    | **Wrangler**         | `wrangler`         |
    | **Sentry**           | `@sentry/cli`      |
    | **Danger**           | `danger`           |
  </Tab>

  <Tab title="Git Hooks">
    | Plugin               | Enabler packages   |
    | :------------------- | :----------------- |
    | **husky**            | `husky`            |
    | **lint-staged**      | `lint-staged`      |
    | **lefthook**         | `lefthook`         |
    | **simple-git-hooks** | `simple-git-hooks` |
  </Tab>

  <Tab title="Other">
    | Plugin                 | Enabler packages                                                                                                             |
    | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
    | **GraphQL Codegen**    | `@graphql-codegen/cli`                                                                                                       |
    | **TypeDoc**            | `typedoc`                                                                                                                    |
    | **openapi-ts**         | `openapi-typescript`                                                                                                         |
    | **Plop**               | `plop`                                                                                                                       |
    | **SVGO**               | `svgo`                                                                                                                       |
    | **SVGR**               | `@svgr/core`, `@svgr/cli`, `@svgr/webpack`                                                                                   |
    | **size-limit**         | `size-limit` (credits `@size-limit/*` and `size-limit-*` presets and plugins)                                                |
    | **c8**                 | `c8`                                                                                                                         |
    | **nyc**                | `nyc`                                                                                                                        |
    | **MSW**                | `msw`                                                                                                                        |
    | **nodemon**            | `nodemon`                                                                                                                    |
    | **PM2**                | `pm2`                                                                                                                        |
    | **dependency-cruiser** | `dependency-cruiser`                                                                                                         |
    | **Hardhat**            | `hardhat`                                                                                                                    |
    | **Bun**                | `bun-types`                                                                                                                  |
    | **OpenCode**           | `opencode.json`, `.opencode/`, or `@opencode-ai/` (credits auto-loaded plugin files and `opencode.json` plugin dependencies) |
  </Tab>
</Tabs>

<Accordion title="Plugins with deep config parsing">
  These plugins go beyond simple package detection. They parse your config files with Oxc's AST parser to extract entry points, dependencies, aliases, and other settings automatically:

  | Plugin           | What it extracts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
  | :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | **ESLint**       | Plugin imports, shared configs, custom rule paths, import resolver packages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | **Vitest**       | Reporters, coverage provider, typecheck checker, browser provider from `vitest.config.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  | **Vite**         | Entry points, `resolve.alias` mappings, plugin imports from `vite.config.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  | **Jest**         | Setup files, transform paths, module mappers from `jest.config.js`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  | **tsd**          | Declaration test directory from `package.json#tsd.directory`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  | **Storybook**    | Story globs, addon imports from `.storybook/main.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | **Tailwind**     | Content paths, plugin imports from `tailwind.config.js`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | **Webpack**      | Entry points including descriptor/context forms, `resolve.alias` mappings, loader/plugin imports from `webpack.config.js`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  | **TypeScript**   | Path aliases, project references from `tsconfig.json`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | **Babel**        | Plugin and preset imports from `babel.config.js`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
  | **Rollup**       | Entry points, plugin imports from `rollup.config.js`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | **Rolldown**     | Entry points, external deps, plugin imports from `rolldown.config.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | **PostCSS**      | Plugin imports from `postcss.config.js`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | **Nuxt**         | Modules, plugins, server routes, `alias`, `imports.dirs`, `components`, `srcDir` from `nuxt.config.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
  | **SvelteKit**    | `kit.alias` mappings, param matchers from `svelte.config.js`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  | **Next.js**      | App Router convention exports (`page`, `layout`, `loading`, `error`, `route`), route segment config, Pages Router exports, middleware, proxy, instrumentation, `mdx-components`, `transpilePackages`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | **Rsbuild**      | Entry points, plugin imports from `rsbuild.config.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | **Remark**       | Plugin imports from `.remarkrc.js`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  | **Angular**      | Styles, scripts, main, polyfills from `angular.json` build targets; ng-packagr `ng-package.json` / `ng-package.prod.json` `lib.entryFile` (default `src/public_api.ts`, resolved relative to the config directory) becomes a library public API entry point, with nested secondary-entry-point configs in the package subtree scanned too; `@Component({ templateUrl, styleUrl })` decorator references create graph edges; standalone `.html` templates and inline `template:` literals both contribute synthetic `<template>` complexity findings (`@if`/`@for`/`@switch`/`@defer`, `*ngIf`, bound attributes, interpolations) suppressible via `<!-- fallow-ignore-file complexity -->` (external) or `// fallow-ignore-next-line complexity` above the `@Component` decorator (inline) |
  | **Nx**           | Executor references, main entry points, tsconfig paths from `project.json`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
  | **Hardhat**      | Plugin imports and side-effect requires from `hardhat.config.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
  | **Contentlayer** | `contentDirPath`, same-file `defineDocumentType` `filePathPattern` entries, and config imports from `contentlayer.config.*`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | **Velite**       | `defineCollection` `pattern` globs joined to the top-level `root` (default `content`), generated `.velite` output, a non-default `output.data` dir, and config imports from `velite.config.*`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  | **UnoCSS**       | Preset and transformer imports from `uno.config.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
  | **Wuchale**      | Adapter imports from `wuchale.config.js`; static custom JavaScript config files referenced from `@wuchale/vite-plugin` in `vite.config.*`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
</Accordion>

<Tip>
  Run `fallow list --plugins` to see which plugins are active in your project.
</Tip>

```bash title="$ fallow list --plugins" theme={null}
Active plugins:
  - nextjs
  - vite
  - vitest
  - playwright
  - storybook
  - eslint
  - typescript
  - tailwind
  - drizzle
```

<Info>
  Don't see your framework? [Custom plugins](/frameworks/custom-plugins) support any internal or third-party tool using declarative JSON or TOML.
</Info>

## See also

<CardGroup>
  <Card title="Custom plugins" icon="screwdriver-wrench" href="/frameworks/custom-plugins">
    Add support for internal frameworks with external plugin files.
  </Card>

  <Card title="fallow list" icon="list" href="/cli/list">
    Inspect active plugins, entry points, and project metadata.
  </Card>
</CardGroup>


# Custom plugins
Source: https://docs.fallow.tools/frameworks/custom-plugins

Create custom fallow plugins for internal frameworks using declarative JSON or TOML files. Define entry points, config files, and used exports.

Create a declarative plugin file for any internal framework or tool fallow doesn't cover. Plugins are JSON or TOML files that tell fallow about your framework's conventions.

<Tip>
  Start with JSONC format for `$schema` support and IDE autocomplete.
</Tip>

## Quick start

<Steps>
  <Step title="Create the plugin file">
    Create a `fallow-plugin-<name>.jsonc` file in your project root:

    ```jsonc theme={null}
    {
      "$schema": "./plugin-schema.json",
      "name": "my-framework",
      "enablers": ["my-framework"],
      "entryPoints": ["src/routes/**/*.{ts,tsx}"],
      "alwaysUsed": ["src/setup.ts"],
      "toolingDependencies": ["my-framework-cli"],
      "usedExports": [
        { "pattern": "src/routes/**/*.{ts,tsx}", "exports": ["default", "loader", "action"] }
      ]
    }
    ```

    Fallow auto-discovers `fallow-plugin-*` files in your project root.
  </Step>

  <Step title="Configure the fields">
    Customize the plugin fields for your framework. Only `name` is required. Add the fields relevant to your use case.

    ### Required

    | Field  | Type   | Description                                           |
    | :----- | :----- | :---------------------------------------------------- |
    | `name` | string | Unique plugin name (shown in `fallow list --plugins`) |

    ### Optional

    | Field                 | Type                  | Description                                                                                                                                                 |
    | :-------------------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `enablers`            | string\[]             | Package names that activate this plugin                                                                                                                     |
    | `entryPoints`         | string\[]             | Glob patterns for entry point files                                                                                                                         |
    | `configPatterns`      | string\[]             | Glob patterns for config files (always-used)                                                                                                                |
    | `alwaysUsed`          | string\[]             | Files always considered used                                                                                                                                |
    | `toolingDependencies` | string\[]             | Packages used via CLI, not imports                                                                                                                          |
    | `detection`           | object                | Rich activation logic (see below)                                                                                                                           |
    | `usedExports`         | object\[]             | Exports always considered used                                                                                                                              |
    | `usedClassMembers`    | (string \| object)\[] | Class method/property names the framework invokes at runtime; scoped objects `{ extends?, implements?, members }` match only classes with matching heritage |
    | `manifestEntries`     | object\[]             | Entry points derived from framework manifest files (see [Manifest-derived entries](#manifest-derived-entries))                                              |
  </Step>

  <Step title="Verify the plugin">
    Confirm fallow picks up your plugin, and (for `manifestEntries`) see exactly what it matched and seeded:

    ```bash theme={null}
    fallow list --plugins            # is the plugin active?
    fallow plugin-check --format json  # what did each rule match, seed, and warn about?
    ```

    `fallow plugin-check` is a read-only dry-run. It reports whether each plugin activated (with the unmet requirement when it did not), and for `manifestEntries` rules the manifests matched, each manifest's `when`-gate result, the entries seeded (with a `path_exists` flag), and typed `warnings[]`. It always exits 0.
  </Step>
</Steps>

## Supported formats

| Format | Extension | Comments         |
| :----- | :-------- | :--------------- |
| JSONC  | `.jsonc`  | `//` and `/* */` |
| JSON   | `.json`   | No               |
| TOML   | `.toml`   | `#`              |

## Detection strategies

Plugins can use simple enablers or rich detection logic with boolean combinators.

<Accordion title="Simple detection (enablers)">
  The simplest way to activate a plugin. Package names are checked against `package.json`. The plugin activates if any enabler matches:

  ```jsonc theme={null}
  {
    "enablers": ["my-framework", "@myorg/"]  // prefix matching with trailing /
  }
  ```

  A trailing `/` enables prefix matching, so `@myorg/` matches any package in the `@myorg` scope.
</Accordion>

<Accordion title="File-based detection">
  Activate a plugin when specific config files exist in the project:

  ```jsonc theme={null}
  {
    "detection": { "type": "fileExists", "pattern": "nuxt.config.*" }
  }
  ```
</Accordion>

<Accordion title="Combined detection (boolean logic)">
  Combine multiple conditions with `all` (AND), `any` (OR), or `not`:

  ```jsonc theme={null}
  {
    "detection": {
      "type": "all",
      "conditions": [
        { "type": "dependency", "package": "@my-org/core" },
        { "type": "fileExists", "pattern": "my-org.config.*" }
      ]
    }
  }
  ```

  This plugin only activates when both `@my-org/core` is installed **and** a `my-org.config.*` file exists.
</Accordion>

## Used exports

Mark specific exports as always-used for convention-based frameworks. These are exports consumed by name at runtime:

```jsonc theme={null}
{
  "usedExports": [
    { "pattern": "src/routes/**/*.{ts,tsx}", "exports": ["default", "loader", "action", "meta"] }
  ]
}
```

## Used class members

Mark class method or property names that the framework invokes at runtime via an interface or contract pattern. Listed names extend fallow's built-in Angular and React lifecycle allowlist, so members implementing these contracts are never flagged as unused class members.

Each entry is either a plain member name (global suppression) or a scoped object that only matches classes whose heritage clause includes the configured `extends` or `implements` identifier:

```jsonc theme={null}
{
  "name": "ag-grid",
  "enablers": ["ag-grid-angular"],
  "usedClassMembers": [
    "agInit",
    { "implements": "ICellRendererAngularComp", "members": ["refresh"] }
  ]
}
```

Plain names like `agInit` are unique enough to suppress globally. Common names like `refresh` or `execute` would produce false negatives on unrelated classes, so scope them with `implements` or `extends`. A scoped rule requires at least one of `extends` or `implements`; an unconstrained object rule is rejected at load time.

This is the right tool for libraries that call methods on consumer classes reflectively: ag-Grid's `AgFrameworkComponent<T>`, TypeORM's `MigrationInterface` (`up`, `down`), Web Components (`connectedCallback`, `disconnectedCallback`, `attributeChangedCallback`), or any strategy/plugin pattern where the library invokes your methods rather than your code doing so directly.

The allowlist only applies to class methods and properties. Enum members with the same names are still checked.

For project-wide allowlists that apply regardless of which packages are installed, use the top-level `usedClassMembers` field in your fallow config instead. See [Configuration overview](/configuration/overview).

## Manifest-derived entries

Some frameworks declare their entry points inside per-package manifest files rather than in `package.json` `main`/`exports` or a single app entry. A large monorepo can have hundreds of these, and the entry file for each is conditional on the manifest's own fields. Static `entryPoints` globs cannot read those fields, so `manifestEntries` lets a plugin derive entries from the manifests themselves.

Each rule finds manifest files by a recursive glob, parses them (JSON or JSONC), and for every manifest that passes the rule's `when` gate, resolves each `entries[].path` **relative to that manifest's directory** into an entry point (using the plugin's `entryPointRole`).

```jsonc theme={null}
// fallow-plugin-kibana.jsonc
{
  "name": "kibana",
  "detection": { "type": "fileExists", "pattern": "**/kibana.jsonc" },
  "entryPointRole": "runtime",
  "manifestEntries": [
    {
      "manifests": "**/kibana.jsonc",   // recursive glob selecting manifests
      "when": { "type": "plugin" },      // only manifests whose `type` is "plugin"
      "entries": [
        { "path": "public/index.{ts,tsx}", "when": { "plugin.browser": true } },
        { "path": "server/index.{ts,tsx}", "when": { "plugin.server": true } },
        { "path": "${plugin.extraPublicDirs}/index.{ts,tsx}" }
      ]
    }
  ]
}
```

| Field       | Type                  | Description                                                                                                                                                            |
| :---------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `manifests` | string                | Recursive glob selecting the manifest files to read                                                                                                                    |
| `format`    | `"jsonc"` \| `"json"` | Manifest format. Defaults to `jsonc`, which also parses plain JSON                                                                                                     |
| `when`      | object                | Manifest-level gate: a map of dotted field path to an expected value. ALL must match by strict equality for the manifest to be processed. Empty matches every manifest |
| `entries`   | object\[]             | The entries to seed per matching manifest (each `{ path, when? }`)                                                                                                     |

**`entries[].path`** is a glob relative to the manifest's directory. It must encode its own extension (`public/index.{ts,tsx}`), because entry-point globs are matched literally against discovered files (there is no source-extension probing). It may contain **`${dotted.field}` interpolation** that fans out over the named manifest field: a string field yields one entry, an array field yields one entry per element, and a missing or empty field yields none. Each entry may carry its own `when` gate.

`when` matching is **strict equality**: `{ "plugin.browser": true }` matches a manifest whose `plugin.browser` is literally `true`, and a manifest with `plugin.browser: false` is skipped for that entry.

<Note>
  Manifest discovery respects `.gitignore` and skips `node_modules`, so manifests under ignored directories are not seen (their entries would not be analyzed anyway). Fallow emits a warning when a `manifests` glob matches nothing, when a `when` gate excludes every manifest, or when a field path resolves in none of the matched manifests (a likely typo). Run `fallow plugin-check --format json` to see, per rule, which manifests matched, which passed the `when` gate, the entries seeded (with `path_exists`), and any warnings; those warnings (`manifests-matched-none`, `when-excluded-all`, `field-path-unresolved`, `entries-empty`, `manifest-parse-failed`, `entry-outside-root`, `seeded-paths-missing`) are the fastest way to debug a rule that seeds nothing.
</Note>

## Discovery order

Fallow searches for plugin files in this order:

1. **Explicit paths** from the `plugins` config field
2. **`.fallow/plugins/`** directory
3. **Project root**: `fallow-plugin-*.{jsonc,json,toml}` files

### Using the `plugins` config field

```jsonc theme={null}
// .fallowrc.json
{
  "plugins": [
    "tools/fallow-plugins/",
    "vendor/my-plugin.jsonc"
  ]
}
```

## Examples

### React Router

```jsonc theme={null}
{
  "$schema": "./plugin-schema.json",
  "name": "react-router",
  "enablers": ["react-router", "@tanstack/react-router"],
  "entryPoints": ["src/routes/**/*.{ts,tsx}", "app/routes/**/*.{ts,tsx}"],
  "configPatterns": ["react-router.config.{ts,js}"],
  "toolingDependencies": ["@react-router/dev"],
  "usedExports": [
    { "pattern": "{src,app}/routes/**/*.{ts,tsx}", "exports": ["default", "loader", "action", "meta", "handle", "shouldRevalidate"] }
  ]
}
```

### Internal tooling

```jsonc theme={null}
{
  "$schema": "./plugin-schema.json",
  "name": "our-build-system",
  "enablers": ["@internal/build"],
  "configPatterns": ["build.config.{ts,js}", ".buildrc"],
  "alwaysUsed": ["scripts/build/**/*.ts", "config/**/*.ts"],
  "toolingDependencies": ["@internal/build", "@internal/lint-rules"]
}
```

<Info>
  External plugins cover most use cases. AST-based config parsing (like the built-in ESLint or Vite plugins do) requires a built-in Rust plugin.
</Info>

## JSON Schema

Generate the schema locally for IDE autocomplete. The schema is generated dynamically and doesn't exist at a remote URL:

```bash theme={null}
fallow plugin-schema > plugin-schema.json
```

Then reference it in your plugin file:

```jsonc theme={null}
{
  "$schema": "./plugin-schema.json"
}
```

## See also

<CardGroup>
  <Card title="Built-in plugins" icon="puzzle-piece" href="/frameworks/built-in">
    Browse the built-in framework and tooling plugins.
  </Card>

  <Card title="fallow list" icon="list" href="/cli/list">
    Verify active plugins and inspect project metadata.
  </Card>
</CardGroup>


# React & Next.js analysis
Source: https://docs.fallow.tools/frameworks/react

Fallow's cross-file React and Next.js analysis: React Server Components directive rules, App Router route checks, component health signals, and what counts as a used component or server action.

React is fallow's largest-ecosystem surface, and Next.js is its most deeply parsed framework. Because fallow builds a whole-project module graph instead of linting one file at a time, it catches React and Next.js problems that per-file tools (`eslint-plugin-react`, `eslint-plugin-next`, `vue-tsc`-style checkers) structurally cannot see: a `"use client"` file exporting a server-only name, two route files that resolve to the same URL, a prop drilled through three components, a server action wired to nothing.

This page consolidates the React and Next.js rules. Each rule has a fuller definition (with severities, suppression syntax, and abstain heuristics) on the [dead-code explanation page](/explanations/dead-code); this page is the React-focused index and cross-links into it.

<Info>
  The Next.js and React rules are dependency-gated. Each one runs only when the relevant package (`next`, or `react` / `react-dom` / `preact`) is a declared dependency, so they never fire on an unrelated project.
</Info>

## React Server Components directive rules

These four rules check the `"use client"` / `"use server"` boundary across the whole project, in the same pass as the rest of dead-code analysis, before a build runs. They run only when `next` is a declared dependency.

### invalid-client-export

A file carrying `"use client"` that also exports a server-only or route-segment-config name (`metadata`, `generateMetadata`, `viewport`, `generateStaticParams`, `dynamic`, `revalidate`, `runtime`, the Pages Router data functions, a route HTTP method handler, and the rest of the reserved set). Next.js rejects these at build time. Fallow catches it statically, and the component's `default` export is never flagged. Default `warn`.

See [invalid client exports](/explanations/dead-code#invalid-client-exports).

### mixed-client-server-barrel

A barrel file (one with at least one `export ... from` re-export) that re-exports both a `"use client"` module and a server-only module. Importing any single name from such a barrel can drag the other origin's directive context across the React Server Components boundary, which surfaces as confusing build or hydration errors far from the barrel. This is a cross-file shape that a single-file linter cannot reason about. The check classifies only direct re-export origins, skips type-only re-exports, and never flags a barrel that merely mixes a client module with an ordinary utility. Default `warn`.

See [mixed client/server barrels](/explanations/dead-code#mixed-client-server-barrels).

### misplaced-directive

A `"use client"` or `"use server"` directive written below an import (or any other statement) instead of in the file's leading prologue. Once any statement precedes it, the bundler treats the string as an ordinary expression and silently ignores it, so a file you intended as a client component is treated as a server module. Nothing errors, which is what makes it dangerous. The fix is always to move the directive above every `import`. Default `warn`.

See [misplaced directives](/explanations/dead-code#misplaced-directives).

### unused-server-action

A Next.js Server Action (an export of a `"use server"` file) that no code in the project references: no import-and-call, no `action={fn}` binding, no `<form action={fn}>`. This is the cross-graph "exported but wired to nothing" direction where dead actions accumulate as a page is refactored, and `eslint-plugin-next` cannot see it because it is single-file. It is a more specific re-classification of `unused-export` for `"use server"` files, reusing fallow's whole-project reference graph, so prop forwarding and wrapped action factories (`withAuditLogging(...)`) are credited as real uses. Default `warn`.

<Note>
  Because this reclassifies a subset of `unused-export` (default `error`) into `unused-server-action` (default `warn`), a dead action that previously failed CI as `unused-export` now reports as a warning. Set `unused-server-action: "error"` to keep failing on it, and re-save any baseline snapshot once.
</Note>

See [unused server actions](/explanations/dead-code#unused-server-actions).

## Next.js App Router route rules

Both route rules are pure path arithmetic over your App Router tree (so there is no heuristic to misfire), are scoped per app-root using your workspace package roots (so a monorepo with several independent Next apps sharing a path is not flagged), and run only when `next` is a declared dependency. Route groups `(name)` are transparent to the URL, parallel slots `@name` fork the position, and intercepting markers / private `_folders` are excluded.

### route-collision

Two or more App Router route files (a `page` or a `route` handler) that resolve to the same URL within one app-root. Because route groups and parallel slots do not change the URL, `app/(marketing)/about/page.tsx` and `app/(shop)/about/page.tsx` both own `/about`. Next.js fails the build here, but it names only one colliding file and aborts; fallow surfaces every colliding file at once, before the build. Default `error`, because it mirrors a `next build` failure: a project hitting it was already red.

See [route collisions](/explanations/dead-code#route-collisions).

### dynamic-segment-name-conflict

Two or more sibling dynamic route segments at the same tree position using different param spellings (`[id]` vs `[slug]`, or a catch-all `[...x]` vs an optional catch-all `[[...x]]`). Next.js throws "You cannot use different slug names for the same dynamic path" at runtime when the position is hit.

<Warning>
  `next build` does NOT catch this. The build succeeds and CI stays green, then the route crashes the first time it is requested. Fallow's static catch is the only gate that fails on it, which is why it defaults to `error`.
</Warning>

See [dynamic segment name conflicts](/explanations/dead-code#dynamic-segment-name-conflicts).

## React component health

The component-health signals look at React and Preact components as a graph: how many places render a component, whether a prop is dead inside a live component, and whether a component is pure structural indirection. Three of these are opt-in and default to `off`; the prop and fan-in signals are on by default.

### Component render fan-in

Fan-in is the number of files that import a given file, and it doubles as a component blast-radius metric: a component rendered in many places is high fan-in, so any change to it ripples widely. Fallow already computes fan-in for every file as part of its health analysis, surfaces it in hotspot and refactoring-target output, and feeds high fan-in into the coupling penalty in the health score.

See [fan-in / fan-out](/explanations/health) on the health page for how the metric is computed and where the effective threshold comes from.

### unused-component-prop (React arm)

A prop that is destructured from a component's first parameter and read nowhere in the component body. This is the in-component dead-input direction on a live component: the component is rendered, but one of its declared props is wired to nothing. `unused-component-prop` shares one rule key across frameworks; the React / Preact arm is dep-gated on `react` / `react-dom` / `next` / `preact`, covers inline-destructured literal props, and stays false-positive-safe by abstaining on rest spread (`{...rest}`), props forwarded by spread, props passed wholesale to a hook, a `forwardRef` / `memo` component whose props come from an imported interface, and exported public-API component props. Default `warn`.

See [unused component props](/explanations/dead-code#unused-component-props).

### prop-drilling (opt-in, default off)

A prop forwarded unused through two or more intermediate components before a component finally consumes it. "Forwarded unused" means an intermediate reads the prop only as the root of a child-JSX attribute value (`<Child userName={user.name} />` passes `user` straight through), never substantively. This is a cross-file graph signal that per-file linters structurally cannot see. When enabled it reports one located chain per drilled prop (the owning source, each pass-through hop, and the consumer, each with file, line, and component name) and abstains whenever it cannot prove a clean pass-through: any `{...props}` / `{...rest}` spread, a `cloneElement`, a component passed as a prop / render prop / function-as-children, a matching context `*.Provider` in the subtree, or any dynamic hop. Off by default.

<Note>
  Enable with `prop-drilling: "warn"` (or `"error"`) under `rules`. When enabled it also contributes a small, capped penalty to the health score (one point per chain, capped at five); with the rule off the health score is unchanged.
</Note>

See [prop drilling](/explanations/dead-code#prop-drilling).

### thin-wrapper (opt-in, default off)

A component whose entire body is `return <Child {...props} />`: it renders a single child, forwards all props through a spread, and adds no markup, no hooks, and no logic of its own. It is pure structural indirection that every call site could render directly. It abstains on intentional indirection: a `forwardRef` / `memo` wrapper, an exported (public-API) component, a context-provider wrapper, a `cloneElement`, a render-prop / function-as-children, or any wrapper whose body is more than the single spread-forwarded child. Off by default; enable with `thin-wrapper: "warn"` (or `"error"`) under `rules`.

See [thin wrapper](/explanations/dead-code#thin-wrapper).

### duplicate-prop-shape (opt-in, default off)

Three or more components, across two or more files, that declare an identical set of prop names, suggesting a shared `Props` type (or a base component) should be extracted. It stays noise-free by requiring an exact full-set match, a minimum of four significant prop names after stripping ubiquitous DOM-passthrough names (`id`, `className`, `children`, `style`, ...), and at least three components in at least two files, so two buttons that merely share `{label, onClick}` are never grouped. Off by default; enable with `duplicate-prop-shape: "warn"` (or `"error"`) under `rules`.

See [duplicate prop shape](/explanations/dead-code#duplicate-prop-shape).

<Info>
  `prop-drilling`, `thin-wrapper`, and `duplicate-prop-shape` all default to `off`. Enable the ones you want under [`rules`](/configuration/rules):

  ```jsonc .fallowrc.json theme={null}
  {
    "rules": {
      "prop-drilling": "warn",
      "thin-wrapper": "warn",
      "duplicate-prop-shape": "warn"
    }
  }
  ```
</Info>

## Reachability: what counts as used

A correctly wired-up component or server action is never flagged, because fallow's framework plugins credit the conventions each router uses to reach code. Coverage includes:

* **Next.js App Router**: convention exports (`page`, `layout`, `loading`, `error`, `route`, and the metadata files), route segment config, `middleware`, `proxy`, and `instrumentation` are credited as entry points.
* **Next.js Pages Router**: any file under `pages/`, plus the data functions Next consumes by name (`getStaticProps`, `getServerSideProps`, `getStaticPaths`).
* **Server-action bindings**: `action={fn}`, `<form action={fn}>`, plain import-and-call, component-prop forwarding, and wrapped action factories all count as real uses of a `"use server"` export.
* **React Router** (`react-router`, `@react-router/dev`), **Remix** (`@remix-run/dev`), and **TanStack Router** (`@tanstack/react-router`, `@tanstack/start`, `@tanstack/react-start`): their route conventions are recognized so route modules are not flagged as unused.

Because these conventions are credited automatically, the component and server-action rules only fire on genuinely orphaned code. See [built-in plugins](/frameworks/built-in) for the full enabler-package list and what each plugin extracts, and run `fallow list --plugins` to see which are active in your project.

<Info>
  Don't see a convention credited? Add the file to [`entry`](/configuration/overview) or write a [custom plugin](/frameworks/custom-plugins). Verify any specific finding with `fallow dead-code --trace <file>:<symbol>` before acting on it.
</Info>

## See also

<CardGroup>
  <Card title="Dead code explained" icon="skull-crossbones" href="/explanations/dead-code">
    Full definitions, severities, and suppression syntax for every rule above.
  </Card>

  <Card title="Rules & severity" icon="scale-balanced" href="/configuration/rules">
    Set each rule to error, warn, or off, and enable the opt-in component signals.
  </Card>

  <Card title="Built-in plugins" icon="puzzle-piece" href="/frameworks/built-in">
    Auto-detected enabler packages for Next.js, React Router, Remix, and TanStack Router.
  </Card>

  <Card title="Health explained" icon="chart-line" href="/explanations/health">
    Fan-in, blast radius, and the coupling penalty in the health score.
  </Card>
</CardGroup>


# Fallow documentation
Source: https://docs.fallow.tools/index

Get started with Fallow: codebase intelligence for TypeScript and JavaScript. Free static analysis of code and styles: unused code, duplication, complexity, architecture drift, and design-system consistency. Optional runtime intelligence for hot paths, cold paths, and deletion confidence.

Fallow is **codebase intelligence for TypeScript and JavaScript**.

Use the static layer to find unused code, duplication, complexity hotspots, architecture drift, design-system styling drift, and feature-flag branches across your module graph. Add the optional runtime layer when you want to know what actually executed in production.

## Start here

<Steps>
  <Step title="Run Fallow without installing">
    ```bash theme={null}
    npx fallow
    ```

    No config needed for the first run.
  </Step>

  <Step title="Read the results">
    Dead code, duplication, complexity, and styling, in one pass.
  </Step>

  <Step title="Go deeper">
    ```bash theme={null}
    npx fallow dead-code
    npx fallow dupes
    npx fallow health
    npx fallow fix --dry-run
    ```
  </Step>
</Steps>

## What Fallow helps you do

<CardGroup>
  <Card title="Delete cold code" icon="trash" href="/analysis/dead-code">
    Remove unused files, exports, and dependencies with confidence.
  </Card>

  <Card title="Reduce duplication" icon="clone" href="/analysis/duplication">
    Find repeated logic before it spreads.
  </Card>

  <Card title="Prioritize refactors" icon="fire" href="/explanations/health">
    Use complexity and health analysis to focus cleanup work.
  </Card>

  <Card title="Add TypeScript evidence" icon="code" href="/analysis/type-aware">
    Confirm exact symbol use, class contracts, affected files, and targeted tests.
  </Card>

  <Card title="Add runtime evidence" icon="chart-network" href="/analysis/runtime-coverage">
    See hot paths, cold paths, and runtime-backed deletion evidence.
  </Card>
</CardGroup>

## Pick your workflow

<CardGroup>
  <Card title="CLI" icon="terminal" href="/quickstart">
    Best place to start. Works locally, in CI, and in agent loops.
  </Card>

  <Card title="VS Code" icon="window" href="/integrations/vscode">
    Real-time diagnostics, Code Lens, and one-click fixes in the editor.
  </Card>

  <Card title="MCP and agents" icon="robot" href="/integrations/mcp">
    Structured tool calling for Claude Code, Cursor, and other agents.
  </Card>
</CardGroup>

## Understand the two layers

Static analysis answers: **what is connected to what?**

Runtime intelligence answers: **what actually ran?**

They meet in `fallow health`.

<Card title="Static vs runtime intelligence" icon="book-open" href="/explanations/static-vs-runtime">
  Read the mental model before you set up runtime collection.
</Card>

## Most-used pages

<CardGroup>
  <Card title="Quick start" icon="rocket" href="/quickstart" />

  <Card title="Configuration" icon="gear" href="/configuration/overview" />

  <Card title="CI integration" icon="shield-check" href="/integrations/ci" />

  <Card title="CLI reference" icon="terminal" href="/cli/dead-code" />
</CardGroup>


# Installation
Source: https://docs.fallow.tools/installation

Install fallow via npx, npm, pnpm, yarn, cargo, Docker, or a prebuilt binary. Binaries for macOS, Linux, and Windows.

The fastest way to try Fallow is to run it directly:

```bash theme={null}
npx fallow
```

If you use Fallow often, install it globally.

<Tabs>
  <Tab title="npm (recommended)">
    Prebuilt binaries for macOS, Linux, and Windows. No Rust toolchain required.

    ```bash theme={null}
    npm install -g fallow
    ```

    <Tip>
      The npm package uses `optionalDependencies` to download the correct platform binary automatically.
    </Tip>
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add -g fallow
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn global add fallow
    ```
  </Tab>

  <Tab title="Cargo">
    Use this if you already have a Rust toolchain.

    ```bash theme={null}
    cargo install fallow-cli
    ```
  </Tab>

  <Tab title="Docker">
    Use this when you want to run fallow without installing Node.js, npm, or Rust on the host.

    ```bash theme={null}
    docker build -t fallow:local https://github.com/fallow-rs/fallow.git#main
    docker run --rm -v "$PWD:/workspace" --user "$(id -u):$(id -g)" fallow:local audit --format json --quiet
    ```

    The image runs fallow as a one-shot CLI against `/workspace`. The `--user` mapping keeps `.fallow/` caches and generated reports owned by your host user, and it lets `fallow audit` use git base detection without Git's dubious-ownership guard blocking the mounted repository. The image includes git, Node.js, npm, and Corepack; fallow does not install your project dependencies automatically.

    For Compose, copy [`examples/docker/compose.yaml`](https://github.com/fallow-rs/fallow/blob/main/examples/docker/compose.yaml) into the target project after building the image, then run:

    ```bash theme={null}
    docker compose run --rm fallow audit --format json --quiet
    ```

    <Warning>
      Fallow is a one-shot CLI, not a long-running service. In Portainer or other stack tools, use a one-shot run command instead of deploying it as an always-on service, or override the command for an interactive shell. Container exit codes are the fallow process exit codes, so CI can gate on the `docker run` or `docker compose run` result directly.
    </Warning>

    On Linux and WSL the commands above work as written. On Windows outside WSL, pass an absolute project path accepted by Docker Desktop and keep the mounted working directory at `/workspace`. For containerized runtime coverage inventory, pass the container path prefix so inventory paths match what the runtime beacon reports:

    ```bash theme={null}
    docker run --rm -v "$PWD:/workspace" --user "$(id -u):$(id -g)" fallow:local coverage upload-inventory --path-prefix /workspace --format json --quiet
    ```
  </Tab>

  <Tab title="Binary download">
    Download prebuilt binaries from [GitHub Releases](https://github.com/fallow-rs/fallow/releases).

    | Target                                     | Platform            |
    | :----------------------------------------- | :------------------ |
    | `fallow-aarch64-apple-darwin.tar.gz`       | macOS Apple Silicon |
    | `fallow-x86_64-apple-darwin.tar.gz`        | macOS Intel         |
    | `fallow-x86_64-unknown-linux-gnu.tar.gz`   | Linux x64 (glibc)   |
    | `fallow-aarch64-unknown-linux-gnu.tar.gz`  | Linux ARM64 (glibc) |
    | `fallow-x86_64-unknown-linux-musl.tar.gz`  | Linux x64 (musl)    |
    | `fallow-aarch64-unknown-linux-musl.tar.gz` | Linux ARM64 (musl)  |
    | `fallow-x86_64-pc-windows-msvc.zip`        | Windows x64         |
  </Tab>
</Tabs>

## Verify

```bash theme={null}
fallow --version
```

<Check>
  If you see a version number, you're all set.
</Check>

## Next step

Go to the [Quick start](/quickstart) and run your first analysis.


# Agent Skills
Source: https://docs.fallow.tools/integrations/agent-skills

Install fallow analysis skills for Claude Code, Cursor, Windsurf, Gemini CLI, and other AI agents that support the Agent Skills specification.

Agent skills give AI coding agents structured knowledge about how to use fallow. Skills cover when to run each command, what flags to use, how to read the output, and how to avoid common pitfalls. Instead of relying on the agent's general knowledge, skills provide precise, up-to-date instructions for codebase health, cleanup analysis, circular dependency detection, duplication, and complexity hotspots.

<Info>
  Skills work alongside the CLI and MCP integrations. They tell agents *how* to use fallow effectively, while the CLI and MCP provide the *tools* to do it.
</Info>

## What's included

The [fallow-skills](https://github.com/fallow-rs/fallow-skills) package includes:

| Component             | Description                                                                                      |
| :-------------------- | :----------------------------------------------------------------------------------------------- |
| **Analysis skill**    | Workflows for unused code, duplication, complexity, boundary analysis, auto-fix, and CI setup    |
| **CLI reference**     | Complete command specs, flags, output formats, and configuration                                 |
| **Gotchas**           | Common pitfalls with correct vs. incorrect examples (e.g., `fix --yes` in non-TTY)               |
| **Workflow patterns** | Recipes for CI pipelines, monorepo analysis, migrating from knip/jscpd, and incremental adoption |

## Installation

<Tip>
  A project that already has fallow installed from npm can skip the manual steps: [`fallow agent install`](/cli/agent) writes the skill where Claude Code, Codex, and Cursor look for it, together with the MCP registration, an `AGENTS.md` task map, and the commit/push gate. `--dry-run` shows the plan first.
</Tip>

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    /plugin marketplace add fallow-rs/fallow-skills
    /plugin install fallow-skills@fallow-rs/fallow-skills
    ```
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git ~/.cursor/skills/fallow-skills
    ```
  </Tab>

  <Tab title="OpenAI Codex">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git ~/.agents/skills/fallow-skills
    ```
  </Tab>

  <Tab title="Windsurf">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git ~/.codeium/windsurf/skills/fallow-skills
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git .github/skills/fallow-skills
    ```
  </Tab>

  <Tab title="Gemini CLI">
    ```bash theme={null}
    gemini skills install https://github.com/fallow-rs/fallow-skills.git
    ```
  </Tab>

  <Tab title="Amp">
    ```bash theme={null}
    git clone https://github.com/fallow-rs/fallow-skills.git ~/.config/agents/skills/fallow-skills
    ```
  </Tab>
</Tabs>

Skills follow the open [Agent Skills](https://agentskills.io) specification and work with any compatible agent.

## What agents can do after installation

Once installed, agents know how to respond to natural language requests like these:

<CardGroup>
  <Card title="Find cleanup opportunities" icon="broom">
    "Find all unused exports in this project". Agent runs `fallow dead-code --format json --quiet --unused-exports` and summarizes findings.
  </Card>

  <Card title="Clean up dependencies" icon="box-open">
    "Are there any unused dependencies?" Agent runs targeted analysis and suggests removals.
  </Card>

  <Card title="Detect duplication" icon="copy">
    "Find code duplication in the codebase". Agent runs `fallow dupes` with the right mode and interprets clone families.
  </Card>

  <Card title="Auto-fix" icon="wrench">
    "Remove unused exports". Agent runs dry-run first, shows proposed changes, then applies with `--yes`.
  </Card>

  <Card title="CI setup" icon="shield-check">
    "Set up a code quality gate in CI". Agent generates the correct GitHub Actions workflow with baselines.
  </Card>

  <Card title="Debug false positives" icon="bug">
    "Why is this export flagged?" Agent uses `--trace` to investigate and suggests suppression if needed.
  </Card>
</CardGroup>

## Skills vs MCP vs CLI

|                      | Skills                                | MCP                                    | CLI                                |
| :------------------- | :------------------------------------ | :------------------------------------- | :--------------------------------- |
| **What it provides** | Knowledge about *how* to use fallow   | Structured tool interface              | Direct command execution           |
| **Setup**            | One-time install per agent            | MCP server configuration               | fallow binary in PATH              |
| **Agent support**    | Any agent with skill support          | Agents with MCP support                | Any agent that runs shell commands |
| **Best for**         | Teaching agents fallow best practices | Typed tool calling in agent frameworks | Universal compatibility            |

<Tip>
  For the best experience, combine all three. Install the skill for knowledge, configure MCP for structured tool calling, and keep fallow in PATH for CLI fallback.
</Tip>

## See also

<CardGroup>
  <Card title="Agent integration" icon="robot" href="/integrations/mcp">
    CLI and MCP integration for AI agents.
  </Card>

  <Card title="Adopt Fallow in an existing repo" icon="rocket" href="/adoption#8-clean-up-with-an-agent">
    The agent-driven cleanup workflow and copy-paste prompt.
  </Card>

  <Card title="CI integration" icon="shield-check" href="/integrations/ci">
    Catch codebase issues in your CI pipeline.
  </Card>

  <Card title="VS Code extension" icon="window" href="/integrations/vscode">
    Real-time feedback for human developers.
  </Card>
</CardGroup>


# Health badges
Source: https://docs.fallow.tools/integrations/badges

Add a shields.io-compatible health badge to your README showing your project's health score and letter grade.

Add a health badge to your README to show your project's code health at a glance.

```bash theme={null}
fallow health --format badge > badge.svg
```

The badge displays the letter grade and numeric score in shields.io flat style:

<div>
  <img alt="zod: B (71)" />

  <img alt="preact: B (76)" />

  <img alt="svelte: B (73)" />

  <img alt="vite: C (65)" />
</div>

Grades: **A** (≥85, green) · **B** (70–84, green) · **C** (55–69, yellow) · **D** (40–54, orange) · **F** (\<40, red).

## Hosting the badge

The SVG needs a stable URL for your README to reference. Three options, from simplest to most reliable. Options 2 and 3 render only for public repositories; see [Private repositories](#private-repositories).

### Option 1: Commit to your repo

Generate the badge and commit it directly:

```bash theme={null}
fallow health --format badge > .github/badges/health.svg
git add .github/badges/health.svg
git commit -m "chore: update health badge"
```

Then reference it in your README:

```markdown theme={null}
![fallow health](.github/badges/health.svg)
```

This is the simplest approach but the badge only updates when you regenerate and commit.

### Option 2: Publish from CI (recommended)

Add a step to your CI workflow that generates the badge and publishes it to a `badges` branch:

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    - name: Generate health badge
      run: fallow health --format badge > badge.svg

    - name: Publish badge
      uses: peaceiris/actions-gh-pages@v4
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: .
        publish_branch: badges
        keep_files: true
        include_files: badge.svg
    ```

    Then reference the badge from the `badges` branch:

    ```markdown theme={null}
    ![fallow health](https://raw.githubusercontent.com/your-org/your-repo/badges/badge.svg)
    ```
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    health-badge:
      stage: deploy
      script:
        - fallow health --format badge > badge.svg
      artifacts:
        paths:
          - badge.svg
    ```

    Use GitLab's [badge API](https://docs.gitlab.com/ee/user/project/badges.html) to link the artifact.
  </Tab>
</Tabs>

### Option 3: Shields.io endpoint

If you prefer dynamic badges via shields.io, generate a JSON endpoint file instead:

```bash theme={null}
fallow health --format json --score --quiet 2>/dev/null \
  | jq '{schemaVersion: 1, label: "fallow", message: "\(.health_score.grade) (\(.health_score.score | floor))", color: (if .health_score.score >= 85 then "brightgreen" elif .health_score.score >= 70 then "green" elif .health_score.score >= 55 then "yellow" elif .health_score.score >= 40 then "orange" else "red" end)}' \
  > health-badge.json
```

Host the JSON file (e.g., in a Gist or on the `badges` branch) and use the shields.io endpoint badge:

```markdown theme={null}
![fallow health](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/your-org/your-repo/badges/health-badge.json)
```

This keeps the badge rendering on shields.io's CDN and always shows the latest score.

## Private repositories

`raw.githubusercontent.com` (Option 2) and the shields.io endpoint (Option 3) only render for **public** repositories. Both hosts serve raw content with no access to private repos, so the badge shows as a broken image. Putting a personal access token in the URL is insecure and against GitHub's terms, so avoid that.

For a private repo, commit the badge into the repository and reference it with a **relative link**. GitHub renders relative image links for any viewer with read access to the repo:

```markdown theme={null}
![fallow health](.github/badges/health.svg)
```

To keep it fresh from CI, regenerate the badge and commit it back to a tracked path on your default branch instead of publishing to a separate `badges` branch:

```yaml theme={null}
- name: Update health badge
  run: |
    fallow health --format badge > .github/badges/health.svg
    git config user.name "github-actions[bot]"
    git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
    git add .github/badges/health.svg
    git diff --quiet --cached || git commit -m "chore: update health badge [skip ci]"
    git push
```

The job needs `permissions: contents: write`. A relative link resolves against the branch the README is viewed on, so the badge has to live on that branch: a separate orphan `badges` branch (Option 2) cannot be reached by a relative link, which is why private repos commit the badge directly.

## Monorepo badges

For workspace packages, scope the badge with `--workspace`:

```bash theme={null}
fallow health --format badge --workspace my-package > badges/my-package.svg
```

## Technical details

* Self-contained SVG with embedded Verdana font metrics. No external requests
* Unique element IDs per badge, so you can inline multiple badges on one page
* `--format badge` automatically enables `--score` (no need to pass both)
* Exit code 2 with an error message if the score cannot be computed
* Also available via the `FALLOW_FORMAT=badge` environment variable


# CI integration
Source: https://docs.fallow.tools/integrations/ci

Run fallow in CI with GitHub Actions or GitLab CI to catch changed-code risk, cleanup opportunities, duplication, and complexity hotspots on every push and PR. Supports SARIF upload, Code Quality reports, rich MR comments, inline review with suggestions, and baseline diffing.

CI catches changed-code risk, cleanup opportunities, duplication, and complexity issues that get past agent workflows and editor review.

<Tip>
  For TypeScript rollout, start with type-aware analysis in `best-effort` mode
  and inspect `_meta.type_aware` in JSON output. Switch to `complete` only when
  partial or unavailable semantic evidence must fail the job. Type-aware
  analysis adds a slower semantic pass. See
  [Type-aware TypeScript analysis](/analysis/type-aware).
</Tip>

<Tabs>
  <Tab title="GitHub Action">
    <Steps>
      <Step title="Add the action">
        Add fallow to your workflow file:

        ```yaml theme={null}
        name: Fallow analysis
        on: [push, pull_request]

        jobs:
          fallow:
            runs-on: ubuntu-latest
            steps:
              - uses: actions/checkout@v4
              - uses: fallow-rs/fallow@v3
                with:
                  format: sarif
        ```

        This runs all analyses (dead code + duplication + complexity) by default. Use the `command` input to run a specific analysis.

        <Note>
          When you enable `comment: true` or `review-comments: true`, grant the
          job `contents: read`, `id-token: write`, `pull-requests: write`, and
          `checks: write`. The identity permission lets the Action obtain a
          short-lived Fallow GitHub App token, so feedback is authored by
          `fallow-cloud[bot]`. Without `id-token: write`, analysis and posting
          continue with `github-actions[bot]`.
        </Note>

        ```yaml theme={null}
        permissions:
          contents: read
          id-token: write
          pull-requests: write
          checks: write
        ```
      </Step>

      <Step title="Configure inputs">
        Customize the action with these inputs:

        | Input                                                       | Default                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |        |                                                                                                     |
        | :---------------------------------------------------------- | :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
        | `command`                                                   | -- (all)                   | Command to run (`dead-code`, `dupes`, `health`, `audit`, `security`, `fix`, or empty for all). Legacy alias: `check` = `dead-code`.                                                                                                                                                                                                                                                                                                                                                                                      |        |                                                                                                     |
        | `root`                                                      | `.`                        | Project root directory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |        |                                                                                                     |
        | `config`                                                    | --                         | Path to config file (`.fallowrc.json`, `.fallowrc.jsonc`, `fallow.toml`, or `.fallow.toml`)                                                                                                                                                                                                                                                                                                                                                                                                                              |        |                                                                                                     |
        | `format`                                                    | `sarif`                    | Output format                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |        |                                                                                                     |
        | `production`                                                | `false`                    | Enable production mode for every analysis                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |        |                                                                                                     |
        | `production-dead-code`                                      | `false`                    | Combined mode only: per-analysis production mode for dead-code                                                                                                                                                                                                                                                                                                                                                                                                                                                           |        |                                                                                                     |
        | `production-health`                                         | `false`                    | Combined mode only: per-analysis production mode for health                                                                                                                                                                                                                                                                                                                                                                                                                                                              |        |                                                                                                     |
        | `production-dupes`                                          | `false`                    | Combined mode only: per-analysis production mode for duplication                                                                                                                                                                                                                                                                                                                                                                                                                                                         |        |                                                                                                     |
        | `fail-on-issues`                                            | `true`                     | Exit with code 1 if issues are found                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |        |                                                                                                     |
        | `changed-since`                                             | --                         | Only check files changed since this ref                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |        |                                                                                                     |
        | `auto-changed-since`                                        | `true`                     | Automatically scope to changed files in PR context using base SHA. Ignored when `changed-since` is set.                                                                                                                                                                                                                                                                                                                                                                                                                  |        |                                                                                                     |
        | `baseline`                                                  | --                         | Path to baseline file for comparison. Rejected with exit 2 when `command: audit`; use `dead-code-baseline` / `health-baseline` / `dupes-baseline` instead.                                                                                                                                                                                                                                                                                                                                                               |        |                                                                                                     |
        | `save-baseline`                                             | --                         | Save current results as a baseline file. Rejected with exit 2 when `command: audit` (audit runs three analyses with incompatible baseline formats).                                                                                                                                                                                                                                                                                                                                                                      |        |                                                                                                     |
        | `version`                                                   | --                         | Fallow version override. When omitted, the action uses the project `package.json` `fallow` dependency spec if present, otherwise `latest`. The Action ref and the fallow CLI version are independent: `uses: fallow-rs/fallow@v3` selects the Action wrapper code only, while the installed CLI resolves from this input, then the project `package.json` `fallow` dependency, then `latest`.                                                                                                                            |        |                                                                                                     |
        | `workspace`                                                 | --                         | Scope output to one or more workspaces (exact names, globs, `!` negation; comma-separated)                                                                                                                                                                                                                                                                                                                                                                                                                               |        |                                                                                                     |
        | `changed-workspaces`                                        | --                         | Git-derived monorepo scoping: scope to workspaces containing any file changed since `REF` (e.g. `origin/main`). Requires `fetch-depth: 0`. Mutually exclusive with `workspace`. A missing ref is a hard error (exit 2) rather than silent full-scope fallback.                                                                                                                                                                                                                                                           |        |                                                                                                     |
        | `comment`                                                   | `false`                    | Post results as a PR comment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |        |                                                                                                     |
        | `review-comments`                                           | `false`                    | Post inline PR review comments with typed `review-github` output and reconcile resolved threads on later runs                                                                                                                                                                                                                                                                                                                                                                                                            |        |                                                                                                     |
        | `review-guidance`                                           | `false`                    | Add collapsed "What to do" guidance blocks to inline PR review comments. Requires `review-comments: true`                                                                                                                                                                                                                                                                                                                                                                                                                |        |                                                                                                     |
        | `review-id`                                                 | --                         | Stable identifier (1-64 characters, `A-Za-z0-9._-`) that isolates inline review comments when multiple fallow review jobs target the same pull request. See [Isolating parallel review jobs](#isolating-parallel-review-jobs).                                                                                                                                                                                                                                                                                           |        |                                                                                                     |
        | `annotations`                                               | `true`                     | Emit findings as inline PR annotations via workflow commands (no Advanced Security required). On fallow >= 3.4.2 the action renders these natively via `fallow report --format github-annotations`; older binaries fall back to the bundled jq renderers, and `version: latest` users flip to the native path silently. The step log line `fallow: annotations rendered via native github-annotations` (or `via jq fallback`) tells you which renderer ran. The job summary follows the same rule with `github-summary`. |        |                                                                                                     |
        | `max-annotations`                                           | `50`                       | Maximum number of inline annotations to emit. On the native path the cap is applied to the rendered stream (GitHub itself displays at most 10 annotations per type per step).                                                                                                                                                                                                                                                                                                                                            |        |                                                                                                     |
        | `github-token`                                              | `${{ github.token }}`      | GitHub token for PR comments and SARIF upload                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |        |                                                                                                     |
        | `branded-token`                                             | `true`                     | Use a short-lived Fallow GitHub App token for comments and reviews when the workflow grants `id-token: write`. Falls back to `github-token` when unavailable.                                                                                                                                                                                                                                                                                                                                                            |        |                                                                                                     |
        | `broker-url`                                                | `https://api.fallow.cloud` | Fallow token broker used to exchange the workflow identity for the branded app token.                                                                                                                                                                                                                                                                                                                                                                                                                                    |        |                                                                                                     |
        | `dupes-mode`                                                | `mild`                     | Detection mode for dupes command                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |        |                                                                                                     |
        | `min-tokens`                                                | --                         | Minimum token count for a clone (dupes command)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |        |                                                                                                     |
        | `min-lines`                                                 | --                         | Minimum line count for a clone (dupes command)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |        |                                                                                                     |
        | `threshold`                                                 | --                         | Fail if duplication exceeds this % (dupes command)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |        |                                                                                                     |
        | `skip-local`                                                | `false`                    | Only report cross-directory duplicates (dupes command)                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |        |                                                                                                     |
        | `score`                                                     | `false`                    | Compute health score (0-100 with letter grade). Enables the health delta header in PR comments (health and bare command)                                                                                                                                                                                                                                                                                                                                                                                                 |        |                                                                                                     |
        | `trend`                                                     | `false`                    | Compare current metrics against the most recent saved snapshot. Implies `score` (health and bare command)                                                                                                                                                                                                                                                                                                                                                                                                                |        |                                                                                                     |
        | `save-snapshot`                                             | --                         | Save vital signs snapshot for trend tracking. Set to `true` for default path or provide a custom path (health and bare command)                                                                                                                                                                                                                                                                                                                                                                                          |        |                                                                                                     |
        | `type-aware`                                                | `false`                    | Enable optional project-wide TypeScript semantic evidence. Does not emit compiler diagnostics or generic typed lint findings.                                                                                                                                                                                                                                                                                                                                                                                            |        |                                                                                                     |
        | `type-aware-projects`                                       | `""`                       | Comma-separated tsconfig paths. Empty uses automatic project discovery.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |        |                                                                                                     |
        | `type-aware-require`                                        | `best-effort`              | Use `complete` to fail when semantic analysis is partial or unavailable, including valid zero-finding runs.                                                                                                                                                                                                                                                                                                                                                                                                              |        |                                                                                                     |
        | `dry-run`                                                   | `true`                     | Preview changes without modifying files (fix command)                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |        |                                                                                                     |
        | `coverage`                                                  | --                         | Path to Istanbul `coverage-final.json` for accurate per-function CRAP scores (health and audit commands)                                                                                                                                                                                                                                                                                                                                                                                                                 |        |                                                                                                     |
        | `coverage-root`                                             | --                         | Absolute prefix to strip from Istanbul file paths before matching (health and audit commands). Use when coverage was generated under a different checkout root in CI / Docker (e.g., `/home/runner/work/myapp`).                                                                                                                                                                                                                                                                                                         |        |                                                                                                     |
        | `max-crap`                                                  | `30.0`                     | CRAP score threshold (health and audit commands). Functions meeting or exceeding this score contribute to the verdict.                                                                                                                                                                                                                                                                                                                                                                                                   |        |                                                                                                     |
        | `gate`                                                      | `new-only`                 | Audit verdict gate. `new-only` fails only on findings introduced by the changeset; `all` fails on every finding in changed files.                                                                                                                                                                                                                                                                                                                                                                                        |        |                                                                                                     |
        | `security-gate`                                             | --                         | Security delta gate for `command: security`. `new` fails only on changed-line candidates; `newly-reachable` fails only on candidates that became reachable from entry points (needs a base ref via `changed-since` or PR auto-scoping). Gated security failures exit with code 8, and the `issues` output counts only matching gate candidates. PR comment and review renderers do not support security envelopes yet and are skipped for this command.                                                                  |        |                                                                                                     |
        | `dead-code-baseline` / `health-baseline` / `dupes-baseline` | --                         | Per-analysis baseline file paths for the audit command (saved by \`fallow dead-code                                                                                                                                                                                                                                                                                                                                                                                                                                      | health | dupes --save-baseline\`). Used so pre-existing issues on touched files do not dominate the verdict. |
        | `args`                                                      | --                         | Additional arguments to pass to fallow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |        |                                                                                                     |
      </Step>

      <Step title="Upload SARIF (optional)">
        Upload results to GitHub Code Scanning to get inline annotations on the PR diff:

        ```yaml theme={null}
        - uses: fallow-rs/fallow@v3
          with:
            format: sarif

        - uses: github/codeql-action/upload-sarif@v4
          with:
            sarif_file: fallow-results.sarif
        ```
      </Step>
    </Steps>

    ```bash title="GitHub Actions job summary" theme={null}
    fallow: 8 issues found

    Dead Code (3 issues)
    | Type | File | Symbol | Line |
    |------|------|--------|------|
    | unused-export | src/utils/format.ts | formatCurrency | 12 |
    | unused-export | src/utils/format.ts | formatPercentage | 28 |
    | unused-file | src/legacy/oldApi.ts | n/a | n/a |

    Duplication (3 clone groups, 1.8%)
    | Files | Lines | Tokens |
    |-------|-------|--------|
    | src/tax/utils.ts ↔ src/savings/utils.ts | 25 | 92 |

    Complexity (2 hotspots)
    | File | Function | Cyclomatic | Cognitive |
    |------|----------|------------|-----------|
    | src/server/router.ts:42 | handleRequest | 28 | 34 |

    Completed in 48ms
    ```

    <Info>
      GitHub Code Scanning is available on public repositories for free (no GitHub Advanced Security needed) and on private or internal repositories with GitHub Advanced Security enabled. On a public repository the action always attempts the upload (the first upload initializes Code Scanning); on a private or internal repository without Advanced Security it warns, skips SARIF upload, and keeps the job summary plus primary fallow output available.

      The upload requires the job to grant `permissions: security-events: write`. Without it, the upload step fails. On a public repository this surfaces as a job failure rather than a silent skip, so add the permission alongside `sarif: true`.
    </Info>

    <Info>
      PR summary comments use fallow's native `pr-comment-github` format. Inline review comments use `review-github`, then `fallow ci reconcile-review --provider github` marks stale fallow review threads resolved when findings disappear.
    </Info>

    <Info>
      GitHub inline review comments target the current PR file state (`side: RIGHT`). Findings on deleted lines are not modeled yet; fallow's diagnostics are current-state oriented in normal use.
    </Info>

    <Info>
      The action automatically detects your package manager (npm, pnpm, or yarn) from lock files. Review comments and annotations show the correct install/uninstall commands for your project.
    </Info>
  </Tab>

  <Tab title="GitLab CI">
    <Steps>
      <Step title="Include the template">
        Add fallow to your `.gitlab-ci.yml`:

        ```yaml theme={null}
        include:
          - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'

        fallow:
          extends: .fallow
        ```

        This runs all analyses (dead code + duplication + complexity) on every MR and push to the default branch.
      </Step>

      <Step title="Configure variables">
        Customize with CI/CD variables:

        | Variable                                                                                           | Default    | Description                                                                                                                                                                                                                                                                                                                                                                                                 |        |                          |
        | :------------------------------------------------------------------------------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------ |
        | `FALLOW_COMMAND`                                                                                   | `""`       | Command to run (`dead-code`, `dupes`, `health`, `audit`, `security`, `fix`, or empty for all). Legacy alias: `check` = `dead-code`.                                                                                                                                                                                                                                                                         |        |                          |
        | `FALLOW_ROOT`                                                                                      | `.`        | Project root directory                                                                                                                                                                                                                                                                                                                                                                                      |        |                          |
        | `FALLOW_CONFIG`                                                                                    | --         | Path to config file                                                                                                                                                                                                                                                                                                                                                                                         |        |                          |
        | `FALLOW_PRODUCTION`                                                                                | `""`       | Set to `"true"` to enable production mode for every analysis. Empty defers to per-analysis env and config.                                                                                                                                                                                                                                                                                                  |        |                          |
        | `FALLOW_PRODUCTION_DEAD_CODE`                                                                      | `""`       | Combined mode only: set to `"true"`/`"false"` to override `FALLOW_PRODUCTION` for dead-code. Empty defers to it.                                                                                                                                                                                                                                                                                            |        |                          |
        | `FALLOW_PRODUCTION_HEALTH`                                                                         | `""`       | Combined mode only: set to `"true"`/`"false"` to override `FALLOW_PRODUCTION` for health. Empty defers to it.                                                                                                                                                                                                                                                                                               |        |                          |
        | `FALLOW_PRODUCTION_DUPES`                                                                          | `""`       | Combined mode only: set to `"true"`/`"false"` to override `FALLOW_PRODUCTION` for duplication. Empty defers to it.                                                                                                                                                                                                                                                                                          |        |                          |
        | `FALLOW_FAIL_ON_ISSUES`                                                                            | `true`     | Fail pipeline if issues found                                                                                                                                                                                                                                                                                                                                                                               |        |                          |
        | `FALLOW_TYPE_AWARE`                                                                                | `""`       | Set to `"true"` to enable semantic evidence, `"false"` to disable it, or leave empty to defer to repository config.                                                                                                                                                                                                                                                                                         |        |                          |
        | `FALLOW_TYPE_AWARE_PROJECTS`                                                                       | `""`       | Comma-separated tsconfig paths. Empty uses automatic project discovery. Each path is forwarded as a separate CLI flag.                                                                                                                                                                                                                                                                                      |        |                          |
        | `FALLOW_TYPE_AWARE_REQUIRE`                                                                        | `""`       | `best-effort` or `complete`. Empty defers to repository config; `complete` fails on partial or unavailable semantic evidence.                                                                                                                                                                                                                                                                               |        |                          |
        | `FALLOW_CHANGED_SINCE`                                                                             | --         | Only check files changed since this ref (auto-detected in MR pipelines)                                                                                                                                                                                                                                                                                                                                     |        |                          |
        | `FALLOW_BASELINE`                                                                                  | --         | Path to baseline file for comparison. Rejected with exit 2 when `FALLOW_COMMAND=audit`; use `FALLOW_AUDIT_DEAD_CODE_BASELINE` / `FALLOW_AUDIT_HEALTH_BASELINE` / `FALLOW_AUDIT_DUPES_BASELINE` instead.                                                                                                                                                                                                     |        |                          |
        | `FALLOW_SAVE_BASELINE`                                                                             | --         | Save current results as a baseline file. Rejected with exit 2 when `FALLOW_COMMAND=audit` (audit runs three analyses with incompatible baseline formats).                                                                                                                                                                                                                                                   |        |                          |
        | `FALLOW_SECURITY_GATE`                                                                             | `""`       | Security delta gate for `FALLOW_COMMAND: "security"`. `new` fails only on changed-line candidates; `newly-reachable` fails only on candidates that became reachable from entry points (needs a base ref via `FALLOW_CHANGED_SINCE` or MR auto-detection). Gated security failures exit with code 8. MR comment and review renderers do not support security envelopes yet and are skipped for this command. |        |                          |
        | `FALLOW_COMMENT`                                                                                   | `false`    | Post a rich MR summary comment with collapsible sections for each analysis                                                                                                                                                                                                                                                                                                                                  |        |                          |
        | `FALLOW_REVIEW`                                                                                    | `false`    | Post inline MR discussions on changed lines with suggestion blocks for auto-fixable issues                                                                                                                                                                                                                                                                                                                  |        |                          |
        | `FALLOW_REVIEW_GUIDANCE`                                                                           | `false`    | Add collapsed "What to do" guidance blocks to inline MR discussions                                                                                                                                                                                                                                                                                                                                         |        |                          |
        | `FALLOW_REVIEW_ID`                                                                                 | --         | Stable identifier (1-64 characters, `A-Za-z0-9._-`) that isolates inline review discussions when multiple fallow review jobs target the same MR. See [Isolating parallel review jobs](#isolating-parallel-review-jobs).                                                                                                                                                                                     |        |                          |
        | `FALLOW_SUMMARY_SCOPE`                                                                             | `all`      | Sticky MR summary scope. Use `diff` to apply the diff filter to project-level dependency/catalog/override findings too. Inline review discussions are unaffected                                                                                                                                                                                                                                            |        |                          |
        | `FALLOW_PR_COMMENT_LAYOUT`                                                                         | `default`  | Sticky MR comment layout: `default`, `compact`, `gate-only`, or `details`. Use `gate-only` when Code Quality is the primary MR surface                                                                                                                                                                                                                                                                      |        |                          |
        | `FALLOW_MAX_COMMENTS`                                                                              | `50`       | Maximum number of inline review comments to post (applies to `FALLOW_REVIEW`)                                                                                                                                                                                                                                                                                                                               |        |                          |
        | `FALLOW_CODEQUALITY`                                                                               | `true`     | Generate Code Quality report (inline MR annotations)                                                                                                                                                                                                                                                                                                                                                        |        |                          |
        | `FALLOW_VERSION`                                                                                   | --         | Fallow version to use. Empty auto-detects the project `package.json` `fallow` dependency and falls back to `latest`; set explicitly to override the local pin.                                                                                                                                                                                                                                              |        |                          |
        | `FALLOW_SCRIPTS_REF`                                                                               | --         | Pin CI scripts to a specific git ref (tag, branch, or SHA) for reproducible builds. Empty prefers vendored scripts, then derives from an exact installed fallow version when possible.                                                                                                                                                                                                                      |        |                          |
        | `FALLOW_SKIP_INSTALL`                                                                              | `""`       | Set to `"true"` to skip `npm install -g fallow` and use the `fallow` already resolvable on the job shell's `PATH` (fails fast if none is found). See the setup gotchas step below.                                                                                                                                                                                                                          |        |                          |
        | `FALLOW_DIFF_FILTER`                                                                               | `added`    | Filter line-level findings to added diff hunks; use `diff_context`, `file`, or `nofilter` to widen review scope.                                                                                                                                                                                                                                                                                            |        |                          |
        | `FALLOW_WORKSPACE`                                                                                 | --         | Scope output to one or more workspaces (exact names, globs, `!` negation; comma-separated)                                                                                                                                                                                                                                                                                                                  |        |                          |
        | `FALLOW_CHANGED_WORKSPACES`                                                                        | --         | Git-derived monorepo scoping: scope to workspaces containing any file changed since `REF`. Requires full git history. Mutually exclusive with `FALLOW_WORKSPACE`. Missing ref is a hard error.                                                                                                                                                                                                              |        |                          |
        | `FALLOW_DUPES_MODE`                                                                                | `mild`     | Detection mode for dupes (`strict`, `mild`, `weak`, `semantic`)                                                                                                                                                                                                                                                                                                                                             |        |                          |
        | `FALLOW_SCORE`                                                                                     | `false`    | Compute health score (0-100 with letter grade). Enables the health delta header in MR comments (health and bare command)                                                                                                                                                                                                                                                                                    |        |                          |
        | `FALLOW_TREND`                                                                                     | `false`    | Compare current metrics against the most recent saved snapshot. Implies `FALLOW_SCORE` (health and bare command)                                                                                                                                                                                                                                                                                            |        |                          |
        | `FALLOW_SAVE_SNAPSHOT`                                                                             | --         | Save vital signs snapshot for trend tracking. Set to `true` for default path or provide a custom path (health and bare command)                                                                                                                                                                                                                                                                             |        |                          |
        | `FALLOW_COVERAGE`                                                                                  | --         | Path to Istanbul `coverage-final.json` for accurate per-function CRAP scores (health, audit, and default combined commands)                                                                                                                                                                                                                                                                                 |        |                          |
        | `FALLOW_COVERAGE_ROOT`                                                                             | --         | Rebase Istanbul file paths before matching (health, audit, and default combined commands). Use when coverage was generated under a different checkout root in CI / Docker.                                                                                                                                                                                                                                  |        |                          |
        | `FALLOW_MAX_CRAP`                                                                                  | `30.0`     | CRAP score threshold (health and audit commands)                                                                                                                                                                                                                                                                                                                                                            |        |                          |
        | `FALLOW_AUDIT_GATE`                                                                                | `new-only` | Audit verdict gate (`new-only` or `all`)                                                                                                                                                                                                                                                                                                                                                                    |        |                          |
        | `FALLOW_AUDIT_DEAD_CODE_BASELINE` / `FALLOW_AUDIT_HEALTH_BASELINE` / `FALLOW_AUDIT_DUPES_BASELINE` | --         | Per-analysis baseline file paths for the audit command (saved by \`fallow dead-code                                                                                                                                                                                                                                                                                                                         | health | dupes --save-baseline\`) |
        | `FALLOW_ARGS`                                                                                      | --         | Additional arguments (space-separated)                                                                                                                                                                                                                                                                                                                                                                      |        |                          |

        <Info>
          In MR pipelines, the template automatically passes `--changed-since` to scope analysis to files changed in the merge request. No manual configuration needed.
        </Info>

        <Info>
          The template automatically detects your package manager (npm, pnpm, or yarn) from lock files. Review comments and suggestions show the correct install/uninstall commands for your project.
        </Info>

        Example: full MR feedback with summary comment and inline review:

        ```yaml theme={null}
        fallow:
          extends: .fallow
          variables:
            FALLOW_COMMENT: "true"
            FALLOW_REVIEW: "true"
        ```

        Example: dead code only with MR comments:

        ```yaml theme={null}
        fallow:
          extends: .fallow
          variables:
            FALLOW_COMMAND: "dead-code"
            FALLOW_COMMENT: "true"
        ```
      </Step>

      <Step title="Code Quality reports">
        The template automatically generates a GitLab Code Quality report (CodeClimate format). This shows fallow findings as **inline annotations** directly on the MR diff, the GitLab equivalent of GitHub Code Scanning.

        No additional configuration needed. The report is uploaded as a CI artifact automatically. If you invoke fallow yourself outside the template, both `--format codeclimate` and the alias `--format gitlab-codequality` produce the same JSON array consumed by GitLab.
      </Step>

      <Step title="Rich MR comments">
        **Summary comment**: Set `FALLOW_COMMENT: "true"` to post a rich MR comment with collapsible sections for dead code, duplication, and complexity findings. The comment is updated on each push (no spam). Set `FALLOW_SUMMARY_SCOPE: "diff"` when the sticky summary should hide pre-existing project-level dependency/catalog/override findings outside the diff. Set `FALLOW_PR_COMMENT_LAYOUT: "gate-only"` when GitLab Code Quality is the main MR surface and the sticky comment should stay compact.

        **Inline review**: Set `FALLOW_REVIEW: "true"` to post inline MR discussions directly on changed lines. Auto-fixable issues include GitLab suggestion blocks that can be applied with one click. Use `FALLOW_MAX_COMMENTS` to cap the number of inline comments (default: 50). Set `FALLOW_REVIEW_GUIDANCE: "true"` to add collapsed "What to do" guidance to each inline finding. The template renders native `review-gitlab` envelopes with `position_type`, `base_sha`, `start_sha`, and `head_sha` from GitLab diff refs, then runs `fallow ci reconcile-review --provider gitlab` so stale fallow discussions are resolved after fixes.

        ```yaml theme={null}
        fallow:
          extends: .fallow
          variables:
            FALLOW_COMMENT: "true"    # Rich summary comment
            FALLOW_SUMMARY_SCOPE: "diff" # Filter project-level findings in the summary too
            FALLOW_PR_COMMENT_LAYOUT: "gate-only" # Keep the sticky summary compact
            FALLOW_REVIEW: "true"     # Inline discussions with suggestions
            FALLOW_REVIEW_GUIDANCE: "true" # Collapsed "What to do" blocks
            FALLOW_MAX_COMMENTS: "30" # Limit inline comments
        ```
      </Step>

      <Step title="Authentication">
        MR summary comments (`FALLOW_COMMENT`) and inline review (`FALLOW_REVIEW`) require a `GITLAB_TOKEN` (project access token or PAT) with `api` scope. Set it as a CI/CD variable.

        <Warning>
          GitLab's documented `CI_JOB_TOKEN` permissions allow reading MR notes, but not creating, updating, or deleting them. The template skips MR comment / review posting with a warning when `GITLAB_TOKEN` is unset rather than failing the pipeline. `CI_JOB_TOKEN` is still useful for GitLab package registry authentication.
        </Warning>
      </Step>

      <Step title="Vendoring (offline runners)">
        If your runners cannot reach `raw.githubusercontent.com`, vendor the template and helper scripts into your repo. Run once locally:

        ```bash theme={null}
        npx fallow ci-template gitlab --vendor
        ```

        This writes `ci/gitlab-ci.yml` plus two helper scripts (`ci/scripts/comment.sh`, `ci/scripts/review.sh`) under `ci/`. Commit the generated files and switch to a local include:

        ```yaml theme={null}
        include:
          - local: 'ci/gitlab-ci.yml'

        fallow:
          extends: .fallow
        ```

        The vendored template prefers the local scripts and skips the remote fetch path entirely. Pass `--force` to overwrite files that have diverged from the bundled template.
      </Step>

      <Step title="Setup gotchas">
        * The template sets `GIT_STRATEGY: "fetch"` so shared templates that set `GIT_STRATEGY=none` do not leave fallow without a working tree.
        * The template sets `GIT_DEPTH: "0"` so `--changed-since` can diff against the MR base SHA without shallow-clone ambiguity.
        * For private GitLab npm registries, create `.npmrc` during the job with `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}` rather than committing tokens.
        * For pnpm projects with `minimumReleaseAge`, add `fallow` and `@fallow-cli/*` to `minimumReleaseAgeExclude` when you need to consume a just-published fallow release immediately.

        To run the template against a fallow you install yourself (for example a pnpm-catalog pin), set `FALLOW_SKIP_INSTALL: "true"`, override `image:` to your base image, and make sure your install step leaves `fallow` resolvable on the job shell's `PATH`. A bare `pnpm install` / `npm install` only writes `node_modules/.bin/fallow`, which GitLab does **not** add to `PATH` automatically, so prepend it yourself. A job that `extends: .fallow` and defines its own `before_script` **replaces** the template's `before_script` (GitLab does not merge them), so compose with `!reference` to keep the template's install and script-prep block:

        ```yaml theme={null}
        fallow:
          extends: .fallow
          before_script:
            - export PATH="$CI_PROJECT_DIR/node_modules/.bin:$PATH"
            - !reference [.fallow, before_script]
          variables:
            FALLOW_SKIP_INSTALL: "true"
        ```

        The job then skips `npm install -g fallow` and runs your exact binary, so CI matches your local lint gate. If you also enable `FALLOW_COMMENT` / `FALLOW_REVIEW` and your binary is a dev build whose `--version` is not an exact release (for example `2.3.0-dev`), pin `FALLOW_SCRIPTS_REF` to a real tag or vendor `ci/scripts/` so the MR-integration scripts can still be fetched.
      </Step>
    </Steps>

    <Info>
      The GitLab template caches parse results per branch via `.fallow/`, so incremental runs are fast.
    </Info>

    <Accordion title="Complete example configuration">
      A full `.gitlab-ci.yml` setup with summary comments, inline review, and Code Quality:

      ```yaml theme={null}
      include:
        - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'

      fallow:
        extends: .fallow
        variables:
          FALLOW_COMMENT: "true"        # Rich MR summary with collapsible sections
          FALLOW_REVIEW: "true"         # Inline discussions with suggestion blocks
          FALLOW_MAX_COMMENTS: "50"     # Cap inline review comments (default: 50)
          FALLOW_CODEQUALITY: "true"    # Code Quality report for MR annotations
          FALLOW_FAIL_ON_ISSUES: "true" # Fail pipeline on issues
          FALLOW_PRODUCTION: "true"     # Exclude test/dev files
          # FALLOW_SCRIPTS_REF: "v1.0.0" # Pin scripts to a specific version
      ```

      The template automatically:

      * Detects your package manager (npm/pnpm/yarn) from lock files
      * Scopes analysis to changed files in MR pipelines via `--changed-since`
      * Caches parse results per branch for fast incremental runs
      * Uploads Code Quality artifacts for inline MR annotations
    </Accordion>
  </Tab>

  <Tab title="Manual Setup">
    If you prefer not to use the action or template, run fallow directly:

    ```yaml theme={null}
    - run: npx fallow --ci              # All analyses (dead code + dupes + health)
    - run: npx fallow dead-code --ci    # Dead code only
    - run: npx fallow dupes --ci        # Duplication only
    - run: npx fallow health --ci       # Complexity hotspots only
    ```

    The `--ci` flag enables SARIF output, fail-on-issues, and quiet mode in one flag. Or configure individually:

    ```yaml theme={null}
    - run: npx fallow --fail-on-issues --format compact
    ```

    <Info>
      The `--ci`, `--fail-on-issues`, and `--sarif-file` flags work on all commands: `dead-code`, `dupes`, `health`, and bare `fallow`.
    </Info>

    ### PR/MR comments

    Post results as a comment using markdown output:

    <Tabs>
      <Tab title="GitHub Actions">
        ```yaml theme={null}
        - run: npx fallow dead-code --format markdown | gh pr comment ${{ github.event.pull_request.number }} --body-file -
        - run: npx fallow dupes --format markdown | gh pr comment ${{ github.event.pull_request.number }} --body-file -
        - run: npx fallow health --format markdown | gh pr comment ${{ github.event.pull_request.number }} --body-file -
        ```
      </Tab>

      <Tab title="GitLab CI">
        Use the built-in template with `FALLOW_COMMENT`:

        ```yaml theme={null}
        fallow:
          extends: .fallow
          variables:
            FALLOW_COMMENT: "true"
        ```

        Or manually with the GitLab API:

        ```yaml theme={null}
        fallow:
          script:
            - npx fallow --format markdown > fallow-report.md
            - |
              curl --request POST \
                --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
                "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" \
                --data-urlencode "body@fallow-report.md"
          rules:
            - if: $CI_MERGE_REQUEST_IID
        ```
      </Tab>
    </Tabs>

    ### Consuming review envelopes from your own code

    Use this path when your CI runners cannot use remote includes, do not have `jq` installed, or cannot delegate API tokens to third-party binaries. Run fallow to emit the typed `review-github` or `review-gitlab` envelope, then POST the comments yourself from the same job that already holds the token. Fallow has already done the rendering, fingerprinting, and DiffNote positioning; the consumer just iterates and POSTs.

    #### Envelope shape

    ```bash theme={null}
    gh pr diff $PR_NUMBER | npx fallow audit --diff-stdin --format review-github
    glab mr diff $CI_MERGE_REQUEST_IID | npx fallow audit --diff-stdin --format review-gitlab
    ```

    Output (v2 envelope, fallow >= 2.77.0):

    ```json theme={null}
    {
      "event": "COMMENT",
      "body": "### Fallow audit\n\n3 inline findings selected for GitHub review.\n\n<!-- fallow-review -->\n\n<!-- fallow-fingerprint:v2: 06bf55db1c35210d -->",
      "summary": {
        "body": "### Fallow audit\n\n3 inline findings selected for GitHub review.\n\n<!-- fallow-review -->\n\n<!-- fallow-fingerprint:v2: 06bf55db1c35210d -->",
        "fingerprint": "06bf55db1c35210d"
      },
      "comments": [
        {
          "path": "src/utils.ts",
          "line": 42,
          "side": "RIGHT",
          "body": "**error** `fallow/unused-export`: ...\n\n<!-- fallow-fingerprint:v2: 9a8b7c6d5e4f3a2b -->",
          "fingerprint": "9a8b7c6d5e4f3a2b"
        },
        {
          "path": "package.json",
          "line": 5,
          "side": "RIGHT",
          "body": "**error** `fallow/unused-dependency`: ...\n\n**warn** `fallow/unused-dev-dependency`: ...\n\n<!-- fallow-fingerprint:v2: merged:37df0011a9d7ac87 -->",
          "fingerprint": "merged:37df0011a9d7ac87"
        }
      ],
      "marker_regex": "^<!-- fallow-fingerprint:v2: ((?:[a-z]+:)?[0-9a-f]{16}) -->\\s*$",
      "marker_regex_flags": "m",
      "meta": {
        "schema": "fallow-review-envelope/v2",
        "provider": "github",
        "check_conclusion": "failure"
      }
    }
    ```

    Every entry under `comments[]` is fully rendered Markdown, ready to POST as-is. The `<!-- fallow-fingerprint:v2: <fingerprint> -->` marker embedded in each body is the stable identifier used for reconciliation across runs. The top-level `marker_regex` is the canonical extraction pattern; running it (with one capture group) against any existing PR/MR comment yields the fingerprint string. fallow emits the multiline `m` flag separately in `marker_regex_flags` rather than baking `(?m)` into the pattern, because JavaScript RegExp rejects standalone inline flag groups. Consumers pass both fields to their regex engine:

    ```js theme={null}
    const re = new RegExp(env.marker_regex, env.marker_regex_flags);
    ```

    ```rust theme={null}
    let re = regex::RegexBuilder::new(&env.marker_regex)
        .multi_line(env.marker_regex_flags.contains('m'))
        .build()?;
    ```

    The top-level `summary: { body, fingerprint }` block carries the sticky-summary comment. `summary.body` is byte-identical to the legacy top-level `body` field (which is retained for v1 consumers); `summary.fingerprint` is what consumers match against existing comments to upsert the sticky summary in place. One fallow invocation now produces both the summary and the inline comments, so consumers no longer need a second `fallow --format pr-comment-{github,gitlab}` run.

    When multiple findings collide on the same `path:line` (e.g., three `unused-dependency` variants on `package.json:5`), they collapse into one comment with stacked body paragraphs and a `fingerprint = "merged:<16-char hash of sorted constituent fingerprints>"`. The composite identity shifts whenever the set of constituents changes, so bundled wrappers (and `fallow ci reconcile-review`) consuming only the primary fingerprint correctly skip the comment when its content is unchanged and re-post it when membership changes. Single-finding comments keep the bare 16-hex `fingerprint` shape.

    Consumers that want update-in-place reconciliation (preserving reviewer reply threads across content changes) implement their own identity tracking by extracting the fingerprint via `marker_regex`, comparing constituents by re-running fallow against the new HEAD, and calling the vendor edit endpoint (`PATCH /pulls/comments/{id}` on GitHub, `PUT /discussions/.../notes/{note_id}` on GitLab) when the constituents differ from the existing comment. fallow's bundled scripts do not implement this path; the cost (auth scopes, retry semantics, edit-on-resolved-thread 422 handling) is paid only by consumers that need thread preservation.

    Each comment may also carry a `truncated: bool` field. When `true`, the body was truncated to fit under a conservative 65,536-byte cap (GitHub PR review comments empirically reject anything larger; GitLab note bodies accept up to 1,000,000 characters per the [GitLab application limits docs](https://docs.gitlab.com/administration/instance_limits/)). Truncated bodies always contain three co-present signals: the typed `truncated: true` flag, an inline `<!-- fallow-truncated -->` HTML marker, and a `> Body truncated by fallow.` blockquote breadcrumb. The closing fallow-fingerprint marker survives truncation so reconciliation continues to work.

    For GitLab, each comment additionally carries a `position` block with `base_sha`, `start_sha`, `head_sha`, `position_type`, `old_path`, `new_path`, and `new_line`, matching the fields GitLab's discussions API expects. **For renamed files** (when fallow is run with `--diff-file` or `--diff-stdin`), `old_path` is populated with the base-side filename from the diff's `rename from` / `rename to` extended headers; inline comments on renamed files now anchor correctly via GitLab's discussion-position API. Falls back to the head-side path when no rename is present in the diff (the common case).

    #### Environment variables that feed the envelope

    | Variable                                                                        | Provider | Purpose                                                                                                                                    |
    | :------------------------------------------------------------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
    | `FALLOW_MAX_COMMENTS`                                                           | Both     | Caps the number of inline comments (default 50).                                                                                           |
    | `FALLOW_REVIEW_GUIDANCE`                                                        | Both     | Adds collapsed "What to do" guidance blocks to each inline finding when set to a truthy value.                                             |
    | `FALLOW_SUMMARY_SCOPE`                                                          | Both     | Controls sticky PR/MR summary scope only: `all` keeps project-level findings outside the diff, `diff` applies the diff filter to them too. |
    | `FALLOW_PR_COMMENT_LAYOUT`                                                      | Both     | Controls sticky PR/MR summary layout: `default`, `compact`, `gate-only`, or `details`.                                                     |
    | `CI_MERGE_REQUEST_DIFF_BASE_SHA`                                                | GitLab   | Auto-populates `position.base_sha`.                                                                                                        |
    | `CI_COMMIT_SHA`                                                                 | GitLab   | Auto-populates `position.head_sha`.                                                                                                        |
    | `FALLOW_GITLAB_BASE_SHA` / `FALLOW_GITLAB_START_SHA` / `FALLOW_GITLAB_HEAD_SHA` | GitLab   | Overrides the auto-populated SHAs when running outside a standard GitLab MR pipeline.                                                      |

    If neither `CI_MERGE_REQUEST_DIFF_BASE_SHA` nor `FALLOW_GITLAB_BASE_SHA` is set, the `position` block is emitted with `null` SHAs and the consumer must supply them from the MR's `diff_refs` before POSTing.

    #### Minimal consumer (GitLab)

    ```bash theme={null}
    fallow audit --diff-stdin --format review-gitlab < diff.patch > plan.json

    jq -c '.comments[]' plan.json | while read -r comment; do
      curl --silent --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
        --header "Content-Type: application/json" \
        --data "$comment" \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/discussions"
    done
    ```

    If `jq` is also unavailable on your runner, parse the JSON in your CI language of choice (Node, Python, Go) and POST each entry verbatim. The wire shape under `comments[].position` matches GitLab's discussions API one-for-one, so no field remapping is required.

    #### Reconciliation across runs

    To avoid duplicate threads on later pushes, fetch the existing MR discussions before POSTing and extract their fingerprints via the marker. The simplest sed-based extraction matches the marker prefix `<!-- fallow-fingerprint:v2: ` plus the fingerprint token, then compares against `comments[].fingerprint`:

    ```bash theme={null}
    existing=$(curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
      "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/discussions?per_page=100")

    existing_fps=$(echo "$existing" | jq -r '.[].notes[].body? // empty' \
      | sed -n 's|.*fallow-fingerprint:v2: \([^ ]*\) .*|\1|p' \
      | sort -u)

    # For each comment in plan.json, only POST when its fingerprint
    # is not already present in $existing_fps.
    ```

    For automated stale-thread cleanup (mark threads as resolved when a finding disappears between runs), use `fallow ci reconcile-review --provider gitlab` if you can grant a token to fallow itself. If you cannot, mirror the same fingerprint diff logic in your own script: the marker convention is the contract that lets both reconciliation paths agree. The bundled reconciler accepts both v1 (`<!-- fallow-fingerprint: <hash> -->`) and v2 (`<!-- fallow-fingerprint:v2: <fingerprint> -->`) markers during the migration window, so re-processing a v1 backlog after upgrading is transparent.

    The reconciler applies provider changes fail-fast. When a provider target disappears or a mutation fails, JSON output keeps the existing `apply_errors` array and may add `apply_hint`, `failed_fingerprints`, and `unapplied_fingerprints` so CI wrappers and custom integrations can surface a retry hint without guessing which stale findings were left unresolved.

    #### Schema stability

    The envelope is tagged `meta.schema: "fallow-review-envelope/v2"` (issue #528 evolution). Field additions are backwards-compatible (consumers should ignore unknown fields). The fingerprint hash is derived from `rule_id + path + snippet`, so it survives whitespace-only changes and body Markdown evolution. Consumers running v1-shaped logic against v2 output continue to work; the v1 top-level `body` field is retained for that path. Consumers running v2-aware logic should validate the schema marker against `^fallow-review-envelope/v[0-9]+$` so the same code keeps working when fallow bumps to v3 in the future.

    ### Duplication checks

    ```yaml theme={null}
    - run: npx fallow dupes --threshold 5 --format compact
    ```

    This fails if the overall duplication percentage exceeds 5%.

    Use `--changed-since` to only check duplication in files modified in the PR/MR:

    ```yaml theme={null}
    - run: npx fallow dupes --changed-since origin/main --format compact
    ```

    ### Health checks

    ```yaml theme={null}
    - run: npx fallow health --format compact
    ```

    Reports complexity hotspots and circular dependencies. Use `--max-cyclomatic 15` to customize the threshold.
  </Tab>

  <Tab title="Other CI">
    Fallow works in any CI environment that can run Node.js or [install fallow](/installation). The pattern is the same everywhere:

    ```bash theme={null}
    # Run all analyses (no install needed)
    npx fallow --format compact

    # Or individual commands
    npx fallow dead-code --format compact
    npx fallow dupes --format compact
    npx fallow health --format compact

    # Or download the binary directly
    curl -fsSL https://get.fallow.dev | sh
    fallow --format compact
    ```

    ### Exit codes

    | Code | Meaning                                     |
    | :--- | :------------------------------------------ |
    | `0`  | No error-severity issues found              |
    | `1`  | Error-severity issues found                 |
    | `2`  | Fatal error (invalid config, parse failure) |
  </Tab>
</Tabs>

<Tip>
  Both the GitHub Action and GitLab CI template automatically scope analysis to changed files in PR/MR context. No extra configuration needed.
</Tip>

### Isolating parallel review jobs

When multiple fallow review jobs target the same pull request or merge request (for example, one job per workspace in a CI matrix), give each job a stable review id: the `review-id` Action input on GitHub, or the `FALLOW_REVIEW_ID` variable on GitLab. The id must be 1-64 characters from `A-Za-z0-9._-`.

Reconciliation is exact-scope: a run only deduplicates against, and resolves, comments that carry the same review id. Unscoped runs only see unscoped comments, so adding an id to a new job never touches an existing job's threads.

```yaml theme={null}
# GitHub Actions matrix: one review scope per workspace
- uses: fallow-rs/fallow@v3
  with:
    review-comments: true
    workspace: ${{ matrix.workspace }}
    review-id: ${{ matrix.workspace }}
```

Without distinct ids, parallel jobs share one scope: each job would deduplicate against the other jobs' comments and resolve their threads as stale.

### Binary verification

The `fallow-rs/fallow` GitHub Action and the GitLab CI template both install fallow via `npm install -g fallow@<spec>`. Each `@fallow-cli/<platform>` npm package ships an Ed25519 `.sig` next to every binary plus an embedded SHA-256 digest in its `package.json#fallowDigests` field. Verification runs in two layers across two independent surfaces:

1. **Ed25519 signature** (offline, rooted in the workflow's signing key): the embedded public key in fallow's npm wrapper verifies all three binaries (`fallow`, `fallow-lsp`, `fallow-mcp`). A tampered binary fails closed with a specific failure code (`sig-invalid`, `digest-mismatch`, `binary-missing`, `sig-missing`, or `digest-unavailable`).
2. **SHA-256 digest** (offline, rooted in the platform package's `fallowDigests` field): the verifier confirms each binary's SHA-256 matches the digest written into the platform package's `package.json` at release time. A swapped binary that somehow carried a valid signature would still fail the digest check.

These two layers run on every install surface:

* **`fallow`, `fallow-lsp`, `fallow-mcp` first invocation**: the bin wrapper runs Ed25519 + SHA-256 before exec'ing the platform binary on the first run after install or upgrade. A small JSON sentinel next to the platform binary (or in `$XDG_CACHE_HOME/fallow/sentinels/` when the platform pkg dir is read-only, e.g. yarn PnP, Docker layered images) caches the verified state so subsequent invocations skip verification on a cache hit. `fallow --version` adds a trailing `verified: yes (<sentinel-path>)` line so vendor questionnaires and CI logs can confirm the integrity posture in one command.
* **Action installer re-runs both layers** (`action/scripts/install.sh`) after `npm install -g --ignore-scripts`. The verifier is loaded from the checked-out Action tree, not the installed npm package, so a tampered installer cannot self-validate. This is defense in depth on CI runners, where secrets exposure is highest.

A failed verification produces a `::error::` annotation in the Action log and a non-zero exit, aborting the workflow before any user code reads a swapped binary.

<Note>
  The npm wrapper used to run verification during `postinstall`. That hook is removed ahead of [npm RFC 868](https://github.com/npm/rfcs/pull/868) (`npm/cli#9360`) Phase 2, which will block postinstall hooks by default unless consumers add fallow to their `package.json#allowScripts`. The cryptographic property is preserved bit-for-bit by the first-invocation path; same public key, same offline `fallowDigests` lookup, same fail-closed behavior.
</Note>

Three environment variables tune the lazy-verify path:

* `FALLOW_SKIP_BINARY_VERIFY=1` skips Ed25519 + SHA-256 verification. Use only when deliberately replacing the published binary (source builds, airgapped mirrors, signed-repack registries). The skipped state is recorded in `fallow --version` output as `verified: skipped (FALLOW_SKIP_BINARY_VERIFY is set)` so the bypass remains visible in CI logs and vendor audits.
* `FALLOW_VERIFY_CACHE_DIR=<path>` redirects the sentinel file to a writable directory when the platform package dir is read-only. Cascade is platform-pkg-dir, then this override, then `$XDG_CACHE_HOME/fallow/sentinels/` (or `%LOCALAPPDATA%\fallow\sentinels\` on Windows).
* `FALLOW_VERIFY_LOG=1` emits one structured stderr line per outcome (`fallow-verify outcome=ok cache=hit sentinel=...`) for CI diagnostic logs.

To override verification in the Action:

```yaml theme={null}
- uses: fallow-rs/fallow@v3
  env:
    FALLOW_SKIP_BINARY_VERIFY: '1'
```

Do not set this in normal CI configurations. The public key fingerprint and the manual out-of-band verification recipe live in [`SECURITY.md`](https://github.com/fallow-rs/fallow/blob/main/SECURITY.md) on the main repo. The VS Code extension performs its own Ed25519 verification on its auto-downloaded binary; see [the extension docs](/integrations/vscode) for details.

### PR/MR-only analysis

Only analyze files changed in the current pull request or merge request:

<Tabs>
  <Tab title="GitHub Action">
    The action does this automatically via `auto-changed-since` (enabled by default). To disable and run a full analysis on PRs:

    ```yaml theme={null}
    - uses: fallow-rs/fallow@v3
      with:
        auto-changed-since: false
    ```

    To use a custom ref instead of the PR base SHA:

    ```yaml theme={null}
    - uses: fallow-rs/fallow@v3
      with:
        changed-since: origin/main
    ```
  </Tab>

  <Tab title="GitLab CI">
    The template does this automatically in MR pipelines. To use a custom ref instead:

    ```yaml theme={null}
    fallow:
      extends: .fallow
      variables:
        FALLOW_CHANGED_SINCE: "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    ```
  </Tab>

  <Tab title="Manual">
    ```yaml theme={null}
    - run: npx fallow --changed-since origin/main
    ```
  </Tab>
</Tabs>

Adopting fallow on a codebase with existing findings? Baselines report only new issues; see [PR enforcement in the adoption guide](/adoption#7-turn-on-pr-enforcement).

### Severity-aware PR gate (audit)

The default combined run gates on raw issue count: any finding in the changed files fails CI. That's the right contract for a tight feedback loop, but it doesn't honor rule severity. A project with `unused-exports: warn` (or any warn-tier rule) still fails CI when a PR touches a file with pre-existing warn-tier findings.

`fallow audit` is the severity-aware alternative. It combines dead-code, complexity, and duplication analysis scoped to changed files and returns a verdict (`pass` / `warn` / `fail`):

* **`pass`**: no issues in changed files
* **`warn`**: only warn-tier issues; CI does not fail
* **`fail`**: error-tier issues found; CI fails

By default audit runs in `gate: new-only` mode, so only findings *introduced* by the current changeset affect the verdict. Pre-existing findings show up in the PR comment as inherited (with a count), but they do not gate the merge.

<Tabs>
  <Tab title="GitHub Action">
    ```yaml theme={null}
    - uses: fallow-rs/fallow@v3
      with:
        command: audit
        gate: new-only        # default; fails only on findings introduced by this PR
        fail-on-issues: true
    ```

    The action exposes `outputs.verdict` (`pass`/`warn`/`fail`) and `outputs.gate` so downstream steps can branch on the verdict:

    ```yaml theme={null}
    - uses: fallow-rs/fallow@v3
      id: fallow
      with:
        command: audit

    - name: Block release on regression
      if: steps.fallow.outputs.verdict == 'fail'
      run: exit 1
    ```
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    fallow:
      extends: .fallow
      variables:
        FALLOW_COMMAND: "audit"
        FALLOW_AUDIT_GATE: "new-only"
        FALLOW_FAIL_ON_ISSUES: "true"
    ```
  </Tab>

  <Tab title="Manual">
    ```bash theme={null}
    npx fallow audit --base origin/main --gate new-only --quiet
    ```

    Exits 0 on `pass`/`warn`, 1 on `fail`.
  </Tab>
</Tabs>

### Detecting silent failures

CI integrations can degrade silently when the GitHub or GitLab API returns a 5xx, rate-limit response, or partial-pagination failure. Three structured signals let workflow operators detect this:

<Tabs>
  <Tab title="GitHub Actions">
    Three composite-action outputs are emitted on every run, regardless of whether the failure path was taken. Default values let downstream `if:` gates match positively (`== 'false'` or `== 'none'`) without an absent-vs-false ambiguity:

    | Output                      | Values                                  | Meaning                                                                                                                                                                                                                                                                    |
    | --------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `changed-files-unavailable` | `false` (default) / `true`              | The analyze step could not enumerate PR-changed files. Analysis ran against the full codebase. Common cause: transient GitHub API failure or token without `pull_requests: read` scope.                                                                                    |
    | `post-skipped-reason`       | `none` (default) / `pagination_failure` | The Post review comments step aborted the inline-review POST. Only set to `pagination_failure` when the multi-comment fingerprint dedup lookup failed and the action skipped posting to avoid duplicate threads.                                                           |
    | `dedup-lookup-failed`       | `false` (default) / `true`              | A dedup lookup failed on either the Post PR comment or the Post review comments step. Distinct from `post-skipped-reason`: the summary-only paths post a fresh comment anyway (potential duplicate) when their lookup fails. Gate on this to detect either degraded state. |

    ```yaml theme={null}
    - uses: fallow-rs/fallow@v3
      id: fallow

    - name: Alert on degraded scoping
      if: steps.fallow.outputs.changed-files-unavailable == 'true'
      run: echo "::warning::Fallow ran unscoped; PR scoping disabled by API failure"

    - name: Alert on dedup degradation
      if: steps.fallow.outputs.dedup-lookup-failed == 'true'
      run: echo "::warning::Fallow PR comments may be duplicated"
    ```

    A 4xx response (auth, scope, permission errors) on the multi-comment review path escalates to `exit 1` and fails the action step, because re-running will not resolve a configuration error. 5xx responses, retry-exhausted 429s, and network errors return `exit 0` with the warning so transient blips do not break PRs.
  </Tab>

  <Tab title="GitLab CI">
    Two sidecar artifacts written by `comment.sh` and `review.sh` carry the same signals; both are declared in the template's `artifacts: paths:` so downstream jobs can read them:

    | Artifact                         | Values                                  | Meaning                                                                                                                                                       |
    | -------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `fallow-skip-reason.txt`         | `none` (default) / `pagination_failure` | The inline-review POST was aborted because the dedup lookup against `/discussions` failed and posting would risk N duplicate threads.                         |
    | `fallow-dedup-lookup-failed.txt` | `false` (default) / `true`              | A dedup lookup failed on either `comment.sh` or `review.sh`. The summary-only paths still post (potential duplicate); set this for the degraded-state signal. |

    ```yaml theme={null}
    alert-degraded-fallow:
      stage: notify
      needs: [fallow]
      script: |
        if [ "$(cat fallow-skip-reason.txt)" = "pagination_failure" ]; then
          echo "WARNING: Fallow inline review skipped to avoid duplicates"
        fi
        if [ "$(cat fallow-dedup-lookup-failed.txt)" = "true" ]; then
          echo "WARNING: Fallow MR comments may be duplicated; re-run the fallow job"
        fi
    ```

    A 4xx response on the multi-discussion review path returns `exit 1`, but the template's existing `bash review.sh || echo "WARNING: ..."` swallows it. Operators who want CI-fatal behavior on auth misconfiguration should drop the `|| echo` from their template or gate on the sidecar markers.
  </Tab>
</Tabs>

#### Migrating from combined to audit

If your project is on the default combined run today and you want severity-aware gating, add `command: audit` (`FALLOW_COMMAND: audit`) and the existing PR comment, annotations, and review comments continue to work. The audit run produces an extra verdict banner at the top of the PR comment:

```
> :x: Audit failed · gate: `new-only` · 2 new findings introduced by this PR · 5 inherited (not gated)
```

Use `gate: all` (`FALLOW_AUDIT_GATE: "all"`) if you want every finding in changed files to gate, ignoring the inherited-vs-introduced split. This is the strict posture: nothing slips in, but pre-existing findings on touched files block the merge until cleaned up.

<Tip>
  Audit needs a base ref. The action and GitLab CI template auto-detect the PR/MR base, so no extra configuration is needed for that workflow. On non-PR pipelines (release branches, scheduled jobs), set `changed-since` (`FALLOW_CHANGED_SINCE`) explicitly; the runners hard-error rather than silently analyze nothing.
</Tip>

## The three tracks together

CI works best when combined with agent and editor integration:

1. **Agent** generates code and runs `fallow --changed-since HEAD~1` to self-check
2. **Human** reviews in VS Code, sees Code Lens annotations on new exports
3. **CI** runs the full analysis and catches anything that slipped through

```mermaid theme={null}
flowchart TB
  A["Agent<br/>fallow --changed-since HEAD~1"] -->|generates + self-checks| B["Code"]
  B --> C["Human<br/>VS Code Code Lens"]
  C -->|reviews| D["Pull Request"]
  D --> E["CI<br/>Full fallow analysis + SARIF"]
  E -->|passes| F["main"]
```

## See also

<CardGroup>
  <Card title="Agent integration" icon="robot" href="/integrations/mcp">
    How AI agents use fallow via CLI and MCP.
  </Card>

  <Card title="Rule configuration" icon="sliders" href="/configuration/rules">
    Configure severity levels and issue types.
  </Card>

  <Card title="Production mode" icon="rocket" href="/analysis/production-mode">
    Exclude test and dev files from analysis.
  </Card>

  <Card title="Health badges" icon="award" href="/integrations/badges">
    Add a health score badge to your README.
  </Card>
</CardGroup>


# Claude Code hooks
Source: https://docs.fallow.tools/integrations/claude-hooks

Block Claude Code git commits and pushes with a PreToolUse hook that runs fallow audit and feeds structured findings back to the agent.

Claude Code hooks let you insert deterministic checks into the agent loop. This pattern is not a Git hook. It is a local `PreToolUse` gate on Claude's `Bash` tool. When Claude tries `git commit` or `git push`, the hook runs `fallow audit --format json --quiet --explain --gate-marker agent`. `pass` and `warn` are allowed. `fail` is blocked, and the JSON findings are sent back to Claude on stderr so it can fix the code and retry.

<Info>
  This is Option C: local agent gate in the adoption rollout. Use it together with the shared CI gate from [fallow audit](/cli/audit), not instead of it. See [Adopt Fallow in an existing repo](/adoption#7-turn-on-pr-enforcement).
</Info>

## Install it in one command

```bash theme={null}
fallow hooks install --target agent
```

That command writes a project-level `.claude/settings.json` and `.claude/hooks/fallow-gate.sh`. It detects whether your repo also has an `AGENTS.md` or `.codex/` and, if so, adds a managed Codex fallback block to `AGENTS.md` as well; the block includes the task-to-command matrix from [`fallow schema`](/cli/schema) and refreshes on upgrade when you re-run the installer. To remove the generated artifacts later, run `fallow hooks uninstall --target agent`.

Preview first with `--dry-run`:

```bash theme={null}
fallow hooks install --target agent --dry-run
```

Output looks like this, with one line per affected path and a description of what changed:

```text theme={null}
fallow hooks install --target agent (install):
  .claude/settings.json          updated (1 handler added, 1 preserved)
  .claude/hooks/fallow-gate.sh   created
  AGENTS.md                      managed block inserted
```

<Note>
  [`fallow agent install`](/cli/agent) installs this gate together with the skill, the MCP registration, and an `AGENTS.md` task map for every harness it detects. The older `fallow setup-hooks` command is deprecated: it still works throughout fallow 3 with a warning and is removed in the next major.
</Note>

## Install globally for every repo

Pass `--user` to install the gate under your home directory instead of per-project. The settings file lands at `~/.claude/settings.json`, the hook script at `~/.claude/hooks/fallow-gate.sh`, and the emitted handler command uses `"$HOME"` in place of `"$CLAUDE_PROJECT_DIR"` so it resolves in every repo Claude Code opens:

```bash theme={null}
fallow hooks install --target agent --user
```

Project-level installs override the global one when both are present, so you can still opt a specific repo into a stricter or laxer policy.

## Gate semantics

The hook runs `fallow audit --format json --quiet --explain --gate-marker agent` and blocks the agent's `git commit` or `git push` only when the audit returns `verdict: "fail"`. The `--gate-marker agent` flag lets local [Impact tracking](/cli/impact) record blocked-then-cleared containment events when it is enabled. Audit defaults to `gate=new-only`: inherited findings on touched files are reported in `attribution` and annotated with `introduced: false` on individual issues, but they do not affect the verdict. Only findings the changeset *introduces* fail the gate.

This is the adoption-friendly default for legacy codebases: an agent editing a 10-year-old file is not punished for the existing dead exports already there, only for any new ones it adds.

To gate every finding in changed files (the strict mode), set the gate in your project config:

```toml fallow.toml theme={null}
[audit]
gate = "all"
```

Or override per invocation by editing `.claude/hooks/fallow-gate.sh` to pass `--gate all` explicitly. The script is regenerated on every `fallow hooks install --target agent` run, so prefer the config-file approach for persistence.

## Comparison base

The hook runs bare `fallow audit` with no `--base`, so audit auto-detects the comparison base as the `git merge-base` (fork point) against the branch's upstream or the remote default (`origin/main`). The merge-base is resolved at run time, so a branch freshly cut from `origin/main` is gated only on the changes it actually introduces.

Two setups want an explicit base. Set [`FALLOW_AUDIT_BASE`](/configuration/environment#fallow_audit_base) (it takes effect because the gate passes no `--base`):

* **Forks.** On a fork, `origin` is your fork and can lag the real upstream. Pin `FALLOW_AUDIT_BASE=upstream/main` so the gate compares against the true upstream.
* **A non-default integration branch.** If your team merges into `develop` (or a release branch) rather than `main`, pin `FALLOW_AUDIT_BASE=origin/develop`.

The env var is the right knob here because the generated `fallow-gate.sh` is regenerated on every `fallow hooks install --target agent` run, so an edit to the script does not survive a reinstall.

## Version floor

The installed gate enforces a minimum fallow version via the `FALLOW_GATE_MIN_VERSION` env var (default `2.85.0`). The gate passes `--gate-marker agent` (added in v2.85.0) so local Impact can record blocked-then-cleared events; older binaries reject the flag entirely, which would make every audit fail open. The gate therefore blocks with an upgrade hint when the `fallow` on `PATH` is below the floor. This prevents a stale npm-global or `~/.cargo/bin/fallow` from masquerading as a working gate.

```bash theme={null}
# Raise the floor (require a newer fallow across your team)
export FALLOW_GATE_MIN_VERSION=3.0.0

# Disable (only do this if you know why)
export FALLOW_GATE_MIN_VERSION=
```

Every block logs the binary path and version that fired it, e.g. `fallow-gate: blocked by fallow 2.48.1 at /usr/local/bin/fallow`, so "which binary ran this?" is answered without re-diagnosis. The header of the installed script also stamps `# Installer version: X.Y.Z` for forensics when the gate disagrees with your current `fallow --version`.

## Inspect hook state

`fallow hooks status` shows what is installed on all three surfaces without touching anything: the Git pre-commit hook, the Claude Code gate, and the Codex `AGENTS.md` managed block. Agents and scripts use the JSON form before proposing setup changes:

```bash theme={null}
fallow hooks status --format json
```

```json theme={null}
{
  "hooks": {
    "git":    { "installed": true,  "managed_block_present": true,  "user_edited": false, "path": ".git/hooks/pre-commit",        "script_version": null,     "min_version_floor": null },
    "claude": { "installed": true,  "managed_block_present": true,  "user_edited": false, "path": ".claude/hooks/fallow-gate.sh", "script_version": "3.1.0", "min_version_floor": "2.85.0" },
    "codex":  { "installed": false, "managed_block_present": false, "user_edited": false, "path": "AGENTS.md",                    "script_version": null,     "min_version_floor": null }
  }
}
```

`user_edited` flags a hook file that exists but no longer carries fallow's generator marker (or a torn managed block), so an agent knows not to overwrite it without asking. `script_version` and `min_version_floor` expose the gate script's installer stamp and version floor, which lets tooling detect a stale gate.

## Remove it

```bash theme={null}
fallow hooks uninstall --target agent
```

Removes the fallow-gate handler from `.claude/settings.json`, deletes the hook script if it still carries the generator marker (use `--force` to remove user-edited scripts), and strips the managed block from `AGENTS.md`. Handlers you added outside fallow stay untouched. Pass `--user` to uninstall the global artifacts at `~/.claude/` instead of the project ones.

The uninstall flow is idempotent: running it a second time prints `unchanged` / `not present` and exits 0. Dry-run is supported (`fallow hooks uninstall --target agent --dry-run`).

`fallow hooks install --target agent` also recognises and cleans up hook commands that older manual setups emitted (absolute paths, `~/`-based paths, Windows drive paths), so re-running it on a pre-existing install upgrades the handler to the canonical form without leaving duplicates.

<Note>
  Related but distinct: `fallow hooks install --target git` scaffolds a shell-level Git pre-commit hook in `.git/hooks/` that runs fallow on changed files. That is the *human* enforcement path. This page is the *agent* enforcement path. The two can be used together: git hooks catch human commits, the agent gate catches agent commits.
</Note>

## Manual setup

### 1. Create `.claude/settings.json`

```json theme={null}
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fallow-gate.sh"
          }
        ]
      }
    ]
  }
}
```

### 2. Create `.claude/hooks/fallow-gate.sh`

Copy the canonical script from the fallow repo, [`crates/cli/src/setup_hooks/fallow-gate.sh`](https://github.com/fallow-rs/fallow/blob/main/crates/cli/src/setup_hooks/fallow-gate.sh), into `.claude/hooks/fallow-gate.sh`. Omit the `# Installer version:` line (the installer stamps it for forensics). Prefer `fallow hooks install --target agent`; copy by hand only where you cannot run that command.

### 3. Make the script executable

```bash theme={null}
chmod +x .claude/hooks/fallow-gate.sh
```

<Tip>
  The hook checks `fallow` first, then falls back to `npx --no-install fallow`. Keep `jq` on PATH because the hook reads Claude's stdin JSON and Fallow's JSON output. Skip paths print one stderr line so the agent does not silently trust a missing gate.
</Tip>

<Note>
  In JSON mode, `fallow audit` reports invalid refs, non-Git directories, and config errors as `{ "error": true, ... }` with exit code `2`. The gate lets those through so a brand-new repo or empty history is not stuck before the first successful audit.
</Note>

<Warning>
  This gate runs before Claude executes the shell command, so `git push --no-verify` does not bypass it. Keep CI on `fallow audit` as the shared gate for humans and non-Claude workflows.
</Warning>

## Codex fallback

Codex now has an experimental hooks surface, but the low-friction fallback while it stabilizes is still `AGENTS.md`. Add this to your repo root `AGENTS.md`:

```md theme={null}
## Fallow local gate

Before any `git commit` or `git push`, run `fallow audit --format json --quiet --explain --gate-marker agent`. If the verdict is `fail`, fix the reported findings before retrying. Treat JSON runtime errors like `{ "error": true, ... }` as non-blocking.
```

`fallow hooks install --target agent` maintains this block for you, scoped between `<!-- fallow:setup-hooks:start -->` and `<!-- fallow:setup-hooks:end -->` markers so re-running the command is idempotent.

## Why this works well with agents

`fallow audit --explain` gives Claude structured findings with docs links and fix guidance, while [Agent Skills](/integrations/agent-skills) teaches the agent how to act on them. The result is a tight feedback loop: Claude tries to commit or push, the gate blocks only real `fail`-severity issues, Claude reads the JSON envelope, fixes the code, and retries.

<CardGroup>
  <Card title="Adoption rollout" icon="rocket" href="/adoption#7-turn-on-pr-enforcement">
    See Option C: local agent gate next to warn-everywhere and error-plus-baselines.
  </Card>

  <Card title="fallow audit" icon="shield-check" href="/cli/audit">
    Reference for verdicts, JSON output, and baselines.
  </Card>

  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/integrations/agent-skills">
    Teach the agent what to do after the gate blocks.
  </Card>
</CardGroup>


# Integrations
Source: https://docs.fallow.tools/integrations/index

Use Fallow from agents, editors, and CI systems. MCP, VS Code, GitHub Actions, and GitLab CI.

Fallow runs in three common places:

* **Agents**: structured output and MCP tools
* **Editors**: real-time feedback while coding
* **CI**: review and merge gating

<CardGroup>
  <Card title="MCP" icon="robot" href="/integrations/mcp">
    Typed tool calling for Claude Code, Cursor, Windsurf, and other agents.
  </Card>

  <Card title="Agent Skills" icon="sparkles" href="/integrations/agent-skills">
    Reusable agent guidance and workflows.
  </Card>

  <Card title="VS Code" icon="window" href="/integrations/vscode">
    Diagnostics, Code Lens above exports, and one-click code actions.
  </Card>

  <Card title="Neovim" icon="terminal" href="/integrations/neovim">
    Real-time diagnostics through Neovim's built-in LSP client.
  </Card>

  <Card title="CI" icon="shield-check" href="/integrations/ci">
    GitHub Actions, GitLab CI, and generic pipelines.
  </Card>

  <Card title="Health badges" icon="award" href="/integrations/badges">
    Shields.io-compatible SVG badges for README files.
  </Card>
</CardGroup>

## Recommended starting point

* If you are a **developer**, start with the CLI, then add VS Code.
* If you are using **agents**, start with CLI JSON output, then add MCP.
* If you are rolling out to a **team**, start with CI, then layer in runtime intelligence later.


# Agent integration
Source: https://docs.fallow.tools/integrations/mcp

Integrate fallow with AI agents via CLI and MCP. Unused code, duplication, complexity hotspots, boundary violations, and auto-fix in Claude Code, Cursor, and Windsurf.

AI coding agents generate code at scale, but they don't perform codebase-level analysis. Building a module graph, tracing re-export chains, detecting duplication across thousands of files, scoring complexity hotspots: these require a dedicated tool. Fallow provides deterministic, exhaustive codebase analysis that agents call via CLI or MCP.

<Info>
  Every agent that can run shell commands can use fallow. The CLI is the primary interface. MCP is an optional structured layer on top.
</Info>

## Why agents need fallow

Codebase analysis means building and traversing a graph, not reading files in a context window.

| What agents can't do                                             | What fallow does                                        |
| :--------------------------------------------------------------- | :------------------------------------------------------ |
| Build a complete module graph across thousands of files          | Builds and caches the full graph in one pass            |
| Track re-export chains through barrel files                      | Resolves `export *` chains through unlimited levels     |
| Know if an export is used somewhere outside their context window | Exhaustively checks every import in the entire codebase |
| Detect code duplication across files they haven't seen           | Suffix array algorithm catches clones across all files  |
| Determine which `package.json` dependencies are actually unused  | Traces imports and script binaries to actual usage      |
| Guarantee completeness (no missed files, no false negatives)     | Deterministic: same input always produces same output   |

## CLI: the primary agent interface

Every AI coding agent can run shell commands. No MCP required:

```bash theme={null}
# Full dead code analysis with JSON output
fallow dead-code --format json

# Only check changed files (great for agent PR workflows)
fallow dead-code --changed-since main --format json

# Find code duplication
fallow dupes --format json

# Preview what auto-fix would remove
fallow fix --dry-run --format json

# Apply fixes (agents should use --yes to skip confirmation)
fallow fix --yes --format json

# Detect feature flags and environment gates
fallow flags --format json

# List project info (plugins, entry points, file count)
fallow list --format json
```

<Tip>
  Always use `--format json` when agents run fallow. JSON output is structured, machine-readable, and easy for LLMs to parse. The human-readable format works too, but JSON eliminates parsing ambiguity.
</Tip>

<Tip>
  Consuming fallow's JSON output from TypeScript? `import type { CheckOutput, HealthOutput, DupesOutput, AuditOutput } from "fallow/types"` exposes the full output contract, generated from the same schema fallow uses internally. `SchemaVersion` is pinned to a literal at codegen time so major schema bumps fail to compile at your call sites instead of silently drifting.
</Tip>

## MCP: structured tool calling

For agents that support <Tooltip>[MCP (Model Context Protocol)](https://modelcontextprotocol.io)</Tooltip>, `fallow-mcp` exposes analysis as structured tools. Agents get typed inputs and outputs instead of parsing CLI text.

The MCP server uses <Tooltip>stdio transport</Tooltip> and a hybrid adapter. Supported requests run in process, while command-owned options use a managed `fallow` CLI subprocess. Set `FALLOW_BIN` only when CLI-backed calls need a specific binary (defaults to `fallow` in `PATH`).

Install with `cargo install fallow-mcp` or grab a binary from [GitHub Releases](https://github.com/fallow-rs/fallow/releases).

<Tabs>
  <Tab title="Claude Code">
    Register the server with the Claude Code CLI, which writes the configuration for you:

    ```bash theme={null}
    # Available in every project on this machine
    claude mcp add fallow --scope user fallow-mcp

    # This repository only, checked in for the whole team
    claude mcp add fallow --scope project fallow-mcp
    ```

    `--scope project` creates `.mcp.json` in the repository root. [`fallow agent install`](/cli/agent) writes the same entry for every detected harness, probing for a working launcher first. You can also write the file by hand:

    ```json theme={null}
    {
      "mcpServers": {
        "fallow": {
          "command": "fallow-mcp"
        }
      }
    }
    ```

    Run `claude mcp list` to confirm fallow is registered.

    <Warning>
      Claude Code does not read `mcpServers` from `.claude/settings.json`. A server defined there is ignored without an error, so use `.mcp.json` or `claude mcp add`.
    </Warning>
  </Tab>

  <Tab title="Cursor">
    Cursor reads MCP servers from `mcp.json`. Create `.cursor/mcp.json` in the project root to scope fallow to one project, or `~/.cursor/mcp.json` in your home directory to make it available everywhere:

    ```json theme={null}
    {
      "mcpServers": {
        "fallow": {
          "command": "fallow-mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other MCP clients">
    Any MCP-compatible client can connect to `fallow-mcp`. The server uses stdio transport:

    ```bash theme={null}
    # Start the MCP server directly
    fallow-mcp

    # With a custom fallow binary path
    FALLOW_BIN=/usr/local/bin/fallow fallow-mcp
    ```

    Configure your client to launch `fallow-mcp` as a stdio subprocess.
  </Tab>
</Tabs>

<Note>
  **Installed fallow as a project devDependency?** `"command": "fallow-mcp"` assumes the binary is on your `PATH` (a global install). When fallow lives in `node_modules/.bin/`, it is not on `PATH`, so the server fails to start with `ENOENT`. Launch it through your package manager's runner so the binary resolves from `node_modules/.bin/`:

  <CodeGroup>
    ```json npm theme={null}
    {
      "mcpServers": {
        "fallow": {
          "command": "npx",
          "args": ["fallow-mcp"]
        }
      }
    }
    ```

    ```json pnpm theme={null}
    {
      "mcpServers": {
        "fallow": {
          "command": "pnpm",
          "args": ["exec", "fallow-mcp"]
        }
      }
    }
    ```

    ```json yarn theme={null}
    {
      "mcpServers": {
        "fallow": {
          "command": "yarn",
          "args": ["fallow-mcp"]
        }
      }
    }
    ```

    ```json bun theme={null}
    {
      "mcpServers": {
        "fallow": {
          "command": "bunx",
          "args": ["fallow-mcp"]
        }
      }
    }
    ```
  </CodeGroup>

  Start the agent from the project root so the runner finds the local install. If you need an explicit fallow binary, keep setting `FALLOW_BIN`.
</Note>

### Available MCP tools

| Tool                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `analyze`                   | Full dead code analysis (`fallow dead-code --format json`). Detects unused files, exports, types, dependencies, enum/class members, unresolved imports, unlisted dependencies, duplicate exports, circular dependencies, re-export cycles (barrel files that form a structural loop, silently breaking re-exports), boundary violations, framework component findings (unused props, emits, inputs, outputs, Svelte events, unrendered components, and unprovided injects), rule-pack policy violations (banned calls and banned imports declared via the `rulePacks` config key), stale suppressions, unused pnpm catalog entries, empty pnpm catalog groups, and unresolved pnpm catalog references (consumer `package.json` references a catalog that does not declare the package; `pnpm install` would fail). Private type leaks are opt-in via `issue_types: ["private-type-leaks"]`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `check_changed`             | Incremental analysis of changed files (`fallow dead-code --changed-since`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `security_candidates`       | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, severity, evidence, trace, optional `reachability`, blind-spot counters, and optional `unresolved_callee_diagnostics` samples for dynamic callee follow-up. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), where URL-category sinks may include `url_shape` (`fixed-origin-dynamic-path` or `dynamic-origin`), an optional `taint_flow` source-to-sink triple, and a stable `finding_id` (equal to the SARIF fingerprint) for cross-run correlation; there is no `impact` field (deciding exploitability is the agent's job). Set `surface: true` to include top-level `attack_surface[]` entries with defensive-boundary prompts for a verifier. Set `gate` to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires `changed_since`. `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow; `reachability.taint_confidence` tiers each reachable candidate as `arg-level` (sink argument traces to a same-module source read, strong) or `module-level` (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `surface`, `gate`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, untrusted-source reachability trace hops, and unresolved-callee diagnostics. See [Security agent verification](/cli/security-agent-verification) for the verifier packet and verdict recipe. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `inspect_target`            | Compose one evidence bundle for a file or exported symbol. File targets use `target: { type: "file", file }`; symbol targets use `target: { type: "symbol", file, export_name }`. Returns `kind: "inspect_target"`, normalized target identity, `trace_file`, optional `trace_export`, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, and security candidates scoped to the file. Evidence sections carry `status` and `scope`; symbol targets warn when supporting evidence is file-scoped. Set the opt-in `symbol_chain: true` option to also attach the best-effort symbol-level call chain (the same data as [`fallow trace`](/cli/trace)) as a `symbol_chain` evidence section; only meaningful for a symbol target, default off (best-effort, syntactic, off the ranked path). Supports `root`, `config`, `production`, `workspace`, `no_cache`, and `threads`; `production` applies to trace, dead-code, and health evidence only. Raise `FALLOW_TIMEOUT_SECS` for large repos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `code_execute`              | Bounded read-only Code Mode for composing multiple fallow analysis calls in one JavaScript snippet. The snippet receives `{ fallow, root }`, returns JSON-serializable data, and can call read-only helpers such as `fallow.projectInfo`, `fallow.audit`, `fallow.checkHealth`, and `fallow.run(tool, params)` for the same allowlist. Mutating fix tools are not exposed. The sandbox has no filesystem, network, imports, `eval`, `Function`, `process`, `require`, `Deno`, `Bun`, or shell access. Params: `code`, optional `root`, `timeout_ms` (capped at 30000), and `max_output_bytes` (capped at 4000000).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `find_dupes`                | Code duplication detection (`fallow dupes --format json`). Each clone group carries a stable `fingerprint` and numeric `spread`; near-miss groups also carry `similarity`. Pass `near: true` to include function-scoped near-miss clones. Use the fingerprint with `trace_clone` to inspect a group. Import declarations are excluded by default; pass `ignore_imports: false` to count them again. `stats.clone_groups_ignored` reports config-filtered groups, while `stats.near_candidates_skipped` signals bounded near-miss comparisons that were skipped. Clone instances omit their verbatim source text by default; pass `include_fragments: true` to get it back.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `find_similar_code`         | Read-only semantic function discovery through the pinned local model (`fallow similar-code --format json --quiet`). Returns unverified candidates with provider and model provenance, completion, limits, skips, and cache accounting. Scope with `files`, `workspace`, `changed_since`, `changed_workspaces`, `threshold`, `min_lines`, or `top`. The score is not a probability or verdict. The tool never downloads a model. If setup is missing, ask the user to run `fallow similar-code setup --local`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `inspect_similar_code`      | Reproduce one `candidate_id` and return bounded source, graph, ownership, churn, test, deterministic-duplication, and side-effect evidence. Read-only. Use it before judging a candidate and abstain when evidence is unavailable. The tool does not write verdicts or edit source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `fix_preview`               | Dry-run auto-fix preview (`fallow fix --dry-run --format json`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `fix_apply`                 | Apply auto-fixes (`fallow fix --yes --format json`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `guard`                     | Report the architecture rules that apply to given files before editing them: boundary zone, allowed import zones, forbidden calls, and rule-pack policies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `check_health`              | Complexity metrics, file health scores, hotspots, and refactoring targets (`fallow health --format json`). Set `file_scores: true` for maintainability index, `hotspots: true` for churn analysis, `targets: true` for ranked recommendations sorted by efficiency, `trend: true` for per-metric deltas against the most recent snapshot. Set `complexity_breakdown: true` to add a per-decision-point `contributions[]` array to each complexity finding (each `else-if`, nested `if`, boolean operator, loop, `case`, etc. with its source line and cyclomatic/cognitive weight) so you can explain WHY a function scored high and pinpoint which lines to refactor. Set `css: true` to add a `css_analytics` section: structural CSS slop that per-rule linters do not aggregate (specificity hotspots, `!important` density, deep nesting, design-token sprawl) plus cleanup candidates (unreferenced custom properties / `@keyframes`, dead Vue `<style scoped>` classes, unused `@property` / `@layer`, Tailwind arbitrary-value bypasses, Tailwind v4 `@theme` `unused_theme_tokens`, duplicate declaration blocks) and undefined-reference candidates, each with a read-only verification step in its `actions[]`. It also adds `token_consumers`, a reverse index of where each design token is consumed (per token a `consumer_count` plus a located `consumers[]` sample) so an agent can read a token's blast radius before changing it; it covers Tailwind v4 `@theme` tokens (`kind` `theme-var` / `css-var` / `utility` / `apply`) and CSS-in-JS token definitions: StyleX `defineVars`, vanilla-extract `createTheme`-family definitions, and PandaCSS `defineTokens` (`token` is binding-qualified; `kind` is `js-member` for member access and `js-call` for Panda `token(...)` calls). `consumer_count` is a static lower bound (a computed class name like `bg-${c}`, dynamic import strings, unresolved aliases, generated package state, or computed token access can still be invisible) and the field is descriptive context, not a finding (no `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. Set `churn_file` to a `fallow-churn/v1` JSON path to drive hotspots/ownership/targets from imported VCS history instead of git, for projects with no git repository (Yandex Arc, Mercurial, Perforce); the file is authoritative for the window, so `since` then only labels output. Set `runtime_coverage` to merge a V8 or Istanbul coverage dump; tune it with `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), and `low_traffic_threshold` (default 0.001). Set `group_by` to `owner`, `directory`, `package`, or `section` to partition results: each group gets its own `vital_signs`, `health_score`, and optional `coverage_source_consistency` recomputed from the group's files (top-level metrics stay project-wide), SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field. Findings include a bucketed `coverage_tier` (`none`/`partial`/`high`) and `coverage_source` for CRAP-triggered entries; `summary.coverage_source_consistency` reports whether those sources are uniform or mixed. Actions pick `add-tests` / `increase-coverage` when coverage can still clear CRAP, or `refactor-function` when cyclomatic >= maxCrap, see "Structured actions" below. |
| `check_runtime_coverage`    | Merge runtime-coverage data into the health report. Required `coverage` param accepts a V8 coverage directory, a single V8 coverage JSON, or an Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring (a V8 directory containing multiple JSON files) requires an active license JWT. Tunable via `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), `low_traffic_threshold` (default 0.001), `max_crap` (default 30.0), `top`, and `group_by`. Protocol-0.3+ sidecars emit a `summary.capture_quality` block flagging short-window captures. Cloud runtime rows can expose `resolutionStatus` / `mappingQuality` on function-list JSON and `resolution_status` / `mapping_quality` in runtime-context JSON. Use the confidence table below before acting on file-level runtime signals. Can exceed the default 120s timeout on large dumps; raise `FALLOW_TIMEOUT_SECS` accordingly. Pick this over `check_health` when you have a coverage dump.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `get_hot_paths`             | Runtime-context slice over the same local runtime coverage pipeline. Same input schema and free-vs-paid contract as `check_runtime_coverage`; read `runtime_coverage.hot_paths` for production hot paths sorted by percentile and invocation count.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `get_blast_radius`          | Runtime-context slice for blast-radius review. Same input schema and free-vs-paid contract as `check_runtime_coverage`; read `runtime_coverage.blast_radius` for stable `fallow:blast:<hash>` IDs, caller counts, traffic-weighted caller reach, optional cloud deploy touch counts, and low/medium/high risk bands.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `get_importance`            | Runtime-context slice for production-importance review. Same input schema and free-vs-paid contract as `check_runtime_coverage`; read `runtime_coverage.importance` for stable `fallow:importance:<hash>` IDs, invocations, cyclomatic complexity, owner count, 0-100 score, and templated reason.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `get_cleanup_candidates`    | Runtime-context slice for cleanup review. Same input schema and free-vs-paid contract as `check_runtime_coverage`; read `runtime_coverage.findings` for `safe_to_delete`, `review_required`, `low_traffic`, and `coverage_unavailable` verdicts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `get_cloud_runtime_context` | Runtime-context slice backed by fallow cloud instead of a local dump (`fallow coverage analyze --cloud --format json`), and the only fallow MCP tool that makes a network call. Required `repo` (`owner/repo`); `project_id`, `period_days` (1 through 90, default 30), `environment`, and `commit_sha` narrow the cloud selection, while `production`, `top`, and `min_invocations_hot` behave as on `check_runtime_coverage`. The key is `FALLOW_API_KEY` in the server environment and never a parameter: without one the call is refused before anything runs, with `code: "cloud_api_key_missing"`. Returns the same `runtime_coverage` block the local tools return, joined against the checkout at `root`, so a `root` on a different revision quietly empties `findings` and raises a `cloud_functions_unmatched` warning. Confirm `runtime_coverage.summary.data_source` is `cloud`, and read the source-map confidence table below before acting on file-level signals.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `get_token_blast_radius`    | Design-token blast radius from static analysis (free, no runtime dump). Runs `fallow health --css --format json`; read `css_analytics.token_consumers` for, per token, its defining site plus a `consumer_count` and a capped located `consumers[]` sample of `{path,line,kind}`. Covers Tailwind v4 `@theme` tokens (`token` is the `--`-prefixed custom property; `kind` `theme-var` / `css-var` / `utility` / `apply`) plus CSS-in-JS token definitions: StyleX `defineVars`, vanilla-extract `createTheme` / `createThemeContract` / `createGlobalTheme`, and PandaCSS `defineTokens`. StyleX and vanilla-extract consumers use binding-qualified dotted paths like `vars.color.primary` with `kind` `js-member`; PandaCSS consumers use token paths like `tokens.colors.brand` with `kind` `js-call`. A focused entry point so you do not need `css=true` on `check_health`. `consumer_count` is a static lower bound (a computed class name like `bg-${c}`, dynamic import strings, unresolved aliases, generated package state, or computed token access can still be invisible), so use it to size the impact of editing or renaming a token, not to decide deletion; the Tailwind dead-token verdict stays on `unused_theme_tokens`, and CSS-in-JS tokens have no dead-token finding (so a CSS-in-JS `consumer_count` of 0 is weaker).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `audit`                     | Audit changed files for dead code, complexity, duplication, and styling ([`fallow audit --format json`](/cli/audit)). Returns a verdict (pass/warn/fail). Set `base` to specify the comparison ref, `gate` to `new-only` or `all`, and `include_entry_exports=true` to also catch typos in entry-file exports (`meatdata` vs `metadata`). Set `coverage` to an Istanbul `coverage-final.json` path (and absolute `coverage_root` when paths need rebasing for CI / Docker checkouts) for accurate per-function CRAP scoring in the health sub-analysis. Styling analytics are included by default in audit, including `styling_findings` and `css_analytics` when the project has CSS or CSS-in-JS evidence. Set `css_deep=false` to skip project-wide styling reachability, or `css_deep=true` to force it back on when config disables it. Set `runtime_coverage` (V8 dir / V8 JSON / Istanbul JSON) to fold runtime-coverage findings into the same audit invocation; tune with `min_invocations_hot` (default 100). When `FALLOW_DIFF_FILE` or `FALLOW_CHANGED_SINCE` is set in the agent's env, `runtime_coverage.verdict` promotes `hot-path-touched` over `cold-code-detected` for PR-review contexts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `decision_surface`          | Surface the few consequential structural decisions a change embeds (coupling, public API, dependency), each as a judgment question with the routed expert; ranked, capped, and signal\_id-anchored. Reads the same graph-derived [review brief](/cli/audit#review-brief-and-decision-surface) as `fallow review` (the brief path of `fallow audit`). Returns the decision surface with exactly three shippable categories: `coupling-boundary` (a new cross-zone dependency edge), `public-api-contract` (a new exported public-API surface, or a changed contract consumed by modules outside this diff), and `dependency` (a new third-party dependency). Each decision is anchored to a `signal_id` fallow deterministically derived from the graph, ranked by consequence (blast radius x reversibility), paired with the routed expert (who to ask), and may carry `previous_signal_id` (the id the anchor had before a `git mv`, so a review surface can re-attach a prior comment across a rename). Each decision also carries a `tradeoff` clause (the named structural sacrifice stated as a fact, e.g. "Couples app to infra; N in-repo modules already depend on this anchor") and `internal_consumer_count` (the honest per-anchor count of in-repo modules outside the diff that already depend on it, the display number you read reversibility from, distinct from the ranking-only `blast`). Set `base` to specify the comparison ref and `max_decisions` to cap the surfaced decisions (default 4, clamped to a 3 to 5 band). The brief always exits 0; the verdict is carried informationally and never gates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `fallow_explain`            | Explain one issue type without running analysis ([`fallow explain <issue-type> --format json`](/cli/explain)). Returns rationale, example, fix guidance, and docs URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `project_info`              | Project metadata, including plugins, files, and entry points (`fallow list --format json`). Set `entry_points`, `files`, `plugins`, or `boundaries` to `true` to request specific sections.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `recommend`                 | Recommend a project-tailored fallow config for cold-start onboarding (`fallow recommend --format json`). Read-only: from framework / workspace / tooling detection it returns a loader-validated `proposed_config` you can write as-is, plus a `decisions[]` list that classifies each setting as `auto` (decided from detection, applied silently), `default` (a disclosed, overridable default with a rationale), or `taste` (a genuinely subjective choice surfaced as an `AskUserQuestion`-shaped prompt with no baked-in answer). Detected TypeScript projects receive an informational `typeAware.enabled` decision with the opt-in command, cost boundary, and guide link; it is never written into `proposed_config`. `root`-only; writing no config at all is a valid outcome.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `feature_flags`             | Detect feature flag patterns in the codebase ([`fallow flags --format json`](/cli/flags)). Identifies environment variable flags, SDK calls from common providers, and config object patterns. Set `top` to limit results.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `list_suppressions`         | List active fallow-ignore suppression markers grouped per file with line, kind, level, reason, and a stale cross-reference ([`fallow suppressions --format json`](/cli/suppressions)). A read-only governance inventory for seeing what a clean verdict is hiding, not a gate: always exits 0 even when suppressions exist. Scope with `workspace`, `changed_since` (the natural pull-request review scope), or repeated `file` entries. Runs a full analysis, so raise `FALLOW_TIMEOUT_SECS` on large repos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `list_boundaries`           | Architecture boundary zones and access rules (`fallow list --boundaries --format json`). Returns zone definitions, access rules, per-zone file counts, and `logical_groups[]` (pre-expansion `autoDiscover` parents with verbatim paths, discovered children, a `status` enum (`ok` / `empty` / `invalid_path`), summed `file_count`, optional `authored_rule`, optional `fallback_zone` cross-reference for the Bulletproof case, optional `merged_from` for duplicate parent declarations, optional `original_zone_root` echo for monorepo subtree scopes, and optional `child_source_indices` attribution for multi-path autoDiscover). Returns `{"configured": false}` if no boundaries are configured.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `trace_export`              | Trace why an export is used or unused (`fallow dead-code --trace FILE:EXPORT_NAME --format json`). Required `file` and `export_name` params. Returns file reachability, entry-point status, direct references, re-export chains, and a reason string. If `export_name` is a class / enum / store MEMBER rather than a top-level export, returns a member trace instead (`member_name`, `member_kind`, `owner_export`, `owner_is_used`) reporting the owning declaration's reachability and usage plus a pointer to the matching `--unused-<kind>-members` command; branch on field presence (`export_name` vs `member_name`). Use before deleting a supposedly-unused export or debugging an unused-class-member finding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `trace_symbol`              | Trace exact TypeScript symbol references, namespaces, aliases, and re-export hops (`fallow dead-code --type-aware --trace FILE:EXPORT --format json --quiet`). Required `file` and `export_name`; optional `type_aware_projects` and `type_aware_require` (`best-effort` or `complete`). This adds semantic proof to Fallow's project-wide usage evidence without returning TypeScript compiler diagnostics or lint findings.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `symbol_impact`             | Return exact-symbol consumers, transitive affected files, and targeted tests for a TypeScript export (`fallow dead-code --type-aware --symbol-impact FILE:EXPORT --format json --quiet`). Required `file` and `export_name`; optional `type_aware_projects` and `type_aware_require` (`best-effort` or `complete`). Use it to plan a rename, deletion, or API change. It is advisory change-impact evidence, not a substitute for `tsc` or Oxlint.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `trace_file`                | Trace all graph edges for a file (`fallow dead-code --trace-file PATH --format json`). Required `file` param. Returns reachability, entry-point status, exports, imports-from, imported-by, and re-exports. Use to decide whether a file is isolated, barrel-only, or imported by live entry points.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `trace_dependency`          | Trace where a dependency is imported (`fallow dead-code --trace-dependency PACKAGE --format json`). Required `package_name` param. Returns importing files, type-only importers, total import count, `used_in_scripts` (true when invoked from `package.json` scripts or CI configs like `.github/workflows/*.yml` / `.gitlab-ci.yml`), and `is_used` (combined import + script signal, mirrors the unused-deps detector so build tools like `microbundle` or `vitest` invoked only via scripts are correctly classified as used). Use before removing a dependency or moving it between `dependencies` and `devDependencies`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `trace_clone`               | Deep-dive a duplicate-code clone group (`fallow dupes --trace <spec> --format json`). Address it by exactly one of: `file` + `line` (a source location), or `fingerprint` (a `dup:<id>` from a prior `find_dupes` result). Returns the matched instance plus every clone group containing it. Each traced group carries its `fingerprint`, an extract-function `suggestion`, and an optional `suggested_name`. Supports `mode`, `near`, `min_tokens`, `min_lines`, `threshold`, `skip_local`, `cross_language`, and `ignore_imports`. Use the same `near` value as the originating `find_dupes` call when tracing a near-miss group.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `trace_import_path`         | Shortest import path between two modules (`fallow trace --path FROM TO --format json`). Required `from` and `to` file params. Returns `reachable`, `hops`, and a `path` array of import hops carrying `type_only` and `import_line`. An unreachable pair is a result, not an error: `reachable` is `false` with an empty `path`. The same module both ways answers `reachable: true`, and both cases report `hops: 0`, so branch on `reachable` rather than the count. Use it to see how one module ends up depending on another.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `trace_error`               | Resolve a runtime stack trace's frames to the definitions they name (`fallow trace-error --format json`). Paste the trace text in the required `trace` param, with an optional `source` label. Classifies every frame as `in_project`, `node_modules`, or `out_of_corpus`, then resolves the in-project ones. A frame matching several definitions reports `ambiguous` and lists them; a frame matching nothing reports `not_found`; a frame never asked about reports `not_attempted`. No source maps are read, so a frame in generated build output is reported as such. See [`fallow trace-error`](/cli/trace-error).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `impact`                    | Read the local, opt-in Fallow Impact value report (`fallow impact --format json`). Runs no analysis: reports current surfacing counts, the trend since the last recorded run, pre-commit gate containment, and (on impact v1.5+) resolved/suppressed attribution. History is read from a per-project file in the user's private config dir (never inside the repo). Read-only and `root`-only (no `config` / `no_cache` / `threads`); the mutating `enable` / `disable` / `default` lifecycle is not exposed. The report carries `enabled_source` (`project` / `user` / `default`); on a project where tracking was never enabled it returns a populated `{"enabled": false, ...}` report (never `{}`), so an agent branches on `enabled` and `enabled_source` then `record_count`, recommending `fallow impact enable` only when `explicit_decision` is `false` (never asked), and staying silent when `true` (deliberately disabled here). Local-developer signal: fallow never records in CI, so there it returns an empty report and is not a CI metric.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `impact_closure`            | Trace the impact closure for one file (`fallow dead-code --impact-closure <path> --format json`). Returns the transitive affected-but-not-in-diff set plus coordination gaps for consumers of the file contract. Supports `path`, `root`, `config`, `production`, `workspace`, `no_cache`, and `threads`; use it as review-planning evidence, not proof that affected files are wrong.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `impact_all`                | Roll every tracked project on this machine into one cross-repo value report (`fallow impact --all --format json`). Runs no analysis: reads the per-project histories in the user config dir and returns `kind: "impact-cross-repo"` with `project_count`, `tracked_count`, `unreadable_count`, a `totals` roll-up summed over all tracked projects (including repos since deleted from disk), and a `projects[]` array. Each row carries a hashed `project_key` (never a filesystem path; always present), an optional human `label` (the repo's folder basename; omitted on rows from older stores, so fall back to `project_key`), `last_recorded`, and the same per-project `report` shape as `impact`. Use this for a portfolio view; use `impact` (with `root`) for one project. `sort` orders rows (`recent` default / `resolved` / `contained` / `name`); `limit` caps rows while `totals` still cover every project. Projects enabled but with no recorded history are counted but not listed. Read-only; the mutating enable / disable / default / reset lifecycle is not exposed. Local-developer signal: empty in CI, not a CI metric.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### Runtime source-map confidence

Cloud runtime tools can include source-map confidence metadata when the response `capabilities` array contains `function_identity_v2`. Function list responses use `resolutionStatus` and `mappingQuality`; runtime-context responses use `resolution_status` and `mapping_quality`. These fields describe source-map confidence, not whether the function ran.

| Values                | Meaning                                                            | Agent action                                                                                                                   |
| :-------------------- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `resolved` + `high`   | The source map resolved the generated position to original source. | Trust the file path and line number. Reference the original source confidently.                                                |
| `fallback` + `medium` | A source map exists, but it did not cover this generated position. | Treat the file-level signal as approximate. Ask the developer to rebuild with denser source maps before making a precise edit. |
| `unresolved` + `low`  | No matching source map was uploaded for this bundle and commit.    | Ask the operator to upload the source map before acting on file-level coverage signals.                                        |
| `null` + `null`       | The row does not include source-map confidence metadata.           | Treat the row as missing confidence metadata. Do not downgrade it to `low` without other evidence.                             |

<CodeGroup>
  ```json Example request theme={null}
  {
    "tool": "analyze",
    "arguments": {
      "production": true,
      "issue_types": ["unused-exports", "unused-files"]
    }
  }
  ```

  ```json Example response theme={null}
  {
    "schema_version": 9,
    "version": "3.24.1",
    "elapsed_ms": 42,
    "total_issues": 1,
    "unused_exports": [
      {
        "path": "src/utils/format.ts",
        "export_name": "formatCurrency",
        "is_type_only": false,
        "line": 12,
        "col": 0,
        "span_start": 280,
        "is_re_export": false
      }
    ]
  }
  ```
</CodeGroup>

### Notable tool parameters

Some tools accept additional parameters beyond the common `root`, `config`, `no_cache`, and `threads`:

| Tool                                         | Parameter               | Type            | Description                                                                                                                                                                                                                                                                                                                                          |
| :------------------------------------------- | :---------------------- | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `analyze`                                    | `boundary_violations`   | bool            | Convenience alias for `issue_types: ["boundary-violations"]`                                                                                                                                                                                                                                                                                         |
| `find_dupes`                                 | `changed_since`         | string          | Only report duplication in files changed since a git ref                                                                                                                                                                                                                                                                                             |
| `find_dupes` / `trace_clone`                 | `near`                  | bool            | Include function-scoped near-miss clones with small structural edits. Default `false`.                                                                                                                                                                                                                                                               |
| `find_dupes`                                 | `include_fragments`     | bool            | Include the verbatim source text on each clone instance. Default `false`: `file` plus the line and column range address the same code, and the text is most of the response. Set it `true` only when you need the source without reading the files.                                                                                                  |
| `find_dupes` / `trace_clone`                 | `min_occurrences`       | integer (≥ 2)   | Minimum number of occurrences before a clone group is reported. Default 2. Raise to skip pair-only clones and focus on widespread copy-paste worth refactoring. JSON output gains `stats.clone_groups_below_min_occurrences` when the filter hides anything.                                                                                         |
| `find_similar_code` / `inspect_similar_code` | `threshold`             | number (0 to 1) | Model-specific discovery cutoff. It is not a probability or quality gate.                                                                                                                                                                                                                                                                            |
| `find_similar_code` / `inspect_similar_code` | `min_lines` / `top`     | integer         | Exclude tiny functions and cap returned candidates.                                                                                                                                                                                                                                                                                                  |
| `find_similar_code` / `inspect_similar_code` | `files`                 | string\[]       | Keep candidate pairs touching one of these root-relative files.                                                                                                                                                                                                                                                                                      |
| `inspect_similar_code`                       | `candidate_id`          | string          | Required immutable candidate ID from `find_similar_code`.                                                                                                                                                                                                                                                                                            |
| `security_candidates`                        | `gate`                  | string          | `new` gates changed-line candidates; `newly-reachable` gates candidates that became reachable from entry points and requires `changed_since`.                                                                                                                                                                                                        |
| `audit`                                      | `gate`                  | string          | `new-only` gates only introduced findings; `all` gates every finding in changed files                                                                                                                                                                                                                                                                |
| `audit`                                      | `css_deep`              | bool            | Controls audit deep styling reachability. Omit it for the default project-wide styling pass, set `false` to skip project-wide styling reachability, or set `true` to force `--css-deep` when config disables it.                                                                                                                                     |
| `audit` / `check_health`                     | `coverage`              | string          | Path to Istanbul-format `coverage-final.json` for accurate per-function CRAP scores. Resolution is consistent on typed and CLI-backed routes: an explicit tool parameter wins, followed by `FALLOW_COVERAGE`, then `health.coverage` from config.                                                                                                    |
| `audit` / `check_health`                     | `coverage_root`         | string          | Absolute prefix to strip from file paths in coverage data before prepending the project root. Use when coverage was generated under a different checkout root in CI or Docker. Resolution is consistent on typed and CLI-backed routes: an explicit tool parameter wins, followed by `FALLOW_COVERAGE_ROOT`, then `health.coverageRoot` from config. |
| `analyze` / `check_changed` / `audit`        | `include_entry_exports` | bool            | Also report unused exports in entry files. Catches typos in framework-convention exports (e.g. `meatdata` vs `metadata`). ORs with the `includeEntryExports` config value.                                                                                                                                                                           |
| `fallow_explain`                             | `issue_type`            | string          | Issue type token or rule id to explain                                                                                                                                                                                                                                                                                                               |
| `project_info`                               | `entry_points`          | bool            | Request detected entry points                                                                                                                                                                                                                                                                                                                        |
| `project_info`                               | `files`                 | bool            | Request all discovered source files                                                                                                                                                                                                                                                                                                                  |
| `project_info`                               | `plugins`               | bool            | Request active framework plugins                                                                                                                                                                                                                                                                                                                     |
| `project_info`                               | `boundaries`            | bool            | Request architecture boundary zones and rules                                                                                                                                                                                                                                                                                                        |
| `analyze`                                    | `group_by`              | string          | Group output by `owner` (CODEOWNERS), `directory` (first path component), `package` (workspace), or `section` (GitLab CODEOWNERS `[Section]` headers, with `owners` metadata per group)                                                                                                                                                              |

### Structured actions in tool responses

All tools return structured `actions` arrays on every finding, enabling agents to programmatically apply fixes or suppressions:

* **Dead code** (`analyze`, `check_changed`): fix action (e.g. `remove-export`) + suppress action. Agents can use the `auto_fixable` flag to decide whether to call `fix_apply` or handle the suggestion manually. See the [dead-code CLI reference](/cli/dead-code#fix-suggestions-in-json-output) for action type details.
* **Health** (`check_health`, `audit`): complexity findings and styling findings carry an `actions` array. Complexity findings select their primary action with the CRAP/coverage formula keyed off `coverage_tier`, `cyclomatic`, and `max_crap_threshold`; possible action types include `refactor-function`, `add-tests`, `increase-coverage`, and `suppress-line`. Styling findings use styling-specific read-only verification and suppression actions. When `--baseline`/`--save-baseline` is passed OR `health.suggestInlineSuppression: false`, `suppress-line` is omitted and a top-level `actions_meta: { suppression_hints_omitted: true, reason }` breadcrumb is added (under `health.actions_meta` in combined-mode and audit output). Targets get `apply-refactoring` + suppress (when evidence exists). Hotspots get `refactor-file` + `add-tests`.
* **Duplication** (`find_dupes`, `audit`): `extract-shared` + suppress actions on clone families and groups.
* **Audit** (`audit`): inherits actions from all three sub-analyses (dead code, health, duplication).

### Command-level `next_steps[]`

Distinct from the per-finding `actions[]`, the `analyze`, `check_health`, `find_dupes`, and `audit` responses (and combined output) carry a top-level `next_steps[]` array of read-only follow-up commands computed from the run's findings. Each entry is `{ id, command, reason }`:

* `command` is runnable as-is and never a fix or any other mutating command (fallow surfaces evidence; deciding and applying the change is the agent's job).
* The stable kebab-case `id` (`setup`, `impact-report`, `trace-unused-export`, `trace-clone`, `complexity-breakdown`, `scope-workspaces`, `audit-changed`) names a verification step to run before acting. When working through MCP, dispatch on the `id` to the matching tool (`trace_export`, `trace_clone`, `check_health` with `complexity_breakdown: true`, `audit`) or `code_execute` host call rather than shelling out the CLI `command` string.
* A leading `setup` step (command: `fallow schema`) appears only on unconfigured, non-CI projects with findings. It has no mutating tool equivalent by design: read the manifest, then offer the guided-setup commands (`fallow init --agents`, `fallow hooks install --target agent`) to the user instead of running them unprompted. It disappears once a config exists or after `fallow init --decline`.
* An at-most-weekly `impact-report` step (command: `fallow impact`) carries the local value digest (commits contained at the gate, findings resolved) when impact tracking is enabled and has non-zero results. The cadence stamp lives in the impact store, so it is consistent across agents and sessions, and the step may appear even on a clean run. Relay the non-zero numbers to the user in one line.

The array is deduplicated, priority-ordered, capped at three, and omitted when empty. Set `FALLOW_SUGGESTIONS=off` in the server `env` to suppress it.

#### `value_schema` on `add-to-config` actions

`add-to-config` actions (emitted for `unused-dependency`, `type-only-dependency`, `test-only-dependency`, `duplicate-export`, and similar findings where the resolution is "add an entry to the fallow config") carry an optional `value_schema` field alongside `value`:

```json theme={null}
{
  "type": "add-to-config",
  "config_key": "ignoreDependencies",
  "value": "autoprefixer",
  "value_schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/ignoreDependencies/items"
}
```

The `value_schema` URL is a JSON Pointer fragment into fallow's published `schema.json`. Agents that want to validate `value` before writing it into a user's config (for example, to reject a malformed `{ file, exports }` rule object on the `ignoreExports` action) can fetch the linked schema and apply it locally. The field is strictly additive: actions that did not have a schema before continue to work without one, and agents that ignore the field keep working unchanged.

## Resources

Besides tools, the server exposes read-only reference material as MCP resources: no subprocess, no analysis run, cacheable by URI (your client reads them through its own resource tool, for example `ReadMcpResourceTool` in Claude Code). Every payload is plain JSON; the server version travels in each content item's `_meta.fallow_version`, so a cached copy is self-describing and the schema resources stay valid strict JSON Schema. The catalogue is fixed at build time (no subscriptions, no list-changed notifications).

| Resource                                                                        | Content                                                                                                                                                               |
| :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fallow://tools`                                                                | The tool manifest: name, one-line description, nearest CLI fallback, key parameters, license, and read-only flag for every tool                                       |
| `fallow://issue-types`                                                          | Every issue type with its command, category, config key, zero-config default severity, opt-in and fixable flags, docs URL, and explain URI                            |
| `fallow://explain`                                                              | Index of every explainable issue type with a one-line summary and its `fallow://explain/{issue_type}` URI                                                             |
| `fallow://explain/{issue_type}`                                                 | The explain document for one issue type, the same payload as `fallow explain <issue-type> --format json`                                                              |
| `fallow://task-matrix`                                                          | The task-to-command matrix that also drives `AGENTS.md` and `fallow --help`: which read-only command to run before deleting, refactoring, committing, or scoping work |
| `fallow://schema/config`, `fallow://schema/plugin`, `fallow://schema/rule-pack` | The JSON Schemas printed by `fallow config-schema`, `fallow plugin-schema`, and `fallow rule-pack-schema`                                                             |

`{issue_type}` accepts the bare id (`unused-export`), the namespaced id (`fallow/unused-export`), or the CLI filter spelling. Unknown URIs return a structured error whose `data` lists the known URIs; an unknown issue type lists the nearest matches. The numeric code is `-32002` for clients on protocol versions before 2026-07-28 and `-32602` from then on, so key on `data` rather than the code. The same catalogue is published as `mcp_resources` in [`fallow schema`](/cli/schema).

## Combined output from bare `fallow`

Running bare `fallow` (no subcommand) executes all analyses in one pass and returns a combined JSON object with `dead_code`, `duplication`, and `health` sections:

```bash theme={null}
fallow --format json
```

This is the most efficient way for agents to get a full picture of the codebase in a single call. The combined output includes all issue types from dead code, duplication findings, and health metrics.

## Environment variables

| Variable              | Description                                                                                                                                                                                                                                                    |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FALLOW_BIN`          | Path to the fallow CLI binary for CLI-backed calls. The MCP server checks, in order: this env var, a sibling binary next to `fallow-mcp`, then `fallow` in `PATH`. It does not affect typed in-process calls.                                                  |
| `FALLOW_TIMEOUT_SECS` | Deadline in seconds (default: `120`) for both typed and CLI-backed calls. A timed-out typed call returns `FALLOW_MCP_API_TIMEOUT`; a timed-out CLI call kills the process tree and returns `FALLOW_MCP_SUBPROCESS_TIMEOUT`. Increase for very large codebases. |

## Error handling

The MCP server returns structured JSON errors from both adapter paths:

* **Typed API timeout**: returns the `FALLOW_MCP_API_TIMEOUT` code. The response is bounded, although in-process work may finish in the background.
* **CLI exit code 1**: treated as success (issues found, not an error). The full JSON output is returned.
* **CLI exit code 2+**: passes through the CLI's structured JSON error from stdout when available. If no JSON is available, the server constructs `{"error": true, "message": "...", "exit_code": N}` from stderr.
* **CLI timeout**: kills the process tree and returns the `FALLOW_MCP_SUBPROCESS_TIMEOUT` code.

## See also

<CardGroup>
  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/integrations/agent-skills">
    Install fallow skills for Claude Code, Cursor, Windsurf, and more.
  </Card>

  <Card title="CI integration" icon="shield-check" href="/integrations/ci">
    Catch what agents and humans miss in CI.
  </Card>

  <Card title="VS Code extension" icon="window" href="/integrations/vscode">
    Real-time feedback for human developers.
  </Card>

  <Card title="All analysis areas" icon="magnifying-glass" href="/analysis/dead-code">
    Dead code, duplication, complexity, and boundaries.
  </Card>
</CardGroup>


# Neovim
Source: https://docs.fallow.tools/integrations/neovim

Real-time fallow diagnostics in Neovim via the built-in LSP client: unused code, duplication, circular dependencies, and complexity, with hover, quick-fix code actions, and code lens.

Neovim talks to the same `fallow-lsp` language server that powers the VS Code extension, through Neovim's built-in LSP client. The setup is intentionally thin: it launches the existing binary instead of re-implementing any analysis in the editor, so results match the CLI and CI exactly.

<Info>
  Requires Neovim 0.11+ for the `vim.lsp.config` / `vim.lsp.enable` API shown below. Older versions can still attach `fallow-lsp` through `nvim-lspconfig` or a manual `vim.lsp.start`.
</Info>

## What works

* **Real-time diagnostics** for unused files, exports, types, dependencies, enum and class members, unresolved imports, unlisted dependencies, duplicate exports, circular dependencies, and code duplication
* **Opt-in security candidate diagnostics** when you raise the `security-sink` or `security-client-server-leak` rule to `warn` or `error` in your fallow config. Candidates surface as advisory `information` squiggles (unverified, verify before acting); the hover leads with the confidence signals and points to `fallow security --file` for the full trace, and a quick-fix dismisses the candidate. Default off, so squiggles appear only after you raise the rule.
* **Hover information** with export usage counts, unused status, and duplicate block locations
* **Quick-fix code actions** to remove unused exports or delete unused files
* **Code lens** with export reference counts, where Neovim surfaces them

## Installation

<Steps>
  <Step title="Install Fallow so fallow-lsp is on your PATH">
    ```sh theme={null}
    npm install -g fallow
    ```

    Or add it as a project devDependency (`npm install -D fallow`) and point `cmd` at `node_modules/.bin/fallow-lsp`.
  </Step>

  <Step title="Confirm Neovim can see the binary">
    ```sh theme={null}
    fallow-lsp --version
    ```
  </Step>

  <Step title="Register and enable the server">
    Add the configuration below to your Neovim config, then open a TypeScript or JavaScript project.
  </Step>
</Steps>

## Configuration

```lua theme={null}
vim.lsp.config("fallow", {
	cmd = { "fallow-lsp" },
	filetypes = { "javascript", "typescript", "javascriptreact", "typescriptreact" },
	root_markers = { ".fallowrc.json", "package.json", ".git" },
	init_options = {
		-- Every issue type is enabled by default. List only the ones you
		-- want to turn off; any key you omit stays enabled.
		issueTypes = {
			["circular-dependencies"] = false,
		},
	},
})

vim.lsp.enable("fallow")
```

`init_options` is optional; `cmd`, `filetypes`, and `root_markers` alone are enough to attach.

### Issue-type toggles

Fallow reads per-issue toggles from LSP initialization options. Set an issue type to `false` to hide it in editor diagnostics without touching your project config. The keys are Fallow's issue types in kebab-case (`unused-exports`, `unresolved-imports`, `circular-dependencies`, and so on); a client can fetch the live catalog through the custom `fallow/issueTypes` request to stay in sync.

### Scope to changed files

Pass a git ref as `changedSince` to scope diagnostics to files changed since that ref, mirroring `fallow dead-code --changed-since`. This is the Neovim equivalent of the VS Code `fallow.changedSince` setting, useful for adopting fallow on a legacy codebase without surfacing every pre-existing finding:

```lua theme={null}
init_options = {
	changedSince = "fallow-baseline",
},
```

<Note>
  **When diagnostics appear.** Fallow delivers diagnostics through the LSP 3.17 pull model and refreshes them on save. The first analysis runs when the server attaches, so a freshly opened buffer shows findings once the initial pass completes (or after the next save), not necessarily the instant the file opens. Cross-file findings anchored to files you have not opened (for example `package.json` for unlisted dependencies) are pushed so they still surface.
</Note>

## Binary resolution

Neovim runs `cmd` exactly as configured. If `fallow-lsp` is not on Neovim's `PATH`, point `cmd` at an absolute path:

```lua theme={null}
vim.lsp.config("fallow", {
	cmd = { "/absolute/path/to/fallow-lsp" },
	filetypes = { "javascript", "typescript", "javascriptreact", "typescriptreact" },
	root_markers = { ".fallowrc.json", "package.json", ".git" },
})
```

## Verifying the setup

1. Open a TypeScript or JavaScript project.
2. Run `:checkhealth vim.lsp`.
3. Confirm `fallow` is attached:

   ```vim theme={null}
   :lua vim.print(vim.lsp.get_clients({ name = "fallow" }))
   ```

## See also

<CardGroup>
  <Card title="VS Code extension" icon="window" href="/integrations/vscode">
    The richer editor surface: sidebar views, status bar, and fix preview.
  </Card>

  <Card title="Agent integration" icon="robot" href="/integrations/mcp">
    How AI agents use fallow via CLI and MCP.
  </Card>

  <Card title="Analysis areas" icon="magnifying-glass" href="/analysis/dead-code">
    All issue types the language server reports.
  </Card>
</CardGroup>


# Node.js bindings
Source: https://docs.fallow.tools/integrations/node-bindings

Call fallow analyses directly from Node.js via NAPI bindings. No CLI subprocess or JSON parsing, with the same JSON envelopes the CLI emits.

The `@fallow-cli/fallow-node` package exposes the main fallow analyses as async Node.js functions. The bindings avoid CLI subprocesses and JSON parsing, reuse the shared analysis layer, and return the same JSON report envelopes the CLI emits for `--format json`. The optional `detectSimilarCode` function verifies and launches its exact local model companion.

Use them when you want to embed fallow inside another tool, a Node.js server, an editor extension, or a custom script that otherwise would shell out to the CLI.

## Install

```bash theme={null}
npm install @fallow-cli/fallow-node
```

The package is a native NAPI-RS addon with platform-specific `optionalDependencies` for macOS (arm64, x64), Linux (gnu + musl on arm64 and x64), and Windows (x64, arm64). npm picks the matching binary at install time.

Node 18 or newer is required.

## Basic usage

```ts theme={null}
import {
  detectDeadCode,
  detectDuplication,
  detectSimilarCode,
  computeHealth,
} from '@fallow-cli/fallow-node';

const deadCode = await detectDeadCode({
  root: process.cwd(),
  explain: true,
});

console.log(deadCode.summary.total_issues);
console.log(deadCode.unused_exports);

const similar = await detectSimilarCode({
  root: process.cwd(),
  threshold: 0.8,
  top: 20,
});

console.log(similar.candidates);
```

Every function returns a promise resolving to the same JSON envelope the CLI emits when called with `--format json`: a top-level `kind` discriminator on typed roots, `schema_version`, `summary`, relative paths, injected `actions` arrays, and (when `explain: true`) a `_meta` block with docs links.

## API

All eight functions are async and accept an optional options object. Unknown fields are ignored. Enum-like fields take lowercase CLI-style literals (`"mild"`, `"cyclomatic"`, `"handle"`, `"low"`).

| Function                               | CLI equivalent                           | Returns                                                           |
| :------------------------------------- | :--------------------------------------- | :---------------------------------------------------------------- |
| `detectDeadCode(options?)`             | `fallow dead-code --format json`         | `DeadCodeReport`                                                  |
| `detectCircularDependencies(options?)` | `fallow dead-code --circular-deps`       | `DeadCodeReport` filtered to the `circular_dependencies` category |
| `detectBoundaryViolations(options?)`   | `fallow dead-code --boundary-violations` | `DeadCodeReport` filtered to the `boundary_violations` category   |
| `detectDuplication(options?)`          | `fallow dupes --format json`             | `DuplicationReport`                                               |
| `detectSimilarCode(options?)`          | `fallow similar-code --format json`      | `SimilarCodeReport` with unverified candidates                    |
| `detectFeatureFlags(options?)`         | `fallow flags --format json`             | `FeatureFlagsReport`                                              |
| `computeComplexity(options?)`          | `fallow health --format json`            | `HealthReport`                                                    |
| `computeHealth(options?)`              | `fallow health --format json`            | Alias for `computeComplexity` with a product-oriented name        |

### Shared options

Every options object extends `AnalysisOptions`:

| Field               | Type       | Default         | Purpose                                                                                          |
| :------------------ | :--------- | :-------------- | :----------------------------------------------------------------------------------------------- |
| `root`              | `string`   | `process.cwd()` | Project root directory                                                                           |
| `configPath`        | `string`   | auto-discover   | Path to `.fallowrc.json` / `.fallowrc.jsonc` / `fallow.toml` / `.fallow.toml`                    |
| `noCache`           | `boolean`  | `false`         | Skip the extraction cache                                                                        |
| `threads`           | `number`   | CPU count       | Parallelism; must be > 0                                                                         |
| `production`        | `boolean`  | `false`         | Production mode (excludes test/build files)                                                      |
| `changedSince`      | `string`   | unset           | Scope analysis to files changed since a git ref                                                  |
| `workspace`         | `string[]` | unset           | Restrict to named workspace packages (monorepo)                                                  |
| `changedWorkspaces` | `string`   | unset           | Restrict to workspaces whose files changed since a git ref. Mutually exclusive with `workspace`. |
| `explain`           | `boolean`  | `false`         | Inject a `_meta` block with metric / rule documentation                                          |

### Dead-code options

`detectDeadCode`, `detectCircularDependencies`, and `detectBoundaryViolations` accept the same superset, `DeadCodeOptions`. Setting any of the filter booleans below restricts the report to the selected issue types; leaving them all unset returns every category (the CLI's default behavior).

| Field                                                                            | Type       |                                                                      |
| :------------------------------------------------------------------------------- | :--------- | -------------------------------------------------------------------- |
| `unusedFiles` / `unusedExports` / `unusedDeps` / `unusedTypes`                   | `boolean`  |                                                                      |
| `unusedEnumMembers` / `unusedClassMembers`                                       | `boolean`  |                                                                      |
| `unresolvedImports` / `unlistedDeps`                                             | `boolean`  |                                                                      |
| `duplicateExports` / `circularDeps` / `boundaryViolations` / `staleSuppressions` | `boolean`  |                                                                      |
| `files`                                                                          | `string[]` | Restrict to specific files (like `fallow dead-code path/to/file.ts`) |
| `includeEntryExports`                                                            | `boolean`  | Report unused exports on entry files                                 |

### Duplication options

`DuplicationOptions` adds duplication-specific fields on top of `AnalysisOptions`:

| Field            | Type                                         | Default        |
| :--------------- | :------------------------------------------- | :------------- |
| `mode`           | `"strict" \| "mild" \| "weak" \| "semantic"` | `"mild"`       |
| `near`           | `boolean`                                    | `false`        |
| `minTokens`      | `number`                                     | `50`           |
| `minLines`       | `number`                                     | `5`            |
| `minOccurrences` | `number`                                     | `2`            |
| `threshold`      | `number`                                     | `0` (no limit) |
| `skipLocal`      | `boolean`                                    | `false`        |
| `crossLanguage`  | `boolean`                                    | `false`        |
| `ignoreImports`  | `boolean`                                    | `true`         |
| `top`            | `number`                                     | unset          |

Each returned clone group includes `spread`. Near-miss groups also include `similarity`. Duplication stats can include `clone_groups_ignored` and `near_candidates_skipped`; zero values are omitted.

### Similar-code options

`SimilarCodeOptions` adds model-backed discovery fields on top of
`AnalysisOptions`:

| Field       | Type                 | Default         |
| :---------- | :------------------- | :-------------- |
| `threshold` | `number` from 0 to 1 | config or `0.8` |
| `minLines`  | positive `number`    | config or `3`   |
| `top`       | positive `number`    | unset           |
| `files`     | `string[]`           | unset           |

The loader resolves the exact-version `fallow-similar-code` package and
verifies its native binary before source is read. `detectSimilarCode` never
downloads the model. After explicit user approval, run
`fallow similar-code setup --local` once through the CLI. Results remain
unverified. Read [Semantic similar code](/analysis/similar-code) before using a
score to plan a refactor.

### Feature flag options

`FeatureFlagsOptions` adds one field on top of `AnalysisOptions`:

| Field | Type     | Default |
| :---- | :------- | :------ |
| `top` | `number` | unset   |

### Complexity / health options

`ComplexityOptions` mirrors the `fallow health` flag surface:

| Field                                                                      | Type                                                      | Notes                                     |
| :------------------------------------------------------------------------- | :-------------------------------------------------------- | :---------------------------------------- |
| `maxCyclomatic`, `maxCognitive`                                            | `number` (0 to 65535)                                     | Per-function thresholds                   |
| `maxCrap`                                                                  | `number`                                                  | CRAP score ceiling                        |
| `top`                                                                      | `number`                                                  | Truncate rankings                         |
| `sort`                                                                     | `"cyclomatic" \| "cognitive" \| "lines" \| "severity"`    | Finding sort order (default `cyclomatic`) |
| `complexity`, `fileScores`, `coverageGaps`, `hotspots`, `targets`, `score` | `boolean`                                                 | Enable individual report sections         |
| `ownership`, `ownershipEmails`                                             | `boolean` + `"raw" \| "handle" \| "anonymized" \| "hash"` | Ownership-aware hotspots                  |
| `effort`                                                                   | `"low" \| "medium" \| "high"`                             | Filter refactoring targets                |
| `since`, `minCommits`                                                      | `string`, `number`                                        | Git history window for hotspots           |
| `coverage`, `coverageRoot`                                                 | `string`                                                  | Istanbul coverage file + root             |

## Structured errors

Rejected promises throw a `FallowNodeError` (a plain `Error` with extra fields) that mirrors the CLI's structured error surface:

```ts theme={null}
import type { FallowNodeError } from '@fallow-cli/fallow-node';

try {
  await detectDeadCode({ root: '/does/not/exist' });
} catch (err) {
  const e = err as FallowNodeError;
  console.error(e.name);      // "FallowNodeError"
  console.error(e.message);   // "analysis root does not exist: ..."
  console.error(e.exitCode);  // 2
  console.error(e.code);      // "FALLOW_INVALID_ROOT"
  console.error(e.context);   // "analysis.root"
  console.error(e.help);      // optional remediation hint
}
```

The exit-code ladder matches the CLI: `0` ok, `2` generic / validation, `7` network (paid features only), etc.

## When to use bindings vs the CLI

| Use the bindings                                                                  | Use the CLI                                                              |
| :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
| Embedding fallow in a long-running Node process (editor, devserver, CI runner)    | One-off invocation from a shell script or GitHub Action                  |
| You already have a Node runtime and want to skip subprocess + JSON parse overhead | You want zero runtime dependencies (native binary via `npx fallow`)      |
| You need to call many analyses in sequence without re-initializing                | You want CLI human output, progress bars, or interactive flags           |
| You need typed access to the result envelope in TypeScript                        | You consume the analysis from Rust, Python, Go, or any non-Node language |

Both paths run the same analysis engine and return the same data. The bindings are not a reduced subset.

## Limitations

* The bindings wrap the **one-shot** analyses. Commands that write to the filesystem (`fix`, `init`, `hooks install`, `hooks uninstall`, `audit --save-baseline`, `license activate`, `coverage setup`) are not exposed.
* `detectSimilarCode` is read-only and never performs its first model download. Use the CLI after explicit approval: `fallow similar-code setup --local`.
* No baseline or regression support yet. Use the CLI's `--baseline` / `--save-baseline` flags for those workflows.
* No watch mode. If you want incremental analysis, re-invoke the relevant function; fallow's per-file cache makes repeat runs fast.
* The API surface is young; breaking changes between minor versions are possible until it stabilizes.


# VS Code extension
Source: https://docs.fallow.tools/integrations/vscode

Real-time codebase analysis in your editor: unused code, duplication, complexity hotspots, and boundary violations. Inline warnings, Code Lens reference counts, and one-click fixes.

The VS Code extension provides real-time diagnostics for unused code, duplication, complexity, and boundary violations, powered by the fallow LSP server, plus sidebar views and status-bar surfaces for project health, security candidates, runtime coverage, the changed-files audit verdict, monorepo workspace scoping, and license management.

<Info>
  Code Lens shows reference counts above each export. Click to peek all usages. Exports with zero references stand out immediately.
</Info>

## Features

* **Real-time diagnostics** for dead-code issue types, updated via LSP without running a separate CLI process
* **Code Lens** with reference counts above each export (click to peek references)
* **Hover information** with export usage counts, unused status, and duplicate block locations
* **Quick-fix code actions** to remove unused exports or delete unused files
* **Refactor actions** to extract duplicates into shared functions
* **Tree views** in the sidebar with per-category icons, issue count badge, and welcome view
* **Status bar** with color-coded severity, rich tooltip breakdown, and command links
* **Diagnostic documentation links**: click any diagnostic code to open its docs page
* **Related information**: circular dependencies, duplicate exports, and code duplication diagnostics link to all related files
* **Fix preview** with a searchable Quick Pick for reviewing and navigating fixes
* **JSON schema** for `.fallowrc.json` with autocomplete and validation
* **Auto-download** of the LSP binary
* **Getting Started walkthrough** on first install

### Codebase intelligence surfaces

Beyond the real-time LSP diagnostics above, the extension surfaces the rest of fallow's analysis, each as its own opt-in sidebar view or status-bar item:

* **Health view** (sidebar): project health score and grade, top complexity findings, and hotspot / refactoring candidates, from a separate lazy run. Opt out with `fallow.health.enabled`.
* **Security Candidates view** (sidebar): local security candidates (`client-server-leak`, the tainted-sink CWE catalogue), framed as **unverified candidates to verify**, never confirmed vulnerabilities. Opt in with `fallow.security.enabled`.
* **Runtime Coverage view** (sidebar): hot paths and cleanup candidates (safe-to-delete / review-required) from a loaded coverage capture.
* **Audit verdict** (status bar): a pass / warn / fail signal for your current change set, mirroring `fallow audit`.
* **License management**: activate, view status, refresh, and deactivate a Fallow license without leaving the editor.
* **Monorepo workspace scope** (status bar): a picker to scope sidebar analysis (and the Health, Security, and Audit surfaces) to a single package, forwarding `--workspace`.

## Installation

<Steps>
  <Step title="Install the extension">
    Search for "fallow" in the VS Code extensions marketplace, or install from the command line:

    ```bash theme={null}
    code --install-extension fallow-rs.fallow-vscode
    ```
  </Step>

  <Step title="Binary resolution">
    The extension finds binaries automatically. It checks the `fallow.lspPath` setting first, then `node_modules/.bin/` for a local devDependency (`pnpm add -D fallow`), then system PATH, or auto-downloads from GitHub releases.
  </Step>

  <Step title="Getting Started walkthrough">
    On first install, a walkthrough opens automatically with four steps: **Run Analysis**, **Explore Results**, **Fix Issues**, and **Configure Rules**. Each step links directly to the relevant command. You can reopen it from the Command Palette at any time.
  </Step>

  <Step title="Start coding">
    Open any TypeScript or JavaScript project. Fallow activates automatically and starts analyzing. Diagnostics appear inline, and Code Lens annotations show above exports.
  </Step>
</Steps>

## Status bar

The status bar shows the current issue count and duplication percentage. It updates in real time as the LSP server completes analysis via a custom `fallow/analysisComplete` notification. No separate CLI process needed.

* **Color-coded background**: red when unresolved imports are present (errors), yellow when other issues exist (warnings), default when the project is clean
* **Rich tooltip**: hover to see a per-category breakdown of all issues (unused files, exports, dependencies, circular dependencies, clone groups, etc.)
* **Command links in tooltip**: Run Analysis, Auto-Fix, and Show Output are one click away

Additional status-bar items, each independently toggleable:

* **Health score** segment with the project grade (toggle with `fallow.health.statusBar`)
* **Audit verdict** for the current change set: pass / warn / fail, color-coded, with a gating-candidate count (toggle with `fallow.audit.statusBar.enabled`)
* **License indicator** showing the active license state (toggle with `fallow.license.showStatusBar`)
* **Workspace scope** picker showing the package analysis is scoped to in a monorepo (hidden on single-package projects)

## Diagnostics

Every diagnostic includes a clickable **diagnostic code** (e.g., `unused-export`, `unresolved-import`) that opens the corresponding documentation page at [docs.fallow.tools](https://docs.fallow.tools).

### Related information

Some diagnostics include related information that links to other files involved in the issue. Click a related location in the Problems panel to jump directly to it.

* **Circular dependencies**: each file in the cycle chain is listed as a related location, so you can trace the full cycle
* **Duplicate exports**: links to the other files that export the same name
* **Code duplication**: links to all other instances of the duplicated block

### Severity levels

| Issue type                                                   | Severity           | Appearance                   |
| :----------------------------------------------------------- | :----------------- | :--------------------------- |
| Unresolved imports                                           | Error (red)        | Red underline                |
| Unused files, dependencies, circular deps, duplicate exports | Warning (yellow)   | Yellow underline             |
| Unused exports, types, enum/class members                    | Hint               | Faded text (unnecessary tag) |
| Code duplication                                             | Information (blue) | Blue underline               |
| Security candidates (opt-in)                                 | Information (blue) | Blue underline               |

Security candidate diagnostics are **off by default** and distinct from the **Security Candidates** sidebar view. They appear in the editor gutter only when you raise the `security-sink` or `security-client-server-leak` rule to `warn` or `error` in your fallow config, framed as unverified candidates to verify (advisory, never a red error). The hover leads with the confidence signals and points to `fallow security --file` for the full trace; a quick-fix dismisses the candidate.

## Tree views

The sidebar groups issues by type and duplicates by clone family. Each category uses a distinct icon for quick scanning:

| Category              | Icon        |
| :-------------------- | :---------- |
| Unused files          | File        |
| Unused exports        | Method      |
| Unused types          | Interface   |
| Unused dependencies   | Package     |
| Unused enum members   | Enum member |
| Unresolved imports    | Error       |
| Circular dependencies | Sync        |
| Duplicate exports     | Files       |

A **badge** on the sidebar icon shows the total issue count at a glance. When no analysis has been run yet, a **welcome view** appears with a "Run Analysis" button.

Clicking any item in the tree opens the file at the exact line and column.

## Fix preview

**Fallow: Preview Fixes (Dry Run)** opens a searchable Quick Pick listing each available fix with its type and file location. Select an item to navigate to it in the editor, or choose **Apply all fixes** at the bottom to apply everything at once.

After applying fixes, the extension automatically saves modified files, restarts the LSP server, and re-runs analysis so diagnostics update immediately.

## Config autocomplete

`.fallowrc.json` files get autocomplete and validation powered by the published [JSON schema](https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json). The extension registers this automatically, no extra setup needed.

## Commands

| Command                                                    | Description                                                                                              |
| :--------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| **Fallow: Run Analysis**                                   | Run full analysis                                                                                        |
| **Fallow: Set Baseline at HEAD**                           | Create or use the local `fallow-baseline` tag at `HEAD`, set `fallow.changedSince`, and refresh analysis |
| **Fallow: Auto-Fix (unexport unused, remove unused deps)** | Apply auto-fixes                                                                                         |
| **Fallow: Preview Fixes (Dry Run)**                        | Preview fixes in a searchable Quick Pick                                                                 |
| **Fallow: Restart Language Server**                        | Restart the language server                                                                              |
| **Fallow: Show Output Channel**                            | Open the LSP output channel                                                                              |
| **Fallow: Reload Health**                                  | Re-run the Health view analysis                                                                          |
| **Fallow: Scan for Security Candidates**                   | Populate the Security Candidates view                                                                    |
| **Fallow: Select Workspace Scope...**                      | Scope analysis to one monorepo package                                                                   |
| **Fallow: Clear Workspace Scope (Analyze All)**            | Remove the workspace scope                                                                               |
| **Fallow: Load Runtime Coverage**                          | Point the Runtime Coverage view at a capture                                                             |
| **Fallow: Reload Runtime Coverage**                        | Re-read the current coverage capture                                                                     |
| **Fallow: Clear Runtime Coverage**                         | Clear the loaded coverage                                                                                |
| **Fallow: Audit Changed Files**                            | Compute the pass/warn/fail audit verdict for the current changes                                         |
| **Fallow: Activate License**                               | Activate a license (paste a token, load a file, or start a trial)                                        |
| **Fallow: Show License Status**                            | Show the current license state                                                                           |
| **Fallow: Refresh License**                                | Refresh the license from the server                                                                      |
| **Fallow: Deactivate License**                             | Deactivate the license on this machine                                                                   |

<Accordion title="Extension settings">
  | Setting                              | Default         | Description                                                                                                                                                                                                                                                                                |
  | :----------------------------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `fallow.lspPath`                     | -               | Path to `fallow-lsp` binary (highest priority, overrides local `node_modules/.bin`, PATH, and auto-download)                                                                                                                                                                               |
  | `fallow.autoDownload`                | `true`          | Auto-download the LSP binary when not found locally or in PATH                                                                                                                                                                                                                             |
  | `fallow.typeAware.enabled`           | `false`         | Add exact TypeScript symbol evidence to Fallow's project-wide analysis. Does not surface compiler diagnostics or generic typed lint rules. Requires Fallow 3.9.2 or newer.                                                                                                                 |
  | `fallow.typeAware.projects`          | `[]`            | Optional tsconfig paths for type-aware analysis. Relative paths resolve from the workspace root.                                                                                                                                                                                           |
  | `fallow.typeAware.require`           | `"best-effort"` | Keep incomplete semantic evidence advisory, or choose `"complete"` to fail after emitting the conservative result.                                                                                                                                                                         |
  | `fallow.issueTypes`                  | all             | Which issue types to report                                                                                                                                                                                                                                                                |
  | `fallow.duplication.threshold`       | `0`             | Maximum allowed duplication percentage before the analysis is marked as failing (`0` = no limit)                                                                                                                                                                                           |
  | `fallow.duplication.minTokens`       | `50`            | Minimum token count for a clone before it can be reported as duplicated code                                                                                                                                                                                                               |
  | `fallow.duplication.minLines`        | `5`             | Minimum line count for a clone before it can be reported as duplicated code                                                                                                                                                                                                                |
  | `fallow.duplication.minOccurrences`  | `2`             | Minimum occurrences before a clone group is reported (raise to `3`+ to skip pair-only clones)                                                                                                                                                                                              |
  | `fallow.duplication.mode`            | `mild`          | Duplication detection mode                                                                                                                                                                                                                                                                 |
  | `fallow.duplication.near`            | `false`         | Include function-scoped near-miss clones with small structural edits alongside exact clones. Requires Fallow 3.15.0 or newer.                                                                                                                                                              |
  | `fallow.duplication.skipLocal`       | `false`         | Only report duplicate code that appears across different directories                                                                                                                                                                                                                       |
  | `fallow.duplication.crossLanguage`   | `false`         | Compare TypeScript and JavaScript files after stripping TypeScript type annotations                                                                                                                                                                                                        |
  | `fallow.duplication.ignoreImports`   | `true`          | Exclude module wiring from duplicate-code detection. Enabled by default for ES imports, re-export declarations, and top-level static `require()` binding declarations; set to `false` to count module wiring as clone candidates again.                                                    |
  | `fallow.production`                  | `"auto"`        | Production mode for the sidebar tree and the editor diagnostics (they stay in sync). `"auto"` defers to the project config, `"on"` forces production mode on, `"off"` forces it off even if the project config enables it. Editor-only; CLI and CI always report every finding.            |
  | `fallow.changedSince`                | `""`            | Git ref to scope diagnostics and the sidebar to files changed since that ref (mirrors `--changed-since`). Tag a baseline commit (e.g. `fallow-baseline`) and set this to the tag to enforce "no new issues going forward" while ignoring pre-existing findings.                            |
  | `fallow.diagnostics.severity`        | `"warning"`     | Render Fallow editor diagnostics as `warning`, `information`, or `hint`. `hint` keeps findings available without squiggles. Editor-only; CLI and CI output are unchanged.                                                                                                                  |
  | `fallow.diagnostics.mutedCategories` | `[]`            | Team-shareable baseline of Fallow diagnostic category codes to hide in the editor, such as `code-duplication` or `stale-suppression`. Commit in `.vscode/settings.json`; local mutes can still hide more or show a baseline-hidden category. Editor-only; CLI and CI output are unchanged. |
  | `fallow.workspace`                   | `""`            | Scope sidebar analysis (and the Health, Security, and Audit surfaces) to a single monorepo package by name. Empty = analyze the whole project. Forwarded as `--workspace`.                                                                                                                 |
  | `fallow.health.enabled`              | `true`          | Show the Health view (score and grade, complexity findings, hotspot and refactoring candidates)                                                                                                                                                                                            |
  | `fallow.health.hotspots`             | `true`          | Include git churn hotspots in the Health view (walks git history; disable to skip that cost)                                                                                                                                                                                               |
  | `fallow.health.topFindings`          | `20`            | Maximum number of complexity findings shown in the Health view                                                                                                                                                                                                                             |
  | `fallow.health.statusBar`            | `true`          | Show the project health score and grade in the status bar                                                                                                                                                                                                                                  |
  | `fallow.health.inlineComplexity`     | `true`          | Show a compact complexity lens (`N cyc, N cog`) above functions that exceed Fallow Health thresholds. Click the lens to expand or collapse that function's per-line `+N` breakdown                                                                                                         |
  | `fallow.complexity.breakdownEnabled` | `true`          | Master switch for the complexity breakdown (lens, per-line markers, and hovers) shown in the editor after the Health view runs                                                                                                                                                             |
  | `fallow.complexity.afterText`        | `false`         | Always show the dim per-line `+N` token for every complex function, instead of only the function you expand (via its lens) or select in the Health view. Hovering always shows the breakdown regardless                                                                                    |
  | `fallow.complexity.decorationCap`    | `200`           | Number of top complexity findings fetched for editor decorations, independent of `fallow.health.topFindings`                                                                                                                                                                               |
  | `fallow.security.enabled`            | `false`         | Surface local **security candidates** (`client-server-leak`, tainted-sink CWE catalogue) in the Security Candidates view. Unverified candidates to verify, not confirmed vulnerabilities.                                                                                                  |
  | `fallow.audit.gate`                  | `new-only`      | Which findings affect the audit verdict shown in the editor (mirrors `fallow audit --gate`)                                                                                                                                                                                                |
  | `fallow.audit.statusBar.enabled`     | `true`          | Show the audit verdict (pass/warn/fail) for the current change set in the status bar                                                                                                                                                                                                       |
  | `fallow.audit.runOnSave`             | `false`         | Re-run the audit verdict when a JS/TS file is saved (off by default)                                                                                                                                                                                                                       |
  | `fallow.coverage.capturePath`        | `""`            | Path to a local runtime-coverage capture (file or directory) for the Runtime Coverage view                                                                                                                                                                                                 |
  | `fallow.coverage.top`                | `0`             | Show only the top N hot paths and findings in the Runtime Coverage view (`0` = all)                                                                                                                                                                                                        |
  | `fallow.license.showStatusBar`       | `true`          | Show a Fallow license indicator in the status bar                                                                                                                                                                                                                                          |
  | `fallow.license.refreshOnStartup`    | `false`         | Probe license status once when the extension activates (off by default; no network on startup)                                                                                                                                                                                             |
  | `fallow.trace.server`                | `off`           | LSP trace level for debugging                                                                                                                                                                                                                                                              |
</Accordion>

### Adopting fallow on a legacy codebase

Run **Fallow: Set Baseline at HEAD** from the Command Palette to keep existing issues hidden while flagging new ones. The command creates the local lightweight `fallow-baseline` tag at the current commit, writes `fallow.changedSince` to the workspace settings, and refreshes analysis.

It confirms before replacing another effective baseline setting, refuses multi-root workspaces, and never moves an existing tag or pushes to a remote.

To share the baseline with your team, push that tag explicitly and commit the generated `.vscode/settings.json` change:

```bash theme={null}
git push origin refs/tags/fallow-baseline
git add .vscode/settings.json
git commit -m "chore: set fallow baseline"
```

Pair the same tag with `fallow dead-code --changed-since fallow-baseline` in CI to enforce the same contract on pull requests.

<Note>
  **Shallow clone footgun.** `actions/checkout@v4` defaults to `fetch-depth: 1` and GitLab CI defaults to `GIT_DEPTH: 50`. If your baseline tag predates that fetch boundary, `--changed-since` and `fallow.changedSince` silently fall back to full scope (the LSP logs a warning to the Fallow output channel). Set `fetch-depth: 0` on `actions/checkout` (or `GIT_DEPTH: 0` in GitLab CI) when you use a long-lived baseline tag.
</Note>

## See also

<CardGroup>
  <Card title="Agent integration" icon="robot" href="/integrations/mcp">
    How AI agents use fallow via CLI and MCP.
  </Card>

  <Card title="CI integration" icon="shield-check" href="/integrations/ci">
    Add fallow to your CI pipeline.
  </Card>

  <Card title="Analysis areas" icon="magnifying-glass" href="/analysis/dead-code">
    All issue types shown in real time by the extension.
  </Card>
</CardGroup>


# Fallow vs Knip
Source: https://docs.fallow.tools/migration/comparison

Compare fallow and knip for TypeScript and JavaScript codebase analysis. Side-by-side benchmarks, detection capabilities, plugin coverage, and when to choose each tool. Fallow also covers duplication, complexity, and architecture boundaries.

Fallow and knip both detect unused code in TypeScript and JavaScript projects. Knip is a mature tool with broad plugin coverage. Fallow is a Rust-native alternative that goes beyond unused code: it also covers code duplication, complexity hotspots, maintainability scoring, architecture boundary enforcement, and design-system styling in a single binary.

Use this comparison to decide which tool fits your project.

## Performance

Fallow is a compiled Rust binary with rayon-based parallelism. Knip runs on Node.js. Version 6 adopted the Oxc parser via NAPI bindings, which significantly narrowed the gap with v5, but knip remains single-threaded.

Cold runs (no cache) so both tools work from scratch. Fastest tool per row in bold.

| Project                                               |  Files |    fallow | knip v5 |   knip v6 |
| :---------------------------------------------------- | -----: | --------: | ------: | --------: |
| [zod](https://github.com/colinhacks/zod)              |    174 |  **47ms** |   279ms |     279ms |
| [preact](https://github.com/preactjs/preact)          |    244 |  **74ms** |   2.01s |     2.01s |
| [fastify](https://github.com/fastify/fastify)         |    286 |  **64ms** |   205ms |     205ms |
| [vue/core](https://github.com/vuejs/core)             |    522 | **138ms** | errors¹ |   errors¹ |
| [TanStack/query](https://github.com/TanStack/query)   |    901 | **560ms** |   1.04s |     1.04s |
| [vite](https://github.com/vitejs/vite)                |  1,420 | **595ms** | errors¹ |   errors¹ |
| [astro](https://github.com/withastro/astro)           |  2,859 |     3.76s |   1.21s | **1.21s** |
| [svelte](https://github.com/sveltejs/svelte)          |  3,337 | **611ms** |   632ms |     632ms |
| [next.js](https://github.com/vercel/next.js)          | 20,558 | **2.95s** | errors¹ |   errors¹ |
| [TypeScript](https://github.com/microsoft/TypeScript) | 38,146 |     2.22s |   736ms | **736ms** |

<Info>
  Benchmarked on real-world open-source projects from 174 to 38,146 files against fallow 2.100.0, knip 5.87.0, and knip 6.6.1 on Apple M5 (10 cores), 32 GB RAM, macOS 26.4, Node v22.22.1. Median of 5 cold runs (no cache) with 2 warmups. The knip v6 column is the primary comparison; current knip v5 and v6 produce equivalent timings on the projects they can load, and fallow's lead over knip v5 is wider on the small-to-mid projects (for example fallow 13.7x on fastify, 13.0x on zod, 10.3x on preact). fallow is fastest on small-to-mid projects (fastify, preact, query, svelte, zod). On large projects, knip v6's Oxc parser is faster on astro and TypeScript; fallow's advantage there is doing more in one tool. fallow's persistent cache makes repeat (warm) runs faster again, the table uses the conservative cold numbers.

  ¹ Current knip (both v5 and v6) exits without valid output on next.js, vite, and vue/core. It loads and executes a project's own config and JSON files to read plugin settings, which works well on apps but trips on a few framework monorepos where fallow (purely syntactic, no config execution) completes with no setup. **vite**: a workspace `package.json` carries a UTF-8 BOM that knip's `JSON.parse` rejects (a robustness gap, reportable upstream; fallow strips BOMs). **vue/core**: a private `sfc-playground/vite.config.ts` fails to load. **next.js**: the framework's own monorepo needs a build for its jest config and per-workspace entry config for its `dist`-published packages, this is the framework source, not a Next.js app (which is what knip's Next.js plugin targets). All are fixable with knip config; fallow needs none.
</Info>

### Why fallow is faster

| Factor      | fallow                               | knip                               |
| :---------- | :----------------------------------- | :--------------------------------- |
| Language    | Compiled Rust binary                 | Node.js runtime                    |
| Parser      | Oxc (native Rust)                    | Oxc via NAPI bindings              |
| Parallelism | rayon work-stealing across all cores | Single-threaded                    |
| Startup     | Instant (no JIT warmup)              | Node.js bootstrap + module loading |
| Memory      | Flat contiguous data structures      | GC-managed heap                    |

### Memory and large codebases

Fallow uses flat edge storage and lock-free parallel resolution, so it handles large monorepos well. Memory usage scales linearly with file count rather than with the Node.js GC heap.

## Detection capabilities

<Tabs>
  <Tab title="Comparison table">
    | Capability                           |           fallow           |        knip        |
    | :----------------------------------- | :------------------------: | :----------------: |
    | Unused files                         |             Yes            |         Yes        |
    | Unused exports                       |             Yes            |         Yes        |
    | Unused types                         |             Yes            |         Yes        |
    | Unused dependencies                  |             Yes            |         Yes        |
    | Unused devDependencies               |             Yes            |         Yes        |
    | Unused enum members                  |             Yes            |         Yes        |
    | Unused class members                 |             Yes            | No (dropped in v6) |
    | Unresolved imports                   |             Yes            |         Yes        |
    | Unlisted dependencies                |             Yes            |         Yes        |
    | Duplicate exports                    |             Yes            |         No         |
    | Code duplication                     |    Yes (`fallow dupes`)    |         No         |
    | Circular dependencies                |             Yes            |         Yes        |
    | Complexity hotspots                  |    Yes (`fallow health`)   |         No         |
    | Architecture boundary violations     |             Yes            |         No         |
    | Feature flag detection               |    Yes (`fallow flags`)    |         No         |
    | CRAP score thresholds (`--max-crap`) |             Yes            |         No         |
    | Runtime coverage (paid)              | Yes (`--runtime-coverage`) |         No         |
    | TS namespace declaration members     |             No             |   Yes (new in v6)  |
  </Tab>

  <Tab title="Details">
    **Fallow extras:**

    * **Unused class members**: Knip dropped class member detection in v6. Fallow retains it with whole-object-use heuristics (`Object.values`, `Object.keys`, `for..in`, spread, computed access).
    * **Duplicate exports**: Detects the same symbol exported from multiple modules, helping clean up barrel file sprawl.
    * **Code duplication**: Built-in `fallow dupes` command with four detection modes (strict, mild, weak, semantic), clone family grouping, and refactoring suggestions. No need for a separate tool like jscpd.
    * **Circular dependencies**: Detected via the module graph. Both fallow and knip support circular dependency detection.
    * **Namespace import narrowing**: `import * as ns from './x'` followed by `ns.foo` or `const { foo } = ns` narrows to only mark accessed exports as used. Includes scope-aware unused import binding detection via `oxc_semantic`. Imports where the binding is never read don't count as references.
    * **Complexity hotspots**: `fallow health` reports per-function cyclomatic and cognitive complexity, CRAP (Change Risk Anti-Patterns) score with optional Istanbul coverage, unit size, and a composite health score. `--max-crap`, `--max-cyclomatic`, and `--max-cognitive` gate CI on thresholds.
    * **Architecture boundary violations**: Enforces cross-package or cross-layer import rules declared in config. Flags imports that cross defined boundaries.
    * **Feature flag detection**: `fallow flags` scans for feature flag patterns, correlates them with dead code, and outputs SARIF / markdown / JSON / MCP.
    * **Runtime coverage (paid)**: Merges V8 runtime samples with the static graph to surface hot / cold paths and runtime-weighted health.

    **Knip extras:**

    * **TS namespace declaration members**: New in v6, detecting unused members of TypeScript `namespace` declarations (the `namespace Foo { export const bar }` syntax).
  </Tab>
</Tabs>

## Plugin coverage

| Capability            | fallow                                                      | knip                              |
| :-------------------- | :---------------------------------------------------------- | :-------------------------------- |
| Built-in catalogue    | Major frameworks and tools                                  | Broader niche and legacy coverage |
| Config parsing        | Supported where configuration affects entry points or usage | Supported                         |
| Custom plugin support | Yes (JSONC, JSON, TOML, or inline)                          | Yes (JS functions)                |

Knip has broader plugin coverage, particularly for niche and legacy tooling. Fallow covers all major frameworks and the most popular tools across every category.

<Tabs>
  <Tab title="Shared coverage">
    Both tools have plugins for: Next.js, Nuxt, Remix, SvelteKit, Gatsby, Astro, Angular, NestJS, Vite, Webpack, Rollup, Vitest, Jest, Playwright, Cypress, Storybook, ESLint, Biome, TypeScript, Babel, Tailwind, PostCSS, Prisma, Turborepo, Nx, semantic-release, and many more.
  </Tab>

  <Tab title="Fallow-only plugins">
    Rspack, Rsbuild, Rolldown, Tsdown, Drizzle, Knex, Kysely, TypeORM, Wrangler (Cloudflare), Expo, React Native, Electron, i18next, Parcel, Oxlint, SWC, WebdriverIO, Cucumber, lefthook, Docusaurus, Capacitor, typedoc, c8/nyc, markdownlint, Remark, and others.
  </Tab>

  <Tab title="Knip-only plugins">
    Knip covers additional tools like Wireit, GitHub Actions, Netlify, and several other niche integrations. Check the [knip plugin list](https://knip.dev/reference/plugins) for the full inventory.
  </Tab>
</Tabs>

<Info>
  If your project uses a framework that fallow doesn't have a plugin for, you can [create a custom plugin](/frameworks/custom-plugins) in JSONC, JSON, or TOML. No code required.
</Info>

## Features fallow has that knip doesn't

<CardGroup>
  <Card title="SARIF output" icon="file-code">
    Upload results directly to GitHub Code Scanning with `--format sarif`. Integrated into your PR review workflow.
  </Card>

  <Card title="Baseline comparison" icon="code-compare">
    `--save-baseline` and `--baseline` for incremental CI adoption. Only fail on new issues, not pre-existing ones.
  </Card>

  <Card title="Inline suppression" icon="comment-slash">
    `// fallow-ignore-next-line` and `// fallow-ignore-file` comments for granular, per-line suppression without config changes.
  </Card>

  <Card title="Code duplication" icon="clone">
    Built-in `fallow dupes` with four detection modes, clone family grouping, cross-language matching, and refactoring suggestions.
  </Card>

  <Card title="Complexity and health score" icon="heart-pulse">
    `fallow health` reports cyclomatic / cognitive complexity, CRAP score, risk profiles, and a composite health score. `--max-crap`, `--max-cyclomatic`, and `--max-cognitive` gate CI on per-function thresholds.
  </Card>

  <Card title="Architecture boundaries" icon="shield">
    Enforce cross-package or cross-layer import rules. Boundary violations fail the build without needing ESLint plugins.
  </Card>

  <Card title="Feature flag detection" icon="flag">
    `fallow flags` detects feature flag patterns across the codebase, cross-references them with dead code, and exports to SARIF, markdown, and MCP.
  </Card>

  <Card title="Combined audit" icon="clipboard-check">
    `fallow audit` runs dead code, health, and duplication with a single verdict. Per-analysis baselines (`--dead-code-baseline`, `--health-baseline`, `--dupes-baseline`) let each slice use its own reference.
  </Card>

  <Card title="Standalone rule explainer" icon="circle-question">
    [`fallow explain <issue-type>`](/cli/explain) prints rule rationale, a worked example, fix guidance, and the docs URL without running analysis. Knip has no equivalent. Closest analogs are Credo (`mix credo explain`) for Elixir and Biome's build-time diagnostic explainer; only fallow ships a standalone CLI subcommand plus an MCP tool (`fallow_explain`) that agents can call before fixing a finding.
  </Card>

  <Card title="Git-aware analysis" icon="code-branch">
    `--changed-since <ref>` for file-level scoping and `--changed-workspaces <ref>` for monorepo-level scoping. Perfect for PR-only CI checks.
  </Card>

  <Card title="Workspace filtering" icon="layer-group">
    `--workspace` accepts comma-separated values, globs, and `!` negations (`-w 'apps/*' -w '!apps/legacy'`). Works across every command.
  </Card>

  <Card title="Output grouping" icon="folder-tree">
    `--group-by owner|directory|package|section` partitions findings. `owner` and `section` read GitHub / GitLab CODEOWNERS so unused code is routed to the right reviewer.
  </Card>

  <Card title="Auto-fix dry run" icon="wand-magic-sparkles">
    Preview all fixes with `fallow fix --dry-run` before applying. JSON output for programmatic review.
  </Card>

  <Card title="Trace and debug tooling" icon="magnifying-glass">
    `--trace FILE:EXPORT` to trace export usage chains, `--trace-file PATH` for file edges, `--trace-dependency PACKAGE` for dependency usage, `--performance` for pipeline timing.
  </Card>

  <Card title="CSS Modules tracking" icon="paintbrush">
    `.module.css` and `.module.scss` class names are extracted as named exports and tracked through `styles.className` member accesses.
  </Card>

  <Card title="MCP server" icon="robot">
    Built-in `fallow-mcp` exposes `analyze`, `find_dupes`, `check_health`, `audit`, `check_runtime_coverage`, and more as typed tools for AI agents.
  </Card>

  <Card title="Claude Code hooks" icon="hammer">
    `fallow hooks install --target agent` installs a `PreToolUse` gate that blocks `git commit` / `git push` when `fallow audit` fails, with a structured envelope agents can act on.
  </Card>
</CardGroup>

**Additional features:**

* **Production mode**: `--production` excludes test/dev files and detects type-only dependencies that should be devDependencies.
* **TOML configuration**: In addition to JSONC/JSON, fallow supports `fallow.toml` for teams that prefer TOML.
* **Cross-reference analysis**: `fallow dead-code --include-dupes` finds dead code that is also duplicated, showing high-priority cleanup targets.

## Features knip has that fallow doesn't

<CardGroup>
  <Card title="More plugins" icon="puzzle-piece">
    Knip covers more niche, legacy, and ecosystem-specific tooling.
  </Card>

  <Card title="Custom reporters" icon="paintbrush">
    Write custom reporter functions in JavaScript for fully custom output formatting.
  </Card>

  <Card title="Tags filtering" icon="tags">
    `--tags` flag filters results based on JSDoc `@public`/`@internal` annotations.
  </Card>
</CardGroup>

## When to choose fallow

<CardGroup>
  <Card title="Speed matters" icon="gauge-high">
    Large codebases where sub-second analysis enables watch mode and tight CI feedback loops.
  </Card>

  <Card title="CI pipelines" icon="circle-check">
    SARIF for GitHub Code Scanning, baselines for incremental adoption, `--changed-since` for PR-scoped checks.
  </Card>

  <Card title="Dead code + duplication" icon="layer-group">
    Replace both knip and jscpd with a single tool. Cross-reference dead code with duplication for prioritized cleanup.
  </Card>

  <Card title="Gradual adoption" icon="stairs">
    Per-issue severity rules (`error`/`warn`/`off`) and inline suppression comments let teams adopt incrementally.
  </Card>

  <Card title="AI-assisted development" icon="robot">
    Your team uses AI coding agents. Fallow provides `--format json` for CLI, an MCP server for typed tool calling, and `--changed-since` for PR-scoped checks.
  </Card>
</CardGroup>

## When to choose knip

<CardGroup>
  <Card title="Niche plugins" icon="puzzle-piece">
    Your project depends on a specific tool that only knip has a plugin for, and a custom plugin isn't worth the effort.
  </Card>

  <Card title="Already working well" icon="thumbs-up">
    Knip is already integrated and performance isn't a pain point. No reason to migrate for the sake of it.
  </Card>

  <Card title="Custom reporters" icon="code">
    You need fully custom output formatting via JavaScript reporter functions.
  </Card>
</CardGroup>

## Summary table

|                                                       | fallow                                                                                                                                  | knip                              |
| :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| Language                                              | Rust                                                                                                                                    | Node.js (TypeScript)              |
| Parser                                                | Oxc (native)                                                                                                                            | Oxc (NAPI bindings)               |
| Speed vs knip v6                                      | Faster on small-to-mid projects (up to 27.1x on preact); knip v6 faster on astro and TypeScript; knip errors on next.js, vite, vue/core | Baseline                          |
| Parallelism                                           | Multi-core (rayon)                                                                                                                      | Single-threaded                   |
| Dead code coverage                                    | Files, exports, dependencies, members, cycles, boundaries, and more                                                                     | Comparable core coverage          |
| Code duplication                                      | Built-in                                                                                                                                | Not included                      |
| Complexity and health score                           | Built-in (`fallow health`)                                                                                                              | No                                |
| Architecture boundaries                               | Yes                                                                                                                                     | No                                |
| Feature flag detection                                | Yes (`fallow flags`)                                                                                                                    | No                                |
| Combined audit verdict                                | Yes (`fallow audit`)                                                                                                                    | No                                |
| Built-in plugins                                      | Major frameworks and tools                                                                                                              | Broader niche and legacy coverage |
| Custom plugins                                        | JSONC/JSON/TOML                                                                                                                         | JavaScript                        |
| SARIF output                                          | Yes                                                                                                                                     | No                                |
| Baseline comparison                                   | Yes (per-analysis)                                                                                                                      | No                                |
| Inline suppression                                    | Yes                                                                                                                                     | No                                |
| Git-aware (`--changed-since`, `--changed-workspaces`) | Yes                                                                                                                                     | Partial                           |
| CODEOWNERS grouping                                   | Yes (`--group-by owner`, `section`)                                                                                                     | Yes (reporter)                    |
| Workspace filtering (globs, negation)                 | Yes                                                                                                                                     | Yes                               |
| Circular dependencies                                 | Yes                                                                                                                                     | Yes                               |
| Auto-fix                                              | Yes                                                                                                                                     | Yes                               |
| Config formats                                        | JSONC, JSON, TOML                                                                                                                       | JSON, TS                          |
| Runtime dependency                                    | None (standalone binary)                                                                                                                | Node.js                           |
| MCP server                                            | Built-in (`fallow-mcp`)                                                                                                                 | No                                |

## Migrating from knip?

If you're coming from knip, fallow has a one-command migration path that automatically translates your configuration.

<CardGroup>
  <Card title="Migrate from knip" icon="right-left" href="/migration/from-knip">
    Automatic config migration with `fallow migrate`.
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get started with fallow in 2 minutes.
  </Card>
</CardGroup>


# Migrating from jscpd
Source: https://docs.fallow.tools/migration/from-jscpd

Migrate from jscpd to fallow when you want duplication detection together with unused code, complexity, circular dependencies, and architecture boundaries.

Fallow can replace jscpd when you want duplication detection as part of a broader codebase audit. It also covers unused code detection, complexity analysis, circular dependencies, and architecture boundaries in the same binary.

## Migration workflow

<Steps>
  <Step title="Preview the migration">
    Run `fallow migrate --dry-run` to see the generated config without writing anything:

    ```bash theme={null}
    fallow migrate --dry-run
    ```

    Fallow searches for `.jscpd.json` and the `jscpd` field in `package.json`.
  </Step>

  <Step title="Generate the config">
    Once you're happy with the preview, run the migration:

    ```bash theme={null}
    fallow migrate            # Write .fallowrc.json
    fallow migrate --toml     # Or output as fallow.toml
    ```
  </Step>

  <Step title="Review the config">
    Open the generated config and verify the translated thresholds, token counts, and ignore patterns.
  </Step>

  <Step title="Run fallow dupes">
    Run your first duplication analysis:

    ```bash theme={null}
    fallow dupes
    ```
  </Step>
</Steps>

## What gets migrated

| jscpd       | fallow                             |
| :---------- | :--------------------------------- |
| `threshold` | `duplicates.threshold`             |
| `minTokens` | `duplicates.minTokens`             |
| `minLines`  | `duplicates.minLines`              |
| `ignore`    | `ignorePatterns`                   |
| `format`    | -- (fallow auto-detects languages) |

## Comparison

|                              | fallow                            | jscpd                                                       |
| :--------------------------- | :-------------------------------- | :---------------------------------------------------------- |
| Raw duplication speed        | Part of the broader audit flow    | jscpd v5 is faster on the current README benchmark fixtures |
| Detection modes              | 4 (strict, mild, weak, semantic)  | 3 (strict, mild, weak)                                      |
| Algorithm                    | Suffix array with LCP             | Rust rewrite in v5                                          |
| Unused code + circular deps  | Built-in (`fallow dead-code`)     | Not included                                                |
| Complexity + maintainability | Built-in (`fallow health`)        | Not included                                                |
| Clone families               | Yes, with refactoring suggestions | No                                                          |
| Cross-language               | TS to JS type stripping           | Format-based                                                |
| Baseline tracking            | Yes                               | No                                                          |
| Runtime dependency           | Native binary                     | Native binary in v5                                         |

## Detection mode mapping

jscpd v5 supports `strict`, `mild`, and `weak` modes. The closest fallow equivalent for exact token matching is `strict`.

Fallow defaults to `mild` mode, which normalizes syntax variations and may flag more clones than jscpd did. To match jscpd's behavior more closely, use `strict` mode:

```bash theme={null}
fallow dupes --mode strict
```

For broader matching that catches renamed variables:

```bash theme={null}
fallow dupes --mode semantic
```

## One tool for the full picture

One binary replaces separate jscpd, knip, and madge workflows:

```bash theme={null}
fallow dead-code    # Unused code + circular deps + boundaries
fallow dupes        # Code duplication (replaces jscpd)
fallow health       # Complexity hotspots + maintainability scores
fallow              # All of the above in one pass
```

## See also

<CardGroup>
  <Card title="Duplication analysis" icon="clone" href="/analysis/duplication">
    Deep dive into fallow's duplication detection engine.
  </Card>

  <Card title="fallow dupes" icon="terminal" href="/cli/dupes">
    Full CLI reference for the dupes command.
  </Card>
</CardGroup>


# Migrating from knip
Source: https://docs.fallow.tools/migration/from-knip

Migrate from knip to fallow in minutes. One command converts your knip config. Fallow also covers duplication, complexity, and architecture boundaries that knip does not.

Fallow provides a one-command migration path from knip. Your existing configuration is automatically translated. Beyond what knip covers, fallow also detects code duplication, complexity hotspots, maintainability scores, and architecture boundary violations.

## Migration workflow

<Steps>
  <Step title="Preview the migration">
    Run `fallow migrate --dry-run` to see the generated config without writing anything:

    ```bash theme={null}
    fallow migrate --dry-run
    ```

    Fallow searches for: `knip.json`, `knip.jsonc`, `.knip.json`, `.knip.jsonc`, `knip.ts`, `knip.config.ts`, and the `knip` field in `package.json`. TypeScript config files (`knip.ts`, `knip.config.ts`) are detected but cannot be parsed. Convert to `knip.json` first.

    ```bash title="$ fallow migrate --dry-run" theme={null}
    Detected knip config: knip.json

    Migrating settings:
      entry          → entry: ["src/index.ts", "src/cli.ts"]
      ignore         → ignorePatterns: ["**/*.generated.ts"]
      ignoreDeps     → ignoreDependencies: ["@types/node"]

    ⚠ Cannot migrate:
      ignoreBinaries → not applicable in fallow

    Would write: .fallowrc.json
    Run without --dry-run to write the config.
    ```
  </Step>

  <Step title="Generate the config">
    Once you're happy with the preview, run the migration:

    ```bash theme={null}
    fallow migrate            # Write .fallowrc.json
    fallow migrate --toml     # Or output as fallow.toml
    ```
  </Step>

  <Step title="Review the config">
    Open the generated config and verify the translated entry points, ignore patterns, and plugin mappings. Warnings are shown for any fields that couldn't be migrated automatically.
  </Step>

  <Step title="Run your first analysis">
    Run dead code analysis and compare results against knip. Then explore the other analyses that knip does not cover:

    ```bash theme={null}
    fallow dead-code    # Unused code + circular deps + boundaries
    fallow dupes        # Code duplication
    fallow health       # Complexity hotspots + maintainability scores
    fallow              # All of the above in one pass
    ```
  </Step>
</Steps>

## What gets migrated

| knip                      | fallow                                                                                   |
| :------------------------ | :--------------------------------------------------------------------------------------- |
| `entry`                   | `entry`                                                                                  |
| `project`                 | -- (fallow auto-discovers project files)                                                 |
| `ignore`                  | `ignorePatterns`                                                                         |
| `ignoreDependencies`      | `ignoreDependencies`                                                                     |
| `ignoreExportsUsedInFile` | `ignoreExportsUsedInFile` (boolean and `{ type, interface }` object form both supported) |
| `ignoreBinaries`          | -- (not applicable)                                                                      |
| Plugin configs            | Closest fallow plugin equivalent                                                         |

## Warnings and caveats

`fallow migrate` is loud about anything it cannot translate so the migration is not silently lossy.

**Unknown rule names.** If your knip `rules`, `exclude`, or `include` entries reference a key that fallow does not know (typo, future knip rule, or an issue type the migrator has not yet catalogued), the migration emits a warning like:

```
Warning (1 skipped field):
  [knip] `rules.unsued-files`: unknown knip issue type `unsued-files`; not migrated
  (suggestion: check for a typo or report the missing mapping at https://docs.fallow.tools/migration/from-knip)
```

If the key is in the documented unmappable list (`binaries`, `optionalPeerDependencies`, and similar issue types knip emits but fallow does not), the warning reads `issue type \`X\` has no fallow equivalent\` and has no suggestion.

**Glob-engine drift.** Knip and fallow use different glob engines, so `entry` and `ignorePatterns` are copied verbatim but may match a slightly different file set than they did under knip. When the migrated config carries either field, the migrate command prints:

```
Note: knip and fallow use different glob engines; verify migrated entry / ignorePatterns
      with `fallow dead-code` before relying on CI. See https://docs.fallow.tools/migration/from-knip
```

Common patterns (brace expansion `{ts,tsx}`, double-star `**`, `src/**`) match identically across both engines. Known drift today: fallow's `ignorePatterns` does not honor leading `!` as negation; entries are matched literally. Run `fallow dead-code` on a representative subset before relying on the migrated globs in CI.

## Comparison

<Tabs>
  <Tab title="Speed">
    Fallow is a Rust-native standalone binary. No Node.js runtime, no JIT warmup, no garbage collection pauses.

    Cold runs (no cache) on real open-source projects (174 to 38,146 files). Fastest tool per row in bold.

    | Project                                               |  Files |    fallow |      knip |       Faster |
    | :---------------------------------------------------- | -----: | --------: | --------: | -----------: |
    | [zod](https://github.com/colinhacks/zod)              |    174 |  **47ms** |     279ms |  fallow 5.9x |
    | [preact](https://github.com/preactjs/preact)          |    244 |  **74ms** |     2.01s | fallow 27.1x |
    | [fastify](https://github.com/fastify/fastify)         |    286 |  **64ms** |     205ms |  fallow 3.2x |
    | [vue/core](https://github.com/vuejs/core)             |    522 |     138ms |  errors\* |  fallow only |
    | [TanStack/query](https://github.com/TanStack/query)   |    901 | **560ms** |     1.04s |  fallow 1.9x |
    | [vite](https://github.com/vitejs/vite)                |  1,420 |     595ms |  errors\* |  fallow only |
    | [astro](https://github.com/withastro/astro)           |  2,859 |     3.76s | **1.21s** |    knip 3.1x |
    | [svelte](https://github.com/sveltejs/svelte)          |  3,337 | **611ms** |     632ms |  fallow 1.0x |
    | [next.js](https://github.com/vercel/next.js)          | 20,558 |     2.95s |  errors\* |  fallow only |
    | [TypeScript](https://github.com/microsoft/TypeScript) | 38,146 |     2.22s | **736ms** |    knip 3.0x |

    \* Current knip (v5 and v6) exits without valid output on next.js, vite, and vue/core (it fails loading those projects' own config files); fallow analyzes them.

    | Metric             | fallow                   | knip                            |
    | :----------------- | :----------------------- | :------------------------------ |
    | Runtime dependency | None (standalone binary) | Node.js                         |
    | CI setup           | Download binary          | Install Node + npm dependencies |

    Numbers are knip v6 (knip 6.6.1). fallow is faster on the small-to-mid projects (fastify, preact, query, svelte, zod), while current knip is faster on astro and TypeScript. fallow's edge is doing more in one tool, not always raw dead-code speed, and it analyzes the three projects knip cannot load here. Against knip v5 (knip 5.87.0) fallow's lead widens (for example fallow 13.7x on fastify, 13.0x on zod, 10.3x on preact).
  </Tab>

  <Tab title="Features">
    | Feature               | fallow                    | knip                   |
    | :-------------------- | :------------------------ | :--------------------- |
    | Duplication detection | Built-in (`fallow dupes`) | Not included           |
    | SARIF output          | Yes                       | No                     |
    | Baseline comparison   | Yes (`--baseline`)        | No                     |
    | Git-aware analysis    | `--changed-since`         | No                     |
    | Production mode       | `--production`            | No                     |
    | Auto-fix              | Exports + dependencies    | Exports + dependencies |
    | Config format         | JSONC, JSON, TOML         | JSON, TS               |
  </Tab>

  <Tab title="Coverage">
    | Capability         | fallow                                                              | knip                              |
    | :----------------- | :------------------------------------------------------------------ | :-------------------------------- |
    | Built-in catalogue | Major frameworks and tools                                          | Broader niche and legacy coverage |
    | Dead code coverage | Files, exports, dependencies, members, cycles, boundaries, and more | Comparable core coverage          |
    | Custom plugins     | Yes                                                                 | Yes                               |
  </Tab>
</Tabs>

## See also

<CardGroup>
  <Card title="Custom plugins" icon="plug" href="/frameworks/custom-plugins">
    Build plugins for frameworks fallow doesn't cover yet.
  </Card>

  <Card title="fallow migrate" icon="terminal" href="/cli/migrate">
    Full CLI reference for the migrate command.
  </Card>
</CardGroup>


# Quick start
Source: https://docs.fallow.tools/quickstart

Run Fallow for the first time and understand the output in under a minute. One golden path, then branch into VS Code, CI, MCP, or runtime intelligence.

This page gets you from zero to a useful result fast. Everyone starts the same way. Branch off at the end.

## 1. Run Fallow

From your project root:

```bash theme={null}
npx fallow
```

That runs three analyses in one pass:

* **Dead code**: unused files, exports, dependencies, cycles, boundaries, and more
* **Duplication**: repeated logic across files
* **Health**: complexity hotspots and refactor targets

<Tip>
  Built-in plugins cover Next.js, Vite, Ember, Wuchale, Jest, Tailwind, PandaCSS, Contentlayer, tap, tsd, and more. No configuration needed for the first run.
</Tip>

## 2. Run the focused commands you'll use most

```bash theme={null}
npx fallow dead-code          # Cleanup candidates
npx fallow dupes              # Repeated logic
npx fallow health             # Complexity and refactor targets
npx fallow review             # Advisory review brief over changed files (always exits 0)
npx fallow fix --dry-run      # Preview automatic cleanup
```

* `dead-code` reports unused files, exports, types, dependencies, circular deps, and boundary violations. See the [dead code guide](/analysis/dead-code).
* `dupes` catches AST-based duplicates in the default `mild` mode. Add `--mode semantic` to also catch clones with renamed variables. See the [duplication guide](/analysis/duplication).
* `health` reports complexity findings, per-file maintainability, hotspots, and ranked refactor targets. See the [health explanation](/explanations/health).
* `fix --dry-run` previews automatic cleanup. When you're ready, drop `--dry-run`. See the [auto-fix guide](/analysis/auto-fix).

<Tip>
  Cleaning up or refactoring TypeScript? Add `--type-aware` when aliases,
  re-exports, class contracts, packages, or exact consumers affect the
  decision. This is an optional, slower semantic pass. See
  [Type-aware TypeScript analysis](/analysis/type-aware).
</Tip>

## 3. Pick your next step

<Info>
  Existing repo with backlog? Read [Adopt Fallow in an existing repo](/adoption) for a structured cleanup path, then come back here to wire up CI or VS Code.
</Info>

<CardGroup>
  <Card title="Use it in VS Code" icon="window" href="/integrations/vscode">
    Real-time diagnostics, Code Lens above exports, and one-click fixes.
  </Card>

  <Card title="Use it in CI" icon="shield-check" href="/integrations/ci">
    Turn Fallow into a PR and merge gate with SARIF or MR annotations.
  </Card>

  <Card title="Use it from agents" icon="robot" href="/integrations/mcp">
    Add MCP for structured tool calling from Claude Code, Cursor, and more.
  </Card>

  <Card title="Add runtime evidence" icon="chart-network" href="/analysis/runtime-coverage">
    Layer production execution data into `fallow health`.
  </Card>
</CardGroup>

## Optional: create a config

Fallow works without a config file. When you want to customize, run:

```bash theme={null}
fallow init
```

This auto-detects your project structure and generates a tailored config. It also adds `.fallow/` to your `.gitignore`.

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
    "entry": ["src/workers/*.ts", "scripts/*.ts"],
    "ignorePatterns": ["**/*.generated.ts"],
    "rules": {
      "unused-files": "error",
      "unused-exports": "warn",
      "unused-types": "off"
    }
  }
  ```

  ```toml fallow.toml theme={null}
  entry = ["src/workers/*.ts", "scripts/*.ts"]
  ignorePatterns = ["**/*.generated.ts"]

  [rules]
  unused-files = "error"
  unused-exports = "warn"
  unused-types = "off"
  ```
</CodeGroup>

<Info>
  Migrating from knip or jscpd? Run `fallow migrate`, or see the [knip](/migration/from-knip) or [jscpd](/migration/from-jscpd) guides.
</Info>

## Optional: runtime intelligence

Fallow's static layer is free and open source. If you want to know what actually executed in production, add the runtime layer:

```bash theme={null}
npx fallow license activate --trial --email you@company.com
npx fallow coverage setup
npx fallow health --runtime-coverage ./coverage
```

Before you do that, read [Static vs runtime intelligence](/explanations/static-vs-runtime) for the mental model, then the [runtime coverage guide](/analysis/runtime-coverage) for setup details.

## Next steps

<CardGroup>
  <Card title="Analysis overview" icon="magnifying-glass" href="/analysis/index">
    What Fallow analyzes, at a glance.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Customize entry points, rules, and ignore patterns.
  </Card>

  <Card title="Explanations" icon="book-open" href="/explanations/index">
    Mental models for how Fallow works.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli/dead-code">
    Every command and flag.
  </Card>
</CardGroup>