fallow: The codebase analyzer for TypeScript and JavaScript

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

Running bare fallow now 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.

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`
`-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, explanations are always shown. 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), or `package` (workspace package). See global flags.
`--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
`--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
`--unresolved-imports`	Only report unresolved imports
`--unlisted-deps`	Only report unlisted dependencies
`--duplicate-exports`	Only report duplicate exports
`--circular-deps`	Only report circular dependencies
`--boundary-violations`	Only report boundary violations
`--type-only-deps`	Only report type-only dependencies
`--include-dupes`	Also run duplication analysis and cross-reference with dead code

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

Debugging flags

These flags help you understand how fallow resolves your code and where time is spent.

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

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

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

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

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)

These flags also work with fallow dupes and bare fallow (all analyses). The regression check compares total issue counts across all enabled analyses.

Example output

$ fallow dead-code --format compact

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

Grouped output

Use --group-by to partition issues by ownership or directory. This works with all output formats.

# Group by CODEOWNERS (auto-probes CODEOWNERS, .github/CODEOWNERS, .gitlab/CODEOWNERS, docs/CODEOWNERS)
fallow dead-code --group-by owner

# Group by first directory component
fallow dead-code --group-by directory

# Group by workspace package
fallow dead-code --group-by package

With --format json, grouped output wraps the normal structure:

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

Set a custom CODEOWNERS path via the codeowners field in .fallowrc.json if your file isn’t in a standard location.

Fix suggestions in JSON output

When using --format json, every issue includes an actions array with machine-actionable fix and suppress hints. This lets agents and CI scripts programmatically decide how to resolve each finding.

{
  "path": "src/utils.ts",
  "export_name": "helperFn",
  "line": 10,
  "actions": [
    {
      "type": "remove-export",
      "auto_fixable": true,
      "description": "Remove the `export` keyword from the declaration"
    },
    {
      "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`	One of 14 fix action types 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
`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
`scope`	(optional) Present on `duplicate_exports` suppress actions as `"per-location"` since those span multiple files

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

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,
    "unused_dependencies": 1,
    "unresolved_imports": 0,
    "circular_dependencies": 1,
    "total_issues": 19
  }
}

`baseline_deltas`

When --baseline is used, a baseline_deltas object shows changes since the baseline:

{
  "baseline_deltas": {
    "added": 3,
    "removed": 5,
    "unchanged": 14
  }
}

Dead code analysis

How fallow detects dead code.

Rules configuration

Configure severity and thresholds per rule.

Production mode

Analyze only shipping code.

Commands

fallow dead-code

Options

Output

Filtering

Incremental

Regression detection

Examples

Regression detection

Example output

Grouped output

Fix suggestions in JSON output

Additional JSON fields

`entry_points`

`summary`

`baseline_deltas`

See also

Dead code analysis

Rules configuration

Production mode

Commands

​Options

​Output

​Filtering

​Incremental

​Regression detection

​Examples

​Regression detection

​Example output

​Grouped output

​Fix suggestions in JSON output

​Additional JSON fields

​entry_points

​summary

​baseline_deltas

​See also

Dead code analysis

Rules configuration

Production mode

Options

Output

Filtering

Incremental

Regression detection

Examples

Regression detection

Example output

Grouped output

Fix suggestions in JSON output

Additional JSON fields

`entry_points`

`summary`

`baseline_deltas`

See also