Config: health, tests and type-aware analysis
Find the fallow config keys for health, tests and type-aware analysis, 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.
mutation
- Type:
object
Configures the explicit fallow mutation workflow: runner (auto or vitest), operators (kebab-case names, default the default set), minScore (0 to 100; a lower score exits with code 1), and concurrency (half the logical cores). No key starts a run, and the side-effect override is a CLI flag only.
| Key | Type | Default |
|---|---|---|
runner | string | "auto" |
operators | string[] | |
minScore | number | |
concurrency | integer | |
mutantsPerLine | integer | |
functionScope | boolean | |
typecheck | boolean | |
runnerConfig | string | |
runnerProjects | string[] |
mutation.runner
- Type:
string - Default:
"auto"
The test runner: auto, vitest, node-test or bun-test. auto detects it from the project.
Allowed values:
auto: Detect the runner from the project: thevitestdependency, the test module that the test files import, a Bun file at the root, or anode --testscript.vitest: Vitest 4.1 to 5 from the projectnode_modules.node-test:node:testof Node.js 22.18 or later. Each test file runs in its own Node process.bun-test:bun testof Bun 1.4 or later. Each test file runs in its own Bun process.
mutation.operators
- Type:
string[](optional)
The operators to use. Unset uses the default set. An opt-in operator runs only when this list or --operators names it. --operators wins.
Allowed values:
arithmetic-operator:a + btoa - b, and the other arithmetic pairs.relational-operator:a < btoa <= b, and the other relational pairs.logical-operator:a && btoa || b, and the reverse.negate-condition: A condition to its negation.unary-operator: A unary operator removed or changed.update-operator:i++toi--, and the reverse.removed-call: A call statement removed.return-value: A return value changed.boolean-literal:truetofalse, and the reverse.string-literal: A string or template literal emptied or filled.optional-chaining:a?.btoa.b.regex-literal: One token of a regular expression literal changed: an anchor or a quantifier removed, a{n,m}range shortened to{n}, a character class negated, or a class escape with the opposite case.removed-chain-link:z.number().int()toz.number()in a module-levelconstinitializer: one call link of a fluent chain removed.block-statement: Opt-in. The statements of a block or function body removed.array-literal: Opt-in.[x]to[], and[]to["fallow"].object-literal: Opt-in. A non-empty object literal to{}.method-expression: Opt-in.startsWithtoendsWithand the other method pairs, ors.trim()tos.switch-case: Opt-in. The statements of acaseclause removed.call-expression: Opt-in. A call in an expression position tovoid 0.throw-statement: Opt-in. Athrow new X(...)statement removed.regex-constructor: Opt-in. The regex changes applied to anew RegExp("...")pattern.regex-assertion: Opt-in. A lookaround negated, or\band\Bswapped.nullish-fallback: Opt-in.a ?? btoa.
mutation.minScore
- Type:
number(optional) - Value: at least
0, at most100
The minimum mutation score, from 0 to 100. When the score of a run is lower, fallow mutation exits with code 1. Unset never fails a run. --min-score wins.
mutation.concurrency
- Type:
integer(optional) - Value: at least
1
The number of mutation runner processes. Unset uses half the logical cores. --concurrency wins.
mutation.mutantsPerLine
- Type:
integer(optional) - Value: at least
1
The maximum number of mutants on one source line. The plan keeps the most productive mutants of the line (relational, condition, arithmetic and logical operators first). The others are pending with the reason sampled-out. Unset keeps each mutant. --mutants-per-line wins.
mutation.functionScope
- Type:
boolean(optional)
Widen each changed line to the whole function that holds it, so that a change to a parameter or a signature selects the mutants of the function. Only the changed-code scope uses it. Unset or false mutates the changed lines only. --function-scope turns it on.
mutation.typecheck
- Type:
boolean(optional)
Type-check each survived mutant through the type-aware companion of --type-aware. A survivor that does not type-check becomes compile_error and does not count in the score. A survivor that removes an optional-chaining link or a nullish fallback from a receiver whose type excludes null and undefined gets an advisory equivalence_hint. Its status and the score do not change. Unset or false checks no survivor. --typecheck turns the check on.
mutation.runnerConfig
- Type:
string(optional)
The config file of the test runner, relative to the project root, for example vitest.integration.config.mjs. The file must exist inside the project root. Only the Vitest runner reads it. Unset uses the default config discovery of the runner. --runner-config wins.
mutation.runnerProjects
- Type:
string[](optional)
The names of the Vitest projects that the run uses, as the Vitest --project flag selects them, for example ["unit"]. A name can hold a * wildcard. The run then ignores each other project of the config, also a project from a separate config file. Only the Vitest runner reads it. Unset uses each project. --runner-project wins.
health
- Type:
object
Sets complexity and health thresholds for fallow health (also applied in combined fallow and fallow audit): maxCyclomatic (20), maxCognitive (15), maxCrap (30.0, findings at or above this are reported), crapRefactorBand (5, cyclomatic band below maxCyclomatic where a secondary refactor action is added), maxUnitSize (max function lines before a large-function finding, 60), maxFileLines (max physical lines per file before a file-level finding, 0 means off), coverage/coverageRoot (Istanbul coverage path and path-prefix strip for accurate CRAP), ignore globs (remove files from findings AND the health score), tailwindIgnorePatterns (regexes on normalized prefix-[value] Tailwind arbitrary-value tokens to exclude from --css findings and analytics), thresholdOverrides (per-file/per-function ceilings via files/functions/maxCyclomatic/maxCognitive/maxCrap/maxUnitSize/maxFileLines/reason), ownership (botPatterns and emailMode for --ownership), and suggestInlineSuppression (true, emit suppress-line action hints in JSON). Raise thresholds to relax which functions are flagged, wire coverage for real CRAP scores, or exempt generated/test files via ignore (drops them from the score too) or thresholdOverrides (keeps them visible under a higher ceiling). The max* thresholds govern findings only and never move health_score: its penalties use fixed calibration so grades stay comparable across projects, and ignore is the lever that removes files from the score.
| Key | Type | Default |
|---|---|---|
maxCyclomatic | integer | 20 |
cyclomaticPolicy | string | |
maxCognitive | integer | 15 |
maxCrap | number | 30 |
crapRefactorBand | integer | 5 |
maxUnitSize | integer | 60 |
maxFileLines | integer | |
coverage | string | |
coverageRoot | string | |
ignore | string[] | [] |
tailwindIgnorePatterns | string[] | |
thresholdOverrides | object[] | |
ownership | object | |
changeCoupling | object | |
suggestInlineSuppression | boolean | true |
health.maxCyclomatic
- Type:
integer - Default:
20 - Value: at most
65535
Maximum allowed cyclomatic complexity per function (default: 20). Functions exceeding this threshold are reported. Governs findings only; the health score's complexity penalties use fixed calibration (use health.ignore to remove a file from the score).
health.cyclomaticPolicy
- Type:
string
How the cyclomatic gate counts complexity (default: standard). literal-membership counts a chain of strict equality checks of one identifier against primitive literals (kind === "a" || kind === "b") as one predicate. The policy applies to the maxCyclomatic gate and to every CRAP score, so the maxCrap gate reads the same value. Findings then report the standard value as standard_cyclomatic. The health score, complexity density, and hotspots keep the standard count. Older fallow versions reject this key as unknown, so pair it with minimumVersion.
Allowed values:
standard: Count every decision point,&&,||, and??operator (McCabe).literal-membership: Count a literal membership chain as one predicate. A chain such askind === "a" || kind === "b" || kind === "c"adds no cyclomatic increments for its||operators. Only strict equality checks of one identifier against string, number, bigint, boolean, ornullliterals qualify. Member access, calls, mixed operators, and different operands keep the standard count.
health.maxCognitive
- Type:
integer - Default:
15 - Value: at most
65535
Maximum allowed cognitive complexity per function (default: 15). Functions exceeding this threshold are reported. Governs findings only, never the health score.
health.maxCrap
- Type:
number - Default:
30
Maximum allowed CRAP (Change Risk Anti-Patterns) score per function (default: 30.0). CRAP combines cyclomatic complexity with test coverage: high complexity plus low coverage produces a high CRAP score. Functions meeting or exceeding this threshold are reported. Use --coverage with Istanbul data for accurate per-function CRAP; otherwise fallow estimates coverage from the module graph. Governs findings and the threshold-relative file-score signals (crap_above_threshold, the risk triage tag, and the add_test_coverage refactoring target); measured values such as crap_max and the overall health score never move with it. Set to 0 to disable CRAP enforcement entirely: no findings, nothing counts above threshold, and file-score rows disclose baseline breaches as exempt instead. The complexity-crap rule is different: it decides if a finding fails the run, and off hides the findings but keeps the file-score signals.
health.crapRefactorBand
- Type:
integer - Default:
5 - Value: at most
65535
Band below maxCyclomatic where CRAP-only findings also receive a secondary refactor-function action (default: 5). Set to 0 to only suggest refactoring when cyclomatic already meets the configured threshold.
health.maxUnitSize
- Type:
integer - Default:
60
Maximum function length in lines of code before it is reported as an oversized "large function" (default: 60). Raise it globally, or per file via thresholdOverrides[].maxUnitSize, to relax the bar for generated or test files (where a describe() block spans hundreds of lines) without disabling complexity checks on those files. This filters the reported large-functions list only; the descriptive unit-size profile and the health score still reflect raw sizes against fixed calibration (the unit_size penalty keeps its >60 LOC very-high-risk edge so grades stay comparable across projects; use health.ignore to remove a file from the score entirely).
health.maxFileLines
- Type:
integer
Maximum file length in physical lines before the file is reported as a complexity finding with exceeded: "file_lines" (default: 0, off). Every line counts, also blank lines and comment lines. A final newline does not add a line. Set a limit such as 500 to enable the check, and raise it per file via thresholdOverrides[].maxFileLines. The complexity-file-lines rule decides if a finding fails the run. In fallow audit, a long file that did not grow stays inherited. Older fallow versions reject this key as unknown, so pair it with minimumVersion.
health.coverage
- Type:
string(optional)
Path to Istanbul coverage data (coverage-final.json) or raw V8 coverage (a NODE_V8_COVERAGE directory or one V8 JSON file) for accurate per-function CRAP scores. Relative paths resolve against the project root. The CLI --coverage flag and FALLOW_COVERAGE environment variable override this value. Consulted by fallow health, bare fallow, fallow audit, fallow viz, and the MCP audit / check_health tools.
health.coverageRoot
- Type:
string(optional)
Absolute prefix to strip from Istanbul file paths before CRAP matching. Use when coverage was generated under a different checkout root in CI or Docker. The CLI --coverage-root flag and FALLOW_COVERAGE_ROOT environment variable override this value. Consulted by fallow health, bare fallow, fallow audit, fallow viz, and the MCP audit / check_health tools.
health.ignore
- Type:
string[] - Default:
[]
Glob patterns to exclude from complexity analysis. A single * stays within one path segment; use ** to match across directories.
health.tailwindIgnorePatterns
- Type:
string[]
Regular expressions excluding Tailwind arbitrary-value utilities from token-drift findings and analytics, including CVA variants. Matches the normalized prefix-[value] token, without variants, negative signs, or suffix modifiers. Both -mt-[7px] and mt-[7px] match as mt-[7px]; bg-[#abc]/50 matches as bg-[#abc]. These spellings cannot be excluded independently. Use ^icon-\[ to exclude Iconify tokens, including variants. Defaults to no exclusions. Invalid regexes fail config loading.
health.thresholdOverrides
- Type:
object[]
Per-file or per-function threshold overrides. These keep exceptional functions visible as configured numeric ceilings instead of hiding them behind binary suppressions.
| Key | Type | Default |
|---|---|---|
files | string[] | |
functions | string[] | |
maxCyclomatic | integer | |
maxCognitive | integer | |
maxCrap | number | |
maxUnitSize | integer | |
maxFileLines | integer | |
reason | string |
health.thresholdOverrides[].files
- Type:
string[]
Project-root-relative file globs this override applies to. A single * stays within one path segment; use ** to match across directories.
health.thresholdOverrides[].functions
- Type:
string[]
Exact emitted function names this override applies to. Empty means every function in matching files. Synthetic units are matched by their emitted name, so "<template>" and "<snippet:NAME>" are valid keys. The synthetic "<module>" unit is not: it carries a file's module-scope decision points into the aggregate metrics and never produces a finding, so there is no ceiling for an override to move.
health.thresholdOverrides[].maxCyclomatic
- Type:
integer(optional) - Value: at most
65535
Local cyclomatic complexity ceiling.
health.thresholdOverrides[].maxCognitive
- Type:
integer(optional) - Value: at most
65535
Local cognitive complexity ceiling.
health.thresholdOverrides[].maxCrap
- Type:
number(optional)
Local CRAP ceiling.
health.thresholdOverrides[].maxUnitSize
- Type:
integer(optional)
Local unit-size ceiling: maximum function length in lines of code before it is reported as an oversized "large function". Leave functions empty to relax the bar for every function in the matching files (which covers both the describe() wrapper and the individual it() blocks in a test suite).
health.thresholdOverrides[].maxFileLines
- Type:
integer(optional)
Local file-length ceiling in physical lines. 0 turns the file-length check off for the matching files. The ceiling applies to whole files, so an entry that sets it must leave functions empty.
health.thresholdOverrides[].reason
- Type:
string(optional)
Human-readable rationale for the exception.
health.ownership
- Type:
object
Ownership analysis configuration. Controls bot filtering and email privacy mode for --ownership output.
| Key | Type | Default |
|---|---|---|
botPatterns | string[] | ["*\\[bot\\]*","dependabot*","renovate*","github-actions*","svc-*","*-service-account*"] |
emailMode | string | "handle" |
health.ownership.botPatterns
- Type:
string[] - Default:
["*\\[bot\\]*","dependabot*","renovate*","github-actions*","svc-*","*-service-account*"]
Glob patterns (matched against the author email local-part) that identify bot or service-account commits to exclude from ownership signals. Overrides the defaults entirely when set.
health.ownership.emailMode
- Type:
string - Default:
"handle"
Privacy mode for emitted author emails. Defaults to handle. Override on the CLI via --ownership-emails=raw|handle|anonymized. The legacy spelling hash is still accepted for compatibility.
Allowed values:
raw: Show the raw email address as it appears in git history. Use for public repositories where history is already exposed.handle: Show the local-part only (before the@). Mailmap-resolved where possible. Default. Balances readability and privacy.anonymized: Show a stablexxh3:<16hex>pseudonym derived from the raw email. Non-cryptographic; suitable to keep raw emails out of CI artifacts (SARIF, code-scanning uploads) but not as a security primitive: a known list of org emails can be brute-forced into a rainbow table. Use in regulated environments where even local-parts are sensitive.hash: Older spelling ofanonymized.
health.changeCoupling
- Type:
object
Change coupling thresholds for the change_coupling section and the hidden-coupling refactoring targets. Older fallow versions reject this key as unknown, so pair it with minimumVersion set to the release that added it.
| Key | Type | Default |
|---|---|---|
maxFilesPerCommit | integer | 30 |
minRevisions | integer | 5 |
minSharedRevisions | integer | 5 |
minDegree | number | 0.3 |
health.changeCoupling.maxFilesPerCommit
- Type:
integer - Default:
30 - Value: at least
2, at most1000
Skip a commit that changes more analyzed files than this (default: 30, from 2 to 1000). Bulk commits (renames, format passes) create false pairs. The upper bound keeps the pair count of one commit small.
health.changeCoupling.minRevisions
- Type:
integer - Default:
5
Minimum commits for each file of a pair (default: 5).
health.changeCoupling.minSharedRevisions
- Type:
integer - Default:
5
Minimum commits that change both files of a pair (default: 5).
health.changeCoupling.minDegree
- Type:
number - Default:
0.3 - Value: at least
0, at most1
Minimum coupling degree, from 0 to 1 (default: 0.3). The degree is the number of shared commits divided by the mean commit count of the two files.
health.suggestInlineSuppression
- Type:
boolean - Default:
true
Whether health JSON output emits suppress-line action hints alongside complexity findings (default: true). Set to false to opt out across the project: useful for teams that manage suppressions exclusively through // fallow-ignore-* comments authored by hand or through the fallow.suppress LSP code action, but who do not want CI-driven suppress-line action hints in their JSON output. --baseline activates auto-omission regardless of this setting, since baseline files are a separate suppression mechanism.
typeAware
- Type:
object
Opts into TypeScript semantic analysis for project-wide symbol use, provenance, API surface, symbol impact, and public-signature coupling. This does not surface compiler diagnostics or typed lint rules.
typeAware.enabled
- Type:
boolean - Default:
false
Enable the optional TypeScript semantic pass. Disabled by default.
typeAware.projects
- Type:
string[]
TypeScript project config paths, resolved relative to the project root.
typeAware.require
- Type:
string
Decide whether partial semantic analysis is advisory or gating.
Allowed values:
best-effort: Keep conservative findings and report semantic gaps without failing.complete: Fail the quality gate when any requested semantic query is incomplete.