fallow 3.13.0 → 3.14.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.13.0",
+  "version": "3.14.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,14 +87,14 @@
     "@tanstack/intent": "0.3.6"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.13.0",
-    "@fallow-cli/darwin-x64": "3.13.0",
-    "@fallow-cli/linux-x64-gnu": "3.13.0",
-    "@fallow-cli/linux-arm64-gnu": "3.13.0",
-    "@fallow-cli/linux-x64-musl": "3.13.0",
-    "@fallow-cli/linux-arm64-musl": "3.13.0",
-    "@fallow-cli/win32-arm64-msvc": "3.13.0",
-    "@fallow-cli/win32-x64-msvc": "3.13.0",
-    "fallow-type-aware": "3.13.0"
+    "@fallow-cli/darwin-arm64": "3.14.0",
+    "@fallow-cli/darwin-x64": "3.14.0",
+    "@fallow-cli/linux-x64-gnu": "3.14.0",
+    "@fallow-cli/linux-arm64-gnu": "3.14.0",
+    "@fallow-cli/linux-x64-musl": "3.14.0",
+    "@fallow-cli/linux-arm64-musl": "3.14.0",
+    "@fallow-cli/win32-arm64-msvc": "3.14.0",
+    "@fallow-cli/win32-x64-msvc": "3.14.0",
+    "fallow-type-aware": "3.14.0"
   }
 }

package/schema.json

@@ -141,7 +141,7 @@
       }
     },
     "health": {
-      "description": "Sets complexity and health thresholds for `fallow health` (also applied in combined `fallow` and `fallow audit`): `maxCyclomatic` (20), `maxCognitive` (15), `maxCrap` (30.0, findings at or above this are reported), `crapRefactorBand` (5, cyclomatic band below `maxCyclomatic` where a secondary refactor action is added), `maxUnitSize` (max function lines before a large-function finding, 60), `coverage`/`coverageRoot` (Istanbul coverage path and path-prefix strip for accurate CRAP), `ignore` globs (remove files from findings AND the health score), `thresholdOverrides` (per-file/per-function ceilings via `files`/`functions`/`maxCyclomatic`/`maxCognitive`/`maxCrap`/`maxUnitSize`/`reason`), `ownership` (`botPatterns` and `emailMode` for `--ownership`), and `suggestInlineSuppression` (true, emit `suppress-line` action hints in JSON). Raise thresholds to relax which functions are flagged, wire `coverage` for real CRAP scores, or exempt generated/test files via `ignore` (drops them from the score too) or `thresholdOverrides` (keeps them visible under a higher ceiling).",
+      "description": "Sets complexity and health thresholds for `fallow health` (also applied in combined `fallow` and `fallow audit`): `maxCyclomatic` (20), `maxCognitive` (15), `maxCrap` (30.0, findings at or above this are reported), `crapRefactorBand` (5, cyclomatic band below `maxCyclomatic` where a secondary refactor action is added), `maxUnitSize` (max function lines before a large-function finding, 60), `coverage`/`coverageRoot` (Istanbul coverage path and path-prefix strip for accurate CRAP), `ignore` globs (remove files from findings AND the health score), `thresholdOverrides` (per-file/per-function ceilings via `files`/`functions`/`maxCyclomatic`/`maxCognitive`/`maxCrap`/`maxUnitSize`/`reason`), `ownership` (`botPatterns` and `emailMode` for `--ownership`), and `suggestInlineSuppression` (true, emit `suppress-line` action hints in JSON). Raise thresholds to relax which functions are flagged, wire `coverage` for real CRAP scores, or exempt generated/test files via `ignore` (drops them from the score too) or `thresholdOverrides` (keeps them visible under a higher ceiling). The four `max*` thresholds govern findings only and never move `health_score`: its penalties use fixed calibration so grades stay comparable across projects, and `ignore` is the lever that removes files from the score.",
       "$ref": "#/$defs/HealthConfig",
       "default": {
         "maxCyclomatic": 20,
@@ -935,7 +935,7 @@
       "type": "object",
       "properties": {
         "maxCyclomatic": {
-          "description": "Maximum allowed cyclomatic complexity per function (default: 20).\nFunctions exceeding this threshold are reported.",
+          "description": "Maximum allowed cyclomatic complexity per function (default: 20).\nFunctions exceeding this threshold are reported. Governs findings\nonly; the health score's complexity penalties use fixed calibration\n(use `health.ignore` to remove a file from the score).",
           "type": "integer",
           "format": "uint16",
           "minimum": 0,
@@ -943,7 +943,7 @@
           "default": 20
         },
         "maxCognitive": {
-          "description": "Maximum allowed cognitive complexity per function (default: 15).\nFunctions exceeding this threshold are reported.",
+          "description": "Maximum allowed cognitive complexity per function (default: 15).\nFunctions exceeding this threshold are reported. Governs findings\nonly, never the health score.",
           "type": "integer",
           "format": "uint16",
           "minimum": 0,
@@ -951,7 +951,7 @@
           "default": 15
         },
         "maxCrap": {
-          "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph.",
+          "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph. Governs\nfindings only, never the health score.",
           "type": "number",
           "format": "double",
           "default": 30.0
@@ -965,7 +965,7 @@
           "default": 5
         },
         "maxUnitSize": {
-          "description": "Maximum function length in lines of code before it is reported as an\noversized \"large function\" (default: 60). Raise it globally, or per file\nvia `thresholdOverrides[].maxUnitSize`, to relax the bar for generated or\ntest files (where a `describe()` block spans hundreds of lines) without\ndisabling complexity checks on those files. This filters the reported\nlarge-functions list only; the descriptive unit-size profile and the\nhealth score still reflect raw sizes (use `health.ignore` to remove a\nfile from the score entirely).",
+          "description": "Maximum function length in lines of code before it is reported as an\noversized \"large function\" (default: 60). Raise it globally, or per file\nvia `thresholdOverrides[].maxUnitSize`, to relax the bar for generated or\ntest files (where a `describe()` block spans hundreds of lines) without\ndisabling complexity checks on those files. This filters the reported\nlarge-functions list only; the descriptive unit-size profile and the\nhealth score still reflect raw sizes against fixed calibration (the\n`unit_size` penalty keeps its `>60` LOC very-high-risk edge so grades\nstay comparable across projects; use `health.ignore` to remove a file\nfrom the score entirely).",
           "type": "integer",
           "format": "uint32",
           "minimum": 0,

package/scripts/run-binary.js

@@ -145,12 +145,18 @@ function resolveTypeAwareCompanion(
   }
 }
 
-function childEnvironment(resolvedVersion) {
+function childEnvironment(resolvedVersion, resolveCompanion = resolveTypeAwareCompanion) {
   if (process.env.FALLOW_TYPE_AWARE_BIN) return process.env;
-  const companion = resolveTypeAwareCompanion(resolvedVersion);
+  const companion = resolveCompanion(resolvedVersion);
   return companion === undefined
     ? process.env
-    : { ...process.env, FALLOW_TYPE_AWARE_BIN: companion };
+    : {
+        ...process.env,
+        FALLOW_TYPE_AWARE_BIN: companion,
+        // Marks the wiring as launcher-provided node_modules resolution so
+        // `type-aware status` does not report it as a user-set override.
+        FALLOW_TYPE_AWARE_BIN_SOURCE: "npm-wrapper",
+      };
 }
 
 // Swallow EPIPE on stdout. When fallow's output is piped into a reader that
@@ -223,4 +229,5 @@ module.exports = {
   guardBrokenStdout, // test-only
   exitCodeForChildFailure, // test-only
   resolveTypeAwareCompanion, // test-only
+  childEnvironment, // test-only
 };

package/scripts/run-binary.test.js

@@ -159,6 +159,39 @@ test("resolveTypeAwareCompanion accepts only an exact matching package", (t) =>
   assert.equal(resolveTypeAwareCompanion("3.8.0", resolvePackage), undefined);
 });
 
+test("childEnvironment marks launcher-wired companions as npm-wrapper", (t) => {
+  const { childEnvironment } = require(RUN_BINARY);
+  const previousBin = process.env.FALLOW_TYPE_AWARE_BIN;
+  delete process.env.FALLOW_TYPE_AWARE_BIN;
+  t.after(() => {
+    if (previousBin === undefined) delete process.env.FALLOW_TYPE_AWARE_BIN;
+    else process.env.FALLOW_TYPE_AWARE_BIN = previousBin;
+  });
+
+  const env = childEnvironment("3.8.0", () => "/tmp/fallow-type-aware.mjs");
+  assert.equal(env.FALLOW_TYPE_AWARE_BIN, "/tmp/fallow-type-aware.mjs");
+  assert.equal(env.FALLOW_TYPE_AWARE_BIN_SOURCE, "npm-wrapper");
+
+  // No resolvable companion: the environment passes through untouched.
+  const untouched = childEnvironment("3.8.0", () => undefined);
+  assert.equal(untouched, process.env);
+  assert.equal(untouched.FALLOW_TYPE_AWARE_BIN_SOURCE, undefined);
+});
+
+test("childEnvironment leaves a user-set override unmarked", (t) => {
+  const { childEnvironment } = require(RUN_BINARY);
+  const previousBin = process.env.FALLOW_TYPE_AWARE_BIN;
+  process.env.FALLOW_TYPE_AWARE_BIN = "/opt/custom-sidecar";
+  t.after(() => {
+    if (previousBin === undefined) delete process.env.FALLOW_TYPE_AWARE_BIN;
+    else process.env.FALLOW_TYPE_AWARE_BIN = previousBin;
+  });
+
+  const env = childEnvironment("3.8.0", () => "/tmp/fallow-type-aware.mjs");
+  assert.equal(env, process.env);
+  assert.equal(env.FALLOW_TYPE_AWARE_BIN_SOURCE, undefined);
+});
+
 test(
   "fallow-lsp executes the multicall binary with the lsp-server subcommand",
   { skip: process.platform === "win32" },

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

@@ -517,7 +517,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.13.0",
+  "version": "3.14.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -915,7 +915,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.13.0",
+  "version": "3.14.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -992,7 +992,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.13.0",
+  "version": "3.14.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1093,7 +1093,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1122,7 +1122,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1886,7 +1886,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.13.0",
+  "version": "3.14.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2046,7 +2046,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.13.0",
+  "version": "3.14.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2090,11 +2090,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.13.0",
+  "version": "3.14.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.13.0",
+    "version": "3.14.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -5650,6 +5650,13 @@ maintainability?: (number | null)
 hotspots?: (number | null)
 unused_deps?: (number | null)
 circular_deps?: (number | null)
+/**
+ * Penalty for oversized functions, computed against fixed calibration
+ * (very-high-risk bin edge at 60 LOC). Deliberately independent of
+ * `health.maxUnitSize`, which filters the large-functions findings list
+ * only; raising that threshold empties the list without moving this
+ * penalty. `health.ignore` removes files from the score entirely.
+ */
 unit_size?: (number | null)
 coupling?: (number | null)
 duplication?: (number | null)