fallow 3.13.0 → 3.15.0

package/schema.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "FallowConfig",
+  "description": "The user-facing fallow configuration as authored in `.fallowrc.json` /\n`.fallowrc.jsonc` / `fallow.toml` (or the `fallow` key of `package.json`).\n\nEvery field documents its serialized meaning, default, and precedence\nagainst CLI flags and environment variables where they exist.\n`FallowConfig::resolve` compiles the loaded config (globs, regexes,\nplugin and rule-pack discovery) into a [`ResolvedConfig`] for analysis.\nUnknown keys are rejected at load so typos fail loud.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -121,16 +122,18 @@
       "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.",
+      "description": "Configures clone detection: `enabled` (default true), `mode` (`strict`, `mild` default, `weak`, `semantic`, from least to most identifier/literal blinding; `strict` and `mild` are equivalent under fallow's AST tokenizer, `weak` blinds string literals, `semantic` blinds all identifiers and literals for Type-2 renamed-variable detection), `near` (false, add bounded function-scoped near-miss detection), `minTokens` (50), `minLines` (5), `minOccurrences` (integer >= 2, deserialization fails below 2), `threshold` (max duplication percentage, 0 = no limit), `ignore` globs, `ignoredClones` (reviewed clone keys to hide until their content or occurrence count changes), `ignoreDefaults` (true, merge built-in generated-file ignores), `skipLocal` (only report cross-directory clones), `crossLanguage` (strip TS type annotations to match .ts against .js), `ignoreImports` (true, strip ES import/re-export/top-level require wiring from the token stream), and `normalization` (per-flag `ignoreIdentifiers`/`ignoreStringValues`/`ignoreNumericValues` overrides on top of `mode`). Raise `minOccurrences` to focus on widespread copy-paste, enable `near` for gapped structural clones, or set `mode` to `semantic` to catch renamed-variable exact clones.",
       "$ref": "#/$defs/DuplicatesConfig",
       "default": {
         "enabled": true,
         "mode": "mild",
+        "near": false,
         "minTokens": 50,
         "minLines": 5,
         "minOccurrences": 2,
         "threshold": 0.0,
         "ignore": [],
+        "ignoredClones": [],
         "ignoreDefaults": true,
         "skipLocal": false,
         "crossLanguage": false,
@@ -141,7 +144,7 @@
       }
     },
     "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).",
+      "description": "Sets complexity and health thresholds for `fallow health` (also applied in combined `fallow` and `fallow audit`): `maxCyclomatic` (20), `maxCognitive` (15), `maxCrap` (30.0, findings at or above this are reported), `crapRefactorBand` (5, cyclomatic band below `maxCyclomatic` where a secondary refactor action is added), `maxUnitSize` (max function lines before a large-function finding, 60), `coverage`/`coverageRoot` (Istanbul coverage path and path-prefix strip for accurate CRAP), `ignore` globs (remove files from findings AND the health score), `thresholdOverrides` (per-file/per-function ceilings via `files`/`functions`/`maxCyclomatic`/`maxCognitive`/`maxCrap`/`maxUnitSize`/`reason`), `ownership` (`botPatterns` and `emailMode` for `--ownership`), and `suggestInlineSuppression` (true, emit `suppress-line` action hints in JSON). Raise thresholds to relax which functions are flagged, wire `coverage` for real CRAP scores, or exempt generated/test files via `ignore` (drops them from the score too) or `thresholdOverrides` (keeps them visible under a higher ceiling). The four `max*` thresholds govern findings only and never move `health_score`: its penalties use fixed calibration so grades stay comparable across projects, and `ignore` is the lever that removes files from the score.",
       "$ref": "#/$defs/HealthConfig",
       "default": {
         "maxCyclomatic": 20,
@@ -457,6 +460,7 @@
           "type": "object",
           "properties": {
             "package": {
+              "description": "Exact package name looked up in the project's declared dependencies.",
               "type": "string"
             },
             "type": {
@@ -474,6 +478,7 @@
           "type": "object",
           "properties": {
             "pattern": {
+              "description": "Project-root-relative glob; the plugin activates when any\ndiscovered file matches it. Validated at load like other user\nglobs (no absolute paths or `..` segments).",
               "type": "string"
             },
             "type": {
@@ -491,6 +496,7 @@
           "type": "object",
           "properties": {
             "conditions": {
+              "description": "Sub-conditions combined with logical AND.",
               "type": "array",
               "items": {
                 "$ref": "#/$defs/PluginDetection"
@@ -511,6 +517,7 @@
           "type": "object",
           "properties": {
             "conditions": {
+              "description": "Sub-conditions combined with logical OR.",
               "type": "array",
               "items": {
                 "$ref": "#/$defs/PluginDetection"
@@ -709,6 +716,7 @@
           }
         }
       },
+      "additionalProperties": false,
       "required": [
         "file",
         "exports"
@@ -764,16 +772,20 @@
       ]
     },
     "IgnoreExportsUsedInFileConfig": {
+      "description": "Value of the `ignoreExportsUsedInFile` config key: whether an export\nreferenced elsewhere in its own file is suppressed from `unused-export`.",
       "anyOf": [
         {
+          "description": "Blanket toggle: `true` suppresses any export with a same-file use,\nregardless of kind. The default is `false`.",
           "type": "boolean"
         },
         {
+          "description": "Knip-parity object form restricting the suppression to type-only\nexports.",
           "$ref": "#/$defs/IgnoreExportsUsedInFileByKind"
         }
       ]
     },
     "IgnoreExportsUsedInFileByKind": {
+      "description": "Object form of `ignoreExportsUsedInFile` (`{ \"type\": ..., \"interface\": ... }`),\nrestricting the same-file-use suppression to type-only exports.",
       "type": "object",
       "properties": {
         "type": {
@@ -802,6 +814,11 @@
           "$ref": "#/$defs/DetectionMode",
           "default": "mild"
         },
+        "near": {
+          "description": "Detect structurally similar function bodies with small edits.",
+          "type": "boolean",
+          "default": false
+        },
         "minTokens": {
           "description": "Minimum number of tokens for a clone.",
           "type": "integer",
@@ -837,6 +854,15 @@
           },
           "default": []
         },
+        "ignoredClones": {
+          "description": "Reviewed clone groups to omit from duplication results.\n\nEach entry is `<fingerprint>:<instance_count>`, for example\n`dup:6f12ab34:2`. A content or occurrence-count change produces a new key\nand makes the group reportable again.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^dup:(?:[0-9a-f]{8}|[0-9a-f]{16}(?:-[1-9][0-9]*)?):(?:[2-9]|[1-9][0-9]+)$"
+          },
+          "default": []
+        },
         "ignoreDefaults": {
           "description": "Merge built-in generated-framework ignore patterns with `ignore`.\n\nSet to `false` to use only the user-provided `ignore` list.",
           "type": "boolean",
@@ -935,7 +961,7 @@
       "type": "object",
       "properties": {
         "maxCyclomatic": {
-          "description": "Maximum allowed cyclomatic complexity per function (default: 20).\nFunctions exceeding this threshold are reported.",
+          "description": "Maximum allowed cyclomatic complexity per function (default: 20).\nFunctions exceeding this threshold are reported. Governs findings\nonly; the health score's complexity penalties use fixed calibration\n(use `health.ignore` to remove a file from the score).",
           "type": "integer",
           "format": "uint16",
           "minimum": 0,
@@ -943,7 +969,7 @@
           "default": 20
         },
         "maxCognitive": {
-          "description": "Maximum allowed cognitive complexity per function (default: 15).\nFunctions exceeding this threshold are reported.",
+          "description": "Maximum allowed cognitive complexity per function (default: 15).\nFunctions exceeding this threshold are reported. Governs findings\nonly, never the health score.",
           "type": "integer",
           "format": "uint16",
           "minimum": 0,
@@ -951,7 +977,7 @@
           "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.",
+          "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph. Governs\nfindings only, never the health score.",
           "type": "number",
           "format": "double",
           "default": 30.0
@@ -965,7 +991,7 @@
           "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).",
+          "description": "Maximum function length in lines of code before it is reported as an\noversized \"large function\" (default: 60). Raise it globally, or per file\nvia `thresholdOverrides[].maxUnitSize`, to relax the bar for generated or\ntest files (where a `describe()` block spans hundreds of lines) without\ndisabling complexity checks on those files. This filters the reported\nlarge-functions list only; the descriptive unit-size profile and the\nhealth score still reflect raw sizes against fixed calibration (the\n`unit_size` penalty keeps its `>60` LOC very-high-risk edge so grades\nstay comparable across projects; use `health.ignore` to remove a file\nfrom the score entirely).",
           "type": "integer",
           "format": "uint32",
           "minimum": 0,
@@ -1187,38 +1213,47 @@
       "type": "object",
       "properties": {
         "unused-files": {
+          "description": "A file reachable from no entry point. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "unused-exports": {
+          "description": "An exported symbol no other module imports. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "unused-types": {
+          "description": "An exported type no other module uses. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "private-type-leaks": {
+          "description": "An exported signature referencing a same-file private type. Opt-in;\ndefaults to `off`.",
           "$ref": "#/$defs/Severity",
           "default": "off"
         },
         "unused-dependencies": {
+          "description": "A declared `dependencies` entry never observed used. Defaults to\n`error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "unused-dev-dependencies": {
+          "description": "A declared `devDependencies` entry never observed used. Defaults to\n`warn`; production mode forces it to `off`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "unused-optional-dependencies": {
+          "description": "A declared `optionalDependencies` entry never observed used. Defaults\nto `warn`; production mode forces it to `off`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "unused-enum-members": {
+          "description": "An enum member read nowhere in the project. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "unused-class-members": {
+          "description": "A class member used nowhere; `usedClassMembers` and decorator\nexemptions carve out framework-invoked members. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
@@ -1313,50 +1348,62 @@
           "default": "warn"
         },
         "unresolved-imports": {
+          "description": "An import specifier that resolves to no file or package. Defaults to\n`error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "unlisted-dependencies": {
+          "description": "An imported package not declared in any relevant `package.json`.\nDefaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "duplicate-exports": {
+          "description": "The same export name provided by multiple modules; `ignoreExports`\nexcludes intentional barrel re-exports. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "type-only-dependencies": {
+          "description": "A production dependency imported only via type-only imports (a\n`devDependencies` candidate). Defaults to `warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "test-only-dependencies": {
+          "description": "A production dependency imported only by test files. Defaults to\n`warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "dev-dependencies-in-production": {
+          "description": "A `devDependencies` entry imported by production code, which a\nproduction-only install would omit and break at runtime. Defaults to\n`warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "circular-dependencies": {
+          "description": "A circular import chain between modules. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "re-export-cycle": {
+          "description": "A cycle or self-loop in the re-export subgraph (barrel files\nre-exporting from each other in a loop). Defaults to `warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "boundary-violation": {
+          "description": "An import crossing a forbidden architecture-boundary edge declared in\nthe `boundaries` config. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "coverage-gaps": {
+          "description": "A runtime file or export with no test dependency path. Opt-in;\ndefaults to `off`.",
           "$ref": "#/$defs/Severity",
           "default": "off"
         },
         "feature-flags": {
+          "description": "A detected feature-flag pattern (tuned via the `flags` config).\nOpt-in; defaults to `off`.",
           "$ref": "#/$defs/Severity",
           "default": "off"
         },
         "stale-suppressions": {
+          "description": "A `fallow-ignore` comment or `@expected-unused` tag that no longer\nmatches any issue. Defaults to `warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
@@ -1366,22 +1413,27 @@
           "default": "off"
         },
         "unused-catalog-entries": {
+          "description": "A `pnpm-workspace.yaml` catalog entry referenced by no workspace\npackage. Defaults to `warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "empty-catalog-groups": {
+          "description": "A named pnpm catalog group declaring no entries. Defaults to `warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "unresolved-catalog-references": {
+          "description": "A workspace `package.json` `catalog:` / `catalog:<name>` reference\npointing at a catalog that does not declare the consumed package.\nDefaults to `error`; suppressible only via `ignoreCatalogReferences`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
         "unused-dependency-overrides": {
+          "description": "A pnpm `overrides:` / `pnpm.overrides` entry whose target package no\nworkspace `package.json` declares. Defaults to `warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "misconfigured-dependency-overrides": {
+          "description": "A pnpm `overrides:` / `pnpm.overrides` entry whose key or value cannot\nbe parsed into a valid pnpm shape. Defaults to `error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
@@ -1758,6 +1810,7 @@
       "additionalProperties": false
     },
     "FixConfig": {
+      "description": "The `fix` config section: settings for `fallow fix` apply behavior.",
       "type": "object",
       "properties": {
         "catalog": {
@@ -1770,6 +1823,7 @@
       }
     },
     "CatalogFixConfig": {
+      "description": "The `fix.catalog` section: how `fallow fix` cleans up unused\n`pnpm-workspace.yaml` catalog entries.",
       "type": "object",
       "properties": {
         "deletePrecedingComments": {
@@ -1780,11 +1834,23 @@
       }
     },
     "CatalogPrecedingCommentPolicy": {
-      "type": "string",
-      "enum": [
-        "auto",
-        "always",
-        "never"
+      "description": "Value of `fix.catalog.deletePrecedingComments`: what happens to comment\nlines directly above a catalog entry that `fallow fix` removes. A\n`fallow-keep` marker in the block always preserves it regardless of policy.",
+      "oneOf": [
+        {
+          "description": "Delete the adjacent comment block only when heuristics attribute it to\nthe entry (preceded by a blank line or directly under the catalog\nheader) and it is not a section banner. The default.",
+          "type": "string",
+          "const": "auto"
+        },
+        {
+          "description": "Always delete the adjacent comment block with the entry.",
+          "type": "string",
+          "const": "always"
+        },
+        {
+          "description": "Never delete preceding comments.",
+          "type": "string",
+          "const": "never"
+        }
       ]
     },
     "ResolveConfig": {
@@ -1801,16 +1867,20 @@
       }
     },
     "ProductionConfig": {
+      "description": "Value of the `production` config key: excludes test/spec/story/dev files\nfrom discovery, either globally or per analysis family.",
       "anyOf": [
         {
+          "description": "Boolean form applying to every analysis. The default is `false`.",
           "type": "boolean"
         },
         {
+          "description": "Object form (`{ deadCode?, health?, dupes? }`) scoping production mode\nper analysis family.",
           "$ref": "#/$defs/PerAnalysisProductionConfig"
         }
       ]
     },
     "PerAnalysisProductionConfig": {
+      "description": "Object form of the `production` config key, scoping production mode to\nindividual analysis families in combined `fallow` and `fallow audit`.",
       "type": "object",
       "properties": {
         "deadCode": {
@@ -1848,6 +1918,7 @@
           "default": {}
         }
       },
+      "additionalProperties": false,
       "required": [
         "files"
       ]
@@ -1857,6 +1928,7 @@
       "type": "object",
       "properties": {
         "unused-files": {
+          "description": "Optional override for [`RulesConfig::unused_files`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1867,6 +1939,7 @@
           ]
         },
         "unused-exports": {
+          "description": "Optional override for [`RulesConfig::unused_exports`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1877,6 +1950,7 @@
           ]
         },
         "unused-types": {
+          "description": "Optional override for [`RulesConfig::unused_types`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1887,6 +1961,7 @@
           ]
         },
         "private-type-leaks": {
+          "description": "Optional override for [`RulesConfig::private_type_leaks`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1897,6 +1972,7 @@
           ]
         },
         "unused-dependencies": {
+          "description": "Optional override for [`RulesConfig::unused_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1907,6 +1983,7 @@
           ]
         },
         "unused-dev-dependencies": {
+          "description": "Optional override for [`RulesConfig::unused_dev_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1917,6 +1994,7 @@
           ]
         },
         "unused-optional-dependencies": {
+          "description": "Optional override for [`RulesConfig::unused_optional_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1927,6 +2005,7 @@
           ]
         },
         "unused-enum-members": {
+          "description": "Optional override for [`RulesConfig::unused_enum_members`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1937,6 +2016,7 @@
           ]
         },
         "unused-class-members": {
+          "description": "Optional override for [`RulesConfig::unused_class_members`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1947,6 +2027,7 @@
           ]
         },
         "unused-store-members": {
+          "description": "Optional override for [`RulesConfig::unused_store_members`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1957,6 +2038,7 @@
           ]
         },
         "unprovided-injects": {
+          "description": "Optional override for [`RulesConfig::unprovided_injects`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1967,6 +2049,7 @@
           ]
         },
         "unrendered-components": {
+          "description": "Optional override for [`RulesConfig::unrendered_components`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1977,6 +2060,7 @@
           ]
         },
         "unused-component-props": {
+          "description": "Optional override for [`RulesConfig::unused_component_props`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1987,6 +2071,7 @@
           ]
         },
         "unused-component-emits": {
+          "description": "Optional override for [`RulesConfig::unused_component_emits`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1997,6 +2082,7 @@
           ]
         },
         "unused-component-inputs": {
+          "description": "Optional override for [`RulesConfig::unused_component_inputs`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2007,6 +2093,7 @@
           ]
         },
         "unused-component-outputs": {
+          "description": "Optional override for [`RulesConfig::unused_component_outputs`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2017,6 +2104,7 @@
           ]
         },
         "unused-svelte-events": {
+          "description": "Optional override for [`RulesConfig::unused_svelte_events`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2027,6 +2115,7 @@
           ]
         },
         "unused-server-actions": {
+          "description": "Optional override for [`RulesConfig::unused_server_actions`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2037,6 +2126,7 @@
           ]
         },
         "unused-load-data-keys": {
+          "description": "Optional override for [`RulesConfig::unused_load_data_keys`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2047,6 +2137,7 @@
           ]
         },
         "prop-drilling": {
+          "description": "Optional override for [`RulesConfig::prop_drilling`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2057,6 +2148,7 @@
           ]
         },
         "thin-wrapper": {
+          "description": "Optional override for [`RulesConfig::thin_wrapper`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2067,6 +2159,7 @@
           ]
         },
         "duplicate-prop-shape": {
+          "description": "Optional override for [`RulesConfig::duplicate_prop_shape`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2077,6 +2170,7 @@
           ]
         },
         "css-token-drift": {
+          "description": "Optional override for [`RulesConfig::css_token_drift`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2087,6 +2181,7 @@
           ]
         },
         "css-duplicate-block": {
+          "description": "Optional override for [`RulesConfig::css_duplicate_block`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2097,6 +2192,7 @@
           ]
         },
         "css-selector-complexity": {
+          "description": "Optional override for [`RulesConfig::css_selector_complexity`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2107,6 +2203,7 @@
           ]
         },
         "css-dead-surface": {
+          "description": "Optional override for [`RulesConfig::css_dead_surface`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2117,6 +2214,7 @@
           ]
         },
         "css-broken-reference": {
+          "description": "Optional override for [`RulesConfig::css_broken_reference`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2127,6 +2225,7 @@
           ]
         },
         "unresolved-imports": {
+          "description": "Optional override for [`RulesConfig::unresolved_imports`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2137,6 +2236,7 @@
           ]
         },
         "unlisted-dependencies": {
+          "description": "Optional override for [`RulesConfig::unlisted_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2147,6 +2247,7 @@
           ]
         },
         "duplicate-exports": {
+          "description": "Optional override for [`RulesConfig::duplicate_exports`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2157,6 +2258,7 @@
           ]
         },
         "type-only-dependencies": {
+          "description": "Optional override for [`RulesConfig::type_only_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2167,6 +2269,7 @@
           ]
         },
         "test-only-dependencies": {
+          "description": "Optional override for [`RulesConfig::test_only_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2177,6 +2280,7 @@
           ]
         },
         "dev-dependencies-in-production": {
+          "description": "Optional override for [`RulesConfig::dev_dependencies_in_production`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2187,6 +2291,7 @@
           ]
         },
         "circular-dependencies": {
+          "description": "Optional override for [`RulesConfig::circular_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2197,6 +2302,7 @@
           ]
         },
         "re-export-cycle": {
+          "description": "Optional override for [`RulesConfig::re_export_cycle`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2207,6 +2313,7 @@
           ]
         },
         "boundary-violation": {
+          "description": "Optional override for [`RulesConfig::boundary_violation`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2217,6 +2324,7 @@
           ]
         },
         "coverage-gaps": {
+          "description": "Optional override for [`RulesConfig::coverage_gaps`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2227,6 +2335,7 @@
           ]
         },
         "feature-flags": {
+          "description": "Optional override for [`RulesConfig::feature_flags`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2237,6 +2346,7 @@
           ]
         },
         "stale-suppressions": {
+          "description": "Optional override for [`RulesConfig::stale_suppressions`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2247,6 +2357,7 @@
           ]
         },
         "require-suppression-reason": {
+          "description": "Optional override for [`RulesConfig::require_suppression_reason`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2257,6 +2368,7 @@
           ]
         },
         "unused-catalog-entries": {
+          "description": "Optional override for [`RulesConfig::unused_catalog_entries`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2267,6 +2379,7 @@
           ]
         },
         "empty-catalog-groups": {
+          "description": "Optional override for [`RulesConfig::empty_catalog_groups`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2277,6 +2390,7 @@
           ]
         },
         "unresolved-catalog-references": {
+          "description": "Optional override for [`RulesConfig::unresolved_catalog_references`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2287,6 +2401,7 @@
           ]
         },
         "unused-dependency-overrides": {
+          "description": "Optional override for [`RulesConfig::unused_dependency_overrides`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2297,6 +2412,7 @@
           ]
         },
         "misconfigured-dependency-overrides": {
+          "description": "Optional override for [`RulesConfig::misconfigured_dependency_overrides`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2307,6 +2423,7 @@
           ]
         },
         "security-client-server-leak": {
+          "description": "Optional override for [`RulesConfig::security_client_server_leak`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2317,6 +2434,7 @@
           ]
         },
         "security-sink": {
+          "description": "Optional override for [`RulesConfig::security_sink`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2327,6 +2445,7 @@
           ]
         },
         "policy-violation": {
+          "description": "Optional override for [`RulesConfig::policy_violation`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2337,6 +2456,7 @@
           ]
         },
         "invalid-client-export": {
+          "description": "Optional override for [`RulesConfig::invalid_client_export`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2347,6 +2467,7 @@
           ]
         },
         "mixed-client-server-barrel": {
+          "description": "Optional override for [`RulesConfig::mixed_client_server_barrel`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2357,6 +2478,7 @@
           ]
         },
         "misplaced-directive": {
+          "description": "Optional override for [`RulesConfig::misplaced_directive`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2367,6 +2489,7 @@
           ]
         },
         "route-collision": {
+          "description": "Optional override for [`RulesConfig::route_collision`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2377,6 +2500,7 @@
           ]
         },
         "dynamic-segment-name-conflict": {
+          "description": "Optional override for [`RulesConfig::dynamic_segment_name_conflict`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2389,6 +2513,7 @@
       }
     },
     "RegressionConfig": {
+      "description": "The `regression` config section holding the saved issue-count baseline for\nthe `--fail-on-regression` gate.",
       "type": "object",
       "properties": {
         "baseline": {
@@ -2405,6 +2530,7 @@
       }
     },
     "RegressionBaseline": {
+      "description": "Saved per-issue-type counts written by `--save-baseline` and compared by\n`--fail-on-regression`. Every count defaults to `0` when its key is missing,\nso hand-trimmed baselines stay loadable.",
       "type": "object",
       "properties": {
         "analysisIdentity": {
@@ -2420,126 +2546,147 @@
           }
         },
         "totalIssues": {
+          "description": "Baseline count across all issue types.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unusedFiles": {
+          "description": "Baseline count of `unused-files` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unusedExports": {
+          "description": "Baseline count of `unused-exports` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unusedTypes": {
+          "description": "Baseline count of `unused-types` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unusedDependencies": {
+          "description": "Baseline count of `unused-dependencies` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unusedDevDependencies": {
+          "description": "Baseline count of `unused-dev-dependencies` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unusedOptionalDependencies": {
+          "description": "Baseline count of `unused-optional-dependencies` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unusedEnumMembers": {
+          "description": "Baseline count of `unused-enum-members` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unusedClassMembers": {
+          "description": "Baseline count of `unused-class-members` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unresolvedImports": {
+          "description": "Baseline count of `unresolved-imports` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "unlistedDependencies": {
+          "description": "Baseline count of `unlisted-dependencies` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "duplicateExports": {
+          "description": "Baseline count of `duplicate-exports` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "circularDependencies": {
+          "description": "Baseline count of `circular-dependencies` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "reExportCycles": {
+          "description": "Baseline count of `re-export-cycle` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "typeOnlyDependencies": {
+          "description": "Baseline count of `type-only-dependencies` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "testOnlyDependencies": {
+          "description": "Baseline count of `test-only-dependencies` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "devDependenciesInProduction": {
+          "description": "Baseline count of `dev-dependencies-in-production` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "boundaryViolations": {
+          "description": "Baseline count of `boundary-violation` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "boundaryCoverageViolations": {
+          "description": "Baseline count of boundary-coverage-violation findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "boundaryCallViolations": {
+          "description": "Baseline count of boundary-call-violation findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
           "default": 0
         },
         "policyViolations": {
+          "description": "Baseline count of `policy-violation` findings.",
           "type": "integer",
           "format": "uint",
           "minimum": 0,
@@ -2656,6 +2803,7 @@
       ]
     },
     "AuditConfig": {
+      "description": "The `audit` config section: in-repo defaults for `fallow audit`, each\noverridable by its matching CLI flag.",
       "type": "object",
       "properties": {
         "gate": {
@@ -2698,7 +2846,7 @@
           ]
         },
         "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.",
+          "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. Each sweep also reclaims abandoned entries minted under other repo identities (deleted or moved repos, other git worktrees) once they age past this repo's threshold; entries whose recorded owner root still exists are skipped and stay governed by that repo's own setting. The `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` environment variable overrides this field.",
           "type": [
             "integer",
             "null"
@@ -2716,13 +2864,22 @@
       }
     },
     "AuditGate": {
-      "type": "string",
-      "enum": [
-        "new-only",
-        "all"
+      "description": "Value of `audit.gate`: which findings drive the `fallow audit` verdict.",
+      "oneOf": [
+        {
+          "description": "Fail only on findings the current changeset introduced, determined by\na base-snapshot attribution pass. The default.",
+          "type": "string",
+          "const": "new-only"
+        },
+        {
+          "description": "Fail on every finding in changed files, skipping the attribution pass.",
+          "type": "string",
+          "const": "all"
+        }
       ]
     },
     "CacheConfig": {
+      "description": "The `cache` config section: location and size ceiling of fallow's\npersistent caches (default directory `<root>/.fallow`).",
       "type": "object",
       "properties": {
         "dir": {