fallow 3.14.0 → 3.16.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,
@@ -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"
@@ -562,9 +569,11 @@
           "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.",
+          "description": "Manifest-level gate: a map of field path to an equality expectation or\nan explicit `exists` predicate. Paths use dotted object keys and may\ntraverse arrays with `[*]`. ALL entries must match; a wildcard equality\nmatches when any yielded value equals the expectation. An empty map\nmatches every manifest.",
           "type": "object",
-          "additionalProperties": true,
+          "additionalProperties": {
+            "$ref": "#/$defs/ManifestCondition"
+          },
           "default": {}
         },
         "entries": {
@@ -595,18 +604,46 @@
         }
       ]
     },
+    "ManifestCondition": {
+      "description": "A typed condition used by a manifest entry gate.\n\nPlain JSON values retain strict equality semantics. The reserved\n`{ \"exists\": bool }` object tests field presence without truthiness.",
+      "anyOf": [
+        {
+          "description": "Require the field path to resolve (`true`) or not resolve (`false`).",
+          "$ref": "#/$defs/ManifestExistsPredicate"
+        },
+        {
+          "description": "Require at least one yielded value to equal this JSON value exactly."
+        }
+      ]
+    },
+    "ManifestExistsPredicate": {
+      "description": "The explicit field-presence predicate accepted by [`ManifestCondition`].",
+      "type": "object",
+      "properties": {
+        "exists": {
+          "description": "Whether the field path must resolve to at least one value.",
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "exists"
+      ]
+    },
     "ManifestSeedRule": {
       "description": "A single entry seeded by a [`ManifestEntryRule`], resolved relative to the\nmanifest's directory.",
       "type": "object",
       "properties": {
         "path": {
-          "description": "Entry glob relative to the manifest directory. May contain\n`${dotted.field}` interpolation that fans out over string / array\nmanifest field values (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.",
+          "description": "Entry glob relative to the manifest directory. May contain\n`${dotted.field}` interpolation that fans out over string / array\nmanifest field values; `[*]` traverses object arrays. A missing or empty\nfield seeds nothing. The glob must encode its own extension, such as\n`public/index.{ts,tsx}`. Glob entry patterns are matched literally\nagainst discovered files without\nsource-extension probing.",
           "type": "string"
         },
         "when": {
-          "description": "Per-entry gate (strict equality), evaluated against the same manifest.\nAn empty map always passes.",
+          "description": "Per-entry gate, using the same strict equality and `[*]` traversal as the\nmanifest-level gate. An empty map always passes.",
           "type": "object",
-          "additionalProperties": true,
+          "additionalProperties": {
+            "$ref": "#/$defs/ManifestCondition"
+          },
           "default": {}
         }
       },
@@ -709,6 +746,7 @@
           }
         }
       },
+      "additionalProperties": false,
       "required": [
         "file",
         "exports"
@@ -764,16 +802,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 +844,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 +884,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",
@@ -951,7 +1007,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. Governs\nfindings only, never the health score.",
+          "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph. Governs\nfindings and the threshold-relative file-score signals\n(`crap_above_threshold`, the `risk` triage tag, and the\n`add_test_coverage` refactoring target); measured values such as\n`crap_max` and the overall health score never move with it. Set to\n`0` to disable CRAP enforcement entirely: no findings, nothing counts\nabove threshold, and file-score rows disclose baseline breaches as\nexempt instead.",
           "type": "number",
           "format": "double",
           "default": 30.0
@@ -1187,38 +1243,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 +1378,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 +1443,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 +1840,7 @@
       "additionalProperties": false
     },
     "FixConfig": {
+      "description": "The `fix` config section: settings for `fallow fix` apply behavior.",
       "type": "object",
       "properties": {
         "catalog": {
@@ -1770,6 +1853,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 +1864,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 +1897,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 +1948,7 @@
           "default": {}
         }
       },
+      "additionalProperties": false,
       "required": [
         "files"
       ]
@@ -1857,6 +1958,7 @@
       "type": "object",
       "properties": {
         "unused-files": {
+          "description": "Optional override for [`RulesConfig::unused_files`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1867,6 +1969,7 @@
           ]
         },
         "unused-exports": {
+          "description": "Optional override for [`RulesConfig::unused_exports`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1877,6 +1980,7 @@
           ]
         },
         "unused-types": {
+          "description": "Optional override for [`RulesConfig::unused_types`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1887,6 +1991,7 @@
           ]
         },
         "private-type-leaks": {
+          "description": "Optional override for [`RulesConfig::private_type_leaks`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1897,6 +2002,7 @@
           ]
         },
         "unused-dependencies": {
+          "description": "Optional override for [`RulesConfig::unused_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1907,6 +2013,7 @@
           ]
         },
         "unused-dev-dependencies": {
+          "description": "Optional override for [`RulesConfig::unused_dev_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1917,6 +2024,7 @@
           ]
         },
         "unused-optional-dependencies": {
+          "description": "Optional override for [`RulesConfig::unused_optional_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1927,6 +2035,7 @@
           ]
         },
         "unused-enum-members": {
+          "description": "Optional override for [`RulesConfig::unused_enum_members`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1937,6 +2046,7 @@
           ]
         },
         "unused-class-members": {
+          "description": "Optional override for [`RulesConfig::unused_class_members`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1947,6 +2057,7 @@
           ]
         },
         "unused-store-members": {
+          "description": "Optional override for [`RulesConfig::unused_store_members`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1957,6 +2068,7 @@
           ]
         },
         "unprovided-injects": {
+          "description": "Optional override for [`RulesConfig::unprovided_injects`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1967,6 +2079,7 @@
           ]
         },
         "unrendered-components": {
+          "description": "Optional override for [`RulesConfig::unrendered_components`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1977,6 +2090,7 @@
           ]
         },
         "unused-component-props": {
+          "description": "Optional override for [`RulesConfig::unused_component_props`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1987,6 +2101,7 @@
           ]
         },
         "unused-component-emits": {
+          "description": "Optional override for [`RulesConfig::unused_component_emits`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -1997,6 +2112,7 @@
           ]
         },
         "unused-component-inputs": {
+          "description": "Optional override for [`RulesConfig::unused_component_inputs`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2007,6 +2123,7 @@
           ]
         },
         "unused-component-outputs": {
+          "description": "Optional override for [`RulesConfig::unused_component_outputs`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2017,6 +2134,7 @@
           ]
         },
         "unused-svelte-events": {
+          "description": "Optional override for [`RulesConfig::unused_svelte_events`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2027,6 +2145,7 @@
           ]
         },
         "unused-server-actions": {
+          "description": "Optional override for [`RulesConfig::unused_server_actions`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2037,6 +2156,7 @@
           ]
         },
         "unused-load-data-keys": {
+          "description": "Optional override for [`RulesConfig::unused_load_data_keys`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2047,6 +2167,7 @@
           ]
         },
         "prop-drilling": {
+          "description": "Optional override for [`RulesConfig::prop_drilling`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2057,6 +2178,7 @@
           ]
         },
         "thin-wrapper": {
+          "description": "Optional override for [`RulesConfig::thin_wrapper`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2067,6 +2189,7 @@
           ]
         },
         "duplicate-prop-shape": {
+          "description": "Optional override for [`RulesConfig::duplicate_prop_shape`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2077,6 +2200,7 @@
           ]
         },
         "css-token-drift": {
+          "description": "Optional override for [`RulesConfig::css_token_drift`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2087,6 +2211,7 @@
           ]
         },
         "css-duplicate-block": {
+          "description": "Optional override for [`RulesConfig::css_duplicate_block`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2097,6 +2222,7 @@
           ]
         },
         "css-selector-complexity": {
+          "description": "Optional override for [`RulesConfig::css_selector_complexity`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2107,6 +2233,7 @@
           ]
         },
         "css-dead-surface": {
+          "description": "Optional override for [`RulesConfig::css_dead_surface`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2117,6 +2244,7 @@
           ]
         },
         "css-broken-reference": {
+          "description": "Optional override for [`RulesConfig::css_broken_reference`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2127,6 +2255,7 @@
           ]
         },
         "unresolved-imports": {
+          "description": "Optional override for [`RulesConfig::unresolved_imports`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2137,6 +2266,7 @@
           ]
         },
         "unlisted-dependencies": {
+          "description": "Optional override for [`RulesConfig::unlisted_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2147,6 +2277,7 @@
           ]
         },
         "duplicate-exports": {
+          "description": "Optional override for [`RulesConfig::duplicate_exports`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2157,6 +2288,7 @@
           ]
         },
         "type-only-dependencies": {
+          "description": "Optional override for [`RulesConfig::type_only_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2167,6 +2299,7 @@
           ]
         },
         "test-only-dependencies": {
+          "description": "Optional override for [`RulesConfig::test_only_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2177,6 +2310,7 @@
           ]
         },
         "dev-dependencies-in-production": {
+          "description": "Optional override for [`RulesConfig::dev_dependencies_in_production`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2187,6 +2321,7 @@
           ]
         },
         "circular-dependencies": {
+          "description": "Optional override for [`RulesConfig::circular_dependencies`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2197,6 +2332,7 @@
           ]
         },
         "re-export-cycle": {
+          "description": "Optional override for [`RulesConfig::re_export_cycle`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2207,6 +2343,7 @@
           ]
         },
         "boundary-violation": {
+          "description": "Optional override for [`RulesConfig::boundary_violation`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2217,6 +2354,7 @@
           ]
         },
         "coverage-gaps": {
+          "description": "Optional override for [`RulesConfig::coverage_gaps`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2227,6 +2365,7 @@
           ]
         },
         "feature-flags": {
+          "description": "Optional override for [`RulesConfig::feature_flags`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2237,6 +2376,7 @@
           ]
         },
         "stale-suppressions": {
+          "description": "Optional override for [`RulesConfig::stale_suppressions`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2247,6 +2387,7 @@
           ]
         },
         "require-suppression-reason": {
+          "description": "Optional override for [`RulesConfig::require_suppression_reason`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2257,6 +2398,7 @@
           ]
         },
         "unused-catalog-entries": {
+          "description": "Optional override for [`RulesConfig::unused_catalog_entries`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2267,6 +2409,7 @@
           ]
         },
         "empty-catalog-groups": {
+          "description": "Optional override for [`RulesConfig::empty_catalog_groups`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2277,6 +2420,7 @@
           ]
         },
         "unresolved-catalog-references": {
+          "description": "Optional override for [`RulesConfig::unresolved_catalog_references`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2287,6 +2431,7 @@
           ]
         },
         "unused-dependency-overrides": {
+          "description": "Optional override for [`RulesConfig::unused_dependency_overrides`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2297,6 +2442,7 @@
           ]
         },
         "misconfigured-dependency-overrides": {
+          "description": "Optional override for [`RulesConfig::misconfigured_dependency_overrides`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2307,6 +2453,7 @@
           ]
         },
         "security-client-server-leak": {
+          "description": "Optional override for [`RulesConfig::security_client_server_leak`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2317,6 +2464,7 @@
           ]
         },
         "security-sink": {
+          "description": "Optional override for [`RulesConfig::security_sink`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2327,6 +2475,7 @@
           ]
         },
         "policy-violation": {
+          "description": "Optional override for [`RulesConfig::policy_violation`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2337,6 +2486,7 @@
           ]
         },
         "invalid-client-export": {
+          "description": "Optional override for [`RulesConfig::invalid_client_export`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2347,6 +2497,7 @@
           ]
         },
         "mixed-client-server-barrel": {
+          "description": "Optional override for [`RulesConfig::mixed_client_server_barrel`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2357,6 +2508,7 @@
           ]
         },
         "misplaced-directive": {
+          "description": "Optional override for [`RulesConfig::misplaced_directive`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2367,6 +2519,7 @@
           ]
         },
         "route-collision": {
+          "description": "Optional override for [`RulesConfig::route_collision`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2377,6 +2530,7 @@
           ]
         },
         "dynamic-segment-name-conflict": {
+          "description": "Optional override for [`RulesConfig::dynamic_segment_name_conflict`].",
           "anyOf": [
             {
               "$ref": "#/$defs/Severity"
@@ -2389,6 +2543,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 +2560,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 +2576,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 +2833,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 +2876,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 +2894,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": {