fallow 2.94.0 → 2.95.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.94.0",
+  "version": "2.95.0",
   "description": "Deterministic codebase intelligence for TypeScript and JavaScript. Quality, risk, architecture, dependencies, duplication, and safe cleanup evidence for humans, CI, and agents. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -83,13 +83,13 @@
     "@tanstack/intent": "0.0.41"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.94.0",
-    "@fallow-cli/darwin-x64": "2.94.0",
-    "@fallow-cli/linux-x64-gnu": "2.94.0",
-    "@fallow-cli/linux-arm64-gnu": "2.94.0",
-    "@fallow-cli/linux-x64-musl": "2.94.0",
-    "@fallow-cli/linux-arm64-musl": "2.94.0",
-    "@fallow-cli/win32-arm64-msvc": "2.94.0",
-    "@fallow-cli/win32-x64-msvc": "2.94.0"
+    "@fallow-cli/darwin-arm64": "2.95.0",
+    "@fallow-cli/darwin-x64": "2.95.0",
+    "@fallow-cli/linux-x64-gnu": "2.95.0",
+    "@fallow-cli/linux-arm64-gnu": "2.95.0",
+    "@fallow-cli/linux-x64-musl": "2.95.0",
+    "@fallow-cli/linux-arm64-musl": "2.95.0",
+    "@fallow-cli/win32-arm64-msvc": "2.95.0",
+    "@fallow-cli/win32-x64-msvc": "2.95.0"
   }
 }

package/schema.json

@@ -832,6 +832,13 @@
           },
           "default": []
         },
+        "thresholdOverrides": {
+          "description": "Per-file or per-function threshold overrides. These keep exceptional\nfunctions visible as configured numeric ceilings instead of hiding them\nbehind binary suppressions.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/HealthThresholdOverride"
+          }
+        },
         "ownership": {
           "description": "Ownership analysis configuration. Controls bot filtering and email\nprivacy mode for `--ownership` output.",
           "$ref": "#/$defs/OwnershipConfig",
@@ -852,7 +859,67 @@
           "type": "boolean",
           "default": true
         }
-      }
+      },
+      "additionalProperties": false
+    },
+    "HealthThresholdOverride": {
+      "description": "Per-file or per-function health threshold override.",
+      "type": "object",
+      "properties": {
+        "files": {
+          "description": "Project-root-relative file globs this override applies to.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "functions": {
+          "description": "Exact emitted function names this override applies to. Empty means every\nfunction in matching files.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "maxCyclomatic": {
+          "description": "Local cyclomatic complexity ceiling.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint16",
+          "minimum": 0,
+          "maximum": 65535
+        },
+        "maxCognitive": {
+          "description": "Local cognitive complexity ceiling.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint16",
+          "minimum": 0,
+          "maximum": 65535
+        },
+        "maxCrap": {
+          "description": "Local CRAP ceiling.",
+          "type": [
+            "number",
+            "null"
+          ],
+          "format": "double"
+        },
+        "reason": {
+          "description": "Human-readable rationale for the exception.",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "files"
+      ]
     },
     "OwnershipConfig": {
       "description": "Configuration for ownership analysis (`fallow health --hotspots --ownership`).",

package/skills/fallow/SKILL.md

@@ -149,7 +149,7 @@ Run `fallow <command> --help` for the full flag list per command (see also refer
 | `boundary-violation` | `--boundary-violations` | - | `// fallow-ignore-next-line boundary-violation` | Imports crossing architecture zone boundaries. Presets: `layered`, `hexagonal`, `feature-sliced`, `bulletproof`; `autoDiscover` can create one zone per feature directory; per-rule `allowTypeOnly: [zones]` admits `import type` / `export type` crossings while still blocking value imports. Optional sections: `boundaries.coverage.requireAllFiles` reports unzoned source files (`allowUnmatched` globs exempt intentional ones), and `boundaries.calls.forbidden` bans callee patterns per zone (segment-aware and import-resolved, so `child_process.*` covers `node:child_process` named/namespace/default imports; direct callees only, zoned files only). The whole family shares the `boundary-violation` rule and suppression token (`boundary-call-violation` and `boundary-call-violations` accepted as aliases); start the rule at `warn` for a staged rollout |
 | `boundary-coverage` | - | - | `// fallow-ignore-file boundary-violation` | Source file matches no configured architecture boundary zone; Requires boundaries.coverage.requireAllFiles |
 | `boundary-call-violation` | - | - | `// fallow-ignore-next-line boundary-call-violation` | Zoned file calls a callee its zone forbids; Requires boundaries.calls.forbidden patterns |
-| `policy-violation` | `--policy-violations` | - | `// fallow-ignore-next-line policy-violation` | Calls or imports banned by a declarative rule pack (`rulePacks` config key lists standalone JSON/JSONC files of `banned-call` / `banned-import` rules; pure data, no project code executes). Findings identified as `<pack>/<rule-id>`. Default `warn` master; per-rule `severity` overrides per finding and the exit gate reads the effective severity. Invalid or missing packs fail config load with exit 2. `fallow rule-pack-schema` prints the pack JSON Schema. Suppress with `// fallow-ignore-next-line policy-violation` (one token covers every pack rule on the line). |
+| `policy-violation` | `--policy-violations` | - | `// fallow-ignore-next-line policy-violation` | Calls or imports banned by a declarative rule pack (`rulePacks` config key lists standalone JSON/JSONC files of `banned-call` / `banned-import` rules; pure data, no project code executes). Findings identified as `<pack>/<rule-id>`. Default `warn` master; per-rule `severity` overrides per finding and the exit gate reads the effective severity. Invalid or missing packs fail config load with exit 2. `fallow rule-pack-schema` prints the pack JSON Schema. Use the scoped token to suppress one rule; bare `policy-violation` still covers every pack rule on the line or file. |
 | `stale-suppression` | `--stale-suppressions` | - | - | `fallow-ignore` comments or `@expected-unused` JSDoc tags that no longer match any issue |
 | `unused-catalog-entry` | `--unused-catalog-entries` | yes | - | `pnpm-workspace.yaml` entries no workspace package.json references via `catalog:` (default `warn`) |
 | `empty-catalog-group` | `--empty-catalog-groups` | - | - | Named `catalogs.<name>:` groups in `pnpm-workspace.yaml` with no entries. Top-level `catalog:` placeholders are ignored. Default `warn`. |
@@ -218,14 +218,14 @@ Most tools accept `root`, `config`, `no_cache`, and `threads` params. Exceptions
 
 All JSON responses include structured `actions` arrays on every finding (dead code, health, duplication), enabling programmatic fix application or suppression.
 
+`health.thresholdOverrides[]` lets projects keep known legacy functions visible as configured local ceilings instead of hiding them with suppressions. Each entry has `files` globs, optional exact `functions`, one or more of `maxCyclomatic`, `maxCognitive`, or `maxCrap`, and optional `reason`. Health JSON may include top-level `threshold_overrides[]` entries with `active`, `stale`, or `no_match` status, and complexity findings that use an override carry `effective_thresholds` plus `threshold_source: "override"`.
+
 `dead-code`, `health`, `dupes`, bare `fallow`, and `audit` JSON output also carry a top-level `next_steps` array of read-only follow-up commands computed from the run's findings: each entry is `{ id, command, reason }`. The `command` is runnable as-is (never a placeholder, never `fix` or any other mutating command); the stable kebab-case `id` (`setup`, `impact-report`, `trace-unused-export`, `trace-clone`, `complexity-breakdown`, `scope-workspaces`, `audit-changed`) maps to a verification step you should run BEFORE acting, for example tracing an export before deleting it. A leading `setup` step (command: `fallow schema`) appears only on unconfigured, non-CI projects with findings and doubles as the onboarding trigger below; it disappears after setup or `fallow init --decline`. An at-most-weekly `impact-report` step (command: `fallow impact`) carries the local value digest when impact tracking has non-zero results; it may ride a clean run. When running via MCP, dispatch on the `id` to the matching tool / `code_execute` host call (`trace_export`, `trace_clone`, `check_health` with `complexity_breakdown: true`, `audit`) rather than shelling out the CLI string. The array is deduplicated, capped at three, and omitted when empty; set `FALLOW_SUGGESTIONS=off` to suppress it.
 
 ## Node.js Bindings
-
 Embedding fallow in a Node.js process (editor extensions, servers, custom tooling)? Use the `@fallow-cli/fallow-node` NAPI bindings instead of spawning the CLI: six async functions (`detectDeadCode`, `detectCircularDependencies`, `detectBoundaryViolations`, `detectDuplication`, `computeComplexity`, `computeHealth`) returning the same JSON envelopes as `--format json`. Read-only analysis only; use the CLI for write-path commands. Details: [Node Bindings](references/node-bindings.md).
 
 ## References
-
 - [CLI Reference](references/cli-reference.md): complete command and flag specifications, plus configuration field details
 - [Gotchas](references/gotchas.md): common pitfalls, edge cases, and correct usage patterns
 - [Patterns](references/patterns.md): workflow recipes for CI, monorepos, migration, and incremental adoption

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

@@ -492,7 +492,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.94.0",
+  "version": "2.95.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -516,6 +516,8 @@ fallow health --format json --quiet --trend
 }
 ```
 
+`health.thresholdOverrides[]` config entries can raise local cyclomatic, cognitive, or CRAP ceilings for matching files and optional exact function names. When an override affects output, health JSON includes top-level `threshold_overrides[]` state entries (`active`, `stale`, or `no_match`). Complexity findings evaluated with local ceilings include `effective_thresholds` and `threshold_source: "override"` so agents can see which thresholds drove the finding and avoid treating configured exceptions as hidden suppressions.
+
 When the unit size very-high-risk percentage is >= 3%, the JSON output includes a `large_functions` array listing functions exceeding 60 lines of code:
 
 ```json
@@ -877,7 +879,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.94.0",
+  "version": "2.95.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -952,7 +954,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.94.0",
+  "version": "2.95.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1052,7 +1054,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "2.94.0",
+  "version": "2.95.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1081,7 +1083,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "2.94.0",
+  "version": "2.95.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1697,7 +1699,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.94.0",
+  "version": "2.95.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1857,7 +1859,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.94.0",
+  "version": "2.95.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1901,11 +1903,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.94.0",
+  "version": "2.95.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.94.0",
+    "version": "2.95.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -390,6 +390,10 @@ export type ComplexityMetric = ("cyclomatic" | "cognitive")
  * to cyclomatic complexity and so produces no contribution.
  */
 export type ComplexityContributionKind = ("if" | "else" | "else-if" | "ternary" | "logical-and" | "logical-or" | "nullish-coalescing" | "logical-assignment" | "optional-chain" | "for" | "for-in" | "for-of" | "while" | "do-while" | "switch" | "case" | "catch" | "labeled-break" | "labeled-continue")
+/**
+ * Source for a finding's effective thresholds.
+ */
+export type ThresholdSource = "override"
 /**
  * Discriminant for [`HealthFindingAction::kind`]. Mirrors the action types
  * emitted by `build_health_finding_actions`. A single finding's `actions`
@@ -407,6 +411,10 @@ export type CoverageModel = ("static_binary" | "static_estimated" | "istanbul")
  * Whether CRAP findings in the report used one coverage-source kind or a mix.
  */
 export type CoverageSourceConsistency = ("uniform" | "mixed")
+/**
+ * Lifecycle state for a configured threshold override.
+ */
+export type ThresholdOverrideStatus = ("active" | "stale" | "no_match")
 /**
  * Discriminant for [`UntestedFileAction::kind`]. Mirrors the action types
  * emitted by `build_untested_file_actions`.
@@ -2080,8 +2088,8 @@ introduced?: (AuditIntroduced | null)
 }
 /**
  * Wire-shape envelope for a [`PolicyViolation`] finding. Carries actions for
- * replacing the banned call or import, or suppressing it with the
- * `policy-violation` token.
+ * replacing the banned call or import, or suppressing it with a scoped
+ * `policy-violation:<pack>/<rule-id>` token.
  */
 export interface PolicyViolationFinding {
 /**
@@ -2816,6 +2824,11 @@ export interface HealthReport {
  */
 findings: HealthFinding[]
 summary: HealthSummary
+/**
+ * Configured threshold override states. Entries are emitted for active
+ * exceptions, stale exceptions, and full-run no-match cleanup hints.
+ */
+threshold_overrides?: ThresholdOverrideState[]
 /**
  * Project-wide vital signs (always computed from available data).
  */
@@ -2915,6 +2928,15 @@ component_rollup?: (ComponentRollup | null)
  * otherwise so default and CI output stay lean.
  */
 contributions?: ComplexityContribution[]
+/**
+ * Resolved thresholds used for this finding when a config override changed
+ * at least one ceiling. Omitted for findings using global thresholds.
+ */
+effective_thresholds?: (HealthEffectiveThresholds | null)
+/**
+ * Source of the effective thresholds. Omitted when thresholds are global.
+ */
+threshold_source?: (ThresholdSource | null)
 /**
  * Machine-actionable fix and suppress hints.
  */
@@ -2964,6 +2986,14 @@ weight: number
  */
 nesting: number
 }
+/**
+ * Resolved thresholds used to evaluate a health finding.
+ */
+export interface HealthEffectiveThresholds {
+max_cyclomatic: number
+max_cognitive: number
+max_crap: number
+}
 /**
  * Suggested action attached to a [`ComplexityViolation`].
  *
@@ -3046,6 +3076,36 @@ severity_critical_count: number
 severity_high_count: number
 severity_moderate_count: number
 }
+/**
+ * Report entry describing whether a threshold override is active, stale, or
+ * no longer matching any analyzed file or function.
+ */
+export interface ThresholdOverrideState {
+status: ThresholdOverrideStatus
+override_index: number
+path?: (string | null)
+function?: (string | null)
+configured_thresholds: HealthConfiguredThresholds
+effective_thresholds: HealthEffectiveThresholds
+metrics?: (ThresholdOverrideMetrics | null)
+reason?: (string | null)
+}
+/**
+ * Threshold values configured by a single override entry.
+ */
+export interface HealthConfiguredThresholds {
+max_cyclomatic?: (number | null)
+max_cognitive?: (number | null)
+max_crap?: (number | null)
+}
+/**
+ * Current complexity metrics for a matched threshold override entry.
+ */
+export interface ThresholdOverrideMetrics {
+cyclomatic: number
+cognitive: number
+crap?: (number | null)
+}
 /**
  * Project-wide vital signs , a fixed set of metrics for trend tracking.
  *
@@ -4609,6 +4669,11 @@ elapsed_ms: ElapsedMs
  */
 findings: HealthFinding[]
 summary: HealthSummary
+/**
+ * Configured threshold override states. Entries are emitted for active
+ * exceptions, stale exceptions, and full-run no-match cleanup hints.
+ */
+threshold_overrides?: ThresholdOverrideState[]
 /**
  * Project-wide vital signs (always computed from available data).
  */