Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt

Use this file to discover all available pages before exploring further.

Rules control the severity of each issue type, making it easy to adopt fallow incrementally in CI.
Start with all rules as warn, then promote to error one type at a time as the codebase cleans up.

​
Severity levels

LevelBehavior
errorReport and fail CI (non-zero exit code)
warnReport but exit 0
offDon’t detect or report
Most issue types default to error when not configured. The exceptions are private-type-leaks and coverage-gaps (default off), plus stale-suppressions (default warn).

​
Configuration

{
  "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",
    "boundary-violation": "error",
    "type-only-dependencies": "error",
    "test-only-dependencies": "warn",
    "coverage-gaps": "off",
    "stale-suppressions": "warn"
  }
}

​
Available rule names

RuleDescription
unused-filesFiles not reachable from any entry point
unused-exportsExported symbols never imported
unused-typesType aliases and interfaces never referenced
private-type-leaksOpt-in API hygiene check for exported signatures that reference same-file private types (default off)
unused-dependenciesPackages in dependencies never used
unused-dev-dependenciesPackages in devDependencies never used
unused-optional-dependenciesPackages in optionalDependencies never used
unused-enum-membersEnum values never referenced
unused-class-membersClass members never referenced
unused-catalog-entriesEntries in pnpm-workspace.yaml’s catalog: / catalogs: maps that no workspace package references via the catalog: protocol (default warn)
empty-catalog-groupsNamed catalogs.<name>: groups in pnpm-workspace.yaml that contain no package entries (default warn; top-level catalog: placeholders are ignored)
unresolved-catalog-referencespackage.json references to catalog: / catalog:<name> whose catalog does not declare the package (default error; pnpm install would fail)
unused-dependency-overridespnpm-workspace.yaml#overrides / package.json#pnpm.overrides entries forcing a version no workspace package depends on (default warn; some are intentional pins for transitive CVEs)
misconfigured-dependency-overridespnpm.overrides entries whose key is unparsable or value is missing (default error; pnpm install would fail)
unresolved-importsImports that can’t be resolved
unlisted-dependenciesImported packages not in package.json
duplicate-exportsSame symbol exported from multiple files
circular-dependenciesModules that import each other, directly or transitively
boundary-violationImports that cross user-defined architecture zone boundaries
type-only-dependenciesProduction dependencies only imported via import type
test-only-dependenciesProduction dependencies only imported by test files
coverage-gapsRuntime files and exports not reached by any test dependency path (default off)
stale-suppressionsfallow-ignore comments or @expected-unused JSDoc tags that no longer match any issue (default warn)
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.
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 to avoid blocking CI on pre-existing issues while enforcing rules on new code.
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.
fallow dead-code --fail-on-issues

​
Exit codes

CodeMeaning
0No error-severity issues
1Error-severity issues found
2Fatal error (invalid config, parse failure)

​
See also

Configuration

Full config file reference with all available fields.

CI Integration

Set up fallow in GitHub Actions, GitLab CI, and more.