{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "FallowConfig", "description": "The user-facing fallow configuration as authored in `.fallowrc.json` /\n`.fallowrc.jsonc` / `fallow.toml` / `.fallow.toml`.\n\nEvery field documents its serialized meaning, default, and precedence\nagainst CLI flags and environment variables where they exist.\n`FallowConfig::resolve` compiles the loaded config (globs, regexes,\nplugin and rule-pack discovery) into a [`ResolvedConfig`] for analysis.\nUnknown keys are rejected at load so typos fail loud.", "type": "object", "properties": { "$schema": { "description": "A string pointing at fallow's JSON Schema URL, used only by editors for autocomplete and validation of the config file; it has no effect on analysis and is stripped before serialization (serde skip_serializing, writeOnly in the schema). Set it to `./node_modules/fallow/schema.json` for npm installs (version-aligned, offline, avoids VS Code's untrusted-remote-schema prompt), or `https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json` for non-npm installs; any other value is ignored by fallow.", "type": [ "string", "null" ], "writeOnly": true }, "minimumVersion": { "description": "The lowest fallow version this config is written for, as `MAJOR.MINOR.PATCH`. An older binary stops with a message naming both versions instead of failing on the first field it does not recognize, so a config committed to a shared repository says which upgrade it needs rather than reading like a typo. Optional and unset by default; set it in the same change that adds a field introduced in a newer version. It gates nothing on its own: an unknown key still fails on a binary at or above this version, because there the key really is a typo.", "type": [ "string", "null" ] }, "extends": { "description": "A single parent config source, or an ordered array of them, to inherit before this file's own keys apply; each source is a file-relative path, an `npm:` specifier, or an `https://` URL (`http://` is rejected), deep-merged in order so objects merge field-by-field while arrays and scalars in this file replace the parent's, with cycle and depth guards. Set it to share a base config across a monorepo or team; it is consumed at load and stripped before serialization (serde skip_serializing).", "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "writeOnly": true }, "entry": { "description": "An array of project-root-relative glob patterns whose matching files are seeded as manual entry points, on top of the framework and package.json entries fallow discovers automatically, so their transitive imports are not reported as unused. Set it (e.g. `[\"src/main.ts\"]`) when a file is a real runtime root that no plugin or manifest declares; patterns are validated at load and matched against discovered files. A single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "type": "string" }, "default": [] }, "ignorePatterns": { "description": "An array of project-root-relative glob patterns for files to exclude from analysis entirely; entries are unioned with fallow's built-in defaults (**/node_modules/**, **/dist/**, **/build/**, **/.git/**, **/coverage/**, **/*.min.js, **/*.min.mjs, **/*.min.cjs, **/*.bundle.js), so custom globs add to rather than replace them. Set it (e.g. `[\"generated/**\"]`) to drop generated or vendored trees from every detector; patterns are validated at load. A `!`-prefixed entry is an exception that applies after the defaults and the positive patterns: `\"!src/policy/coverage/**\"` brings back hand-written source under a built-in default such as `**/coverage/**`, and `\"!.config/**\"` adds a hidden directory to discovery. Paths under `node_modules` or `.git` can not be lifted, and a `!` entry that names one of these segments is a config error. A single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "type": "string" }, "default": [] }, "ignoreFindings": { "description": "An array of project-root-relative glob patterns whose source-owned dead-code findings are hidden after analysis without excluding matching files from discovery, parsing, resolution, or the module graph. Use `/` as the path separator on every platform. Positive patterns select paths to hide; `!`-prefixed patterns keep matching paths reportable, and a negated-only array reports only those exception paths. A finding with multiple source owners is hidden only when every owner matches, so a cycle, duplicate-export group, or unlisted dependency with any reportable location remains visible. Architecture, policy, suppression-hygiene, and framework-correctness findings remain visible even when a referenced path matches, as do manifest-owned findings that no source file owns: unused dependencies, unused dev and optional dependencies, catalog entries, and dependency overrides. Use `ignorePatterns` instead when a generated or vendored file must not be analyzed at all. A matching file that parses with errors reports no `source-parse-degraded` diagnostic, and its partial parse does not mark other findings as incomplete; use this only for files that are broken on purpose, such as syntax-error test fixtures. A single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "type": "string" } }, "framework": { "description": "Declares inline external framework plugins as data (array of plugin objects), each with `name` plus optional `enablers` (package names that activate it) or richer `detection` (dependency/file-existence/`all`/`any` checks, taking priority over `enablers`), `entryPoints` (+ `entryPointRole` runtime/support/test), `configPatterns`, `alwaysUsed`, `toolingDependencies`, `usedExports` (`{ pattern, exports }`), and `usedClassMembers`. Set it to keep a custom or in-house framework's entry points, config files, and conventions reachable without a Rust plugin; these definitions are appended to plugins discovered via `plugins`, `.fallow/plugins/`, and root `fallow-plugin-*` files (first occurrence of a name wins), and cannot do AST-based config parsing.", "type": "array", "items": { "$ref": "#/$defs/ExternalPluginDef" }, "default": [] }, "workspaces": { "description": "Monorepo workspace configuration. `patterns` adds workspace package roots beyond manifest discovery; `changedSince` maps exact project-root-relative workspace roots to Git baseline refs. A global changed-since request overrides those per-package baselines.", "anyOf": [ { "$ref": "#/$defs/WorkspaceConfig" }, { "type": "null" } ], "default": null }, "ignoreDependencies": { "description": "A list of package names or package-name globs excluded from BOTH unused-dependency and unlisted-dependency detection, so a runtime-provided or otherwise-untracked package (e.g. `bun:sqlite`, a peer supplied at deploy time) is never flagged as unused when declared nor as unlisted when imported. Set it for packages fallow cannot observe being used and cannot observe being declared. An entry without glob characters matches the package name exactly; an entry with `*`, `?`, `[` or `{` is a glob in the `ignorePatterns` syntax matched against the package name, so `@acme/*` covers every package in the `@acme` scope.", "type": "array", "items": { "type": "string" }, "default": [] }, "ignoreCommandEntries": { "description": "A list of command names whose file arguments fallow does not make entry points. Fallow reads commands in package.json scripts (root and workspace packages), CI files (GitHub Actions and GitLab CI), Dockerfiles, Procfiles, and fly.toml files, and a file that a command names (such as `node scripts/seed.ts`) normally becomes an entry point. A listed command still counts as a used dependency, and its `--config` file is still tracked. Formatters and linters (ESLint, Prettier, Oxlint, Oxfmt, Biome, Stylelint, and similar tools) never make their targets entry points, so they do not need to be listed. Set it for a command whose file arguments are data, not code that runs (e.g. `[\"my-codegen\"]`), or use `[\"*\"]` to turn off entry points from all commands and declare real entries in `entry`. A name matches the command after environment, package-manager, and wrapper prefixes (`npx`, `pnpm exec`, `yarn run`, `varlock run --`), by exact file name; `*` is the only wildcard.", "type": "array", "items": { "type": "string" } }, "ignoreUnresolvedImports": { "description": "A list of glob patterns that suppress only `unresolved-import` findings whose raw import specifier matches; it does not change dependency usage accounting or resolver behavior. Patterns match the import string as written (not a filesystem path), so list both `@example/icons` and `@example/icons/**` to cover a bare package and its subpaths; parent-relative generated specifiers like `../generated/**` are valid, and broad values like `**` can hide real missing modules.", "type": "array", "items": { "type": "string" }, "default": [] }, "ignoreExports": { "description": "A list of per-file rules that exempt named exports from `unused-export` and from duplicate-exports grouping for files matching a glob. Each entry is `{ file: , exports: [, ...] }` where `exports: [\"*\"]` exempts every export in the file and a name list exempts only those names; built for component-library barrels (shadcn/Radix/bits-ui `index.ts`) that intentionally re-export the same short names across many files. A single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "$ref": "#/$defs/IgnoreExportRule" }, "default": [] }, "ignoreCatalogReferences": { "description": "A list of rules that suppress `unresolved-catalog-reference` findings (a workspace `package.json` referencing a `catalog:` or `catalog:` that the catalog does not declare); config-only because `package.json` has no inline-suppression comment surface. Each entry needs a `package` (exact match) plus optional `catalog` (exact catalog-name match) and `consumer` (glob on the consuming package.json path); use it for staged catalog migrations where the catalog edit lands in a separate change.", "type": "array", "items": { "$ref": "#/$defs/IgnoreCatalogReferenceRule" } }, "ignoreDependencyOverrides": { "description": "A list of rules that suppress `unused-dependency-override` and `misconfigured-dependency-override` findings for pnpm `overrides` entries; config-only, matched against the override's target package. Each entry needs a `package` (exact match) plus an optional `source` to scope the suppression to `\"pnpm-workspace.yaml\"` or `\"package.json\"`.", "type": "array", "items": { "$ref": "#/$defs/IgnoreDependencyOverrideRule" } }, "ignoreExportsUsedInFile": { "description": "Controls whether an export referenced only by another symbol in the same file is treated as used (suppressed from `unused-export`) until it becomes completely unreferenced; references inside an export specifier itself (`export { foo }`, `export default foo`) do not count as same-file uses. Accepts `true`/`false` (default `false`, suppress nothing) or the knip-parity object `{ \"type\": true, \"interface\": true }`, which restricts the suppression to type-only exports; fallow groups type aliases and interfaces under one kind, so both object fields behave identically.", "$ref": "#/$defs/IgnoreExportsUsedInFileConfig", "default": false }, "ignoreDecorators": { "description": "A list of decorator names that no longer grant a class member automatic exemption from `unused-class-member`: a member whose every decorator is in this set is checked normally, while a member carrying any decorator NOT listed here stays skipped (frameworks consume decorated members reflectively). Dotted entries match the full decorator path (`ns.foo`) and bare entries match the leftmost segment (so `\"decorators\"` collapses every `@decorators.*`); both `\"@step\"` and `\"step\"` are accepted (leading `@` stripped), and an unmatched entry emits a one-time warning.", "type": "array", "items": { "type": "string" } }, "usedClassMembers": { "description": "A list of class-member names or glob patterns treated as framework-used, so a method a library invokes reflectively (ag-Grid `agInit`/`refresh`, Web Component `connectedCallback`) is not reported as `unused-class-member`; it applies to class members only, not enum members. Each entry is either a plain string/glob (`\"agInit\"`, `\"enter*\"`, `\"*\"`) applied to every class, or a scoped object `{ extends?, implements?, members: [...] }` that applies only when the class matches that heritage clause (a scoped rule requires `extends` or `implements`); patterns matching zero members warn once.", "type": "array", "items": { "$ref": "#/$defs/UsedClassMemberRule" }, "default": [] }, "duplicates": { "description": "Configures clone detection: `enabled` (default true), `mode` (`strict`, `mild` default, `weak`, `semantic`, from least to most identifier/literal blinding; `strict` and `mild` are equivalent under fallow's AST tokenizer, `weak` blinds string literals, `semantic` blinds all identifiers and literals for Type-2 renamed-variable detection), `near` (false, add bounded function-scoped near-miss detection), `minTokens` (50), `minLines` (5), `minOccurrences` (integer >= 2, deserialization fails below 2), `threshold` (max duplication percentage, 0 = no limit), `ignore` globs, `ignoredClones` (reviewed clone keys to hide until their content or occurrence count changes), `ignoreDefaults` (true, merge built-in generated-file ignores), `skipLocal` (only report cross-directory clones), `ignoreSymlinks` (false, omit clone instances whose path is a symlink or lies under a symlinked directory), `crossLanguage` (strip TS type annotations to match .ts against .js), `ignoreImports` (true, strip ES import/re-export/top-level require wiring from the token stream), and `normalization` (per-flag `ignoreIdentifiers`/`ignoreStringValues`/`ignoreNumericValues` overrides on top of `mode`). Raise `minOccurrences` to focus on widespread copy-paste, enable `near` for gapped structural clones, or set `mode` to `semantic` to catch renamed-variable exact clones.", "$ref": "#/$defs/DuplicatesConfig", "default": { "enabled": true, "mode": "mild", "near": false, "minTokens": 50, "minLines": 5, "minOccurrences": 2, "threshold": 0.0, "ignore": [], "ignoredClones": [], "ignoreDefaults": true, "skipLocal": false, "ignoreSymlinks": false, "crossLanguage": false, "ignoreImports": true, "normalization": {}, "minCorpusSizeForShingleFilter": 1024, "minCorpusSizeForTokenCache": 5000 } }, "similarCode": { "description": "Configures the explicit local `similar-code` candidate workflow:\n`threshold` (0.80, model-specific cosine floor), `minLines` (3), and\nadditional `ignore` globs. Provider identity, setup, executables,\nendpoints, credentials, and consent cannot be set by project config.", "$ref": "#/$defs/SimilarCodeConfig", "default": { "threshold": 0.8, "minLines": 3, "ignore": [] } }, "mutation": { "description": "Configures the explicit `fallow mutation` workflow: `runner` (`auto`\nor `vitest`), `operators` (kebab-case names, default each operator),\n`minScore` (0 to 100; a lower score exits with code 1), and\n`concurrency` (half the logical cores). No key starts a run, and the\nside-effect override is a CLI flag only.", "$ref": "#/$defs/MutationConfig" }, "health": { "description": "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), `coverage`/`coverageRoot` (Istanbul coverage path and path-prefix strip for accurate CRAP), `ignore` globs (remove files from findings AND the health score), `thresholdOverrides` (per-file/per-function ceilings via `files`/`functions`/`maxCyclomatic`/`maxCognitive`/`maxCrap`/`maxUnitSize`/`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 four `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.", "$ref": "#/$defs/HealthConfig", "default": { "maxCyclomatic": 20, "maxCognitive": 15, "maxCrap": 30.0, "crapRefactorBand": 5, "maxUnitSize": 60, "coverage": null, "coverageRoot": null, "ignore": [], "ownership": { "botPatterns": [ "*\\[bot\\]*", "dependabot*", "renovate*", "github-actions*", "svc-*", "*-service-account*" ], "emailMode": "handle" }, "changeCoupling": { "maxFilesPerCommit": 30, "minRevisions": 5, "minSharedRevisions": 5, "minDegree": 0.3 }, "suggestInlineSuppression": true } }, "typeAware": { "description": "Opts into TypeScript semantic analysis for project-wide symbol use,\nprovenance, API surface, symbol impact, and public-signature coupling.\nThis does not surface compiler diagnostics or typed lint rules.", "$ref": "#/$defs/TypeAwareConfig" }, "rules": { "description": "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.", "$ref": "#/$defs/RulesConfig", "default": { "unused-files": "error", "unused-exports": "error", "unused-types": "error", "private-type-leaks": "off", "deprecated-exports-in-use": "off", "unused-dependencies": "error", "unused-dev-dependencies": "warn", "unused-optional-dependencies": "warn", "unused-enum-members": "error", "unused-class-members": "error", "unused-store-members": "warn", "unprovided-injects": "warn", "unrendered-components": "warn", "unused-component-props": "warn", "absent-component-props": "off", "unused-component-emits": "warn", "unused-component-inputs": "warn", "unused-component-outputs": "warn", "unused-svelte-events": "warn", "unused-effect-layers": "warn", "unused-tagged-errors": "warn", "unproduced-catch-tags": "warn", "unused-server-actions": "warn", "unused-load-data-keys": "warn", "prop-drilling": "off", "thin-wrapper": "off", "duplicate-prop-shape": "off", "css-token-drift": "warn", "css-duplicate-block": "warn", "css-selector-complexity": "warn", "css-dead-surface": "warn", "css-broken-reference": "warn", "complexity-cyclomatic": "error", "complexity-cognitive": "error", "complexity-crap": "error", "unresolved-imports": "error", "unlisted-dependencies": "error", "duplicate-exports": "error", "type-only-dependencies": "warn", "test-only-dependencies": "warn", "dev-dependencies-in-production": "warn", "circular-dependencies": "error", "re-export-cycle": "warn", "package-cycle": "warn", "boundary-violation": "error", "coverage-gaps": "off", "feature-flags": "off", "stale-suppressions": "warn", "require-suppression-reason": "off", "unused-catalog-entries": "warn", "empty-catalog-groups": "warn", "unresolved-catalog-references": "error", "unused-dependency-overrides": "warn", "misconfigured-dependency-overrides": "error", "security-client-server-leak": "off", "security-sink": "off", "policy-violation": "warn", "invalid-client-export": "warn", "mixed-client-server-barrel": "warn", "misplaced-directive": "warn", "route-collision": "error", "dynamic-segment-name-conflict": "error", "weakened-tests": "warn", "added-suppression": "warn", "test-only-branch": "warn", "diverged-clone-sibling": "off", "added-dependency": "off" } }, "unusedComponentProps": { "description": "Options for the `unused-component-props` rule, currently only `ignorePattern`: a regex matched against each declared prop's local destructure binding name (falling back to the public prop name when unaliased) to exempt intentionally-unused props such as the leading-underscore convention. Set `{ \"ignorePattern\": \"^_\" }` to skip props like `_stage`; matching is unanchored (substring, like ESLint's `RegExp.test`) so anchor with `^`, the pattern is validated at config load (invalid regex fails load), and it applies to Vue, Svelte, Astro, and React/Preact props (unset leaves the rule unchanged).", "$ref": "#/$defs/UnusedComponentPropsConfig" }, "circularDependencies": { "description": "Options for the `circular-dependencies` rule, currently only `ignoreLazyImports`. Set `{ \"ignoreLazyImports\": true }` to skip import edges that load on demand or on another thread (an `import()` inside a function, a template `import()`, a lazy `import.meta.glob`, a worker URL, a webpack worker loader request such as `worker-loader!./work.js`) when fallow looks for cycles. A top-level `await import()`, `require()`, an eager glob, and an edge that also has a static import stay in the cycle graph. Default `false` leaves the rule unchanged.", "$ref": "#/$defs/CircularDependenciesConfig" }, "boundaries": { "description": "Configures architecture boundary enforcement: which source directories belong to which named zone and which zones may import which others, reported as boundary-violation, boundary-coverage-violation, and boundary-call-violation findings (severity via rules.boundary-violation, default error). Set to enforce a layered/module architecture; the object holds `preset` (one of layered, hexagonal, feature-sliced, bulletproof, whose default zones/rules are merged in with the user-declared zones/rules taking precedence), `zones` (each with `name`, `patterns`, `autoDiscover`, optional `root`), `rules` (each with `from`, `allow`, `allowTypeOnly` target-zone lists), `coverage` (`requireAllFiles` plus `allowUnmatched` globs for files matching no zone), and `calls` (a `forbidden` list of `{from, callee}` banned-call rules per zone).", "$ref": "#/$defs/BoundaryConfig", "default": { "zones": [], "rules": [] } }, "flags": { "description": "Configures feature-flag detection: `sdkPatterns` (custom flag-evaluating call signatures, each `{ function, nameArg (zero-based arg index of the flag name, default 0), provider? }`, merged with built-ins for LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog, Vercel Flags, ConfigCat, Flagsmith, Optimizely, and Eppo), `envPrefixes` (env-var prefixes marking `process.env.*` and `import.meta.env.*` accesses as flags, merged with built-ins), and `configObjectHeuristics` (default false; when true, property accesses on objects whose name contains `feature`/`flag`/`toggle` are reported as low-confidence flags). Set `sdkPatterns`/`envPrefixes` to teach fallow a proprietary flag SDK or naming convention, or enable `configObjectHeuristics` for projects that read flags off config objects (higher false-positive rate). Feature-flag findings surface only when the `feature-flags` rule is enabled (default `off`).", "$ref": "#/$defs/FlagsConfig", "default": { "configObjectHeuristics": false } }, "security": { "description": "Scopes the opt-in `fallow security` catalogue: which candidate categories run and which extra local identifiers count as HTTP request objects. Set when tuning security-candidate detection; the object holds `categories` (an object with `include` and/or `exclude` string arrays of catalogue category ids, where `include` restricts to a whitelist and `exclude` removes from the admitted set, both unset admits all ordinary categories) and `requestReceivers` (a string array of project-local names that extend, not replace, the built-in `*.query`/`*.params`/`*.body` source-receiver allowlist). The `hardcoded-secret` and `secret-to-network` categories are include-required: they fire only when explicitly listed in `categories.include`, even when no include list is otherwise set. The valid category ids are enumerated (with title, CWE, and include-required flag) in the `security_categories` block of `fallow schema`, and also listed by `fallow security --help`; they are not in this config-schema.", "$ref": "#/$defs/SecurityConfig", "default": {} }, "fix": { "description": "Configures `fallow fix` behavior. Currently holds one nested section, `catalog` (a `CatalogFixConfig`), whose only key `deletePrecedingComments` (`auto` default, `always`, `never`) governs whether comment lines directly above a removed unused `pnpm-workspace.yaml` catalog entry are deleted with it.", "$ref": "#/$defs/FixConfig", "default": { "catalog": { "deletePrecedingComments": "auto" } } }, "resolve": { "description": "Configures the module resolver. Its one key `conditions` is a list of additional package.json `exports`/`imports` condition names to honor, matched at higher priority than fallow's built-ins (`development`, `import`, `require`, `default`, `types`, `node`, plus `react-native`/`browser` when the React Native or Expo plugin is active). Set it when a package's `exports` map has custom branches (e.g. `worker`, `deno`, `edge`) that fallow should follow instead of the default branch.", "$ref": "#/$defs/ResolveConfig", "default": {} }, "production": { "description": "Enables production mode, which excludes test/spec/story/dev files from discovery and forces `unused-dev-dependencies` and `unused-optional-dependencies` to `off`. Accepts a boolean (default false) applied to all analyses, or a per-analysis object `{ deadCode?, health?, dupes? }` (each boolean, default false) that scopes production mode to individual analyses in combined `fallow` and `fallow audit`. Set it to analyze only shipped code; the `--production`/`--no-production` and `--production-{dead-code,health,dupes}` CLI flags and `FALLOW_PRODUCTION*` env vars override this value (CLI flags win, then per-analysis env, then global env, then config).", "$ref": "#/$defs/ProductionConfig", "default": false }, "plugins": { "description": "List of paths (relative to the project root, must resolve within it) to external plugin definition files or directories in JSONC/JSON/TOML, loaded in addition to the auto-discovered `.fallow/plugins/` directory and root `fallow-plugin-*` files. Set it to load plugin definitions kept outside those default locations; a path resolving outside the project root is skipped with a `tracing::warn`, and paths listed here are searched before the auto-discovered locations (first occurrence of a plugin name wins).", "type": "array", "items": { "type": "string" }, "default": [] }, "rulePacks": { "description": "Paths to declarative rule-pack files (JSON or JSONC), relative to the\nproject root. Each pack declares `banned-call`, `banned-import`, or\n`banned-effect` rules that report as `policy-violation` findings. Packs\nare pure data: no project code is executed. Invalid or missing packs\nfail config load.", "type": "array", "items": { "type": "string" } }, "dynamicallyLoaded": { "description": "An array of project-root-relative glob patterns for files loaded at runtime by a mechanism the static graph cannot see (dynamic path resolution, config-driven loading); matching files are seeded as entry points so they and their imports stay reachable. Empty by default; set it (e.g. `[\"plugins/**/*.ts\", \"locales/**/*.json\"]`) for plugin or locale trees pulled in dynamically. A single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "type": "string" }, "default": [] }, "markupExtensions": { "description": "An array of file extensions, without the leading dot, for server-side template files whose text counts as CSS class references for the `unreferenced-css-class` finding of `fallow health --css`. These files are read as text only: they do not join source discovery or the module graph, so they never become unused files and their imports are not followed. Templates are more lenient than Markdown: the whole text of a template file counts as a dynamic class reference, so any class-like word in it counts as used, also a common word such as `hidden` or `title` in prose or a template tag. A Markdown file joins the reference text only when it has dynamic class syntax. The extensions `liquid`, `njk`, `hbs`, `handlebars`, `twig`, and `blade.php` are always read; set this (e.g. `[\"tpl\", \"erb\"]`) for other template languages. An extension matches the end of a file name, ignoring case, so `blade.php` matches `welcome.blade.php`. Values may contain only letters, digits, `.`, `-`, and `_`. A value whose last segment is a script, stylesheet, data or asset extension (`js`, `ts`, `css`, `json`, `svg`, `xml`, `map`, and similar, so also `module.css` or `d.ts`), or a compound value that ends in a markup extension that fallow already reads (`page.html`), is a config error. The walk uses the ignore files of source discovery (`.gitignore`, `.ignore`), skips `ignorePatterns`, `health.ignore`, `node_modules`, `vendor`, and build output directories, reads only regular files, and skips files over the `--max-file-size` limit. In `extends`, a child list replaces the parent list.", "type": "array", "items": { "type": "string" } }, "overrides": { "description": "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 rules 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); inter-file rules (duplicate-exports, circular-dependencies, re-export-cycle) have no effect in an override (fallow warns during analysis and points to the right mechanism: top-level `ignoreExports` for duplicate-exports, a file-level `// fallow-ignore-file` comment for the others). A single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "$ref": "#/$defs/ConfigOverride" }, "default": [] }, "codeowners": { "description": "A project-root-relative path to a CODEOWNERS file, used by fallow health --hotspots --ownership to attribute declared owners and compute unowned/drifting ownership state; setting it overrides the default probe order (CODEOWNERS, .github/CODEOWNERS, .gitlab/CODEOWNERS, docs/CODEOWNERS). String, defaults to null (auto-probe the standard locations); set it only when the CODEOWNERS file lives at a non-standard location.", "type": [ "string", "null" ] }, "publicPackages": { "description": "An array of internal workspace package names (or globs matched against workspace package names) whose public API is intentionally consumed outside the analyzed graph; their entry points and re-export surface become reachability roots, so their exported files, exports, and class members are not reported as unused. Set it (e.g. `[\"@myorg/shared-lib\", \"@myorg/*\"]`) for library packages in a monorepo that ship an API to external consumers; only meaningful when workspaces are present (an empty list or no workspaces is a no-op).", "type": "array", "items": { "type": "string" }, "default": [] }, "regression": { "description": "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.", "anyOf": [ { "$ref": "#/$defs/RegressionConfig" }, { "type": "null" } ] }, "audit": { "description": "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` (GC window in days for the reusable base-snapshot worktree cache). The matching CLI flag overrides each field.", "$ref": "#/$defs/AuditConfig" }, "sealed": { "description": "When true, restricts this config's extends entries to file-relative paths that resolve inside the config file's own directory; any https:// URL, npm: package, or relative path escaping that directory is rejected at load with a hard error. Boolean, defaults to false (URL, npm, and any-relative extends are permitted); set it to true to harden a config against pulling in remote or out-of-tree bases.", "type": "boolean", "default": false }, "includeEntryExports": { "description": "When true, exports of entry-point files are subject to unused-export detection instead of being auto-credited as used, so a typo'd or stray export in a framework route or package entry (e.g. meatdata for metadata) is flagged; plugin used_exports allowlists are still honored. Boolean, defaults to false; the CLI flag --include-entry-exports applies the same behavior for one run.", "type": "boolean", "default": false }, "showCascade": { "description": "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.", "type": "boolean", "default": false }, "autoImports": { "description": "When true, drops Nuxt convention-based entry-pattern fallbacks so genuinely-unreferenced convention files surface as unused-file. Component fallbacks are kept when nuxt.config customizes components: in a way fallow does not model, and composable/util fallbacks are kept when it customizes imports:; a config that scans no more than the Nuxt defaults (components: false, components: [], components: { dirs: [] }, components: true, imports: { scan: false }, imports: {}, imports: { dirs: [] }) is treated like the default and its fallbacks are dropped; imports: { autoImport: false } on its own is not, because it only switches the injection off while the same directories stay registered behind #imports. A nuxt.config that carries any top-level key fallow cannot read statically, a computed key, an accessor, or a spread such as { ...base, devtools: {} }, keeps both surfaces' fallbacks for that root, because the spread may hold the keys that decide. Only top-level keys count when the config object is readable: a nested key such as a routeRules path ending in components does not keep a fallback. Nested components or imports keys in $production, $development, $test or `$env.`, and components or imports hooks (a components:* key or a nested components object in hooks, also inside those overrides), count as that surface's key; such an override object or hooks object that fallow cannot read statically falls back to a text match for the keys. Each root is classified on its own config plus the configs of its local layers, so one custom nuxt.config in a monorepo does not keep every other workspace's fallbacks. A local layer is a directory named in extends, or a `layers/` directory, that holds a nuxt.config; its convention files are entry points with the flag off and auto-import sources with it on, and `#layers//` resolves to it by its $meta.name (a `layers/` directory without one uses its directory name). A remote or package layer is only a dependency reference. Component names follow Nuxt: a component under components/global or components/islands is named after its own directory (components/global/Foo.vue is ``), and .client, .server, .global and .island suffixes are stripped. A name imported or re-exported by hand from #components or #imports credits its convention file just like a template tag or a bare call; a namespace import names nothing and credits nothing. Boolean, defaults to false; set it for a Nuxt project that has explicitly configured its auto-import directories. Synthesis of auto-import graph edges (resolving `` or `useUserStore()` to their convention files) happens regardless of this flag.", "type": "boolean", "default": false }, "failOnParseError": { "description": "When true, the run fails with exit code 1 if fallow could not parse a source file cleanly (a `source-parse-degraded` or `source-nesting-too-deep` entry in `workspace_diagnostics[]`), and the `parse-error` entry of `gate_outcomes` names each such file. Boolean, defaults to false, so a file the parser rejects only warns. Applies to `fallow dead-code`, `fallow health`, `fallow audit` and the bare `fallow` run; the CLI flag `--fail-on-parse-error` arms the same gate for one run. Older fallow versions reject this key as unknown, so pair it with `minimumVersion` set to the release that added it.", "type": "boolean", "default": false }, "cache": { "description": "Overrides the location and size ceiling of fallow's persistent extraction cache (default `.fallow/cache.bin` under the project root). Set to relocate the cache or cap its footprint; the object holds `dir` (cache directory, relative paths resolve from the project root) and `maxSizeMb` (extraction-cache size limit in megabytes). The `FALLOW_CACHE_MAX_SIZE` environment variable overrides `maxSizeMb`.", "$ref": "#/$defs/CacheConfig" } }, "additionalProperties": false, "allowComments": true, "allowTrailingCommas": true, "$defs": { "ExternalPluginDef": { "description": "A declarative plugin definition loaded from a standalone file or inline config.\n\nExternal plugins provide the same static pattern capabilities as built-in\nplugins (entry points, always-used files, used exports, tooling dependencies),\nbut are defined in standalone files or inline in the fallow config rather than\ncompiled Rust code.\n\nThey cannot do AST-based config parsing (`resolve_config()`), but cover the\nvast majority of framework integration use cases.\n\nSupports JSONC, JSON, and TOML formats. All use camelCase field names.\n\n```json\n{\n \"$schema\": \"https://raw.githubusercontent.com/fallow-rs/fallow/main/plugin-schema.json\",\n \"name\": \"my-framework\",\n \"enablers\": [\"my-framework\", \"@my-framework/core\"],\n \"entryPoints\": [\"src/routes/**/*.{ts,tsx}\"],\n \"configPatterns\": [\"my-framework.config.{ts,js}\"],\n \"alwaysUsed\": [\"src/setup.ts\"],\n \"toolingDependencies\": [\"my-framework-cli\"],\n \"usedExports\": [\n { \"pattern\": \"src/routes/**/*.{ts,tsx}\", \"exports\": [\"default\", \"loader\", \"action\"] }\n ]\n}\n```", "type": "object", "properties": { "name": { "description": "Unique name for this plugin.", "type": "string" }, "detection": { "description": "Rich detection logic (dependency checks, file existence, boolean combinators).\nTakes priority over `enablers` when set.", "anyOf": [ { "$ref": "#/$defs/PluginDetection" }, { "type": "null" } ], "default": null }, "enablers": { "description": "Package names that activate this plugin when found in package.json.\nSupports exact matches and prefix patterns (ending with `/`).\nOnly used when `detection` is not set.", "type": "array", "items": { "type": "string" }, "default": [] }, "entryPoints": { "description": "Glob patterns for entry point files.", "type": "array", "items": { "type": "string" }, "default": [] }, "entryPointRole": { "description": "Coverage role for `entryPoints`.\n\nDefaults to `support`. Set to `runtime` for application entry points\nor `test` for test framework entry points.", "$ref": "#/$defs/EntryPointRole", "default": "support" }, "manifestEntries": { "description": "Entry points DERIVED from framework manifest files.\n\nUnlike `entryPoints` (static globs), each rule finds manifest files by a\nrecursive glob, parses them, and seeds sibling entries resolved relative\nto each manifest's directory, gated on the manifest's own fields. Seeded\nentries use this plugin's `entryPointRole`.", "type": "array", "items": { "$ref": "#/$defs/ManifestEntryRule" }, "default": [] }, "configPatterns": { "description": "Glob patterns for config files (marked as always-used when active).", "type": "array", "items": { "type": "string" }, "default": [] }, "configDefaultExportOptOut": { "description": "Entries of `configPatterns` whose files do not get the `default`\nexport credit under `includeEntryExports`. Use it when the tool reads\nnamed exports, or when the pattern also matches ordinary source files.\nWrite each entry exactly as in `configPatterns`. Other entries have\nno effect.", "type": "array", "items": { "type": "string" }, "default": [] }, "alwaysUsed": { "description": "Files that are always considered \"used\" when this plugin is active.", "type": "array", "items": { "type": "string" }, "default": [] }, "toolingDependencies": { "description": "Dependencies that are tooling (used via CLI/config, not source imports).\nThese should not be flagged as unused devDependencies.", "type": "array", "items": { "type": "string" }, "default": [] }, "usedExports": { "description": "Exports that are always considered used for matching file patterns.", "type": "array", "items": { "$ref": "#/$defs/ExternalUsedExport" }, "default": [] }, "usedClassMembers": { "description": "Class member method/property rules the framework invokes at runtime.\nSupports plain member names for global suppression and scoped objects\nwith `extends` / `implements` constraints when the method name is too\ncommon to suppress across the whole workspace.", "type": "array", "items": { "$ref": "#/$defs/UsedClassMemberRule" }, "default": [] } }, "required": [ "name" ] }, "PluginDetection": { "description": "How to detect if a plugin should be activated.\n\nWhen set on an `ExternalPluginDef`, this takes priority over `enablers`.\nSupports dependency checks, file existence checks, and boolean combinators.", "oneOf": [ { "description": "Plugin detected if this package is in dependencies.", "type": "object", "properties": { "type": { "type": "string", "const": "dependency" }, "package": { "description": "Exact package name looked up in the project's declared dependencies.", "type": "string" } }, "required": [ "type", "package" ] }, { "description": "Plugin detected if this file pattern matches.", "type": "object", "properties": { "type": { "type": "string", "const": "fileExists" }, "pattern": { "description": "Project-root-relative glob; the plugin activates when any\ndiscovered file matches it. Validated at load like other user\nglobs (no absolute paths or `..` segments).\nA single `*` stays within one path segment; use `**` to match across directories.", "type": "string" } }, "required": [ "type", "pattern" ] }, { "description": "All conditions must be true.", "type": "object", "properties": { "type": { "type": "string", "const": "all" }, "conditions": { "description": "Sub-conditions combined with logical AND.", "type": "array", "items": { "$ref": "#/$defs/PluginDetection" } } }, "required": [ "type", "conditions" ] }, { "description": "Any condition must be true.", "type": "object", "properties": { "type": { "type": "string", "const": "any" }, "conditions": { "description": "Sub-conditions combined with logical OR.", "type": "array", "items": { "$ref": "#/$defs/PluginDetection" } } }, "required": [ "type", "conditions" ] } ] }, "EntryPointRole": { "description": "How a plugin's discovered entry points contribute to coverage reachability.", "oneOf": [ { "description": "Runtime/application roots that should count toward runtime reachability.", "type": "string", "const": "runtime" }, { "description": "Test roots that should count toward test reachability.", "type": "string", "const": "test" }, { "description": "Support/setup/config roots that should keep files alive but not count as runtime/test.", "type": "string", "const": "support" } ] }, "ManifestEntryRule": { "description": "A rule that seeds entry points DERIVED from framework manifest files.\n\nFor every file matching `manifests` (a recursive glob) that passes the\nmanifest-level `when` gate, each rule in `entries` is resolved relative to\nthe manifest's directory (with `${dotted.field}` interpolation) into an entry\npoint. Seeded entries use the owning plugin's `entryPointRole`.\n\n```jsonc\n{\n \"manifests\": \"**/kibana.jsonc\",\n \"when\": { \"type\": \"plugin\" },\n \"entries\": [\n { \"path\": \"public/index.{ts,tsx}\", \"when\": { \"plugin.browser\": true } },\n { \"path\": \"server/index.{ts,tsx}\", \"when\": { \"plugin.server\": true } },\n { \"path\": \"${plugin.extraPublicDirs}/index.{ts,tsx}\" }\n ]\n}\n```", "type": "object", "properties": { "manifests": { "description": "Recursive glob selecting the manifest files to read (e.g. `**/kibana.jsonc`).\nA single `*` stays within one path segment; use `**` to match across directories.", "type": "string" }, "format": { "description": "Manifest format. Defaults to `jsonc` (which also parses plain JSON).", "$ref": "#/$defs/ManifestFormat", "default": "jsonc" }, "when": { "description": "Manifest-level gate: a map of field path to an equality expectation or\nan explicit `exists` predicate. Paths use dotted object keys and may\ntraverse arrays with `[*]`. ALL entries must match; a wildcard equality\nmatches when any yielded value equals the expectation. An empty map\nmatches every manifest.", "type": "object", "additionalProperties": { "$ref": "#/$defs/ManifestCondition" }, "default": {} }, "entries": { "description": "Entry rules seeded per matching manifest.", "type": "array", "items": { "$ref": "#/$defs/ManifestSeedRule" } } }, "required": [ "manifests", "entries" ] }, "ManifestFormat": { "description": "Format of the manifest files a [`ManifestEntryRule`] reads.\n\n`jsonc` (the default) also parses plain JSON, so it is the tolerant choice.", "oneOf": [ { "description": "JSONC (comments + trailing commas). Also accepts plain JSON.", "type": "string", "const": "jsonc" }, { "description": "Strict JSON.", "type": "string", "const": "json" } ] }, "ManifestCondition": { "description": "A typed condition used by a manifest entry gate.\n\nPlain JSON values retain strict equality semantics. The reserved\n`{ \"exists\": bool }` object tests field presence without truthiness.", "anyOf": [ { "description": "Require the field path to resolve (`true`) or not resolve (`false`).", "$ref": "#/$defs/ManifestExistsPredicate" }, { "description": "Require at least one yielded value to equal this JSON value exactly." } ] }, "ManifestExistsPredicate": { "description": "The explicit field-presence predicate accepted by [`ManifestCondition`].", "type": "object", "properties": { "exists": { "description": "Whether the field path must resolve to at least one value.", "type": "boolean" } }, "additionalProperties": false, "required": [ "exists" ] }, "ManifestSeedRule": { "description": "A single entry seeded by a [`ManifestEntryRule`], resolved relative to the\nmanifest's directory.", "type": "object", "properties": { "path": { "description": "Entry glob relative to the manifest directory. May contain\n`${dotted.field}` interpolation that fans out over string / array\nmanifest field values; `[*]` traverses object arrays. A missing or empty\nfield seeds nothing. The glob must encode its own extension, such as\n`public/index.{ts,tsx}`. Glob entry patterns are matched literally\nagainst discovered files without\nsource-extension probing.", "type": "string" }, "when": { "description": "Per-entry gate, using the same strict equality and `[*]` traversal as the\nmanifest-level gate. An empty map always passes.", "type": "object", "additionalProperties": { "$ref": "#/$defs/ManifestCondition" }, "default": {} } }, "required": [ "path" ] }, "ExternalUsedExport": { "description": "Exports considered used for files matching a pattern.", "type": "object", "properties": { "pattern": { "description": "Glob pattern for files.\nA single `*` stays within one path segment; use `**` to match across directories.", "type": "string" }, "exports": { "description": "Export names always considered used.", "type": "array", "items": { "type": "string" } } }, "required": [ "pattern", "exports" ] }, "UsedClassMemberRule": { "description": "A `usedClassMembers` entry from config or an external plugin.\n\nSupports either a plain member name or glob pattern (`\"agInit\"`,\n`\"enter*\"`) or a scoped rule that only applies when a class matches\nspecific `extends` / `implements` heritage clauses.", "anyOf": [ { "description": "Globally suppress this class member name or glob pattern for all classes.", "type": "string" }, { "description": "Suppress these class member names only for matching classes.", "$ref": "#/$defs/ScopedUsedClassMemberRule" } ] }, "ScopedUsedClassMemberRule": { "description": "A heritage-constrained `usedClassMembers` rule.", "type": "object", "properties": { "extends": { "description": "Only apply when the class extends this parent class name.", "type": [ "string", "null" ] }, "implements": { "description": "Only apply when the class implements this interface name.", "type": [ "string", "null" ] }, "members": { "description": "Member names or glob patterns that should be treated as framework-used.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "members" ] }, "WorkspaceConfig": { "description": "Workspace configuration for monorepo support.", "type": "object", "properties": { "patterns": { "description": "Additional workspace patterns (beyond what's in root package.json).\n\n`packages` is accepted as a back-compat alias: an older `fallow init --toml`\nwrote `[workspaces]` with a `packages` key, and reading it as `patterns`\nkeeps those existing configs scoping correctly. schemars omits serde\naliases, so `schema.json` documents only `patterns`.", "type": "array", "items": { "type": "string" }, "default": [] }, "changedSince": { "description": "Git baseline refs keyed by workspace roots, written relative to the project root as `fallow list --workspaces` prints them. Scopes `check`, `dead-code`, `dupes` and editor diagnostics; `health`, `security` and `audit` ignore it. A global changed-since request takes precedence. Unlisted workspaces and root files remain in full scope. A key that names no workspace, or a ref that Git cannot resolve, leaves every package in full scope with a warning.", "type": "object", "additionalProperties": { "type": "string" } } } }, "IgnoreExportRule": { "description": "Rule for ignoring specific exports.", "type": "object", "properties": { "file": { "description": "Glob pattern for files.\nA single `*` stays within one path segment; use `**` to match across directories.", "type": "string" }, "exports": { "description": "Export names to ignore (`*` for all).", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "file", "exports" ] }, "IgnoreCatalogReferenceRule": { "description": "Rule for suppressing an `unresolved-catalog-reference` finding.", "type": "object", "properties": { "package": { "description": "Required exact package name whose `unresolved-catalog-reference` finding this rule suppresses; compared by string equality against the referenced package, so one rule targets one package's catalog reference (further narrowed by the optional `catalog` and `consumer` filters, all of which must match).", "type": "string" }, "catalog": { "description": "Optional catalog-name filter: when set, the rule suppresses only references to this exact catalog name (string equality), and when omitted it applies regardless of which catalog is referenced. Use it to scope suppression to one catalog (e.g. `\"react18\"`) while leaving other catalog references for the same package reportable.", "type": [ "string", "null" ] }, "consumer": { "description": "Optional glob matched against the consuming workspace `package.json` path (compiled into a glob matcher at config load): when set, the rule suppresses the finding only for consumers whose path matches, and when omitted it applies to every consumer. Use it to suppress a catalog reference in one specific workspace during a staged migration. A single `*` stays within one path segment; use `**` to match across directories.", "type": [ "string", "null" ] } }, "additionalProperties": false, "required": [ "package" ] }, "IgnoreDependencyOverrideRule": { "description": "Rule for suppressing dependency-override findings.", "type": "object", "properties": { "package": { "description": "Required exact package name whose `unused-dependency-override` or `misconfigured-dependency-override` finding this rule suppresses; compared by string equality against the override's target package, so one rule targets one override entry (further narrowable with the optional `source` filter).", "type": "string" }, "source": { "description": "Optional source filter matched by exact string equality against the override's declaring-file label: set it to `\"pnpm-workspace.yaml\"` or `\"package.json\"` to scope the suppression to overrides declared in that file, or omit it to suppress the package's override regardless of where it is declared.", "type": [ "string", "null" ] } }, "additionalProperties": false, "required": [ "package" ] }, "IgnoreExportsUsedInFileConfig": { "description": "Value of the `ignoreExportsUsedInFile` config key: whether an export\nreferenced elsewhere in its own file is suppressed from `unused-export`.", "anyOf": [ { "description": "Blanket toggle: `true` suppresses any export with a same-file use,\nregardless of kind. The default is `false`.", "type": "boolean" }, { "description": "Knip-parity object form restricting the suppression to type-only\nexports.", "$ref": "#/$defs/IgnoreExportsUsedInFileByKind" } ] }, "IgnoreExportsUsedInFileByKind": { "description": "Object form of `ignoreExportsUsedInFile` (`{ \"type\": ..., \"interface\": ... }`),\nrestricting the same-file-use suppression to type-only exports.", "type": "object", "properties": { "type": { "description": "When `true`, enables the same-file-use suppression for type-only exports (serialized as `type`; part of the object form of `ignoreExportsUsedInFile`). Because fallow groups type aliases and interfaces under one issue kind, setting either `type` or `interface` enables the identical type-only suppression, applied only to exports fallow classifies as type-only.", "type": "boolean", "default": false }, "interface": { "description": "When `true`, enables the same-file-use suppression for type-only exports (part of the object form of `ignoreExportsUsedInFile`). Fallow does not distinguish interfaces from type aliases in this issue kind, so `interface` behaves identically to `type`: setting either one turns on the type-only same-file suppression.", "type": "boolean", "default": false } } }, "DuplicatesConfig": { "description": "Configuration for code duplication detection.", "type": "object", "properties": { "enabled": { "description": "Whether duplication detection is enabled.", "type": "boolean", "default": true }, "mode": { "description": "Detection mode: strict, mild, weak, or semantic.", "$ref": "#/$defs/DetectionMode", "default": "mild" }, "near": { "description": "Detect structurally similar function bodies with small edits.", "type": "boolean", "default": false }, "minTokens": { "description": "Minimum number of tokens for a clone.", "type": "integer", "format": "uint", "minimum": 0, "default": 50 }, "minLines": { "description": "Minimum number of lines for a clone.", "type": "integer", "format": "uint", "minimum": 0, "default": 5 }, "minOccurrences": { "description": "Minimum number of occurrences (instances of the same clone) before a\ngroup is reported. Defaults to 2 (every duplicated pair is reported).\nRaise this to focus on widespread copy-paste worth refactoring and skip\ncontext-sensitive pairs.", "type": "integer", "format": "uint", "minimum": 2, "default": 2 }, "threshold": { "description": "Maximum allowed duplication percentage (0 = no limit).", "type": "number", "format": "double", "default": 0.0 }, "ignore": { "description": "Additional ignore patterns for duplication analysis.\nA single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "type": "string" }, "default": [] }, "ignoredClones": { "description": "Reviewed clone groups to omit from duplication results.\n\nEach entry is `:`, for example\n`dup:6f12ab34:2`. A content or occurrence-count change produces a new key\nand makes the group reportable again.", "type": "array", "items": { "type": "string", "pattern": "^dup:(?:[0-9a-f]{8}|[0-9a-f]{16}(?:-r?[1-9][0-9]*)?):(?:[2-9]|[1-9][0-9]+)$" }, "default": [] }, "ignoreDefaults": { "description": "Merge built-in generated-framework ignore patterns with `ignore`.\n\nSet to `false` to use only the user-provided `ignore` list.", "type": "boolean", "default": true }, "skipLocal": { "description": "Only report cross-directory duplicates.", "type": "boolean", "default": false }, "ignoreSymlinks": { "description": "Omit clone instances whose file path is a symlink, or lies under a\nsymlinked directory, inside the project root.\n\nDefaults to `false`: symlinked instances stay in the report and carry\n`is_symlink: true` in JSON output. Set to `true` to report only\nduplication between real files. A clone group with fewer than two\nremaining instances is not reported. Symlinked files also leave the\ncorpus, so `stats` (files, lines, tokens and the duplication\npercentage that `threshold` checks) count only real files.", "type": "boolean", "default": false }, "crossLanguage": { "description": "Enable cross-language clone detection by stripping type annotations.\n\nWhen enabled, TypeScript type annotations (parameter types, return types,\ngenerics, interfaces, type aliases) are stripped from the token stream,\nallowing detection of clones between `.ts` and `.js` files.", "type": "boolean", "default": false }, "ignoreImports": { "description": "Exclude module-wiring declarations from clone detection.\n\nDefaults to `true`: token-identical module wiring is a structural\nproperty of well-formatted code, not copy-paste, so it should not\nsurface as clone groups. Set to `false` to count module wiring again.\nWhen enabled, ES imports, re-export declarations, and top-level static\nCommonJS `require(\"...\")` binding declarations are stripped from the\ntoken stream before clone detection. Dynamic imports, side-effect\n`require()` calls, nested `require()` calls, dynamic require arguments,\nand mixed declarations are still counted.", "type": "boolean", "default": true }, "normalization": { "description": "Fine-grained normalization overrides on top of the detection mode.", "$ref": "#/$defs/NormalizationConfig", "default": {} }, "minCorpusSizeForShingleFilter": { "description": "Minimum tokenized file count before focused duplicate analysis prefilters\nunchanged files with k-token shingles.", "type": "integer", "format": "uint", "minimum": 0, "default": 1024 }, "minCorpusSizeForTokenCache": { "description": "Minimum source file count before the persistent duplication token cache\nactivates. Below this threshold the cache load/save overhead exceeds the\ntokenize savings, so the cache stays disabled even when not running with\n`--no-cache`.", "type": "integer", "format": "uint", "minimum": 0, "default": 5000 } } }, "DetectionMode": { "description": "Detection mode controlling how aggressively tokens are normalized.\n\nSince fallow uses AST-based tokenization (not lexer-based), whitespace and\ncomments are inherently absent from the token stream. The `Strict` and `Mild`\nmodes are currently equivalent. `Weak` mode additionally blinds string\nliterals. `Semantic` mode blinds all identifiers and literal values for\nType-2 (renamed variable) clone detection.", "oneOf": [ { "description": "All tokens preserved including identifier names and literal values (Type-1 only).", "type": "string", "const": "strict" }, { "description": "Default mode -- equivalent to strict for AST-based tokenization.", "type": "string", "const": "mild" }, { "description": "Blind string literal values (structure-preserving).", "type": "string", "const": "weak" }, { "description": "Blind all identifiers and literal values for structural (Type-2) detection.", "type": "string", "const": "semantic" } ] }, "NormalizationConfig": { "description": "Fine-grained normalization overrides.\n\nEach option, when set to `Some(true)`, forces that normalization regardless of\nthe detection mode. When set to `Some(false)`, it forces preservation. When\n`None`, the detection mode's default behavior applies.", "type": "object", "properties": { "ignoreIdentifiers": { "description": "Blind all identifiers (variable names, function names, etc.) to the same hash.\nDefault in `semantic` mode.", "type": [ "boolean", "null" ] }, "ignoreStringValues": { "description": "Blind string literal values to the same hash.\nDefault in `weak` and `semantic` modes.", "type": [ "boolean", "null" ] }, "ignoreNumericValues": { "description": "Blind numeric literal values to the same hash.\nDefault in `semantic` mode.", "type": [ "boolean", "null" ] } } }, "SimilarCodeConfig": { "description": "Project-owned tuning for the explicit `fallow similar-code` workflow.\n\nProvider identity, executable discovery, model setup, credentials, and\nconsent are intentionally absent. Project configuration cannot select code\ndestinations or authorize model downloads.", "type": "object", "properties": { "threshold": { "description": "Minimum model-specific cosine similarity retained as an unverified\ncandidate. It is not a probability or refactor-safety verdict.", "type": "number", "format": "double", "minimum": 0.0, "maximum": 1.0, "default": 0.8 }, "minLines": { "description": "Minimum source line count for a function to enter model inference.", "type": "integer", "format": "uint", "minimum": 1, "default": 3 }, "ignore": { "description": "Additional project-root-relative globs excluded only from similar-code\nextraction. Global `ignorePatterns` remain authoritative first.\nA single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "type": "string" }, "default": [] } }, "additionalProperties": false }, "MutationConfig": { "description": "Project settings for `fallow mutation`.\n\nProject config cannot widen what a run executes: the override that keeps\nmutants near file system, process, network or database sinks is a CLI\nflag only (`--allow-side-effects`), and no key starts a run.", "type": "object", "properties": { "runner": { "description": "The test runner: `auto`, `vitest`, `node-test` or `bun-test`. `auto`\ndetects it from the project.", "$ref": "#/$defs/MutationRunner", "default": "auto" }, "operators": { "description": "The operators to use. Unset uses each operator. `--operators` wins.", "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MutationOperatorName" } }, "minScore": { "description": "The minimum mutation score, from 0 to 100. When the score of a run is\nlower, `fallow mutation` exits with code 1. Unset never fails a run.\n`--min-score` wins.", "type": [ "number", "null" ], "format": "double", "minimum": 0.0, "maximum": 100.0 }, "concurrency": { "description": "The number of companion processes. Unset uses half the logical cores.\n`--concurrency` wins.", "type": [ "integer", "null" ], "format": "uint", "minimum": 1 }, "typecheck": { "description": "Type-check each survived mutant through the TypeScript-Go companion\nof `--type-aware`. A survivor that does not type-check becomes\n`compile_error` and does not count in the score. Unset or `false`\nchecks no survivor. `--typecheck` turns the check on.", "type": [ "boolean", "null" ] }, "runnerConfig": { "description": "The config file of the test runner, relative to the project root, for\nexample `vitest.integration.config.mjs`. The file must exist inside\nthe project root. Only the Vitest runner reads it. Unset uses the\ndefault config discovery of the runner. `--runner-config` wins.", "type": [ "string", "null" ] } }, "additionalProperties": false }, "MutationRunner": { "description": "The test runner of `fallow mutation`.", "oneOf": [ { "description": "Detect the runner from the project: the `vitest` dependency, the\ntest module that the test files import, a Bun file at the root, or a\n`node --test` script.", "type": "string", "const": "auto" }, { "description": "Vitest 4.1 to 5 from the project `node_modules`.", "type": "string", "const": "vitest" }, { "description": "`node:test` of Node.js 22.18 or later. Each test file runs in its own\nNode process.", "type": "string", "const": "node-test" }, { "description": "`bun test` of Bun 1.4 or later. Each test file runs in its own Bun\nprocess.", "type": "string", "const": "bun-test" } ] }, "MutationOperatorName": { "description": "A mutation operator name, kebab-case.", "oneOf": [ { "description": "`a + b` to `a - b`, and the other arithmetic pairs.", "type": "string", "const": "arithmetic-operator" }, { "description": "`a < b` to `a <= b`, and the other relational pairs.", "type": "string", "const": "relational-operator" }, { "description": "`a && b` to `a || b`, and the reverse.", "type": "string", "const": "logical-operator" }, { "description": "A condition to its negation.", "type": "string", "const": "negate-condition" }, { "description": "A unary operator removed or changed.", "type": "string", "const": "unary-operator" }, { "description": "`i++` to `i--`, and the reverse.", "type": "string", "const": "update-operator" }, { "description": "A call statement removed.", "type": "string", "const": "removed-call" }, { "description": "A return value changed.", "type": "string", "const": "return-value" }, { "description": "`true` to `false`, and the reverse.", "type": "string", "const": "boolean-literal" }, { "description": "A string literal emptied or filled.", "type": "string", "const": "string-literal" }, { "description": "`a?.b` to `a.b`.", "type": "string", "const": "optional-chaining" }, { "description": "One token of a regular expression literal changed: an anchor\nremoved, a character class negated, or a class escape with the\nopposite case.", "type": "string", "const": "regex-literal" }, { "description": "`z.number().int()` to `z.number()` in a module-level `const`\ninitializer: one call link of a fluent chain removed.", "type": "string", "const": "removed-chain-link" } ] }, "HealthConfig": { "description": "Configuration for complexity health metrics (`fallow health`).", "type": "object", "properties": { "maxCyclomatic": { "description": "Maximum allowed cyclomatic complexity per function (default: 20).\nFunctions exceeding this threshold are reported. Governs findings\nonly; the health score's complexity penalties use fixed calibration\n(use `health.ignore` to remove a file from the score).", "type": "integer", "format": "uint16", "minimum": 0, "maximum": 65535, "default": 20 }, "cyclomaticPolicy": { "description": "How the cyclomatic gate counts complexity (default: `standard`).\n`literal-membership` counts a chain of strict equality checks of one\nidentifier against primitive literals (`kind === \"a\" || kind === \"b\"`)\nas one predicate. The policy applies to the `maxCyclomatic` gate and\nto every CRAP score, so the `maxCrap` gate reads the same value.\nFindings then report the standard value as `standard_cyclomatic`. The\nhealth score, complexity density, and hotspots keep the standard\ncount. Older fallow versions reject this key as unknown, so pair it\nwith `minimumVersion`.", "$ref": "#/$defs/CyclomaticPolicy" }, "maxCognitive": { "description": "Maximum allowed cognitive complexity per function (default: 15).\nFunctions exceeding this threshold are reported. Governs findings\nonly, never the health score.", "type": "integer", "format": "uint16", "minimum": 0, "maximum": 65535, "default": 15 }, "maxCrap": { "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph. Governs\nfindings and the threshold-relative file-score signals\n(`crap_above_threshold`, the `risk` triage tag, and the\n`add_test_coverage` refactoring target); measured values such as\n`crap_max` and the overall health score never move with it. Set to\n`0` to disable CRAP enforcement entirely: no findings, nothing counts\nabove threshold, and file-score rows disclose baseline breaches as\nexempt instead. The `complexity-crap` rule is different: it decides if\na finding fails the run, and `off` hides the findings but keeps the\nfile-score signals.", "type": "number", "format": "double", "default": 30.0 }, "crapRefactorBand": { "description": "Band below `maxCyclomatic` where CRAP-only findings also receive a\nsecondary `refactor-function` action (default: 5). Set to `0` to only\nsuggest refactoring when cyclomatic already meets the configured\nthreshold.", "type": "integer", "format": "uint16", "minimum": 0, "maximum": 65535, "default": 5 }, "maxUnitSize": { "description": "Maximum function length in lines of code before it is reported as an\noversized \"large function\" (default: 60). Raise it globally, or per file\nvia `thresholdOverrides[].maxUnitSize`, to relax the bar for generated or\ntest files (where a `describe()` block spans hundreds of lines) without\ndisabling complexity checks on those files. This filters the reported\nlarge-functions list only; the descriptive unit-size profile and the\nhealth score still reflect raw sizes against fixed calibration (the\n`unit_size` penalty keeps its `>60` LOC very-high-risk edge so grades\nstay comparable across projects; use `health.ignore` to remove a file\nfrom the score entirely).", "type": "integer", "format": "uint32", "minimum": 0, "default": 60 }, "coverage": { "description": "Path to Istanbul coverage data (coverage-final.json) or raw V8 coverage\n(a `NODE_V8_COVERAGE` directory or one V8 JSON file) for accurate\nper-function CRAP scores. Relative paths resolve against the project root. The CLI\n`--coverage` flag and `FALLOW_COVERAGE` environment variable override\nthis value. Consulted by `fallow health`, bare `fallow`, `fallow audit`,\n`fallow viz`, and the MCP `audit` / `check_health` tools.", "type": [ "string", "null" ], "default": null }, "coverageRoot": { "description": "Absolute prefix to strip from Istanbul file paths before CRAP matching.\nUse when coverage was generated under a different checkout root in CI\nor Docker. The CLI `--coverage-root` flag and `FALLOW_COVERAGE_ROOT`\nenvironment variable override this value. Consulted by `fallow health`,\nbare `fallow`, `fallow audit`, `fallow viz`, and the MCP `audit` /\n`check_health` tools.", "type": [ "string", "null" ], "default": null }, "ignore": { "description": "Glob patterns to exclude from complexity analysis.\nA single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "type": "string" }, "default": [] }, "thresholdOverrides": { "description": "Per-file or per-function threshold overrides. These keep exceptional\nfunctions visible as configured numeric ceilings instead of hiding them\nbehind binary suppressions.", "type": "array", "items": { "$ref": "#/$defs/HealthThresholdOverride" } }, "ownership": { "description": "Ownership analysis configuration. Controls bot filtering and email\nprivacy mode for `--ownership` output.", "$ref": "#/$defs/OwnershipConfig", "default": { "botPatterns": [ "*\\[bot\\]*", "dependabot*", "renovate*", "github-actions*", "svc-*", "*-service-account*" ], "emailMode": "handle" } }, "changeCoupling": { "description": "Change coupling thresholds for the `change_coupling` section and the\nhidden-coupling refactoring targets. Older fallow versions reject this\nkey as unknown, so pair it with `minimumVersion` set to the release\nthat added it.", "$ref": "#/$defs/ChangeCouplingConfig", "default": { "maxFilesPerCommit": 30, "minRevisions": 5, "minSharedRevisions": 5, "minDegree": 0.3 } }, "suggestInlineSuppression": { "description": "Whether health JSON output emits `suppress-line` action hints\nalongside complexity findings (default: `true`). Set to `false` to\nopt out across the project: useful for teams that manage suppressions\nexclusively through `// fallow-ignore-*` comments authored by hand or\nthrough the `fallow.suppress` LSP code action, but who do not want\nCI-driven `suppress-line` action hints in their JSON output.\n`--baseline` activates auto-omission regardless of this setting,\nsince baseline files are a separate suppression mechanism.", "type": "boolean", "default": true } }, "additionalProperties": false }, "CyclomaticPolicy": { "description": "How `fallow health` counts cyclomatic complexity for its gates.\n\nThe policy changes the cyclomatic value that the `maxCyclomatic` gate reads\nand the cyclomatic value in every CRAP score. It does not change the health\nscore, the complexity density, or the hotspot ranking: those keep the\nstandard count so that grades stay comparable across projects.", "oneOf": [ { "description": "Count every decision point, `&&`, `||`, and `??` operator (`McCabe`).", "type": "string", "const": "standard" }, { "description": "Count a literal membership chain as one predicate. A chain such as\n`kind === \"a\" || kind === \"b\" || kind === \"c\"` adds no cyclomatic\nincrements for its `||` operators. Only strict equality checks of one\nidentifier against string, number, bigint, boolean, or `null` literals\nqualify. Member access, calls, mixed operators, and different operands\nkeep the standard count.", "type": "string", "const": "literal-membership" } ] }, "HealthThresholdOverride": { "description": "Per-file or per-function health threshold override.", "type": "object", "properties": { "files": { "description": "Project-root-relative file globs this override applies to.\nA single `*` stays within one path segment; use `**` to match across directories.", "type": "array", "items": { "type": "string" } }, "functions": { "description": "Exact emitted function names this override applies to. Empty means every\nfunction in matching files. Synthetic units are matched by their emitted\nname, so `\"