fallow dead-code

Analyze your project for dead code. Fallow scans entry points, traces all reachable exports, and reports anything that isn't used.

fallow dead-code
fallow check      # Hidden alias for fallow dead-code

Options

Output

Filtering

Scoping

Type-aware TypeScript evidence

See Type-aware TypeScript analysis for the safety contract and the boundary with tsc and Oxlint.

Incremental

Regression detection

# 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

Examples

fallow dead-code

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:

   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:

   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:

   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:

{
  "regression": {
    "status": "pass",
    "baseline_total": 42,
    "current_total": 45,
    "delta": 3,
    "tolerance": 2.0,
    "tolerance_kind": "percentage",
    "exceeded": false
  }
}

Example output

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:

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

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

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:

{
  "entry_points": [
    "src/index.ts",
    "src/cli.ts",
    "src/workers/sync.ts"
  ]
}

summary

When --summary is used, a summary counts object is included:

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

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

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

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

The stale-suppressions rule defaults to warn. Promote to error for CI enforcement:

{
  "rules": {
    "stale-suppressions": "error"
  }
}

When using --format json, stale suppressions appear in the stale_suppressions array:

{
  "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"
      }
    }
  ]
}

See also