fallow 3.28.0 → 3.30.0

package/schema.json

@@ -190,13 +190,14 @@
       "$ref": "#/$defs/TypeAwareConfig"
     },
     "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.",
+      "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`, `deprecated-exports-in-use`, `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",
         "unused-exports": "error",
         "unused-types": "error",
         "private-type-leaks": "off",
+        "deprecated-exports-in-use": "off",
         "unused-dependencies": "error",
         "unused-dev-dependencies": "warn",
         "unused-optional-dependencies": "warn",
@@ -220,6 +221,9 @@
         "css-selector-complexity": "warn",
         "css-dead-surface": "warn",
         "css-broken-reference": "warn",
+        "complexity-cyclomatic": "error",
+        "complexity-cognitive": "error",
+        "complexity-crap": "error",
         "unresolved-imports": "error",
         "unlisted-dependencies": "error",
         "duplicate-exports": "error",
@@ -261,7 +265,7 @@
       }
     },
     "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`).",
+      "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.*` and `import.meta.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
@@ -363,7 +367,12 @@
       "default": false
     },
     "autoImports": {
-      "description": "When true, drops Nuxt convention-based entry-pattern fallbacks so genuinely-unreferenced convention files surface as unused-file. Component fallbacks are kept when nuxt.config customizes components: in a way fallow does not model, and composable/util fallbacks are kept when it customizes imports:; a config that scans no more than the Nuxt defaults (components: false, components: [], components: { dirs: [] }, components: true, imports: { scan: false }, imports: {}, imports: { dirs: [] }) is treated like the default and its fallbacks are dropped; imports: { autoImport: false } on its own is not, because it only switches the injection off while the same directories stay registered behind #imports. A nuxt.config that carries any top-level key fallow cannot read statically, a computed key, an accessor, or a spread such as { ...base, devtools: {} }, keeps both surfaces' fallbacks for that root, because the spread may hold the keys that decide. Each root is classified on its own config, so one custom nuxt.config in a monorepo does not keep every other workspace's fallbacks. Component names follow Nuxt: a component under components/global or components/islands is named after its own directory (components/global/Foo.vue is `<Foo>`), and .client, .server, .global and .island suffixes are stripped. A name imported or re-exported by hand from #components or #imports credits its convention file just like a template tag or a bare call; a namespace import names nothing and credits nothing. 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.",
+      "description": "When true, drops Nuxt convention-based entry-pattern fallbacks so genuinely-unreferenced convention files surface as unused-file. Component fallbacks are kept when nuxt.config customizes components: in a way fallow does not model, and composable/util fallbacks are kept when it customizes imports:; a config that scans no more than the Nuxt defaults (components: false, components: [], components: { dirs: [] }, components: true, imports: { scan: false }, imports: {}, imports: { dirs: [] }) is treated like the default and its fallbacks are dropped; imports: { autoImport: false } on its own is not, because it only switches the injection off while the same directories stay registered behind #imports. A nuxt.config that carries any top-level key fallow cannot read statically, a computed key, an accessor, or a spread such as { ...base, devtools: {} }, keeps both surfaces' fallbacks for that root, because the spread may hold the keys that decide. Only top-level keys count when the config object is readable: a nested key such as a routeRules path ending in components does not keep a fallback. Nested components or imports keys in $production, $development, $test or `$env.<name>`, and components or imports hooks (a components:* key or a nested components object in hooks, also inside those overrides), count as that surface's key; such an override object or hooks object that fallow cannot read statically falls back to a text match for the keys. Each root is classified on its own config plus the configs of its local layers, so one custom nuxt.config in a monorepo does not keep every other workspace's fallbacks. A local layer is a directory named in extends, or a `layers/<name>` directory, that holds a nuxt.config; its convention files are entry points with the flag off and auto-import sources with it on, and `#layers/<name>/` resolves to it by its $meta.name (a `layers/<name>` directory without one uses its directory name). A remote or package layer is only a dependency reference. Component names follow Nuxt: a component under components/global or components/islands is named after its own directory (components/global/Foo.vue is `<Foo>`), and .client, .server, .global and .island suffixes are stripped. A name imported or re-exported by hand from #components or #imports credits its convention file just like a template tag or a bare call; a namespace import names nothing and credits nothing. 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
+    },
+    "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.",
       "type": "boolean",
       "default": false
     },
@@ -1055,7 +1064,7 @@
           "default": 15
         },
         "maxCrap": {
-          "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph. Governs\nfindings and the threshold-relative file-score signals\n(`crap_above_threshold`, the `risk` triage tag, and the\n`add_test_coverage` refactoring target); measured values such as\n`crap_max` and the overall health score never move with it. Set to\n`0` to disable CRAP enforcement entirely: no findings, nothing counts\nabove threshold, and file-score rows disclose baseline breaches as\nexempt instead.",
+          "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph. Governs\nfindings and the threshold-relative file-score signals\n(`crap_above_threshold`, the `risk` triage tag, and the\n`add_test_coverage` refactoring target); measured values such as\n`crap_max` and the overall health score never move with it. Set to\n`0` to disable CRAP enforcement entirely: no findings, nothing counts\nabove threshold, and file-score rows disclose baseline breaches as\nexempt instead. The `complexity-crap` rule is different: it decides if\na finding fails the run, and `off` hides the findings but keeps the\nfile-score signals.",
           "type": "number",
           "format": "double",
           "default": 30.0
@@ -1076,7 +1085,7 @@
           "default": 60
         },
         "coverage": {
-          "description": "Path to Istanbul-format coverage data for accurate per-function CRAP\nscores. Relative paths resolve against the project root. The CLI\n`--coverage` flag and `FALLOW_COVERAGE` environment variable override\nthis value. Consulted by `fallow health`, bare `fallow`, `fallow audit`,\n`fallow viz`, and the MCP `audit` / `check_health` tools.",
+          "description": "Path to Istanbul coverage data (coverage-final.json) or raw V8 coverage\n(a `NODE_V8_COVERAGE` directory or one V8 JSON file) for accurate\nper-function CRAP scores. Relative paths resolve against the project root. The CLI\n`--coverage` flag and `FALLOW_COVERAGE` environment variable override\nthis value. Consulted by `fallow health`, bare `fallow`, `fallow audit`,\n`fallow viz`, and the MCP `audit` / `check_health` tools.",
           "type": [
             "string",
             "null"
@@ -1310,6 +1319,11 @@
           "$ref": "#/$defs/Severity",
           "default": "off"
         },
+        "deprecated-exports-in-use": {
+          "description": "An export marked `@deprecated` that still has at least one reachable\nreference. Opt-in; defaults to `off`. A per-path override resolves on\nthe file that declares the export, not on the consumer.",
+          "$ref": "#/$defs/Severity",
+          "default": "off"
+        },
         "unused-dependencies": {
           "description": "A declared `dependencies` entry never observed used. Defaults to\n`error`.",
           "$ref": "#/$defs/Severity",
@@ -1425,6 +1439,21 @@
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
+        "complexity-cyclomatic": {
+          "description": "A function above the cyclomatic ceiling (`health.maxCyclomatic` or a\n`thresholdOverrides` entry). The threshold decides if the finding\nexists; this rule decides if it fails the run. Defaults to `error`.\n`warn` reports the finding without a failure, and `off` hides it. A\nfinding above several ceilings takes the most severe of their rules.\nThe rule applies before the `health --min-severity` band gate.\nAfter you set a kind to `off`, save the health baseline again: its\nentries for the hidden findings no longer match.",
+          "$ref": "#/$defs/Severity",
+          "default": "error"
+        },
+        "complexity-cognitive": {
+          "description": "A function above the cognitive ceiling (`health.maxCognitive` or a\n`thresholdOverrides` entry). The threshold decides if the finding\nexists; this rule decides if it fails the run. Defaults to `error`.",
+          "$ref": "#/$defs/Severity",
+          "default": "error"
+        },
+        "complexity-crap": {
+          "description": "A function above the CRAP ceiling (`health.maxCrap` or a\n`thresholdOverrides` entry). The threshold decides if the finding\nexists; this rule decides if it fails the run. Defaults to `error`.\n`off` hides the findings only. `health.maxCrap: 0` also turns off the\nthreshold-relative file-score signals.",
+          "$ref": "#/$defs/Severity",
+          "default": "error"
+        },
         "unresolved-imports": {
           "description": "An import specifier that resolves to no file or package. Defaults to\n`error`.",
           "$ref": "#/$defs/Severity",
@@ -1795,7 +1824,7 @@
           }
         },
         "envPrefixes": {
-          "description": "Environment variable prefixes that indicate feature flags.\nMerged with built-in prefixes. Only `process.env.*` accesses matching\nthese prefixes are reported as feature flags.",
+          "description": "Environment variable prefixes that indicate feature flags.\nMerged with built-in prefixes. Only `process.env.*` and\n`import.meta.env.*` accesses matching these prefixes are reported as\nfeature flags.",
           "type": "array",
           "items": {
             "type": "string"
@@ -1805,6 +1834,13 @@
           "description": "Enable config object heuristic detection.\nWhen true, property accesses on objects whose name contains \"feature\",\n\"flag\", or \"toggle\" are reported as low-confidence feature flags.\nDefault: false (opt-in due to higher false positive rate).",
           "type": "boolean",
           "default": false
+        },
+        "vendorKeyPrefix": {
+          "description": "Prefix to remove from each key of a `--flag-state` vendor export\nbefore the key is compared with the flag names in the code. For\nexample, `\"web.\"` makes the vendor key `web.new-checkout` match the\ncode flag `new-checkout`. A key without the prefix is compared as it\nis.",
+          "type": [
+            "string",
+            "null"
+          ]
         }
       }
     },
@@ -2049,6 +2085,17 @@
             }
           ]
         },
+        "deprecated-exports-in-use": {
+          "description": "Optional override for [`RulesConfig::deprecated_exports_in_use`].",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "unused-dependencies": {
           "description": "Optional override for [`RulesConfig::unused_dependencies`].",
           "anyOf": [
@@ -2302,6 +2349,39 @@
             }
           ]
         },
+        "complexity-cyclomatic": {
+          "description": "Optional override for [`RulesConfig::complexity_cyclomatic`].",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "complexity-cognitive": {
+          "description": "Optional override for [`RulesConfig::complexity_cognitive`].",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "complexity-crap": {
+          "description": "Optional override for [`RulesConfig::complexity_crap`].",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "unresolved-imports": {
           "description": "Optional override for [`RulesConfig::unresolved_imports`].",
           "anyOf": [

package/scripts/lazy-verify.js

@@ -15,7 +15,7 @@
 // bin/fallow exits non-zero before execing the binary. FALLOW_SKIP_BINARY_VERIFY
 // remains the documented escape hatch.
 //
-// Refs: SECURITY.md "Binary distribution and verification".
+// See SECURITY.md for binary distribution and verification.
 //
 // No external deps beyond node:fs / node:path / node:crypto.
 
@@ -24,7 +24,12 @@ const path = require("node:path");
 const crypto = require("node:crypto");
 
 const { resolveSentinelPath } = require("./sentinel-path");
-const { verifyInstalledSync, SKIP_ENV } = require("./verify-binary");
+const {
+  verifyInstalledSync,
+  binaryTargetsForPlatform,
+  isSkipRequested,
+  SKIP_ENV,
+} = require("./verify-binary");
 
 // Bumped to 2 when SHA-256 + platformPkgDir binding landed (closes the
 // cross-install reuse gap in the shared $XDG fallback cache), and to 3 when
@@ -66,11 +71,10 @@ function emitVerifyLog(env, payload) {
   process.stderr.write(`fallow-verify ${parts.join(" ")}\n`);
 }
 
-function binaryTargetsForPlatform(platform) {
-  // Track every executable the multicall CLI may launch without another
-  // wrapper verification boundary.
-  const ext = platform === "win32" ? ".exe" : "";
-  return [`fallow${ext}`, `fallow-similar-code${ext}`];
+// The sentinel binds the same binaries that verify-binary checks, so a new
+// binary cannot pass verification without also invalidating the sentinel.
+function binaryNamesForPlatform(platform) {
+  return binaryTargetsForPlatform(platform).map((t) => t.binary);
 }
 
 function statMtimeMs(absPath) {
@@ -145,7 +149,7 @@ function sha256OfFile(absPath) {
 // integrity gate that defends against same-mtime cross-install reuse where a
 // tampered binary happens to land with the recorded mtime.
 function sentinelBinariesMatch(parsed, platformPkgDir, platform) {
-  for (const target of binaryTargetsForPlatform(platform)) {
+  for (const target of binaryNamesForPlatform(platform)) {
     const recorded = parsed.binaries[target];
     if (!recorded || typeof recorded.mtimeMs !== "number") return false;
     if (typeof recorded.sha256 !== "string" || recorded.sha256.length !== 64) return false;
@@ -173,7 +177,7 @@ function isSentinelValid(sentinelPath, platformPkgDir, manifest, platform) {
 
 function buildSentinelPayload(platformPkgDir, manifest, platform) {
   const binaries = {};
-  for (const target of binaryTargetsForPlatform(platform)) {
+  for (const target of binaryNamesForPlatform(platform)) {
     const binaryPath = path.join(platformPkgDir, target);
     const mtimeMs = statMtimeMs(binaryPath);
     const sha256 = sha256OfFile(binaryPath);
@@ -213,11 +217,6 @@ function writeSentinel(sentinelPath, payload) {
   }
 }
 
-function isSkipRequested(env) {
-  const v = (env || process.env)[SKIP_ENV];
-  return v === "1" || v === "true" || v === "yes";
-}
-
 // Main entry point. Synchronous by design: bin/fallow runs this before
 // execFileSync, so the verify result must be available without awaiting.
 //
@@ -300,7 +299,7 @@ function ensureVerified(input) {
     platform = process.platform,
   } = input || {};
 
-  if (isSkipRequested(env)) {
+  if (isSkipRequested(env || process.env)) {
     const reason = `${SKIP_ENV} is set`;
     // Warn once per process so the bypass stays visible in CI logs and
     // vendor audits regardless of whether the user runs `--version` or
@@ -364,6 +363,5 @@ function _resetWarningState() {
 module.exports = {
   ensureVerified,
   SENTINEL_SCHEMA_VERSION,
-  VERIFY_LOG_ENV,
   _resetWarningState,
 };

package/scripts/lazy-verify.test.js

@@ -5,14 +5,9 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 
-const {
-  ensureVerified,
-  SENTINEL_SCHEMA_VERSION,
-  VERIFY_LOG_ENV,
-  _resetWarningState,
-} = require("./lazy-verify");
+const { ensureVerified, SENTINEL_SCHEMA_VERSION, _resetWarningState } = require("./lazy-verify");
 const { SENTINEL_FILENAME } = require("./sentinel-path");
-const { _verifyWithKey, SKIP_ENV } = require("./verify-binary");
+const { _verifyWithKey, binaryTargetsForPlatform, SKIP_ENV } = require("./verify-binary");
 
 // ---- shared fixtures ------------------------------------------------------
 
@@ -149,6 +144,28 @@ test("ensureVerified verifies and caches a win32 executable on any host", (t) =>
   assert.equal(cached.cached, true);
 });
 
+test("sentinel records the same binaries that verify-binary verifies", (t) => {
+  const cases = [
+    { platform: "linux", platformId: "linux-x64-gnu" },
+    { platform: "win32", platformId: "win32-x64-msvc" },
+  ];
+  for (const { platform, platformId } of cases) {
+    _resetWarningState();
+    const { privateKey, rawPub } = makeKeypair();
+    const dir = mkPlatformDir(privateKey, { platform });
+    t.after(() => cleanup(dir));
+    const input = baseInput(dir, (binaryPath) => _verifyWithKey(binaryPath, rawPub), {
+      platform,
+    });
+
+    const result = ensureVerified(input);
+    assert.equal(result.ok, true);
+    const sentinel = JSON.parse(fs.readFileSync(result.sentinelPath, "utf8"));
+    const verified = binaryTargetsForPlatform(platformId).map((target) => target.binary);
+    assert.deepEqual(Object.keys(sentinel.binaries), verified);
+  }
+});
+
 test("ensureVerified returns cached:true on a valid sentinel", (t) => {
   _resetWarningState();
   const { privateKey, rawPub } = makeKeypair();
@@ -543,9 +560,3 @@ test("ensureVerified warns once on stderr when FALLOW_SKIP_BINARY_VERIFY is set"
   );
   assert.equal(warnings.length, 1, "warning should fire exactly once per process");
 });
-
-// ---- VERIFY_LOG_ENV export ------------------------------------------------
-
-test("VERIFY_LOG_ENV is exported with the documented name", () => {
-  assert.equal(VERIFY_LOG_ENV, "FALLOW_VERIFY_LOG");
-});

package/scripts/sentinel-path.js

@@ -9,7 +9,7 @@
 //   4. Every location read-only: returns { path: null, location: 'none', writable: false }.
 //      Callers run verify on every invocation and surface FALLOW_SKIP_BINARY_VERIFY=1 as the escape.
 //
-// Refs RFC 868 (npm/cli#9360). See .plans/rfc-868-lazy-binary-verify.md.
+// See SECURITY.md for binary distribution and verification.
 
 const fs = require("node:fs");
 const os = require("node:os");
@@ -19,8 +19,8 @@ const SENTINEL_FILENAME = ".fallow-verified";
 
 // Returns true when the directory exists and the current process can create
 // a file in it. Tries an atomic O_CREAT|O_EXCL write so we never disturb an
-// existing sentinel during the writability probe. Falls back to fs.accessSync
-// when mkdtempSync fails for non-permission reasons.
+// existing sentinel during the writability probe. Any failed probe makes this
+// location unavailable so resolution can try the next cache directory.
 function isWritable(dir) {
   if (typeof dir !== "string" || dir.length === 0) {
     return false;
@@ -126,7 +126,7 @@ function tryXdgFallback(env, homeDir, platformId, filename, ensureDir, writableP
 }
 
 // Resolve the sentinel path according to the cascade documented above.
-// Dependency-inject env / homedir / platform / fsProbe so the unit tests can
+// Dependency-inject env / homedir / platform / isWritable / ensureDir so tests can
 // exercise every branch without touching the real filesystem state.
 //
 // Returns: {

package/scripts/sentinel-path.test.js

@@ -89,10 +89,7 @@ test("resolveSentinelPath falls back to FALLOW_VERIFY_CACHE_DIR when platform pk
   }
 });
 
-test("resolveSentinelPath honors FALLOW_VERIFY_CACHE_DIR even when platform pkg dir IS writable", () => {
-  // Per the cascade documented in the source, the platform pkg dir wins when
-  // writable. The cache-dir env is the FALLBACK for when the platform dir is
-  // read-only. We pass a non-existent platform dir to force the fallback.
+test("resolveSentinelPath uses FALLOW_VERIFY_CACHE_DIR when platform pkg dir is unset", () => {
   const cacheDir = mkTmp();
   try {
     const result = resolveSentinelPath({

package/scripts/verify-binary.js

@@ -308,8 +308,8 @@ function binaryTargetsForPlatform(platformId) {
   ];
 }
 
-function isSkipRequested() {
-  const v = process.env[SKIP_ENV];
+function isSkipRequested(env = process.env) {
+  const v = env[SKIP_ENV];
   return v === "1" || v === "true" || v === "yes";
 }
 
@@ -664,4 +664,6 @@ module.exports = {
   EMBEDDED_PUBLIC_KEY,
   ED25519_SPKI_HEADER,
   SKIP_ENV,
+  binaryTargetsForPlatform,
+  isSkipRequested,
 };

package/skills/fallow/SKILL.md

@@ -6,10 +6,10 @@ license: MIT
 
 # Fallow: codebase intelligence for TypeScript and JavaScript
 
-Codebase intelligence for TypeScript and JavaScript. The static layer analyzes code and styles and reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, design-system styling drift, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. Broad framework plugin coverage, zero configuration, sub-second static analysis.
+Codebase intelligence for TypeScript and JavaScript. The static layer analyzes code and styles and reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, design-system styling drift, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review and cold-path deletion confidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. Broad framework plugin coverage, zero configuration, sub-second static analysis.
 
 ## When to Use
-- Find cleanup opportunities: unused files, exports, types, members, dependencies, or stale flags.
+- Find cleanup opportunities: unused files, exports, types, members, dependencies, or feature flags that guard unused exports.
 - Detect code duplication, circular dependencies, architecture boundary issues, and complexity hotspots.
 - Find functions that may implement the same intent despite different names, syntax, or control flow (`fallow similar-code`).
 - Check styling consistency, CSS dead surface, and design-token drift.
@@ -192,9 +192,10 @@ Reports unused exports in entry files (package.json `main`/`exports`, framework
 ```bash
 fallow flags --format json --quiet
 fallow flags --format json --quiet --top 20
+fallow flags --retirement --format json --quiet
 ```
 
-Reports environment-variable gates (`process.env.FEATURE_*`), SDK calls from common flag providers, and config-object patterns, with flag locations, detection confidence, and a cross-reference against dead code. Only `--top N` is command-specific.
+Reports environment-variable gates (`process.env.FEATURE_*`), SDK calls from common flag providers, and config-object patterns, with flag locations, detection confidence, and a cross-reference against dead code. `--top N` limits the list. `--retirement` adds a `retirement` object with one row per flag, the reasons it can be retired (`single-read-site`, `test-only`, `literal-constant`, `identical-branches`, `empty-branch`, `guards-dead-code`, `defined-never-read`), and its age from git (`--flag-age blame|pickaxe|off`; blame gives a lower bound). Filter with `--reason <CODE>` and `--min-age <DAYS>`, order with `--sort age|sites|name`. `--flag-state <FILE>` reads an offline vendor export in one vendor-neutral schema and adds `fully-rolled-out`, `archived-in-vendor`, `missing-in-vendor` and `vendor-only`. With `--retirement`, `--save-regression-baseline <PATH>` and `--fail-on-regression --regression-baseline <PATH>` gate on `distinct_flags` (plus each `--reason` count), and the opt-in `--max-flag-age <DAYS>` fails on old flags. Every format works: compact prints `flag-retire:<reason>:<path>:<line>:<name>`, SARIF adds the rule `fallow/flag-retirement-candidate`, CodeClimate adds `fallow/flag-retirement`. The report is advisory: every action has `auto_fixable: false`, and a person decides what to remove.
 
 ### Surface security candidates for verification
 ```bash
@@ -260,7 +261,7 @@ fallow dead-code --format json --quiet --save-baseline .fallow/snapshot.json
 fallow dead-code --format json --quiet --baseline .fallow/snapshot.json
 ```
 
-`--save-regression-baseline` / `--regression-baseline` / `--fail-on-regression` / `--tolerance` are count-based gates for `dead-code` and bare combined mode. `--save-baseline` / `--baseline` are identity-based (track finding identity, fail on new). `audit` rejects the global baseline flags and uses `--dead-code-baseline` / `--health-baseline` / `--dupes-baseline` instead.
+`--save-regression-baseline` / `--regression-baseline` / `--fail-on-regression` / `--tolerance` are count-based gates for `dead-code`, bare combined mode, and `flags --retirement` (a flags baseline needs a PATH; without `--retirement` the options have no effect on `flags` and it warns). `--save-baseline` / `--baseline` are identity-based (track finding identity, fail on new). `audit` rejects the global baseline flags and uses `--dead-code-baseline` / `--health-baseline` / `--dupes-baseline` instead.
 
 With no path, `--save-regression-baseline` updates `regression.baseline` in the discovered fallow config, or creates `.fallowrc.json` when none exists. Pass a path only when a standalone baseline file is preferred.