fallow 3.35.0 → 3.36.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.35.0",
+  "version": "3.36.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -301,7 +301,7 @@
       "name": "--fail-on-issues",
       "type": "bool",
       "required": false,
-      "description": "Exit with code 1 if issues are found",
+      "description": "Exit 1 on issues, also where the default is 0: bare json, sarif, codeclimate and dupes",
       "possible_values": [
         "true",
         "false"
@@ -7034,6 +7034,7 @@
     "FALLOW_MAX_FILE_SIZE": "Per-file size ceiling in megabytes for source discovery (default 5; 0 = no limit). CLI --max-file-size flag overrides this.",
     "FALLOW_TYPE_AWARE": "Enable or disable TypeScript semantic (type-aware) analysis for the run (true/false/1/0/yes/no/on/off). Precedence: --type-aware/--no-type-aware CLI flags, then FALLOW_TYPE_AWARE, then the audit.typeAware config field, then typeAware.enabled.",
     "FALLOW_TYPE_AWARE_TIMEOUT_SECS": "Wall clock in seconds allowed for one TypeScript semantic sidecar request (default 120; unset, 0, or a non-numeric value keeps the default). Raise it for very large TypeScript programs, where a semantic query scans the whole program.",
+    "FALLOW_TYPE_AWARE_BACKEND": "Experimental. Type-checker backend for the TypeScript semantic sidecar: typescript-go (default) or tsrs. The tsrs backend needs the exact pinned tsrs npm package where fallow-type-aware can resolve it. An unknown value makes the type-aware pass unavailable.",
     "FALLOW_TYPE_AWARE_BIN": "Trusted executable override for the TypeScript semantic refinement sidecar used by dead-code --type-aware. Relative paths resolve from the caller's working directory before --root is applied; project node_modules and PATH are intentionally not searched. Default: sibling of the active Fallow executable.",
     "FALLOW_AUDIT_BASE": "Pins the fallow audit comparison base ref when no --base/--changed-since is passed (e.g. upstream/main).",
     "FALLOW_AUDIT_CACHE_MAX_AGE_DAYS": "GC threshold in days for reusable audit base-snapshot caches (default 30; 0 disables the sweep).",
@@ -8280,7 +8281,7 @@
     ]
   },
   "plugins": {
-    "count": 148,
+    "count": 149,
     "note": "Built-in framework plugins, auto-activated when their enabler dependency is present; run fallow list --plugins for the set active in a specific project",
     "names": [
       "nextjs",
@@ -8421,6 +8422,7 @@
       "nodemon",
       "pm2",
       "dependency-cruiser",
+      "dotenv",
       "wuchale",
       "varlock",
       "pnpm",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.35.0",
+  "version": "3.36.0",
   "mcpName": "io.github.fallow-rs/fallow",
   "description": "Codebase intelligence for TypeScript and JavaScript: health, complexity, duplication, architecture, styling drift, and unused code from one graph. CLI, LSP, and MCP server. Zero config for over 100 frameworks.",
   "license": "MIT",
@@ -89,14 +89,14 @@
     "@tanstack/intent": "0.5.5"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.35.0",
-    "@fallow-cli/darwin-x64": "3.35.0",
-    "@fallow-cli/linux-x64-gnu": "3.35.0",
-    "@fallow-cli/linux-arm64-gnu": "3.35.0",
-    "@fallow-cli/linux-x64-musl": "3.35.0",
-    "@fallow-cli/linux-arm64-musl": "3.35.0",
-    "@fallow-cli/win32-arm64-msvc": "3.35.0",
-    "@fallow-cli/win32-x64-msvc": "3.35.0",
-    "fallow-type-aware": "3.35.0"
+    "@fallow-cli/darwin-arm64": "3.36.0",
+    "@fallow-cli/darwin-x64": "3.36.0",
+    "@fallow-cli/linux-x64-gnu": "3.36.0",
+    "@fallow-cli/linux-arm64-gnu": "3.36.0",
+    "@fallow-cli/linux-x64-musl": "3.36.0",
+    "@fallow-cli/linux-arm64-musl": "3.36.0",
+    "@fallow-cli/win32-arm64-msvc": "3.36.0",
+    "@fallow-cli/win32-x64-msvc": "3.36.0",
+    "fallow-type-aware": "3.36.0"
   }
 }

package/schema.json

@@ -416,7 +416,7 @@
       "default": false
     },
     "failOnParseError": {
-      "description": "When true, the run fails with exit code 1 if fallow could not parse a source file cleanly (a `source-parse-degraded` entry in `workspace_diagnostics[]`), and the `parse-error` entry of `gate_outcomes` names each such file. Boolean, defaults to false, so a file the parser rejects only warns. Applies to `fallow dead-code`, `fallow health`, `fallow audit` and the bare `fallow` run; the CLI flag `--fail-on-parse-error` arms the same gate for one run. Older fallow versions reject this key as unknown, so pair it with `minimumVersion` set to the release that added it.",
+      "description": "When true, the run fails with exit code 1 if fallow could not parse a source file cleanly (a `source-parse-degraded` or `source-nesting-too-deep` entry in `workspace_diagnostics[]`), and the `parse-error` entry of `gate_outcomes` names each such file. Boolean, defaults to false, so a file the parser rejects only warns. Applies to `fallow dead-code`, `fallow health`, `fallow audit` and the bare `fallow` run; the CLI flag `--fail-on-parse-error` arms the same gate for one run. Older fallow versions reject this key as unknown, so pair it with `minimumVersion` set to the release that added it.",
       "type": "boolean",
       "default": false
     },
@@ -538,13 +538,13 @@
           "description": "Plugin detected if this package is in dependencies.",
           "type": "object",
           "properties": {
-            "package": {
-              "description": "Exact package name looked up in the project's declared dependencies.",
-              "type": "string"
-            },
             "type": {
               "type": "string",
               "const": "dependency"
+            },
+            "package": {
+              "description": "Exact package name looked up in the project's declared dependencies.",
+              "type": "string"
             }
           },
           "required": [
@@ -556,13 +556,13 @@
           "description": "Plugin detected if this file pattern matches.",
           "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).\nA single `*` stays within one path segment; use `**` to match across directories.",
-              "type": "string"
-            },
             "type": {
               "type": "string",
               "const": "fileExists"
+            },
+            "pattern": {
+              "description": "Project-root-relative glob; the plugin activates when any\ndiscovered file matches it. Validated at load like other user\nglobs (no absolute paths or `..` segments).\nA single `*` stays within one path segment; use `**` to match across directories.",
+              "type": "string"
             }
           },
           "required": [
@@ -574,16 +574,16 @@
           "description": "All conditions must be true.",
           "type": "object",
           "properties": {
+            "type": {
+              "type": "string",
+              "const": "all"
+            },
             "conditions": {
               "description": "Sub-conditions combined with logical AND.",
               "type": "array",
               "items": {
                 "$ref": "#/$defs/PluginDetection"
               }
-            },
-            "type": {
-              "type": "string",
-              "const": "all"
             }
           },
           "required": [
@@ -595,16 +595,16 @@
           "description": "Any condition must be true.",
           "type": "object",
           "properties": {
+            "type": {
+              "type": "string",
+              "const": "any"
+            },
             "conditions": {
               "description": "Sub-conditions combined with logical OR.",
               "type": "array",
               "items": {
                 "$ref": "#/$defs/PluginDetection"
               }
-            },
-            "type": {
-              "type": "string",
-              "const": "any"
             }
           },
           "required": [
@@ -1269,6 +1269,10 @@
           "maximum": 65535,
           "default": 20
         },
+        "cyclomaticPolicy": {
+          "description": "How the cyclomatic gate counts complexity (default: `standard`).\n`literal-membership` counts a chain of strict equality checks of one\nidentifier against primitive literals (`kind === \"a\" || kind === \"b\"`)\nas one predicate. The policy applies to the `maxCyclomatic` gate and\nto every CRAP score, so the `maxCrap` gate reads the same value.\nFindings then report the standard value as `standard_cyclomatic`. The\nhealth score, complexity density, and hotspots keep the standard\ncount. Older fallow versions reject this key as unknown, so pair it\nwith `minimumVersion`.",
+          "$ref": "#/$defs/CyclomaticPolicy"
+        },
         "maxCognitive": {
           "description": "Maximum allowed cognitive complexity per function (default: 15).\nFunctions exceeding this threshold are reported. Governs findings\nonly, never the health score.",
           "type": "integer",
@@ -1362,6 +1366,21 @@
       },
       "additionalProperties": false
     },
+    "CyclomaticPolicy": {
+      "description": "How `fallow health` counts cyclomatic complexity for its gates.\n\nThe policy changes the cyclomatic value that the `maxCyclomatic` gate reads\nand the cyclomatic value in every CRAP score. It does not change the health\nscore, the complexity density, or the hotspot ranking: those keep the\nstandard count so that grades stay comparable across projects.",
+      "oneOf": [
+        {
+          "description": "Count every decision point, `&&`, `||`, and `??` operator (`McCabe`).",
+          "type": "string",
+          "const": "standard"
+        },
+        {
+          "description": "Count a literal membership chain as one predicate. A chain such as\n`kind === \"a\" || kind === \"b\" || kind === \"c\"` adds no cyclomatic\nincrements for its `||` operators. Only strict equality checks of one\nidentifier against string, number, bigint, boolean, or `null` literals\nqualify. Member access, calls, mixed operators, and different operands\nkeep the standard count.",
+          "type": "string",
+          "const": "literal-membership"
+        }
+      ]
+    },
     "HealthThresholdOverride": {
       "description": "Per-file or per-function health threshold override.",
       "type": "object",

package/skills/fallow/references/cli-reference.md

@@ -440,7 +440,7 @@ The `--entry-weight` JSON output carries `entry_weight.entries[]`, one row per r
 
 To gate eager growth in CI, save a baseline file on the main branch with `fallow list --entry-weight --save-regression-baseline <PATH>`. A later run with `--regression-baseline <PATH>` adds `entry_weight.regression`: per-entry `baseline_eager_bytes`, `current_eager_bytes`, `new_eager_packages` and `exceeded`. The comparison is report-only until you add `--fail-on-regression`; then an entry that grew more than `--tolerance` (bytes, or a percentage such as `5%`) exits 1. A new entry never fails the gate.
 
-The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (for example `undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `workspace-glob-outside-root`, `workspace-pattern-dir-missing`, `nested-project-root`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`, `malformed-pnpm-workspace-yaml`, `skipped-large-file`, `skipped-minified-file`, `skipped-source-dotdir`, `source-read-failure`, `npm-lock-override-resolution-skipped`) with a typed payload (`error`, `pattern`, or none), and a `path` that is project-root-relative with forward slashes on every envelope that carries the array. The same `workspace_diagnostics[]` array is also surfaced on the `fallow dead-code --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes, at the top level of the bare combined `fallow --format json` envelope, on `fallow audit --format json` under `dead_code`, and on the `audit-brief` envelope shared by `fallow review --format json` and `fallow audit --brief --format json`, also under `dead_code` (omitted when empty). The combined carrier is the envelope root, not a section, so `--skip check`, `--only health`, and `--only dupes` all still report what their analyses recorded. The combined root is the union of what every analysis in the run recorded, deduplicated on the whole `kind` (typed payload included) plus `path`, so two overlapping globs still report the same package-less directory once per `pattern` (a declared glob's no-op `./` prefix is normalised away, so one glob written `"./apps/**"` in `package.json` and `apps/**` in `pnpm-workspace.yaml` stays one entry): a combined run walks the project once per analysis, and a per-analysis `production` mode (`production: { deadCode, health, dupes }`, `--production-health`) can give those walks different file sets, so only the union reports what the run as a whole saw. Each analysis contributes the workspace-discovery list its own config load produced, the same list `fallow list --workspaces` reports, so the combined root can carry an `undeclared-workspace` or `glob-matched-no-package-json` entry that the standalone `dead-code`, `check`, `health`, and `dupes` envelopes, which read the process diagnostics registry instead, do not. `fallow audit --format json` and the `audit-brief` envelope are on the same broad side: they fold the dead-code analysis's own list into their `dead_code.workspace_diagnostics[]`, so they too report an `undeclared-workspace` entry the standalone envelopes miss. The CLI and the programmatic route (MCP code mode, NAPI, embedders) agree on everything an analysis records: both folds close with the same process-registry read, which covers what an analysis records after its section captured its list (a `source-read-failure`, or the analysis-stage kinds a health run's own dead-code precompute records) and skips `skipped-large-file`, `skipped-minified-file`, and `skipped-source-dotdir`, since those reach an envelope only from the walk that recorded them. The analysis-stage kinds (`malformed-pnpm-workspace-yaml`, `bun-lockb-override-resolution-skipped`, `bun-lock-override-resolution-skipped`, `pnpm-lock-override-resolution-skipped`, `npm-lock-override-resolution-skipped`, `bun-resolutions-shadowed-by-overrides`, `pnpm-workspace-overrides-ignored`, `boundaries-not-configured`, `rule-packs-not-configured`) are recorded by the dead-code analyze pass, so they only appear on runs that include it: `fallow dupes --format json` and `fallow --only dupes` report the workspace-discovery and source-discovery kinds alone. A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues. The dead-code result adds two more kinds, each with a `pattern` payload and `path: "."`: `ignore-dependencies-glob-unmatched` (an `ignoreDependencies` glob matched no declared dependency; omitted when the run reports no dependency finding, for example with `--unused-files` or `--file`) and `ignore-findings-pattern-unmatched` (an `ignoreFindings` pattern matched no finding). SARIF carries the same entries under `invocations[0].toolConfigurationNotifications[]` of the dead-code run. Markdown, `github-summary`, `pr-comment-github`, `pr-comment-gitlab` and the summary `body` of `review-github` and `review-gitlab` add an `Unmatched config patterns` section. Human, compact, CodeClimate and `github-annotations` print a stderr note. `fallow report --from` uses the same place as the live run of that format.
+The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (for example `undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `workspace-glob-outside-root`, `workspace-pattern-dir-missing`, `nested-project-root`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`, `malformed-pnpm-workspace-yaml`, `skipped-large-file`, `skipped-minified-file`, `skipped-source-dotdir`, `source-read-failure`, `npm-lock-override-resolution-skipped`) with a typed payload (`error`, `pattern`, or none), and a `path` that is project-root-relative with forward slashes on every envelope that carries the array. The same `workspace_diagnostics[]` array is also surfaced on the `fallow dead-code --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes, at the top level of the bare combined `fallow --format json` envelope, on `fallow audit --format json` under `dead_code`, and on the `audit-brief` envelope shared by `fallow review --format json` and `fallow audit --brief --format json`, also under `dead_code` (omitted when empty). The combined carrier is the envelope root, not a section, so `--skip check`, `--only health`, and `--only dupes` all still report what their analyses recorded. The combined root is the union of what every analysis in the run recorded, deduplicated on the whole `kind` (typed payload included) plus `path`, so two overlapping globs still report the same package-less directory once per `pattern` (a declared glob's no-op `./` prefix is normalised away, so one glob written `"./apps/**"` in `package.json` and `apps/**` in `pnpm-workspace.yaml` stays one entry): a combined run walks the project once per analysis, and a per-analysis `production` mode (`production: { deadCode, health, dupes }`, `--production-health`) can give those walks different file sets, so only the union reports what the run as a whole saw. Each analysis contributes the workspace-discovery list its own config load produced, the same list `fallow list --workspaces` reports, so the combined root can carry an `undeclared-workspace` or `glob-matched-no-package-json` entry that the standalone `dead-code`, `check`, `health`, and `dupes` envelopes, which read the process diagnostics registry instead, do not. `fallow audit --format json` and the `audit-brief` envelope are on the same broad side: they fold the dead-code analysis's own list into their `dead_code.workspace_diagnostics[]`, so they too report an `undeclared-workspace` entry the standalone envelopes miss. The CLI and the programmatic route (MCP code mode, NAPI, embedders) agree on everything an analysis records: both folds close with the same process-registry read, which covers what an analysis records after its section captured its list (a `source-read-failure`, or the analysis-stage kinds a health run's own dead-code precompute records) and skips `skipped-large-file`, `skipped-minified-file`, and `skipped-source-dotdir`, since those reach an envelope only from the walk that recorded them. The analysis-stage kinds (`malformed-pnpm-workspace-yaml`, `bun-lockb-override-resolution-skipped`, `bun-lock-override-resolution-skipped`, `pnpm-lock-override-resolution-skipped`, `npm-lock-override-resolution-skipped`, `bun-resolutions-shadowed-by-overrides`, `pnpm-workspace-overrides-ignored`, `boundaries-not-configured`, `rule-packs-not-configured`) are recorded by the dead-code analyze pass, so they only appear on runs that include it: `fallow dupes --format json` and `fallow --only dupes` report the workspace-discovery and source-discovery kinds alone. A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues. The dead-code result adds two more kinds, each with a `pattern` payload and `path: "."`: `ignore-dependencies-glob-unmatched` (an `ignoreDependencies` glob matched no declared dependency; omitted when the run reports no dependency finding, for example with `--unused-files` or `--file`) and `ignore-findings-pattern-unmatched` (an `ignoreFindings` pattern matched no finding). It also adds three kinds for an entry that matched but changed nothing, with the same payload: `entry-pattern-redundant` (every file the `entry` pattern matches is already a runtime entry point from another source), `ignore-dependencies-entry-redundant` (the `ignoreDependencies` entry hid no dependency finding; same gate as the unmatched glob) and `ignore-patterns-entry-redundant` (the `ignorePatterns` glob excluded no file that a built-in ignore, `.gitignore` or the file type filter does not already skip; a glob for build output has an effect only after a build). A `--production` run reports none of the three. SARIF carries the same entries under `invocations[0].toolConfigurationNotifications[]` of the dead-code run. Markdown, `github-summary`, `pr-comment-github`, `pr-comment-gitlab` and the summary `body` of `review-github` and `review-gitlab` add an `Unmatched config patterns` section, and a `Redundant config entries` section for the three redundant kinds. Human, compact, CodeClimate and `github-annotations` print a stderr note. `fallow report --from` uses the same place as the live run of that format.
 
 The `--boundaries` JSON output carries `boundaries.logical_groups[]` alongside the existing `zones[]` / `rules[]` arrays. Each logical-group entry surfaces a user-authored `autoDiscover` parent zone (which expansion otherwise flattens into per-child zones like `features/auth` / `features/billing`): `name`, `children`, `auto_discover` (verbatim user strings), `status` (`ok` / `empty` / `invalid_path`), `source_zone_index`, summed `file_count`, optional `authored_rule` (the pre-expansion `{ allow, allowTypeOnly }` keyed on the parent), optional `fallback_zone` cross-reference when the parent also kept its own `patterns` (Bulletproof case), optional `merged_from` (parent zone indices when the user declared the same parent name twice; surfaces the duplicate in JSON instead of only in `tracing::warn!`), optional `original_zone_root` (echo of the parent's `root` subtree scope for monorepo patchers), and optional `child_source_indices` (parallel to `children`, attributing each child to a specific `auto_discover` entry when multiple paths were authored). The full shape is documented in `docs/output-schema.json` under `ListBoundariesOutput`.
 
@@ -526,7 +526,7 @@ Human output groups paths under "Shared with your team (commit these)" and "Loca
 {
   "kind": "agent-install",
   "schema_version": 1,
-  "fallow_version": "3.35.0",
+  "fallow_version": "3.36.0",
   "root": "/abs/path",
   "mode": "install",
   "dry_run": false,
@@ -737,7 +737,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.35.0",
+  "version": "3.36.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -1148,7 +1148,7 @@ A complexity finding matches its base finding by file path and function name. Th
 
 Growth of a metric that the base finding already exceeded, in the same severity tier, makes the finding `worsened`, not introduced.
 
-An unchanged or decreased metric keeps the finding inherited, also when the exceeded category changes (for example from `both` to `cyclomatic`). When one file has more than one finding with the same function name, each base finding matches at most one head finding. Head findings with unchanged metric values and an unchanged line count match first. Head findings with unchanged metric values match next. The other findings then match in line order.
+An unchanged or decreased metric keeps the finding inherited, also when the exceeded category changes (for example from `both` to `cyclomatic`). When one file has more than one finding with the same function name, each base finding matches at most one head finding. Head findings with unchanged metric values and an unchanged line count match first. Head findings with unchanged metric values match next. Then head findings with unchanged cyclomatic and cognitive values match, also when the CRAP score changed, because a change of the coverage input changes the CRAP score. The other findings then match in line order.
 
 A matched finding that is not introduced is `worsened` when a measured value is higher than in the base finding. The measured values are cyclomatic, cognitive, CRAP (only when both sides have a score) and the line count of the function. The line count must grow by at least 5 lines. It includes comments and blank lines, so the minimum keeps a finding inherited after a short comment or a formatter rewrap. Each complexity finding carries `attribution` (`introduced`, `worsened` or `inherited`). When a value grew, it also carries `worsened_metrics` with the `metric`, the `base` value and the `head` value. An introduced finding that matched a base finding also carries `worsened_metrics`. `attribution.worsened` gives the active mode. `attribution.complexity_worsened` counts the worsened findings, which are also in `complexity_inherited`. `--worsened` (config `audit.worsened`) decides their effect on the verdict:
 
@@ -1212,7 +1212,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.35.0",
+  "version": "3.36.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -1300,7 +1300,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.35.0",
+  "version": "3.36.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1401,7 +1401,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.35.0",
+  "version": "3.36.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1430,7 +1430,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.35.0",
+  "version": "3.36.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -2245,7 +2245,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.35.0",
+  "version": "3.36.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2405,7 +2405,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.35.0",
+  "version": "3.36.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2449,11 +2449,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.35.0",
+  "version": "3.36.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.35.0",
+    "version": "3.36.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/skills/fallow/references/gotchas.md

@@ -179,7 +179,7 @@ Error-severity findings can trigger exit code 1. Default severity varies by rule
 }
 ```
 
-Exit code 1 always means that an enforced gate failed. A load warning or a workspace diagnostic (for example `node-modules-missing` or a tsconfig `extends` that does not resolve) never changes the exit code. The only exception is `source-parse-degraded` with `--fail-on-parse-error`. To find the gate, read `gate_outcomes` in the JSON output and look for an entry with `status: "fail"` and `enforced: true`. Under `--quiet` and in every machine format, fallow also prints one stderr line that names the failed gates, for example `[X] Exit code 1: gate health-findings (3 at or above error) failed.` On `health`, the `complexity-*` rules default to `error`, so each complexity finding fails the run. Set them to `warn` or pass `--report-only` to report without a failure.
+Exit code 1 always means that an enforced gate failed. A load warning or a workspace diagnostic (for example `node-modules-missing` or a tsconfig `extends` that does not resolve) never changes the exit code. The only exceptions are `source-parse-degraded` and `source-nesting-too-deep` with `--fail-on-parse-error`. To find the gate, read `gate_outcomes` in the JSON output and look for an entry with `status: "fail"` and `enforced: true`. Under `--quiet` and in every machine format, fallow also prints one stderr line that names the failed gates, for example `[X] Exit code 1: gate health-findings (3 at or above error) failed.` On `health`, the `complexity-*` rules default to `error`, so each complexity finding fails the run. Set them to `warn` or pass `--report-only` to report without a failure.
 
 ---
 

package/skills/fallow/references/patterns.md

@@ -784,11 +784,11 @@ Prefer `fallow hooks install --target agent` to install this file. The script is
 Behavior you can rely on:
 - The handler walks up from the session directory to the nearest directory that holds `.claude/hooks/fallow-gate.sh` and runs the audit there, so a session in a package directory audits the install root. The walk stops at the first `.git` entry. When it finds no script, the handler runs the script under `$CLAUDE_PROJECT_DIR` from the session directory.
 - The hook process can start in a directory that is not the session directory, for example in the main checkout when the session works in a nested git worktree. The script reads the session directory from the `cwd` field of the hook input and finds the audit root from it with the same walk. When the walk finds no script, for example with the user-scope script in `$HOME`, the audit root is the directory of the hook process when it is in the git work tree of the session. Else it is the git top level of the session directory, or the session directory outside a git repository. The audit root is never `$HOME`. The script compares physical paths, so a symlink does not change the walk. When the hook input has no usable `cwd`, the audit runs in the directory of the hook process.
-- A `git commit` or `git push` can name another work tree. The script audits only that target when the command has the strict form `[cd <dir> &&] git [-C <dir>]... commit|push [<option or name>]...` and git reports another work tree for the target (`git rev-parse --show-toplevel --absolute-git-dir` gives a different top level and a different git directory than for the session directory). For a push, the common git directory must differ too: linked worktrees share refs, so a push from another linked worktree of the session repository audits the session tree and the target. A target in the same work tree keeps the session audit, because `git commit` commits the whole index. Each word in the strict form must be inert: a `-C` directory resolves physically as in git, a `cd` directory starts with `/`, `./` or `../`, a double-quoted word holds no `$`, backquote or backslash, and only a short list of options such as `-m`, `--amend`, `-S` and `-u` is allowed. Any other command audits the session tree as before, plus each directory that it names in another work tree. The gate blocks when one audit fails.
+- A `git commit` or `git push` can name another work tree. The script audits only that target when the command has the strict form `[cd <dir> &&] git [-C <dir>]... commit|push [<option or name>]...` and git reports another work tree for the target (`git rev-parse --show-toplevel --absolute-git-dir` gives a different top level and a different git directory than for the session directory). For a push, the common git directory must differ too: linked worktrees share refs, so a push from another linked worktree of the session repository audits the session tree and the target. The one exception is a push that cannot send the session branch: the options are only `-u`, `-q`, `--set-upstream`, `--force-with-lease` and `--force-if-includes`, `git rev-parse --symbolic-full-name` gives the checked-out branch of the target for each refspec source, that branch is not the session branch, and a push without a refspec has `push.default` unset or `simple`, `current`, `upstream` or `nothing` and no remote `push` or `mirror` setting. That push audits only the target. A git error during this check keeps the session audit. A target in the same work tree keeps the session audit, because `git commit` commits the whole index. Each word in the strict form must be inert: a `-C` directory resolves physically as in git, a `cd` directory starts with `/`, `./` or `../`, a double-quoted word holds no `$`, backquote or backslash, and only a short list of options such as `-m`, `--amend`, `-S` and `-u` is allowed. Any other command audits the session tree as before, plus each directory that it names in another work tree. The gate blocks when one audit fails.
 - Runs only when the intercepted command is a `git commit` or `git push`, including invocations that pass git-level options before the subcommand (`git -c user.name=x commit`, `git --no-pager commit`, `git -C dir push`, `git --git-dir=/x push`); anything else exits 0. Set `FALLOW_GATE_DEBUG=1` to log skipped commands to stderr.
 - Resolves `fallow` from PATH first, then `npx --no-install fallow` as a fallback. Skips with a stderr notice if neither is available or if `jq` is missing.
 - Enforces a version floor via `FALLOW_GATE_MIN_VERSION`. The installed gate script holds the default floor (currently `2.85.0`). Fallow maintainers raise that default by hand; `fallow hooks install` does not set it to the installed version. Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
-- Runs `fallow audit --format json --quiet --explain --gate-marker agent` and, on verdict=`fail`, writes the full JSON envelope to stderr preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable. The gate marker lets local Impact record blocked-then-cleared agent gate events when Impact is enabled.
+- Runs `fallow audit --format json --quiet --explain --gate-marker agent`. On verdict=`fail`, it writes a short block message to stderr: the line `fallow-gate: blocked by fallow <version> at <binary>`, the verdict, one line for each finding that caused the block (`<kind> <path>:<line> <name>`, at most 50 lines), and the path of the full JSON report. Under the default `gate = "new-only"` the listed findings are the ones with `introduced: true`; under `gate = "all"` they are all findings that are not warnings. The full report goes to `.fallow/gate-report.json` in the audited tree, or to `FALLOW_GATE_REPORT` when set (a relative path resolves against the audited tree). Set `FALLOW_GATE_OUTPUT=json` to write the full JSON envelope to stderr instead, preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable. The gate marker lets local Impact record blocked-then-cleared agent gate events when Impact is enabled.
 - On runtime error (`{"error": true, ...}`) or unexpected non-zero exit, fails open with a one-line stderr notice; warn verdicts pass through silently.
 
 ### `.codex/hooks.json`

package/types/output-contract.d.ts

@@ -164,6 +164,10 @@ export type AuditWorsened = ("warn" | "error" | "off")
  * is decided here.
  */
 export type GateStatus = ("pass" | "warn" | "fail" | "skipped")
+/**
+ * Why a file counts for the `parse-error` gate, other than a parser error.
+ */
+export type GateFileReason = "nesting-too-deep"
 /**
  * Analysis mode stored with baselines, snapshots, audit sides, and impact data.
  */
@@ -411,6 +415,7 @@ export type PolicyViolationSeverity = ("error" | "warn")
  * The origin of a stale suppression: inline comment or JSDoc tag.
  */
 export type SuppressionOrigin = ({
+type: "comment"
 /**
  * The issue kind token from the comment (e.g., "unused-exports"), or None for blanket.
  */
@@ -432,8 +437,8 @@ is_file_level: boolean
  * adopted the field stay byte-compatible. See issue #449.
  */
 kind_known?: boolean
-type: "comment"
 } | {
+type: "jsdoc_tag"
 /**
  * The name of the export that was tagged.
  */
@@ -442,7 +447,6 @@ export_name: string
  * Human-authored reason after `--`, when present.
  */
 reason?: (string | null)
-type: "jsdoc_tag"
 })
 /**
  * Where an override entry was declared. Serialized as the filename label
@@ -564,66 +568,67 @@ degrades_analysis?: boolean
 export type WorkspaceDiagnostic1 = ({
 kind: "undeclared-workspace"
 } | {
+kind: "malformed-package-json"
 /**
  * `serde_json` parse error text.
  */
 error: string
-kind: "malformed-package-json"
 } | {
+kind: "glob-matched-no-package-json"
 /**
  * The glob pattern that matched the directory.
  */
 pattern: string
-kind: "glob-matched-no-package-json"
 } | {
+kind: "workspace-glob-outside-root"
 /**
  * The workspace entry, as written in the file.
  */
 pattern: string
-kind: "workspace-glob-outside-root"
 } | {
+kind: "workspace-pattern-dir-missing"
 /**
  * The workspace pattern, as written in the file.
  */
 pattern: string
-kind: "workspace-pattern-dir-missing"
 } | {
 kind: "nested-project-root"
 } | {
+kind: "malformed-tsconfig"
 /**
  * JSONC parse error text.
  */
 error: string
-kind: "malformed-tsconfig"
 } | {
 kind: "tsconfig-reference-dir-missing"
 } | {
+kind: "malformed-pnpm-workspace-yaml"
 /**
  * YAML parse error text.
  */
 error: string
-kind: "malformed-pnpm-workspace-yaml"
 } | {
+kind: "skipped-large-file"
 /**
  * On-disk size of the skipped file in bytes.
  */
 size_bytes: number
-kind: "skipped-large-file"
 } | {
+kind: "skipped-minified-file"
 /**
  * On-disk size of the skipped file in bytes.
  */
 size_bytes: number
-kind: "skipped-minified-file"
 } | {
 kind: "skipped-source-dotdir"
 } | {
+kind: "source-read-failure"
 /**
  * Filesystem or UTF-8 decoding error from `read_to_string`.
  */
 error: string
-kind: "source-read-failure"
 } | {
+kind: "source-parse-degraded"
 /**
  * Number of parser diagnostics reported for the file.
  */
@@ -633,7 +638,12 @@ error_count: number
  * the extracted module is a fragment at best.
  */
 panicked: boolean
-kind: "source-parse-degraded"
+} | {
+kind: "source-nesting-too-deep"
+/**
+ * The bracket nesting cap of the pre-parse scan.
+ */
+limit: number
 } | {
 kind: "bun-lockb-override-resolution-skipped"
 } | {
@@ -645,8 +655,8 @@ kind: "npm-lock-override-resolution-skipped"
 } | {
 kind: "bun-resolutions-shadowed-by-overrides"
 } | {
-cause: PnpmWorkspaceOverridesIgnoredCause
 kind: "pnpm-workspace-overrides-ignored"
+cause: PnpmWorkspaceOverridesIgnoredCause
 } | {
 kind: "node-modules-missing"
 } | {
@@ -654,6 +664,7 @@ kind: "boundaries-not-configured"
 } | {
 kind: "rule-packs-not-configured"
 } | {
+kind: "excluded-by-default-ignore"
 /**
  * The built-in glob that matched, verbatim (for example
  * `** /build/**`).
@@ -677,22 +688,22 @@ file_count: number
  * one matched location out of several.
  */
 directory_count: number
-kind: "excluded-by-default-ignore"
 } | {
+kind: "no-source-files-analyzed"
 /**
  * Candidate source files the built-in ignore patterns removed from
  * this walk, summed across every pattern. `0` when the walk found no
  * candidate to exclude in the first place.
  */
 excluded_file_count: number
-kind: "no-source-files-analyzed"
 } | {
+kind: "file-scores-unavailable"
 /**
  * Scoring error text.
  */
 error: string
-kind: "file-scores-unavailable"
 } | {
+kind: "hotspots-skipped"
 /**
  * Which input stopped it, as a kebab-case token: `not-a-repository`,
  * `no-commits`, `invalid-since` or `churn-file-unreadable`. The set is
@@ -706,25 +717,25 @@ kind: "file-scores-unavailable"
  * remedy for all four.
  */
 cause: string
-kind: "hotspots-skipped"
 } | {
+kind: "change-coupling-skipped"
 /**
  * Kebab-case token: `shallow-clone` (the fetched history is
  * incomplete) or `too-few-commits` (fewer analyzed commits than the
  * minimum revisions of one file). The set is open.
  */
 cause: string
-kind: "change-coupling-skipped"
 } | {
+kind: "shallow-clone"
 /**
  * `true` when the run also asked for ownership attribution, which a
  * shallow clone skews further by inflating single-author dominance.
  */
 ownership_requested: boolean
-kind: "shallow-clone"
 } | {
 kind: "unpinned-clock"
 } | {
+kind: "ownership-unavailable"
 /**
  * Which input failed, as a kebab-case token: `invalid-bot-pattern` or
  * `codeowners-parse-failed`. The set is open.
@@ -734,21 +745,21 @@ cause: string
  * Underlying error text.
  */
 error: string
-kind: "ownership-unavailable"
 } | {
+kind: "trend-snapshot-unreadable"
 /**
  * Filesystem or JSON error text.
  */
 error: string
-kind: "trend-snapshot-unreadable"
 } | {
+kind: "trend-group-baseline-unavailable"
 /**
  * Why the groups have no baseline, as a kebab-case token:
  * `snapshot-has-no-groups` or `grouped-by-mismatch`. The set is open.
  */
 cause: string
-kind: "trend-group-baseline-unavailable"
 } | {
+kind: "plugin-config-unreadable"
 /**
  * The plugin that read the config, as it labels itself:
  * `module-federation` for a standalone `module-federation.config.*`,
@@ -775,8 +786,8 @@ key: string
  * option the message points at.
  */
 reason: string
-kind: "plugin-config-unreadable"
 } | {
+kind: "plugin-effect-not-modeled"
 /**
  * The plugin that read the config, as it labels itself (`nuxt`).
  */
@@ -795,34 +806,51 @@ key: string
  * be classified at all. The set is open.
  */
 reason: string
-kind: "plugin-effect-not-modeled"
 } | {
 kind: "coverage-auto-detected"
 } | {
 kind: "flag-age-shallow-clone"
 } | {
+kind: "flag-age-unavailable"
 /**
  * Why no history is available, as a kebab-case token:
  * `not-a-repository` or `no-commits`. The set is open.
  */
 cause: string
-kind: "flag-age-unavailable"
 } | {
+kind: "ignore-dependencies-glob-unmatched"
 /**
  * The `ignoreDependencies` entry, as written in the config.
  */
 pattern: string
-kind: "ignore-dependencies-glob-unmatched"
 } | {
+kind: "ignore-findings-pattern-unmatched"
 /**
  * The `ignoreFindings` entry, as written in the config.
  */
 pattern: string
-kind: "ignore-findings-pattern-unmatched"
 } | {
+kind: "entry-pattern-redundant"
+/**
+ * The `entry` pattern, as written in the config.
+ */
+pattern: string
+} | {
+kind: "ignore-dependencies-entry-redundant"
+/**
+ * The `ignoreDependencies` entry, as written in the config.
+ */
+pattern: string
+} | {
+kind: "ignore-patterns-entry-redundant"
+/**
+ * The `ignorePatterns` glob, as written in the config.
+ */
+pattern: string
+} | {
+kind: "baseline-install-state-mismatch"
 baseline_node_modules: NodeModulesState
 run_node_modules: NodeModulesState
-kind: "baseline-install-state-mismatch"
 })
 /**
  * Why the declared pnpm version ignores the `overrides` section of
@@ -922,6 +950,15 @@ export type WorsenedMetricKind = ("cyclomatic" | "cognitive" | "crap" | "line_co
  * Audit-mode reason why a complexity finding does not gate the verdict.
  */
 export type AuditGateExemption = "test-file"
+/**
+ * How `fallow health` counts cyclomatic complexity for its gates.
+ *
+ * The policy changes the cyclomatic value that the `maxCyclomatic` gate reads
+ * and the cyclomatic value in every CRAP score. It does not change the health
+ * score, the complexity density, or the hotspot ranking: those keep the
+ * standard count so that grades stay comparable across projects.
+ */
+export type CyclomaticPolicy = ("standard" | "literal-membership")
 /**
  * Coverage model used for CRAP score computation.
  */
@@ -1189,12 +1226,13 @@ export type DiffRiskActionType = ("suppress-line" | "suppress-file" | "suppress-
  * `target` block of [`InspectOutput`], tagged by `type`.
  */
 export type InspectTargetDescriptor = ({
+type: "file"
 /**
  * File path relative to the analysed root.
  */
 file: string
-type: "file"
 } | {
+type: "symbol"
 /**
  * File path relative to the analysed root.
  */
@@ -1203,7 +1241,6 @@ file: string
  * Name of the inspected export.
  */
 export_name: string
-type: "symbol"
 })
 /**
  * `identity` block of [`InspectOutput`]; shape follows the target type.
@@ -2031,7 +2068,8 @@ files?: GateFile[]
  *
  * Today only `parse-error` emits it. The item carries the same facts as the
  * `source-parse-degraded` entry in `workspace_diagnostics[]` for that file,
- * so a consumer can act on the gate without a join.
+ * so a consumer can act on the gate without a join. With `reason` set, the
+ * count and the parser outcome are placeholders.
  */
 export interface GateFile {
 /**
@@ -2039,14 +2077,19 @@ export interface GateFile {
  */
 path: string
 /**
- * The number of parser errors for the file.
+ * The number of parser errors for the file. `1` when `reason` is set.
  */
 error_count: number
 /**
  * True when the parser stopped in the file instead of recovering, so the
- * analysis saw only the part before the error.
+ * analysis saw only the part before the error. `true` when `reason` is set.
  */
 panicked: boolean
+/**
+ * Why the file counts when it is not a parser error. Absent for a parser
+ * error, the only reason before this field existed.
+ */
+reason?: (GateFileReason | null)
 }
 /**
  * Metric and rule definitions emitted under `_meta` when `--explain` is
@@ -3431,7 +3474,7 @@ _meta?: (Meta | null)
  * - source discovery, during the file walk: `skipped-large-file`,
  *   `skipped-minified-file`, `skipped-source-dotdir`,
  *   `excluded-by-default-ignore`, `source-read-failure`,
- *   `source-parse-degraded`;
+ *   `source-parse-degraded`, `source-nesting-too-deep`;
  * - dead-code analysis, from the dependency-catalog and override
  *   detectors: `malformed-pnpm-workspace-yaml`,
  *   `bun-lockb-override-resolution-skipped`;
@@ -3450,10 +3493,11 @@ _meta?: (Meta | null)
  *
  * A diagnostic here is advisory and never withholds a finding. Where an
  * entry reports a source file this run never fully analyzed
- * (`source-parse-degraded`, `source-read-failure`, `skipped-large-file`,
- * `skipped-minified-file`, `skipped-source-dotdir`) it can distort a
- * verdict, so the affected `unused_files[]`, `unused_exports[]`, and
- * dependency entries additionally carry the caveat themselves in their own
+ * (`source-parse-degraded`, `source-nesting-too-deep`,
+ * `source-read-failure`, `skipped-large-file`, `skipped-minified-file`,
+ * `skipped-source-dotdir`) it can distort a verdict, so the affected
+ * `unused_files[]`, `unused_exports[]`, and dependency entries
+ * additionally carry the caveat themselves in their own
  * optional `reachability_caveats[]` array, and a reader who never scrolls
  * back up to this list still sees it. `fallow fix` reads the same array
  * and withholds the removal while a caveat stands.
@@ -7987,9 +8031,17 @@ line: number
  */
 col: number
 /**
- * Cyclomatic complexity of the function.
+ * Cyclomatic complexity of the function, as the cyclomatic gate and the
+ * CRAP score read it. Under the `literal-membership` value of
+ * `health.cyclomaticPolicy`, this is the value after literal membership
+ * chains count as one predicate.
  */
 cyclomatic: number
+/**
+ * Standard `McCabe` cyclomatic complexity, present only when the
+ * `health.cyclomaticPolicy` value gave `cyclomatic` a different value.
+ */
+standard_cyclomatic?: (number | null)
 /**
  * Cognitive complexity of the function.
  */
@@ -8305,6 +8357,15 @@ weight: number
  * consumer explain a cognitive `+3` as "+1 base, +2 nesting".
  */
 nesting: number
+/**
+ * This cyclomatic `||` increment is part of a literal membership chain:
+ * strict equality checks of one identifier against primitive literals
+ * (`kind === "a" || kind === "b"`). The `literal-membership` value of
+ * `health.cyclomaticPolicy` removes these increments from the effective
+ * cyclomatic value. Omitted when `false`, and always `false` under the
+ * default `standard` policy.
+ */
+literal_membership?: boolean
 }
 /**
  * Resolved thresholds used to evaluate a health finding.
@@ -8435,6 +8496,11 @@ functions_above_threshold: number
  * Global cyclomatic-complexity ceiling for this run.
  */
 max_cyclomatic_threshold: number
+/**
+ * Cyclomatic policy of the gates (`health.cyclomaticPolicy`). Absent
+ * under the default `standard` policy.
+ */
+cyclomatic_policy?: (CyclomaticPolicy | null)
 /**
  * Global cognitive-complexity ceiling for this run.
  */
@@ -16769,7 +16835,7 @@ _meta?: (Meta | null)
  * - source discovery, during the file walk: `skipped-large-file`,
  *   `skipped-minified-file`, `skipped-source-dotdir`,
  *   `excluded-by-default-ignore`, `source-read-failure`,
- *   `source-parse-degraded`;
+ *   `source-parse-degraded`, `source-nesting-too-deep`;
  * - dead-code analysis, from the dependency-catalog and override
  *   detectors: `malformed-pnpm-workspace-yaml`,
  *   `bun-lockb-override-resolution-skipped`;
@@ -16788,10 +16854,11 @@ _meta?: (Meta | null)
  *
  * A diagnostic here is advisory and never withholds a finding. Where an
  * entry reports a source file this run never fully analyzed
- * (`source-parse-degraded`, `source-read-failure`, `skipped-large-file`,
- * `skipped-minified-file`, `skipped-source-dotdir`) it can distort a
- * verdict, so the affected `unused_files[]`, `unused_exports[]`, and
- * dependency entries additionally carry the caveat themselves in their own
+ * (`source-parse-degraded`, `source-nesting-too-deep`,
+ * `source-read-failure`, `skipped-large-file`, `skipped-minified-file`,
+ * `skipped-source-dotdir`) it can distort a verdict, so the affected
+ * `unused_files[]`, `unused_exports[]`, and dependency entries
+ * additionally carry the caveat themselves in their own
  * optional `reachability_caveats[]` array, and a reader who never scrolls
  * back up to this list still sees it. `fallow fix` reads the same array
  * and withholds the removal while a caveat stands.
@@ -16829,10 +16896,12 @@ elapsed_ms: ElapsedMs
 /**
  * The verdict of every gate this run evaluated, keyed by name. The CLI
  * always emits it, with the default exit rule of each section that ran
- * (`error-severity-findings`, `health-findings`). Without
+ * (`error-severity-findings`, `health-findings`). A `coverage-gaps` rule
+ * at `error` adds `health-coverage-gaps`. Without
  * `--fail-on-issues` or `--ci`, the machine formats of the combined run
  * exit 0 for findings, so most entries have `enforced: false`. With one of
- * these flags, the findings rules and `duplication-threshold` are
+ * these flags, the findings rules, `health-coverage-gaps` and
+ * `duplication-threshold` are
  * `enforced`, the dupes section adds an enforced `duplication-findings`
  * entry, and every format exits 1 when one fails. For the default
  * exit rules (`error-severity-findings`,
@@ -16984,8 +17053,8 @@ total_flags: number
  * A flags run walks and parses the project like every other analysis, so
  * it records the same discovery kinds: a `skipped-large-file`,
  * `skipped-minified-file`, or `source-read-failure` file was never
- * scanned for flags, and a `source-parse-degraded` file was scanned from
- * a partial module. Each is a reason a flag can be missing from
+ * scanned for flags, a `source-parse-degraded` file was scanned from a
+ * partial module, and a `source-nesting-too-deep` file was not scanned. Each is a reason a flag can be missing from
  * `feature_flags[]`, which is exactly what a consumer reading a
  * zero-result run needs to know. The analysis-stage kinds appear here
  * too: the scan correlates flags with dead exports, so it runs the