fallow 3.2.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Codebase intelligence for TypeScript and JavaScript. Free static analysis of code and styles, optional paid runtime intelligence (Fallow Runtime). Quality, risk, architecture, dependencies, duplication, and design-system drift for humans, CI, and the agents writing your code. Zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -87,13 +87,13 @@
     "@tanstack/intent": "0.3.2"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.2.0",
-    "@fallow-cli/darwin-x64": "3.2.0",
-    "@fallow-cli/linux-x64-gnu": "3.2.0",
-    "@fallow-cli/linux-arm64-gnu": "3.2.0",
-    "@fallow-cli/linux-x64-musl": "3.2.0",
-    "@fallow-cli/linux-arm64-musl": "3.2.0",
-    "@fallow-cli/win32-arm64-msvc": "3.2.0",
-    "@fallow-cli/win32-x64-msvc": "3.2.0"
+    "@fallow-cli/darwin-arm64": "3.3.0",
+    "@fallow-cli/darwin-x64": "3.3.0",
+    "@fallow-cli/linux-x64-gnu": "3.3.0",
+    "@fallow-cli/linux-arm64-gnu": "3.3.0",
+    "@fallow-cli/linux-x64-musl": "3.3.0",
+    "@fallow-cli/linux-arm64-musl": "3.3.0",
+    "@fallow-cli/win32-arm64-msvc": "3.3.0",
+    "@fallow-cli/win32-x64-msvc": "3.3.0"
   }
 }

package/schema.json

@@ -4,6 +4,7 @@
   "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 `https://fallow.dev/schema.json` to get editor IntelliSense; any other value is ignored by fallow.",
       "type": [
         "string",
         "null"
@@ -11,6 +12,7 @@
       "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"
@@ -18,6 +20,7 @@
       "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"
@@ -25,6 +28,7 @@
       "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"
@@ -32,6 +36,7 @@
       "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"
@@ -39,6 +44,7 @@
       "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"
@@ -50,6 +56,7 @@
       "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"
@@ -57,6 +64,7 @@
       "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"
@@ -64,6 +72,7 @@
       "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"
@@ -71,28 +80,33 @@
       "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"
@@ -100,6 +114,7 @@
       "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,
@@ -119,6 +134,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).",
       "$ref": "#/$defs/HealthConfig",
       "default": {
         "maxCyclomatic": 20,
@@ -144,6 +160,7 @@
       }
     },
     "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",
@@ -202,9 +219,11 @@
       }
     },
     "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": [],
@@ -212,16 +231,19 @@
       }
     },
     "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": {
@@ -230,14 +252,17 @@
       }
     },
     "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"
@@ -252,6 +277,7 @@
       }
     },
     "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"
@@ -259,6 +285,7 @@
       "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"
@@ -266,12 +293,14 @@
       "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"
@@ -279,6 +308,7 @@
       "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"
@@ -289,21 +319,26 @@
       ]
     },
     "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"
     }
   },
@@ -350,6 +385,14 @@
           "$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",
@@ -494,6 +537,72 @@
         }
       ]
     },
+    "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",
@@ -564,7 +673,7 @@
       "type": "object",
       "properties": {
         "patterns": {
-          "description": "Additional workspace patterns (beyond what's in root package.json).",
+          "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"
@@ -599,15 +708,18 @@
       "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"
@@ -624,9 +736,11 @@
       "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"
@@ -652,10 +766,12 @@
       "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
         }
@@ -1596,6 +1712,7 @@
       "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"
@@ -1607,6 +1724,7 @@
       "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"
         }
@@ -1647,14 +1765,17 @@
       "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
         }
@@ -1666,12 +1787,14 @@
       "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": {}
         }
@@ -2220,6 +2343,7 @@
       "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"
@@ -2366,39 +2490,46 @@
       "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"

package/scripts/platform-package.js

@@ -13,7 +13,7 @@ function getPlatformPackage(platform, arch, libcFamily) {
   }
 
   if (platform === "linux") {
-    const libc = libcFamily === "musl" ? "musl" : "gnu";
+    const libc = libcFamily === "glibc" ? "gnu" : "musl";
     if (arch === "x64" || arch === "arm64") {
       return `@fallow-cli/linux-${arch}-${libc}`;
     }

package/scripts/platform-package.test.js

@@ -9,9 +9,9 @@ test("maps Windows x64 and arm64 to MSVC packages", () => {
 });
 
 test("maps Linux packages with libc awareness", () => {
-  assert.equal(getPlatformPackage("linux", "x64", "gnu"), "@fallow-cli/linux-x64-gnu");
-  assert.equal(getPlatformPackage("linux", "arm64", "musl"), "@fallow-cli/linux-arm64-musl");
-  assert.equal(getPlatformPackage("linux", "arm64"), "@fallow-cli/linux-arm64-gnu");
+  assert.equal(getPlatformPackage("linux", "x64", "glibc"), "@fallow-cli/linux-x64-gnu");
+  assert.equal(getPlatformPackage("linux", "x64", "musl"), "@fallow-cli/linux-x64-musl");
+  assert.equal(getPlatformPackage("linux", "x64", null), "@fallow-cli/linux-x64-musl");
 });
 
 test("maps macOS packages by architecture", () => {

package/scripts/run-binary.js

@@ -11,6 +11,7 @@
 const { execFileSync } = require("node:child_process");
 const path = require("node:path");
 const fs = require("node:fs");
+const os = require("node:os");
 
 const { getPlatformPackage } = require("./platform-package");
 const { ensureVerified } = require("./lazy-verify");
@@ -107,6 +108,15 @@ function writeVerifiedLineIfVersionQuery(verifyResult, version) {
   }
 }
 
+// Exit code for a child failure caught from execFileSync. A signal death has
+// status === null; map it to the shell convention 128 + signal number so CI
+// gates see a crash, never a success.
+function exitCodeForChildFailure(e) {
+  if (e.status !== null) return e.status;
+  const signalNumber = os.constants.signals[e.signal];
+  return signalNumber ? 128 + signalNumber : 1;
+}
+
 // Read the resolved CLI version from the platform package manifest (its version
 // is released in lockstep with the CLI). Best-effort: never throws, so a
 // missing/garbled manifest just omits the signing annotation on --version.
@@ -159,10 +169,13 @@ function runBinary(binaryBaseName) {
     execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
   } catch (e) {
     if (e.status === undefined) throw e;
+    if (e.status === null) {
+      process.stderr.write(`fallow binary terminated by signal ${e.signal ?? "unknown"}\n`);
+    }
     // Child has already written its --version line via inherited stdio;
     // append the verified line here only on a clean exit.
     if (e.status === 0) writeVerifiedLineIfVersionQuery(verifyResult, resolvedVersion);
-    process.exit(e.status);
+    process.exit(exitCodeForChildFailure(e));
   }
 
   writeVerifiedLineIfVersionQuery(verifyResult, resolvedVersion);
@@ -173,4 +186,5 @@ module.exports = {
   describeVerified, // test-only
   isVersionQuery, // test-only
   guardBrokenStdout, // test-only
+  exitCodeForChildFailure, // test-only
 };

package/scripts/run-binary.test.js

@@ -1,5 +1,6 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
+const os = require("node:os");
 const { spawnSync } = require("node:child_process");
 const path = require("node:path");
 
@@ -74,3 +75,19 @@ test("describeVerified annotates the resolved version's signing status", () => {
   assert.equal(describeVerified(ok, undefined), "verified: yes (sentinel /c/s)");
   assert.equal(describeVerified(ok, ""), "verified: yes (sentinel /c/s)");
 });
+
+test("exitCodeForChildFailure preserves status codes and maps signal deaths", () => {
+  const { exitCodeForChildFailure } = require(RUN_BINARY);
+  assert.equal(exitCodeForChildFailure({ status: 3 }), 3);
+  assert.equal(exitCodeForChildFailure({ status: 0 }), 0);
+  assert.equal(
+    exitCodeForChildFailure({ status: null, signal: "SIGSEGV" }),
+    128 + os.constants.signals.SIGSEGV,
+  );
+  assert.equal(
+    exitCodeForChildFailure({ status: null, signal: "SIGKILL" }),
+    128 + os.constants.signals.SIGKILL,
+  );
+  assert.equal(exitCodeForChildFailure({ status: null, signal: undefined }), 1);
+  assert.equal(exitCodeForChildFailure({ status: null, signal: "NOT_A_SIGNAL" }), 1);
+});