> ## 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 & severity
> 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.
Start with all rules as `warn`, then promote to `error` one type at a time as the codebase cleans up.
## 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` and `coverage-gaps` (default `off`), plus `stale-suppressions` (default `warn`).
## Configuration
```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",
"boundary-violation": "error",
"type-only-dependencies": "error",
"test-only-dependencies": "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"
boundary-violation = "error"
type-only-dependencies = "error"
test-only-dependencies = "warn"
coverage-gaps = "off"
stale-suppressions = "warn"
```
## 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-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.:` 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:` 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 |
| `boundary-violation` | Imports that cross user-defined architecture zone boundaries |
| `type-only-dependencies` | Production dependencies only imported via `import type` |
| `test-only-dependencies` | Production dependencies only imported by test files |
| `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`) |
`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](/analysis/dead-code#baseline-comparison) 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.
```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
Full config file reference with all available fields.
Set up fallow in GitHub Actions, GitLab CI, and more.