Skip to content
Fallow home
All docs pages

Docs home

Config: rules and gates

Find the fallow config keys for rules and gates, with type, default, allowed values and description.

The config file holds the settings of fallow. How config works explains where fallow finds the file and how files merge.

rules

  • Type: object

Sets per-issue-type severity, keyed by kebab-case rule id: error reports and fails CI (non-zero exit), warn reports without failing, off disables detection and reporting entirely (e.g. { "unused-files": "error", "unused-exports": "warn", "private-type-leaks": "off" }). Set a rule off to silence it, warn to demote below CI gating, or error to promote a warn/off-default rule to gating; most rules default to error, dev/optional-dependency and component/store/inject/CSS/catalog rules default to warn, and opt-in rules (private-type-leaks, deprecated-exports-in-use, security-*, prop-drilling, thin-wrapper, duplicate-prop-shape, coverage-gaps, feature-flags, require-suppression-reason) default to off. Singular aliases (unused-file) and warning/none severity spellings are accepted.

Each key takes one of these values:

  • error: Report and set a non-zero exit code.
  • warn: Report without an effect on the exit code.
  • off: Do not detect or report.
KeyDefaultDescription
unused-files"error"A file reachable from no entry point.
unused-exports"error"An exported symbol no other module imports.
unused-types"error"An exported type no other module uses.
private-type-leaks"off"An exported signature referencing a same-file private type.
deprecated-exports-in-use"off"An export marked @deprecated that still has at least one reachable reference.
unused-dependencies"error"A declared dependencies entry never observed used.
unused-dev-dependencies"warn"A declared devDependencies entry never observed used.
unused-optional-dependencies"warn"A declared optionalDependencies entry never observed used.
unused-enum-members"error"An enum member read nowhere in the project.
unused-class-members"error"A class member used nowhere; usedClassMembers and decorator exemptions carve out framework-invoked members.
unused-namespace-members"warn"Exported members of an exported TypeScript namespace that no code reads.
unused-protected-class-members"off"A protected class member that neither its class nor a subclass reads through this or super.
unused-store-members"warn"Store members (Pinia state / getters / actions key, or a setup-store returned key) declared but never accessed by any consumer project-wide.
unprovided-injects"warn"Vue inject(KEY) / Svelte getContext(KEY) whose symbol KEY is provide/setContext'd nowhere in the project (the injected-never-provided dead-half).
unrendered-components"warn"Vue/Svelte single-file component reachable in the module graph but rendered nowhere in the project (the imported-but-never-rendered dead-half).
unused-component-props"warn"Vue <script setup> defineProps, Svelte 5 $props(), or React declared prop referenced nowhere inside its own component.
absent-component-props"off"Used optional inputs absent from inspected callers.
constant-parameters"off"Parameters, and option keys of object-pattern parameters, that each visible call passes in one way.
unused-component-emits"warn"Vue <script setup> defineEmits declared event emitted nowhere inside its own single-file component (no emit('<name>') call).
unused-component-inputs"warn"Angular @Input() / signal input() / model() declared input read nowhere inside its own component (neither the inline/external template nor the class body).
unused-component-outputs"warn"Angular @Output() / signal output() declared output emitted nowhere inside its own component (no this.<output>.emit(...)).
unused-svelte-events"warn"Svelte component dispatching a custom event via createEventDispatcher() whose event name is listened to nowhere in the analyzed project.
unused-effect-layers"warn"Effect layer composed only into other layers that nothing uses.
unused-tagged-errors"warn"Effect tagged error class that only type positions or catchTag handlers reference.
unproduced-catch-tags"warn"catchTag handler for a project tag that no code produces, when no unused-tagged-errors finding covers it.
unused-server-actions"warn"Next.js Server Action (an export of a "use server" file) referenced by no code in the project: no import-and-call, no action={fn} binding, no <form action={fn}>.
unused-load-data-keys"warn"SvelteKit +page.{ts,server.ts,js,server.js} load() return-object key read by no consumer: not off the sibling +page.svelte's data.<key>, nor project-wide via page.data.<key> / $page.data.<key>.
prop-drilling"off"React/Preact prop forwarded unchanged through >= N intermediate pass-through components until a component that substantively consumes it.
thin-wrapper"off"A React/Preact component whose entire body is return <Child {...props}/> (pure structural indirection, a candidate for inlining).
duplicate-prop-shape"off"Three or more React/Preact components across two or more files whose statically-harvested prop NAME set is identical after stripping ubiquitous DOM / passthrough names (a missing shared Props type / base component).
css-token-drift"warn"A CSS / CSS-in-JS design-token drift finding (a hardcoded value where a design token exists, e.g. a Tailwind arbitrary value).
css-duplicate-block"warn"A CSS / CSS-in-JS duplicate declaration block (copy-pasted rule body).
css-selector-complexity"warn"CSS selector / nesting / important-density complexity.
css-dead-surface"warn"CSS dead surface, such as unused scoped SFC classes.
css-broken-reference"warn"CSS broken references, such as missing classes or keyframes.
complexity-cyclomatic"error"A function above the cyclomatic ceiling (health.maxCyclomatic or a thresholdOverrides entry).
complexity-cognitive"error"A function above the cognitive ceiling (health.maxCognitive or a thresholdOverrides entry).
complexity-crap"error"A function above the CRAP ceiling (health.maxCrap or a thresholdOverrides entry).
complexity-file-lines"error"A file above the file-length ceiling (health.maxFileLines or a thresholdOverrides entry).
unresolved-imports"error"An import specifier that resolves to no file or package.
unlisted-dependencies"error"An imported package not declared in any relevant package.json.
unlisted-binaries"warn"A binary that a package.json script or a process call runs, but that no installed or listed package provides.
duplicate-exports"error"The same export name provided by multiple modules; ignoreExports excludes intentional barrel re-exports.
duplicate-export-aliases"warn"One module that exports one binding under two or more names, for example export const a = 1; export default a;.
type-only-dependencies"warn"A production dependency imported only via type-only imports (a devDependencies candidate).
test-only-dependencies"warn"A production dependency imported only by test files.
dev-dependencies-in-production"warn"A devDependencies entry imported by production code, which a production-only install would omit and break at runtime.
circular-dependencies"error"A circular import chain between modules.
re-export-cycle"warn"A cycle or self-loop in the re-export subgraph (barrel files re-exporting from each other in a loop).
package-cycle"warn"A dependency cycle between workspace packages, built from resolved cross-package imports.
boundary-violation"error"An import crossing a forbidden architecture-boundary edge declared in the boundaries config.
coverage-gaps"off"A runtime file or export with no test dependency path.
feature-flags"off"A detected feature-flag pattern (tuned via the flags config).
stale-suppressions"warn"A fallow-ignore comment or @expected-unused tag that no longer matches any issue.
require-suppression-reason"off"Opt-in suppression hygiene rule: when enabled, every fallow-ignore-* comment and @expected-unused tag must carry a -- <reason> suffix.
unused-catalog-entries"warn"A pnpm-workspace.yaml catalog entry referenced by no workspace package.
empty-catalog-groups"warn"A named pnpm catalog group declaring no entries.
unresolved-catalog-references"error"A workspace package.json catalog: / catalog:<name> reference pointing at a catalog that does not declare the consumed package.
unused-dependency-overrides"warn"A pnpm, npm, or Bun override entry whose target package no workspace package.json declares and the active readable lockfile does not resolve.
misconfigured-dependency-overrides"error"A pnpm, npm, or Bun override or Bun resolutions entry whose key or value cannot be parsed in its declaration source's grammar.
security-client-server-leak"off"Opt-in (default off): a "use client" file that transitively imports a module reading a non-public process.env secret.
security-sink"off"Opt-in (default off): a syntactic tainted-sink candidate matched against the data-driven catalogue (security_matchers.toml).
policy-violation"warn"Master severity for rule-pack findings (rulePacks config).
invalid-client-export"warn"A "use client" file that exports a Next.js server-only / route-segment config name (e.g. metadata, revalidate, GET).
mixed-client-server-barrel"warn"A barrel file that re-exports both a "use client" origin module and a server-only origin module.
misplaced-directive"warn"A "use client" / "use server" directive written as an expression statement after a non-directive statement (an import, a const), so the RSC bundler parses it as an ordinary string and silently ignores it.
route-collision"error"Two or more Next.js App Router route files that resolve to the same URL within one app-root.
dynamic-segment-name-conflict"error"Sibling Next.js dynamic route segments at one tree position using different param spellings ([id] vs [slug]).
weakened-tests"warn"An audit diff that weakens tests: a new skip or focus marker, removed test cases, fewer assertions, or a lowered coverage threshold.
added-suppression"warn"An audit diff that adds a lint, type-check, coverage or Fallow suppression comment.
test-only-branch"warn"An audit diff that adds a test-environment branch to a non-test source file.
diverged-clone-sibling"off"An audit diff that edits one copy of a base clone group so that it no longer matches its siblings, while no sibling changed.
added-dependency"off"An audit diff that adds a dependency to a package.json.
introduced-clone-group"warn"A clone group that fallow audit attributes to the change.

overrides

  • Type: object[]
  • Default: []

An ordered list of per-file rule-severity overrides: each entry re-severities specific analysis rules for files its globs match, layered on top of the top-level rules defaults. Set to relax or tighten a rule for a subset of paths (e.g. downgrade unused-exports to warn under a generated directory); each entry has files (glob-pattern array) and rules (a partial per-rule severity map of error/warn/off). Entries apply in list order and a file matched by several entries takes every matching entry's overrides (later entries win on conflict). For most rules, an override cannot start a detector for a rule that is off at top level, so set the top-level rule on and use an override to set off for the other paths. Project-level rules ignore overrides: unused-dependencies, unused-dev-dependencies, unused-optional-dependencies, unlisted-dependencies, unlisted-binaries, type-only-dependencies, test-only-dependencies, dev-dependencies-in-production, duplicate-exports, re-export-cycle and unused-catalog-entries. Fallow reports each such entry as an override-rule-ineffective diagnostic that names the mechanism that works. A single * stays within one path segment; use ** to match across directories.

KeyTypeDefault
filesstring[]
rulesobject

overrides[].files

  • Type: string[]

Glob-pattern string array selecting which source files this override entry applies to (patterns are validated and compiled to matchers at config load). Set to scope the entry's rule severities to a subset of paths (e.g. ["src/generated/**", "**/*.test.ts"]); when several override entries match one file, its severities come from every matching entry, applied in list order (later entries win on conflict). A single * stays within one path segment; use ** to match across directories.

overrides[].rules

  • Type: object

Partial per-rule severity map applied only to files matching this entry's files globs; each rule key takes error, warn, or off, and omitted rules keep their top-level severity. Set to change how specific rules (e.g. unused-exports, unused-files) behave for the scoped paths. Project-level rules ignore overrides: unused-dependencies, unused-dev-dependencies, unused-optional-dependencies, unlisted-dependencies, unlisted-binaries, type-only-dependencies, test-only-dependencies, dev-dependencies-in-production, duplicate-exports, re-export-cycle and unused-catalog-entries. Fallow reports each such entry as an override-rule-ineffective diagnostic that names the mechanism that works. For most other rules, an override cannot start a detector for a rule that is off at top level.

Each key of rules can appear here, with the same values.

regression

  • Type: object (optional)

Holds a saved issue-count baseline that the --fail-on-regression gate compares the current run against, failing only when counts grow beyond tolerance relative to the baseline. Usually written by --save-baseline rather than hand-authored; the object has a single baseline sub-key holding per-issue-type counts (total_issues plus per-kind fields like unused_exports, boundary_violations, policy_violations, each defaulting to 0). Absent means no baseline is embedded in config.

KeyTypeDefault
baselineobject

regression.baseline

  • Type: object (optional)

The saved per-issue-type issue counts that --fail-on-regression compares the current run against; the gate fails only when counts grow beyond the configured tolerance. Typically written by --save-baseline rather than hand-authored; each field (total_issues plus per-kind counts like unused_exports, boundary_violations, policy_violations) is an integer defaulting to 0 when omitted. Absent means no baseline is embedded.

regression.baseline.absentComponentProps

  • Type: integer
  • Default: 0

Baseline count of optional component prop review candidates.

regression.baseline.constantParameters

  • Type: integer

Baseline count of constant parameter review candidates. Absent while zero, so a baseline without the opt-in rule keeps its shape.

regression.baseline.analysisIdentity

  • Type: object

Compatibility identity for the analysis that produced these counts. Missing values in existing configs are treated as syntactic.

regression.baseline.analysisIdentity.mode
  • Type: string

Syntactic or type-aware analysis mode.

Allowed values:

  • syntactic: Normal Fallow analysis with no TypeScript semantic backend.
  • type-aware: Opt-in analysis with one or more semantic capabilities.
regression.baseline.analysisIdentity.semantic_schema_version
  • Type: integer

Version of the semantic result schema, independent of tool versions.

regression.baseline.analysisIdentity.capabilities
  • Type: string[]

Sorted capability set requested for the analysis.

Allowed values:

  • symbol-use: Confirm exact project-wide symbol use for an existing finding.
  • symbol-trace: Explain exact declarations, references, aliases, and re-exports.
  • api-surface: Describe package-public signatures and private type leaks.
  • symbol-impact: Find exact symbol consumers, affected files, and targeted tests.
  • type-coupling: Measure project-local public-signature coupling.
regression.baseline.analysisIdentity.project_config_hash
  • Type: string

Hash of normalized project ownership and compiler configuration.

regression.baseline.analysisIdentity.backend_family
  • Type: string

Backend family, such as typescript-go.

regression.baseline.analysisIdentity.completeness
  • Type: string

Completeness of the resulting semantic analysis.

Allowed values:

  • complete: Every requested query completed without omissions.
  • partial: Some evidence is valid, but bounded or unsupported relations remain.
  • unavailable: No safe semantic assertion could be made.

regression.baseline.totalIssues

  • Type: integer
  • Default: 0

Baseline count across all issue types.

regression.baseline.unusedFiles

  • Type: integer
  • Default: 0

Baseline count of unused-files findings.

regression.baseline.unusedExports

  • Type: integer
  • Default: 0

Baseline count of unused-exports findings.

regression.baseline.unusedTypes

  • Type: integer
  • Default: 0

Baseline count of unused-types findings.

regression.baseline.unusedDependencies

  • Type: integer
  • Default: 0

Baseline count of unused-dependencies findings.

regression.baseline.unusedDevDependencies

  • Type: integer
  • Default: 0

Baseline count of unused-dev-dependencies findings.

regression.baseline.unusedOptionalDependencies

  • Type: integer
  • Default: 0

Baseline count of unused-optional-dependencies findings.

regression.baseline.unusedEnumMembers

  • Type: integer
  • Default: 0

Baseline count of unused-enum-members findings.

regression.baseline.unusedClassMembers

  • Type: integer
  • Default: 0

Baseline count of unused-class-members findings.

regression.baseline.unresolvedImports

  • Type: integer
  • Default: 0

Baseline count of unresolved-imports findings.

regression.baseline.unlistedDependencies

  • Type: integer
  • Default: 0

Baseline count of unlisted-dependencies findings.

regression.baseline.unlistedBinaries

  • Type: integer
  • Default: 0

Baseline count of unlisted-binaries findings.

regression.baseline.duplicateExports

  • Type: integer
  • Default: 0

Baseline count of duplicate-exports findings.

regression.baseline.circularDependencies

  • Type: integer
  • Default: 0

Baseline count of circular-dependencies findings.

regression.baseline.reExportCycles

  • Type: integer
  • Default: 0

Baseline count of re-export-cycle findings.

regression.baseline.packageCycles

  • Type: integer
  • Default: 0

Baseline count of package-cycle findings.

regression.baseline.typeOnlyDependencies

  • Type: integer
  • Default: 0

Baseline count of type-only-dependencies findings.

regression.baseline.testOnlyDependencies

  • Type: integer
  • Default: 0

Baseline count of test-only-dependencies findings.

regression.baseline.devDependenciesInProduction

  • Type: integer
  • Default: 0

Baseline count of dev-dependencies-in-production findings.

regression.baseline.boundaryViolations

  • Type: integer
  • Default: 0

Baseline count of boundary-violation findings.

regression.baseline.boundaryCoverageViolations

  • Type: integer
  • Default: 0

Baseline count of boundary-coverage-violation findings.

regression.baseline.boundaryCallViolations

  • Type: integer
  • Default: 0

Baseline count of boundary-call-violation findings.

regression.baseline.policyViolations

  • Type: integer
  • Default: 0

Baseline count of policy-violation findings.

audit

  • Type: object

Sets in-repo defaults for fallow audit (the changed-files quality gate) so CLI flags need not repeat per run. Set to pin audit behavior; the object holds gate (new-only or all, which findings drive the verdict), css/cssDeep (booleans toggling styling analysis and the project-wide CSS reachability pass), deadCodeBaseline/healthBaseline/dupesBaseline (per-sub-analysis baseline file paths), and cacheMaxAgeDays (the age in days after which fallow removes an entry of the reusable base-snapshot worktree cache). The matching CLI flag overrides each field.

KeyTypeDefault
gatestring
worsenedstring
deadCodeboolean
healthboolean
dupesboolean
cssboolean
cssDeepboolean
deadCodeBaselinestring
healthBaselinestring
dupesBaselinestring
cacheMaxAgeDaysinteger
typeAwareboolean

audit.gate

  • Type: string

Selects which findings affect the fallow audit verdict: new-only (default) fails only on findings introduced by the current changeset (running a base-snapshot attribution pass), while all fails on every finding in changed files and skips that pass. Set to all to gate the full backlog in changed files; the --gate CLI flag overrides this.

Allowed values:

  • new-only: Fail only on findings the current changeset introduced, determined by a base-snapshot attribution pass. An unused file or unused export outside the changed files counts when the base does not report it. The default.
  • all: Fail on every finding in changed files, skipping the attribution pass.

audit.worsened

  • Type: string

Selects how a worsened complexity finding affects the fallow audit verdict under gate: new-only. A worsened finding was already in the base snapshot, and a measured value is higher now. Any growth of cyclomatic, cognitive or CRAP counts. The line count must grow by at least 5 lines, and it includes comments and blank lines. warn (default) makes the verdict at least warn and does not fail the run. error counts a worsened finding like an introduced finding. off reports only the growth of a metric that the finding exceeds as worsened, which gives at least warn. A finding whose exceeded metric grew is worsened when it stays in its severity tier (moderate, high, critical), and introduced when it moves to a higher tier or exceeds a metric that the base finding did not exceed. The --worsened CLI flag overrides this.

Allowed values:

  • warn: A worsened finding makes the verdict at least warn and does not fail the run. The default.
  • error: A worsened finding counts like an introduced finding.
  • off: Growth only in metrics that the finding does not exceed stays inherited. Growth of an exceeded metric stays worsened and gives at least warn.

audit.deadCode

  • Type: boolean (optional)

Toggles the dead-code sub-analysis in fallow audit (unused files, exports, types, members and dependencies, plus boundary violations and circular dependencies, which come from the same pass). Defaults to on when unset; set false to leave it out of the verdict, summary and attribution, on the head and on the base snapshot. fallow audit --skip dead-code turns it off for one run and --only replaces this selection. The review brief (--brief, fallow review) keeps every sub-analysis because it reads the module graph.

audit.health

  • Type: boolean (optional)

Toggles the health sub-analysis in fallow audit (complexity and CRAP findings, plus styling findings, which come from the same pass). Defaults to on when unset; set false to leave it out of the verdict, summary and attribution, on the head and on the base snapshot. fallow audit --skip health turns it off for one run and --only replaces this selection.

audit.dupes

  • Type: boolean (optional)

Toggles the duplication sub-analysis in fallow audit. Defaults to the value of duplicates.enabled when unset, which is on by default; set false to leave clone groups out of the verdict, summary and attribution, on the head and on the base snapshot. fallow audit --skip dupes turns it off for one run and --only replaces this selection.

audit.css

  • Type: boolean (optional)

Toggles styling analytics (CSS and CSS-in-JS) in the fallow audit health sub-pass; these findings are descriptive and verdict-neutral by default (they change the exit code only when a css-* rule is set to error). Defaults to on when unset; set false to skip styling analysis. The --no-css CLI flag forces it off regardless.

audit.cssDeep

  • Type: boolean (optional)

Toggles the project-wide CSS reachability pass in fallow audit, whose cross-file findings are narrowed back to changed anchors. Defaults to on when unset and runs only when css analytics are enabled; set false to keep local styling analytics but skip the whole-project scan. The --css-deep flag re-enables it and --no-css-deep forces it off.

audit.deadCodeBaseline

  • Type: string (optional)

Path to a saved dead-code baseline file (produced by fallow dead-code --save-baseline) that the audit's dead-code sub-analysis compares against, suppressing pre-existing dead-code issues. The --dead-code-baseline CLI flag overrides it and both resolve relative to the project root; each sub-analysis uses a distinct baseline format, so this is separate from healthBaseline and dupesBaseline.

audit.healthBaseline

  • Type: string (optional)

Path to a saved health/complexity baseline file (produced by fallow health --save-baseline) that the audit's health sub-analysis compares against, suppressing pre-existing complexity/health findings. The --health-baseline CLI flag overrides it and both resolve relative to the project root; its baseline format is distinct from the dead-code and dupes baselines.

audit.dupesBaseline

  • Type: string (optional)

Path to a saved duplication baseline file (produced by fallow dupes --save-baseline) that the audit's duplication sub-analysis compares clone groups against, suppressing pre-existing duplicate clones. The --dupes-baseline CLI flag overrides it and both resolve relative to the project root; its baseline format is distinct from the dead-code and health baselines.

audit.cacheMaxAgeDays

  • Type: integer (optional)

Garbage-collection threshold, in whole days, for the persistent reusable base-snapshot worktree caches fallow audit creates: entries older than this window are swept on each audit run. Set to control cache accumulation; 0 disables the sweep and unset defaults to 30 days. Each sweep also reclaims abandoned entries minted under other repo identities (deleted or moved repos, other git worktrees) once they age past this repo's threshold; entries whose recorded owner root still exists are skipped and stay governed by that repo's own setting. The same window applies to the base-snapshot files in the project cache directory, counted from their last use; independent of this window, audit keeps only the newest 32 of those files. The FALLOW_AUDIT_CACHE_MAX_AGE_DAYS environment variable overrides this field.

audit.typeAware

  • Type: boolean (optional)

Overrides the top-level typeAware.enabled opt-in for fallow audit only: set false to keep persistent type-aware analysis on for cleanup commands (dead-code, fix, health) while the audit gate stays syntactic, or true to enable it for audit alone. Unset inherits typeAware.enabled. The --type-aware/--no-type-aware CLI flags and the FALLOW_TYPE_AWARE environment variable both take precedence over this field.

showCascade

  • Type: boolean
  • Default: false

When true, the report keeps the unused exports, unused types, unused class members and unused enum members of a file that is an unused file. Boolean, defaults to false: deleting an unused file removes these findings, so the report hides them and counts them in cascade_hidden. The CLI flag --show-cascade applies the same behavior for one run.