{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "FallowConfig",
"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
},
"extends": {
"description": "An ordered array of parent config sources to inherit before this file's own keys apply; each entry is a file-relative path, an `npm:<package>` 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).",
"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.",
"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.",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"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 whose sole sub-key patterns (array of globs) adds workspace package roots beyond those discovered from package.json workspaces, pnpm-workspace.yaml, and tsconfig references. Optional and absent by default (discovery uses the manifests alone); set it only when workspaces live in directories the standard manifests do not declare.",
"anyOf": [
{
"$ref": "#/$defs/WorkspaceConfig"
},
{
"type": "null"
}
],
"default": null
},
"ignoreDependencies": {
"description": "A list of exact package names 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; matching is exact string equality against the package name, not a glob.",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"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: <glob>, exports: [<name>, ...] }` 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.",
"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:<name>` 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), `minTokens` (50), `minLines` (5), `minOccurrences` (integer >= 2, deserialization fails below 2), `threshold` (max duplication percentage, 0 = no limit), `ignore` globs, `ignoreDefaults` (true, merge built-in generated-file ignores), `skipLocal` (only report cross-directory clones), `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, or set `mode` to `semantic` to catch renamed-variable clones.",
"$ref": "#/$defs/DuplicatesConfig",
"default": {
"enabled": true,
"mode": "mild",
"minTokens": 50,
"minLines": 5,
"minOccurrences": 2,
"threshold": 0.0,
"ignore": [],
"ignoreDefaults": true,
"skipLocal": false,
"crossLanguage": false,
"ignoreImports": true,
"normalization": {},
"minCorpusSizeForShingleFilter": 1024,
"minCorpusSizeForTokenCache": 5000
}
},
"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).",
"$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"
},
"suggestInlineSuppression": true
}
},
"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`, `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",
"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",
"unused-component-emits": "warn",
"unused-component-inputs": "warn",
"unused-component-outputs": "warn",
"unused-svelte-events": "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",
"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",
"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"
}
},
"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"
},
"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.*` 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.",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"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).",
"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
},
"autoImports": {
"description": "When true, drops Nuxt convention-based entry-pattern fallbacks: component fallbacks are dropped unless nuxt.config declares components:, and composable/util fallbacks are dropped unless it declares imports:, so genuinely-unreferenced convention files surface as unused-file. 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 `<Card />` or `useUserStore()` to their convention files) happens regardless of this flag.",
"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,
"$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": []
},
"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": {
"package": {
"type": "string"
},
"type": {
"type": "string",
"const": "dependency"
}
},
"required": [
"type",
"package"
]
},
{
"description": "Plugin detected if this file pattern matches.",
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"type": {
"type": "string",
"const": "fileExists"
}
},
"required": [
"type",
"pattern"
]
},
{
"description": "All conditions must be true.",
"type": "object",
"properties": {
"conditions": {
"type": "array",
"items": {
"$ref": "#/$defs/PluginDetection"
}
},
"type": {
"type": "string",
"const": "all"
}
},
"required": [
"type",
"conditions"
]
},
{
"description": "Any condition must be true.",
"type": "object",
"properties": {
"conditions": {
"type": "array",
"items": {
"$ref": "#/$defs/PluginDetection"
}
},
"type": {
"type": "string",
"const": "any"
}
},
"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`).",
"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 dotted field path to an expected scalar\nvalue. ALL entries must match by STRICT EQUALITY for the manifest to be\nprocessed. An empty map matches every manifest.",
"type": "object",
"additionalProperties": true,
"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"
}
]
},
"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 (a missing or empty field seeds nothing). The glob\nmust encode its own extension (e.g. `public/index.{ts,tsx}`); glob entry\npatterns are matched literally against discovered files without\nsource-extension probing.",
"type": "string"
},
"when": {
"description": "Per-entry gate (strict equality), evaluated against the same manifest.\nAn empty map always passes.",
"type": "object",
"additionalProperties": true,
"default": {}
}
},
"required": [
"path"
]
},
"ExternalUsedExport": {
"description": "Exports considered used for files matching a pattern.",
"type": "object",
"properties": {
"pattern": {
"description": "Glob pattern for files.",
"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": []
}
}
},
"IgnoreExportRule": {
"description": "Rule for ignoring specific exports.",
"type": "object",
"properties": {
"file": {
"description": "Glob pattern for files.",
"type": "string"
},
"exports": {
"description": "Export names to ignore (`*` for all).",
"type": "array",
"items": {
"type": "string"
}
}
},
"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.",
"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": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/$defs/IgnoreExportsUsedInFileByKind"
}
]
},
"IgnoreExportsUsedInFileByKind": {
"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"
},
"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.",
"type": "array",
"items": {
"type": "string"
},
"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
},
"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"
]
}
}
},
"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.",
"type": "integer",
"format": "uint16",
"minimum": 0,
"maximum": 65535,
"default": 20
},
"maxCognitive": {
"description": "Maximum allowed cognitive complexity per function (default: 15).\nFunctions exceeding this threshold are reported.",
"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.",
"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 (use `health.ignore` to remove a\nfile from the score entirely).",
"type": "integer",
"format": "uint32",
"minimum": 0,
"default": 60
},
"coverage": {
"description": "Path to Istanbul-format coverage data for accurate per-function CRAP\nscores. Relative paths resolve against the project root. The CLI\n`--coverage` flag and `FALLOW_COVERAGE` environment variable override\nthis value.",
"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.",
"type": [
"string",
"null"
],
"default": null
},
"ignore": {
"description": "Glob patterns to exclude from complexity analysis.",
"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"
}
},
"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
},
"HealthThresholdOverride": {
"description": "Per-file or per-function health threshold override.",
"type": "object",
"properties": {
"files": {
"description": "Project-root-relative file globs this override applies to.",
"type": "array",
"items": {
"type": "string"
}
},
"functions": {
"description": "Exact emitted function names this override applies to. Empty means every\nfunction in matching files.",
"type": "array",
"items": {
"type": "string"
}
},
"maxCyclomatic": {
"description": "Local cyclomatic complexity ceiling.",
"type": [
"integer",
"null"
],
"format": "uint16",
"minimum": 0,
"maximum": 65535
},
"maxCognitive": {
"description": "Local cognitive complexity ceiling.",
"type": [
"integer",
"null"
],
"format": "uint16",
"minimum": 0,
"maximum": 65535
},
"maxCrap": {
"description": "Local CRAP ceiling.",
"type": [
"number",
"null"
],
"format": "double"
},
"maxUnitSize": {
"description": "Local unit-size ceiling: maximum function length in lines of code before\nit is reported as an oversized \"large function\". Leave `functions` empty\nto relax the bar for every function in the matching files (which covers\nboth the `describe()` wrapper and the individual `it()` blocks in a test\nsuite).",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"reason": {
"description": "Human-readable rationale for the exception.",
"type": [
"string",
"null"
]
}
},
"additionalProperties": false,
"required": [
"files"
]
},
"OwnershipConfig": {
"description": "Configuration for ownership analysis (`fallow health --hotspots --ownership`).",
"type": "object",
"properties": {
"botPatterns": {
"description": "Glob patterns (matched against the author email local-part) that\nidentify bot or service-account commits to exclude from ownership\nsignals. Overrides the defaults entirely when set.",
"type": "array",
"items": {
"type": "string"
},
"default": [
"*\\[bot\\]*",
"dependabot*",
"renovate*",
"github-actions*",
"svc-*",
"*-service-account*"
]
},
"emailMode": {
"description": "Privacy mode for emitted author emails. Defaults to `handle`.\nOverride on the CLI via `--ownership-emails=raw|handle|anonymized`.\nThe legacy spelling `hash` is still accepted for compatibility.",
"$ref": "#/$defs/EmailMode",
"default": "handle"
}
}
},
"EmailMode": {
"description": "Privacy mode for author emails emitted in ownership output.\n\nDefaults to `handle` (local-part only, no domain) so SARIF and JSON\nartifacts do not leak raw email addresses into CI pipelines.",
"oneOf": [
{
"description": "Show the raw email address as it appears in git history.\nUse for public repositories where history is already exposed.",
"type": "string",
"const": "raw"
},
{
"description": "Show the local-part only (before the `@`). Mailmap-resolved where possible.\nDefault. Balances readability and privacy.",
"type": "string",
"const": "handle"
},
{
"description": "Show a stable `xxh3:<16hex>` pseudonym derived from the raw email.\nNon-cryptographic; suitable to keep raw emails out of CI artifacts\n(SARIF, code-scanning uploads) but not as a security primitive:\na known list of org emails can be brute-forced into a rainbow table.\nUse in regulated environments where even local-parts are sensitive.",
"type": "string",
"const": "anonymized"
},
{
"description": "Legacy spelling for [`EmailMode::Anonymized`].",
"type": "string",
"const": "hash"
}
]
},
"RulesConfig": {
"description": "Per-issue-type severity configuration.\n\nControls which issue types cause CI failure, are reported as warnings,\nor are suppressed entirely. Most fields default to `Severity::Error`.\n\nRule names use kebab-case in config files (e.g., `\"unused-files\": \"error\"`).",
"type": "object",
"properties": {
"unused-files": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"unused-exports": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"unused-types": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"private-type-leaks": {
"$ref": "#/$defs/Severity",
"default": "off"
},
"unused-dependencies": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"unused-dev-dependencies": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-optional-dependencies": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-enum-members": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"unused-class-members": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"unused-store-members": {
"description": "Store members (Pinia `state` / `getters` / `actions` key, or a\nsetup-store returned key) declared but never accessed by any consumer\nproject-wide. Defaults to `warn`, not `error` like the closed-set\nclass/enum member rules: a store has an OPEN declaration surface\n(plugins, `$onAction`, dynamic dispatch) so analyzer confidence is\ngenuinely lower; warn encodes that without failing CI. Promotable to\n`error` once validated on a codebase.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unprovided-injects": {
"description": "Vue `inject(KEY)` / Svelte `getContext(KEY)` whose symbol KEY is\n`provide`/`setContext`'d nowhere in the project (the\ninjected-never-provided dead-half). Defaults to `warn`, not `error`:\na DI key has an open provide surface (plugins, app-level provide) so\nanalyzer confidence is lower; warn encodes that without failing CI.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unrendered-components": {
"description": "Vue/Svelte single-file component reachable in the module graph but\nrendered nowhere in the project (the imported-but-never-rendered\ndead-half). Defaults to `warn`, not `error`: a component can be rendered\nreflectively (dynamic `<component :is>`), so analyzer confidence is\nlower; warn encodes that without failing CI.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-component-props": {
"description": "Vue `<script setup>` `defineProps`, Svelte 5 `$props()`, or React\ndeclared prop referenced nowhere inside its own component. The\nsingle-component dead-input direction. Defaults to `warn`, not `error`: a\nprop can be part of a deliberately-stable public component API, so\nanalyzer confidence is lower; warn encodes that without failing CI.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-component-emits": {
"description": "Vue `<script setup>` `defineEmits` declared event emitted nowhere inside\nits own single-file component (no `emit('<name>')` call). The single-file\ndead-input direction. Defaults to `warn`, not `error`: an emit can be part\nof a deliberately-stable public component API, so analyzer confidence is\nlower; warn encodes that without failing CI.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-component-inputs": {
"description": "Angular `@Input()` / signal `input()` / `model()` declared input read\nnowhere inside its own component (neither the inline/external template nor\nthe class body). The single-file dead-input direction, the Angular\nanalogue of `unused-component-prop`. Defaults to `warn`, not `error`: an\ninput can be part of a deliberately-stable public component API, so\nanalyzer confidence is lower; warn encodes that without failing CI.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-component-outputs": {
"description": "Angular `@Output()` / signal `output()` declared output emitted nowhere\ninside its own component (no `this.<output>.emit(...)`). The single-file\ndead-output direction, the Angular analogue of `unused-component-emit`.\nDefaults to `warn`, not `error`: an output can be part of a\ndeliberately-stable public component API, so analyzer confidence is lower;\nwarn encodes that without failing CI.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-svelte-events": {
"description": "Svelte component dispatching a custom event via `createEventDispatcher()`\nwhose event name is listened to nowhere in the analyzed project. The\ncross-file dead-output direction (no eslint-plugin-svelte / svelte-check\nrule covers the listener side). Defaults to `warn`, not `error`: a\ndispatched event can be part of a deliberately-stable public component\nAPI, or a listener may be added later, so analyzer confidence is lower;\nwarn encodes that without failing CI.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-server-actions": {
"description": "Next.js Server Action (an export of a `\"use server\"` file) referenced by\nno code in the project: no import-and-call, no `action={fn}` binding, no\n`<form action={fn}>`. Cross-graph dead-export direction, reclassified out\nof `unused-export` for `\"use server\"` files. Defaults to `warn`, not\n`error`: the rule is new and false-negative-preferring, and reflective\naction-dispatch shapes can hide a real consumer; warn encodes that\nwithout failing CI until corpus-validated.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unused-load-data-keys": {
"description": "SvelteKit `+page.{ts,server.ts,js,server.js}` `load()` return-object key\nread by no consumer: not off the sibling `+page.svelte`'s `data.<key>`,\nnor project-wide via `page.data.<key>` / `$page.data.<key>`. Cross-file\ndead-input direction. Defaults to `warn`, not `error`: the rule is new and\nfalse-negative-preferring (a whole-object `data` pass abstains), and a\nload fetch can have side effects so deletion is a human call; warn encodes\nthat without failing CI until corpus-validated.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"prop-drilling": {
"description": "React/Preact prop forwarded unchanged through `>= N` intermediate\npass-through components until a component that substantively consumes it.\nA graph-derived health signal. Defaults to `off` (opt-in), like\n`private-type-leak` / `security-*`: the located per-chain records and the\nsmall capped health penalty are dormant until the user enables the rule.",
"$ref": "#/$defs/Severity",
"default": "off"
},
"thin-wrapper": {
"description": "A React/Preact component whose entire body is `return <Child {...props}/>`\n(pure structural indirection, a candidate for inlining). A graph-derived\nhealth signal. Defaults to `off` (opt-in), like `prop-drilling`: the\nlocated per-wrapper records are dormant until the user enables the rule.",
"$ref": "#/$defs/Severity",
"default": "off"
},
"duplicate-prop-shape": {
"description": "Three or more React/Preact components across two or more files whose\nstatically-harvested prop NAME set is identical after stripping ubiquitous\nDOM / passthrough names (a missing shared `Props` type / base component).\nA graph-derived structural-refactor health signal. Defaults to `off`\n(opt-in), like `thin-wrapper`: the located per-component records are\ndormant until the user enables the rule.",
"$ref": "#/$defs/Severity",
"default": "off"
},
"css-token-drift": {
"description": "A CSS / CSS-in-JS design-token DRIFT finding (a hardcoded value where a\ndesign token exists, e.g. a Tailwind arbitrary value). A styling-domain\nadvisory surfaced in `fallow audit`; defaults to `warn` (verdict-neutral).\nSet to `error` to gate CI on styling drift, or `off` to silence.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"css-duplicate-block": {
"description": "A CSS / CSS-in-JS DUPLICATE declaration block (copy-pasted rule body).\nA styling-domain advisory surfaced in `fallow audit`; defaults to `warn`\n(verdict-neutral). Set to `error` to gate, or `off` to silence.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"css-selector-complexity": {
"description": "CSS selector / nesting / important-density complexity. A styling-domain\nadvisory surfaced in `fallow audit`; defaults to `warn`\n(verdict-neutral). Set to `error` to gate, or `off` to silence.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"css-dead-surface": {
"description": "CSS dead surface, such as unused scoped SFC classes. A styling-domain\nadvisory surfaced in `fallow audit`; defaults to `warn`\n(verdict-neutral). Set to `error` to gate, or `off` to silence.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"css-broken-reference": {
"description": "CSS broken references, such as missing classes or keyframes. A\nstyling-domain advisory surfaced by deep CSS audit mode; defaults\nto `warn` (verdict-neutral). Set to `error` to gate, or `off` to silence.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unresolved-imports": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"unlisted-dependencies": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"duplicate-exports": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"type-only-dependencies": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"test-only-dependencies": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"dev-dependencies-in-production": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"circular-dependencies": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"re-export-cycle": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"boundary-violation": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"coverage-gaps": {
"$ref": "#/$defs/Severity",
"default": "off"
},
"feature-flags": {
"$ref": "#/$defs/Severity",
"default": "off"
},
"stale-suppressions": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"require-suppression-reason": {
"description": "Opt-in suppression hygiene rule: when enabled, every `fallow-ignore-*`\ncomment and `@expected-unused` tag must carry a `-- <reason>` suffix.",
"$ref": "#/$defs/Severity",
"default": "off"
},
"unused-catalog-entries": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"empty-catalog-groups": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"unresolved-catalog-references": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"unused-dependency-overrides": {
"$ref": "#/$defs/Severity",
"default": "warn"
},
"misconfigured-dependency-overrides": {
"$ref": "#/$defs/Severity",
"default": "error"
},
"security-client-server-leak": {
"description": "Opt-in (default off): a `\"use client\"` file that transitively imports a\nmodule reading a non-public `process.env` secret. Surfaced only by\n`fallow security`; never under bare `fallow` or the `audit` gate.",
"$ref": "#/$defs/Severity",
"default": "off"
},
"security-sink": {
"description": "Opt-in (default off): a syntactic tainted-sink candidate matched against\nthe data-driven catalogue (`security_matchers.toml`). ONE knob gates ALL\ncatalogue categories. Surfaced only by `fallow security`; never under\nbare `fallow` or the `audit` gate.",
"$ref": "#/$defs/Severity",
"default": "off"
},
"policy-violation": {
"description": "Master severity for rule-pack findings (`rulePacks` config). Defaults\nto `warn` so enabling a brand-new policy pack never hard-fails CI on\nits first run; individual pack rules opt up via `\"severity\": \"error\"`.\n`off` is a kill switch that disables the whole evaluator (per-rule\nseverity cannot resurrect it).",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"invalid-client-export": {
"description": "A `\"use client\"` file that exports a Next.js server-only /\nroute-segment config name (e.g. `metadata`, `revalidate`, `GET`).\nNext.js rejects this at build time; fallow catches it statically.\nDefaults to `warn`.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"mixed-client-server-barrel": {
"description": "A barrel file that re-exports BOTH a `\"use client\"` origin module AND a\nserver-only origin module. Importing one name from such a barrel drags\nthe other's directive context across the React Server Components\nboundary (the Next.js App Router footgun). Defaults to `warn`.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"misplaced-directive": {
"description": "A `\"use client\"` / `\"use server\"` directive written as an expression\nstatement after a non-directive statement (an import, a const), so the\nRSC bundler parses it as an ordinary string and silently ignores it.\nThe intended client/server boundary never takes effect. Defaults to\n`warn`.",
"$ref": "#/$defs/Severity",
"default": "warn"
},
"route-collision": {
"description": "Two or more Next.js App Router route files that resolve to the same URL\nwithin one app-root. Next.js fails the build (\"You cannot have two\nparallel pages that resolve to the same path\"); fallow catches it\nstatically and names every colliding file. Defaults to `error`: the\nproject already fails `next build`, so flagging it as an error aligns\nfallow's exit code with the build it mirrors.",
"$ref": "#/$defs/Severity",
"default": "error"
},
"dynamic-segment-name-conflict": {
"description": "Sibling Next.js dynamic route segments at one tree position using\ndifferent param spellings (`[id]` vs `[slug]`). Next.js throws \"You\ncannot use different slug names for the same dynamic path\" at dev and\nproduction runtime when the position is hit; `next build` does NOT catch\nit (the build succeeds), so CI passes while the route crashes on its\nfirst request. fallow catches it statically. Defaults to `error`: the\nroute is a deterministic runtime crash on first request, so failing CI\nis the honest signal even though `next build` stays green (this is the\n\"error-runtime\" severity tier, shared with `route-collision`).",
"$ref": "#/$defs/Severity",
"default": "error"
}
}
},
"Severity": {
"description": "Severity level for rules.\n\nControls whether an issue type causes CI failure (`error`), is reported\nwithout failing (`warn`), or is suppressed entirely (`off`).",
"oneOf": [
{
"description": "Report and fail CI (non-zero exit code).",
"type": "string",
"const": "error"
},
{
"description": "Report but don't fail CI.",
"type": "string",
"const": "warn"
},
{
"description": "Don't detect or report.",
"type": "string",
"const": "off"
}
]
},
"UnusedComponentPropsConfig": {
"description": "Options for the `unused-component-props` rule.\n\nLets a project exempt component props whose local destructure binding name\nmatches a regex from `unused-component-props`, honoring the\n\"accepted-but-intentionally-unused\" leading-underscore convention (Svelte 5\n`$props()`, React destructure) that mirrors TypeScript `noUnusedParameters`\nand ESLint `@typescript-eslint/no-unused-vars` `varsIgnorePattern` /\n`argsIgnorePattern`. Opt-in; an unset `ignorePattern` leaves the rule's\nbehavior unchanged.",
"type": "object",
"properties": {
"ignorePattern": {
"description": "Regex matched against each declared prop's LOCAL destructure binding name\n(e.g. `_stage` in `let { stage: _stage } = $props()`), which falls back\nto the public prop name when there is no alias. A prop whose local name\nmatches is treated as intentionally unused and never reported as\n`unused-component-props`. Matching is unanchored (substring), like\nESLint's `RegExp.test`, so anchor with `^_` to match a leading\nunderscore. Compiled and validated at config load (an invalid regex fails\nload). Applies to Vue, Svelte, Astro, and React/Preact props.",
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"BoundaryConfig": {
"description": "Architecture boundary configuration.",
"type": "object",
"properties": {
"preset": {
"description": "Optional built-in preset.",
"anyOf": [
{
"$ref": "#/$defs/BoundaryPreset"
},
{
"type": "null"
}
]
},
"zones": {
"description": "Zone definitions.",
"type": "array",
"items": {
"$ref": "#/$defs/BoundaryZone"
},
"default": []
},
"rules": {
"description": "Zone import rules.",
"type": "array",
"items": {
"$ref": "#/$defs/BoundaryRule"
},
"default": []
},
"coverage": {
"description": "Optional policy for files that match no zone.",
"$ref": "#/$defs/BoundaryCoverageConfig"
},
"calls": {
"description": "Optional forbidden-call policy for zoned files.",
"$ref": "#/$defs/BoundaryCallsConfig"
}
}
},
"BoundaryPreset": {
"description": "Built-in architecture presets.",
"oneOf": [
{
"description": "Layered architecture.",
"type": "string",
"const": "layered"
},
{
"description": "Hexagonal / ports-and-adapters.",
"type": "string",
"const": "hexagonal"
},
{
"description": "Feature-Sliced Design.",
"type": "string",
"const": "feature-sliced"
},
{
"description": "Bulletproof React.",
"type": "string",
"const": "bulletproof"
}
]
},
"BoundaryZone": {
"description": "A zone grouping files by directory pattern.",
"type": "object",
"properties": {
"name": {
"description": "Zone name.",
"type": "string"
},
"patterns": {
"description": "Membership patterns.",
"type": "array",
"items": {
"type": "string"
}
},
"autoDiscover": {
"description": "Directories whose children become zones.",
"type": "array",
"items": {
"type": "string"
}
},
"root": {
"description": "Optional subtree scope.",
"type": [
"string",
"null"
]
}
},
"required": [
"name"
]
},
"BoundaryRule": {
"description": "An import rule between zones.",
"type": "object",
"properties": {
"from": {
"description": "Source zone.",
"type": "string"
},
"allow": {
"description": "Allowed target zones.",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"allowTypeOnly": {
"description": "Allowed type-only targets.",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"from"
]
},
"BoundaryCoverageConfig": {
"description": "Boundary zone coverage policy.",
"type": "object",
"properties": {
"requireAllFiles": {
"description": "Report source files that do not match any boundary zone.",
"type": "boolean"
},
"allowUnmatched": {
"description": "Glob patterns for files that may remain unmatched by any zone.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"BoundaryCallsConfig": {
"description": "Boundary forbidden-call policy. Applies only to files classified into a\nzone; unzoned files are unrestricted, matching the import rules.",
"type": "object",
"properties": {
"forbidden": {
"description": "Callee patterns that files in a zone may not call.",
"type": "array",
"items": {
"$ref": "#/$defs/ForbiddenCallRule"
}
}
}
},
"ForbiddenCallRule": {
"description": "One forbidden-call entry: files in zone `from` may not call callees\nmatching `callee`.",
"type": "object",
"properties": {
"from": {
"description": "Zone whose files may not make matching calls.",
"type": "string"
},
"callee": {
"description": "Forbidden callee pattern(s). Matching is segment-aware, not substring:\n`child_process.*` matches `child_process.exec` (and named imports from\n`child_process` / `node:child_process`), `fetch` matches only `fetch`,\nand a leading `*.` suffix-matches any object (`*.innerHTML`).",
"$ref": "#/$defs/ForbiddenCallee"
}
},
"required": [
"from",
"callee"
]
},
"ForbiddenCallee": {
"description": "One callee pattern or a list of patterns for a single `from` zone.",
"anyOf": [
{
"description": "A single callee pattern.",
"type": "string"
},
{
"description": "Multiple callee patterns sharing the same `from` zone.",
"type": "array",
"items": {
"type": "string"
}
}
]
},
"FlagsConfig": {
"description": "Feature flag detection configuration.\n\nControls which patterns fallow uses to detect feature flags in source code.\nConfigured via the `flags` section in `.fallowrc.json`, `.fallowrc.jsonc`, `fallow.toml`, or `.fallow.toml`.\n\n# Examples\n\n```json\n{\n \"flags\": {\n \"sdkPatterns\": [\n { \"function\": \"useFlag\", \"nameArg\": 0, \"provider\": \"LaunchDarkly\" }\n ],\n \"envPrefixes\": [\"FEATURE_\", \"NEXT_PUBLIC_ENABLE_\"],\n \"configObjectHeuristics\": false\n }\n}\n```",
"type": "object",
"properties": {
"sdkPatterns": {
"description": "Additional SDK call patterns to detect as feature flags.\nThese are merged with the built-in patterns for common providers\nincluding LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog,\nVercel Flags, ConfigCat, Flagsmith, Optimizely, and Eppo.",
"type": "array",
"items": {
"$ref": "#/$defs/SdkPattern"
}
},
"envPrefixes": {
"description": "Environment variable prefixes that indicate feature flags.\nMerged with built-in prefixes. Only `process.env.*` accesses matching\nthese prefixes are reported as feature flags.",
"type": "array",
"items": {
"type": "string"
}
},
"configObjectHeuristics": {
"description": "Enable config object heuristic detection.\nWhen true, property accesses on objects whose name contains \"feature\",\n\"flag\", or \"toggle\" are reported as low-confidence feature flags.\nDefault: false (opt-in due to higher false positive rate).",
"type": "boolean",
"default": false
}
}
},
"SdkPattern": {
"description": "A custom SDK call pattern for feature flag detection.\n\nDescribes a function call that evaluates a feature flag, e.g.,\n`useFlag('new-checkout')` or `client.getFeatureValue('parser', false)`.",
"type": "object",
"properties": {
"function": {
"description": "Function name to match (e.g., `\"useFlag\"`, `\"variation\"`).",
"type": "string"
},
"nameArg": {
"description": "Zero-based index of the argument containing the flag name.",
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"provider": {
"description": "Optional SDK/provider label shown in output (e.g., `\"LaunchDarkly\"`).",
"type": [
"string",
"null"
]
}
},
"required": [
"function"
]
},
"SecurityConfig": {
"description": "Scopes `fallow security` catalogue behavior. An absent category block admits\nevery catalogue category. `hardcoded-secret` is include-required and only\nruns when explicitly listed in `security.categories.include`.",
"type": "object",
"properties": {
"categories": {
"description": "Include/exclude filter over category ids (e.g. `dangerous-html`).",
"anyOf": [
{
"$ref": "#/$defs/SecurityCategories"
},
{
"type": "null"
}
]
},
"requestReceivers": {
"description": "Additional project-local names for HTTP request objects. These names\nextend the built-in receiver allowlist for `*.query`, `*.params`, and\n`*.body` source patterns. They do not replace the built-ins and do not\ngate `*.searchParams`, which intentionally stays ungated.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"SecurityCategories": {
"description": "Include/exclude lists scoping the active security categories. When `include`\nis set, only those categories are active; `exclude` removes categories from\nthe admitted set. Both unset admits catalogue categories. `hardcoded-secret`\nstill requires explicit inclusion.",
"type": "object",
"properties": {
"include": {
"description": "Catalogue category ids to admit. When set, all others are excluded.",
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"exclude": {
"description": "Catalogue category ids to remove from the admitted set.",
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"FixConfig": {
"type": "object",
"properties": {
"catalog": {
"description": "Groups `fallow fix` settings for pnpm workspace catalog cleanup. Its only key, `deletePrecedingComments` (`auto` default, `always`, `never`), controls whether a comment block directly above a removed unused `pnpm-workspace.yaml` catalog entry is deleted with the entry.",
"$ref": "#/$defs/CatalogFixConfig",
"default": {
"deletePrecedingComments": "auto"
}
}
}
},
"CatalogFixConfig": {
"type": "object",
"properties": {
"deletePrecedingComments": {
"description": "Controls whether comment lines immediately above an unused `pnpm-workspace.yaml` catalog entry are removed when `fallow fix` deletes that entry: `auto` (default: delete only when the comment block is preceded by a blank line or sits directly under the parent catalog header, and never when it is a section banner like `# ====`), `always` (always remove the adjacent comment block), or `never` (leave all preceding comments). A `fallow-keep` marker anywhere in the block always preserves it regardless of this setting. Set `never` for teams that keep hand-authored notes above catalog pins.",
"$ref": "#/$defs/CatalogPrecedingCommentPolicy",
"default": "auto"
}
}
},
"CatalogPrecedingCommentPolicy": {
"type": "string",
"enum": [
"auto",
"always",
"never"
]
},
"ResolveConfig": {
"description": "Module resolver configuration.\n\nControls how fallow resolves import specifiers against package.json\n`exports` / `imports` fields and tsconfig paths. Configured via the\n`resolve` section in `.fallowrc.json`, `.fallowrc.jsonc`, `fallow.toml`, or `.fallow.toml`.\n\n# Examples\n\n```json\n{\n \"resolve\": {\n \"conditions\": [\"development\", \"worker\"]\n }\n}\n```",
"type": "object",
"properties": {
"conditions": {
"description": "Additional export/import condition names to honor during module\nresolution. Merged with fallow's built-in conditions (`development`,\n`import`, `require`, `default`, `types`, `node`; plus `react-native`\nand `browser` when the React Native or Expo plugin is active).\n\nUser conditions are matched with higher priority than the baseline,\nso a package.json `exports` entry like:\n\n```json\n{ \"./api\": { \"worker\": \"./src/api.worker.ts\", \"import\": \"./dist/api.js\" } }\n```\n\nresolves to the `worker` branch when `\"worker\"` is listed here.\n\nSee <https://nodejs.org/api/packages.html#community-conditions-definitions>\nfor the set of community-defined conditions.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ProductionConfig": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/$defs/PerAnalysisProductionConfig"
}
]
},
"PerAnalysisProductionConfig": {
"type": "object",
"properties": {
"deadCode": {
"description": "When `production` is a per-analysis object, enables production mode for dead-code analysis only (boolean, default false): unused-files/exports/dependencies detection excludes test/spec/story/dev files and forces `unused-dev-dependencies`/`unused-optional-dependencies` to `off`, while health and dupes stay on the full tree. Set it to scope production analysis to dead code independently.",
"type": "boolean",
"default": false
},
"health": {
"description": "When `production` is a per-analysis object, enables production mode for the health/complexity analysis only (boolean, default false), so `fallow health` in combined `fallow` and `fallow audit` scores only shipped code (test/spec/story/dev files excluded) while dead-code and dupes stay on the full tree. Set it to scope production analysis to health independently.",
"type": "boolean",
"default": false
},
"dupes": {
"description": "When `production` is a per-analysis object, enables production mode for duplication analysis only (boolean, default false), so clone detection runs on shipped code only (test/spec/story/dev files excluded) while dead-code and health stay on the full tree. Set it to scope production analysis to dupes independently.",
"type": "boolean",
"default": false
}
},
"additionalProperties": false
},
"ConfigOverride": {
"description": "Per-file override entry.",
"type": "object",
"properties": {
"files": {
"description": "Glob-pattern string array selecting which source files this override entry applies to (patterns are validated and compiled to matchers at config load). Set to scope the entry's rule severities to a subset of paths (e.g. `[\"src/generated/**\", \"**/*.test.ts\"]`); when several override entries match one file, its severities come from every matching entry, applied in list order (later entries win on conflict).",
"type": "array",
"items": {
"type": "string"
}
},
"rules": {
"description": "Partial per-rule severity map applied only to files matching this entry's `files` globs; each rule key takes `error`, `warn`, or `off`, and omitted rules keep their top-level severity. Set to change how specific rules (e.g. unused-exports, unused-files) behave for the scoped paths. Inter-file rules (duplicate-exports, circular-dependencies, re-export-cycle) have no effect in an override; fallow warns during analysis and names the right mechanism instead (top-level `ignoreExports` for duplicate-exports, a file-level `// fallow-ignore-file` comment for circular-dependencies and re-export-cycle).",
"$ref": "#/$defs/PartialRulesConfig",
"default": {}
}
},
"required": [
"files"
]
},
"PartialRulesConfig": {
"description": "Partial per-issue-type severity for overrides. All fields optional.",
"type": "object",
"properties": {
"unused-files": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-exports": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-types": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"private-type-leaks": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-dependencies": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-dev-dependencies": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-optional-dependencies": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-enum-members": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-class-members": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-store-members": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unprovided-injects": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unrendered-components": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-component-props": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-component-emits": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-component-inputs": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-component-outputs": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-svelte-events": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-server-actions": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-load-data-keys": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"prop-drilling": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"thin-wrapper": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"duplicate-prop-shape": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"css-token-drift": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"css-duplicate-block": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"css-selector-complexity": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"css-dead-surface": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"css-broken-reference": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unresolved-imports": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unlisted-dependencies": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"duplicate-exports": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"type-only-dependencies": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"test-only-dependencies": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"dev-dependencies-in-production": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"circular-dependencies": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"re-export-cycle": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"boundary-violation": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"coverage-gaps": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"feature-flags": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"stale-suppressions": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"require-suppression-reason": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-catalog-entries": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"empty-catalog-groups": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unresolved-catalog-references": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"unused-dependency-overrides": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"misconfigured-dependency-overrides": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"security-client-server-leak": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"security-sink": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"policy-violation": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"invalid-client-export": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"mixed-client-server-barrel": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"misplaced-directive": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"route-collision": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
},
"dynamic-segment-name-conflict": {
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
}
}
},
"RegressionConfig": {
"type": "object",
"properties": {
"baseline": {
"description": "The saved per-issue-type issue counts that `--fail-on-regression` compares the current run against; the gate fails only when counts grow beyond the configured tolerance. Typically written by `--save-baseline` rather than hand-authored; each field (total_issues plus per-kind counts like unused_exports, boundary_violations, policy_violations) is an integer defaulting to 0 when omitted. Absent means no baseline is embedded.",
"anyOf": [
{
"$ref": "#/$defs/RegressionBaseline"
},
{
"type": "null"
}
]
}
}
},
"RegressionBaseline": {
"type": "object",
"properties": {
"totalIssues": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unusedFiles": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unusedExports": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unusedTypes": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unusedDependencies": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unusedDevDependencies": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unusedOptionalDependencies": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unusedEnumMembers": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unusedClassMembers": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unresolvedImports": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"unlistedDependencies": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"duplicateExports": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"circularDependencies": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"reExportCycles": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"typeOnlyDependencies": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"testOnlyDependencies": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"devDependenciesInProduction": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"boundaryViolations": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"boundaryCoverageViolations": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"boundaryCallViolations": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
},
"policyViolations": {
"type": "integer",
"format": "uint",
"minimum": 0,
"default": 0
}
}
},
"AuditConfig": {
"type": "object",
"properties": {
"gate": {
"description": "Selects which findings affect the `fallow audit` verdict: `new-only` (default) fails only on findings introduced by the current changeset (running a base-snapshot attribution pass), while `all` fails on every finding in changed files and skips that pass. Set to `all` to gate the full backlog in changed files; the `--gate` CLI flag overrides this.",
"$ref": "#/$defs/AuditGate"
},
"css": {
"description": "Toggles styling analytics (CSS and CSS-in-JS) in the `fallow audit` health sub-pass; these findings are descriptive and verdict-neutral by default (they change the exit code only when a css-* rule is set to error). Defaults to on when unset; set `false` to skip styling analysis. The `--no-css` CLI flag forces it off regardless.",
"type": [
"boolean",
"null"
]
},
"cssDeep": {
"description": "Toggles the project-wide CSS reachability pass in `fallow audit`, whose cross-file findings are narrowed back to changed anchors. Defaults to on when unset and runs only when css analytics are enabled; set `false` to keep local styling analytics but skip the whole-project scan. The `--css-deep` flag re-enables it and `--no-css-deep` forces it off.",
"type": [
"boolean",
"null"
]
},
"deadCodeBaseline": {
"description": "Path to a saved dead-code baseline file (produced by `fallow dead-code --save-baseline`) that the audit's dead-code sub-analysis compares against, suppressing pre-existing dead-code issues. The `--dead-code-baseline` CLI flag overrides it and both resolve relative to the project root; each sub-analysis uses a distinct baseline format, so this is separate from `healthBaseline` and `dupesBaseline`.",
"type": [
"string",
"null"
]
},
"healthBaseline": {
"description": "Path to a saved health/complexity baseline file (produced by `fallow health --save-baseline`) that the audit's health sub-analysis compares against, suppressing pre-existing complexity/health findings. The `--health-baseline` CLI flag overrides it and both resolve relative to the project root; its baseline format is distinct from the dead-code and dupes baselines.",
"type": [
"string",
"null"
]
},
"dupesBaseline": {
"description": "Path to a saved duplication baseline file (produced by `fallow dupes --save-baseline`) that the audit's duplication sub-analysis compares clone groups against, suppressing pre-existing duplicate clones. The `--dupes-baseline` CLI flag overrides it and both resolve relative to the project root; its baseline format is distinct from the dead-code and health baselines.",
"type": [
"string",
"null"
]
},
"cacheMaxAgeDays": {
"description": "Garbage-collection threshold, in whole days, for the persistent reusable base-snapshot worktree caches `fallow audit` creates: entries older than this window are swept on each audit run. Set to control cache accumulation; `0` disables the sweep and unset defaults to 30 days. The `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` environment variable overrides this field.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
}
}
},
"AuditGate": {
"type": "string",
"enum": [
"new-only",
"all"
]
},
"CacheConfig": {
"type": "object",
"properties": {
"dir": {
"description": "Directory for fallow's persistent analysis cache. Relative paths resolve\nfrom the project root.",
"type": [
"string",
"null"
]
},
"maxSizeMb": {
"description": "Maximum size of the persistent extraction cache, in megabytes.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
}
},
"additionalProperties": false
}
}
}