fallow 2.88.2 → 2.89.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.88.2",
+  "version": "2.89.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, 96 framework plugins.",
   "license": "MIT",
   "repository": {
@@ -83,13 +83,13 @@
     "@tanstack/intent": "0.0.41"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.88.2",
-    "@fallow-cli/darwin-x64": "2.88.2",
-    "@fallow-cli/linux-x64-gnu": "2.88.2",
-    "@fallow-cli/linux-arm64-gnu": "2.88.2",
-    "@fallow-cli/linux-x64-musl": "2.88.2",
-    "@fallow-cli/linux-arm64-musl": "2.88.2",
-    "@fallow-cli/win32-arm64-msvc": "2.88.2",
-    "@fallow-cli/win32-x64-msvc": "2.88.2"
+    "@fallow-cli/darwin-arm64": "2.89.0",
+    "@fallow-cli/darwin-x64": "2.89.0",
+    "@fallow-cli/linux-x64-gnu": "2.89.0",
+    "@fallow-cli/linux-arm64-gnu": "2.89.0",
+    "@fallow-cli/linux-x64-musl": "2.89.0",
+    "@fallow-cli/linux-arm64-musl": "2.89.0",
+    "@fallow-cli/win32-arm64-msvc": "2.89.0",
+    "@fallow-cli/win32-x64-msvc": "2.89.0"
   }
 }

package/scripts/run-binary.js

@@ -14,6 +14,7 @@ const fs = require("node:fs");
 
 const { getPlatformPackage } = require("./platform-package");
 const { ensureVerified } = require("./lazy-verify");
+const { isPreSigningVersion } = require("./verify-binary");
 
 function resolvePlatformPackageName() {
   if (process.platform !== "linux") {
@@ -29,13 +30,34 @@ function resolvePlatformPackageName() {
 }
 
 function isVersionQuery(argv) {
-  // clap registers both --version and -V on the root command.
+  // The root command answers all three version flags (--version, -V, and the
+  // TS/JS-toolchain-style -v), so the verified-status line must be appended for
+  // every one of them, not just --version / -V.
   const tail = argv.slice(2);
   if (tail.length === 0) return false;
-  return tail[0] === "--version" || tail[0] === "-V";
+  return tail[0] === "--version" || tail[0] === "-V" || tail[0] === "-v";
 }
 
-function describeVerified(result) {
+// Signing status of the resolved CLI version, appended to the `verified:` line.
+// Most informative on the `skipped` path: a fleet running with
+// FALLOW_SKIP_BINARY_VERIFY can see whether the pinned version is even signable
+// (pre-signing versions predate the 2.77.0 epoch and have no signature to
+// verify). Best-effort: an unknown/unreadable version yields no annotation.
+function describeSigning(version) {
+  if (typeof version !== "string" || version.length === 0) {
+    return "";
+  }
+  return isPreSigningVersion(version)
+    ? `; fallow ${version} unsigned (predates 2.77.0)`
+    : `; fallow ${version} signed`;
+}
+
+function describeVerified(result, version) {
+  const status = describeVerifiedStatus(result);
+  return `${status}${describeSigning(version)}`;
+}
+
+function describeVerifiedStatus(result) {
   if (result.skipped) {
     return `verified: skipped (${result.reason})`;
   }
@@ -79,9 +101,21 @@ function printVerifyError(verifyResult) {
   );
 }
 
-function writeVerifiedLineIfVersionQuery(verifyResult) {
+function writeVerifiedLineIfVersionQuery(verifyResult, version) {
   if (isVersionQuery(process.argv)) {
-    process.stdout.write(`${describeVerified(verifyResult)}\n`);
+    process.stdout.write(`${describeVerified(verifyResult, version)}\n`);
+  }
+}
+
+// Read the resolved CLI version from the platform package manifest (its version
+// is released in lockstep with the CLI). Best-effort: never throws, so a
+// missing/garbled manifest just omits the signing annotation on --version.
+function readResolvedVersion(manifestPath) {
+  try {
+    const version = JSON.parse(fs.readFileSync(manifestPath, "utf8")).version;
+    return typeof version === "string" ? version : undefined;
+  } catch {
+    return undefined;
   }
 }
 
@@ -105,6 +139,7 @@ function guardBrokenStdout() {
 function runBinary(binaryBaseName) {
   guardBrokenStdout();
   const { pkg, manifestPath, platformPkgDir } = resolvePlatformPaths();
+  const resolvedVersion = readResolvedVersion(manifestPath);
 
   const binaryName = process.platform === "win32" ? `${binaryBaseName}.exe` : binaryBaseName;
   const binaryPath = path.join(platformPkgDir, binaryName);
@@ -126,11 +161,11 @@ function runBinary(binaryBaseName) {
     if (e.status === undefined) throw e;
     // Child has already written its --version line via inherited stdio;
     // append the verified line here only on a clean exit.
-    if (e.status === 0) writeVerifiedLineIfVersionQuery(verifyResult);
+    if (e.status === 0) writeVerifiedLineIfVersionQuery(verifyResult, resolvedVersion);
     process.exit(e.status);
   }
 
-  writeVerifiedLineIfVersionQuery(verifyResult);
+  writeVerifiedLineIfVersionQuery(verifyResult, resolvedVersion);
 }
 
 module.exports = {

package/scripts/run-binary.test.js

@@ -37,3 +37,40 @@ test("guardBrokenStdout rethrows non-EPIPE stdout errors (exit 1)", () => {
   assert.match(res.stderr, /Error: write ENOSPC/, "the rethrown error reaches stderr");
   assert.doesNotMatch(res.stderr, /is not a function/, "guard must be present, not absent");
 });
+
+test("isVersionQuery recognizes --version, -V, and -v as the first argument", () => {
+  const { isVersionQuery } = require(RUN_BINARY);
+  assert.equal(isVersionQuery(["node", "fallow", "--version"]), true);
+  assert.equal(isVersionQuery(["node", "fallow", "-V"]), true);
+  assert.equal(
+    isVersionQuery(["node", "fallow", "-v"]),
+    true,
+    "-v must append the verified line too",
+  );
+  assert.equal(isVersionQuery(["node", "fallow"]), false);
+  assert.equal(isVersionQuery(["node", "fallow", "dead-code"]), false);
+  assert.equal(
+    isVersionQuery(["node", "fallow", "dead-code", "-v"]),
+    false,
+    "-v only counts as the first arg",
+  );
+});
+
+test("describeVerified annotates the resolved version's signing status", () => {
+  const { describeVerified } = require(RUN_BINARY);
+  const ok = { ok: true, sentinelPath: "/c/s" };
+  // Signed-era version: appended as `signed`.
+  assert.match(
+    describeVerified(ok, "2.83.0"),
+    /verified: yes \(sentinel \/c\/s\); fallow 2\.83\.0 signed/,
+  );
+  // Pre-signing version: the fleet pre-flight signal, most useful on skip.
+  const skipped = { skipped: true, reason: "FALLOW_SKIP_BINARY_VERIFY is set" };
+  assert.match(
+    describeVerified(skipped, "2.76.0"),
+    /verified: skipped \(.*\); fallow 2\.76\.0 unsigned \(predates 2\.77\.0\)/,
+  );
+  // Unknown / unreadable version: no annotation, version line stays intact.
+  assert.equal(describeVerified(ok, undefined), "verified: yes (sentinel /c/s)");
+  assert.equal(describeVerified(ok, ""), "verified: yes (sentinel /c/s)");
+});

package/scripts/verify-binary.js

@@ -81,6 +81,10 @@ function _verifyWithKey(binaryPath, rawPubKey) {
     signature = fs.readFileSync(sigPath);
   } catch (err) {
     if (err && err.code === "ENOENT") {
+      // Low-level result: the version-aware guidance is attached one layer up
+      // in verifyOneBinary{,Sync}, which knows the resolved platform-package
+      // version and can distinguish a pre-signing version from a >=2.77.0
+      // package whose signature is missing (a tampering signal). Refs #944.
       return { ok: false, code: "sig-missing", message: `signature not found at ${sigPath}` };
     }
     return {
@@ -389,16 +393,69 @@ function resolvePlatformPackageForVerify(opts) {
   };
 }
 
+// Signed platform binaries ship from fallow 2.77.0 onward (the `.sig` staging
+// step, the `files` entries, and this verifier all landed in #488, first
+// released in 2.77.0). A resolved version below this epoch has no signature and
+// never will (npm is immutable), so its missing-sig failure is expected and the
+// fix is to upgrade the pin. A version at or above the epoch whose signature is
+// absent is a different, alarming case (tampered or incomplete package).
+const SIGNING_EPOCH = [2, 77, 0];
+
+// True when `version` is a parseable semver strictly below the signing epoch.
+// An unparsable / unknown version returns false so the caller uses the
+// cautious (possible-tampering) message rather than telling the user to bump.
+function isPreSigningVersion(version) {
+  if (typeof version !== "string") {
+    return false;
+  }
+  const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return false;
+  }
+  const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
+  for (let i = 0; i < SIGNING_EPOCH.length; i += 1) {
+    if (parts[i] < SIGNING_EPOCH[i]) {
+      return true;
+    }
+    if (parts[i] > SIGNING_EPOCH[i]) {
+      return false;
+    }
+  }
+  return false;
+}
+
+// Attach version-aware remediation to a `sig-missing` low-level result. Other
+// failure codes pass through untouched. The split distinguishes a pre-signing
+// version (no signature exists and never will, so the fix is to upgrade the
+// pin) from a >=2.77.0 package whose signature is unexpectedly absent (a
+// tampering signal). Each message gives the CONSTRUCTIVE fix only; the bypass
+// escape hatch (FALLOW_SKIP_BINARY_VERIFY) is owned by the caller's trailer and
+// SECURITY.md, deliberately not surfaced here so a tampering victim is never
+// nudged to bypass and the env is not normalized in CI logs.
+function describeSigMissing(result, version) {
+  if (result.code !== "sig-missing") {
+    return result;
+  }
+  const message = isPreSigningVersion(version)
+    ? `${result.message}. fallow ${version} predates signed binaries (signatures ship in 2.77.0 ` +
+      `and later), so this package has no signature to verify. Bump the \`fallow\` dependency in ` +
+      `your project's package.json to >=2.77.0 (for example \`npm install fallow@latest\`).`
+    : `${result.message}. fallow ${version} should be signed but its signature is missing; the ` +
+      `platform package may be tampered with or incomplete. Reinstall with \`npm install fallow@latest\` ` +
+      `and report it if it persists on a clean install.`;
+  return { ...result, message };
+}
+
 // Verify one binary against its sig + expected SHA-256. Used by both the
 // sync and async verify-installed entry points; the digest provider may be
 // sync (returns string) or async (returns Promise<string>), and the loop body
 // awaits the value regardless. Keeps the outer functions a flat for-loop so
 // cyclomatic + cognitive complexity stays low.
-async function verifyOneBinary(target, dir, pkg, manifestPath, verifyFn, digestProvider) {
+async function verifyOneBinary(target, dir, pkg, manifestPath, verifyFn, digestProvider, version) {
   const binaryPath = path.join(dir, target.binary);
   const sigResult = verifyFn(binaryPath);
   if (!sigResult.ok) {
-    return { ...sigResult, binary: binaryPath, package: pkg };
+    return { ...describeSigMissing(sigResult, version), binary: binaryPath, package: pkg };
   }
   // Prefer the digest embedded in the platform package's package.json
   // (written at release time by `npm-prep`). Falling back to the GitHub
@@ -478,7 +535,15 @@ async function verifyInstalled(options) {
   const boundProvider = async (args) => digestProvider({ ...args, version });
 
   for (const target of binaryTargetsForPlatform(platformId)) {
-    const result = await verifyOneBinary(target, dir, pkg, manifestPath, verify, boundProvider);
+    const result = await verifyOneBinary(
+      target,
+      dir,
+      pkg,
+      manifestPath,
+      verify,
+      boundProvider,
+      version,
+    );
     if (!result.ok) return result;
   }
   return { ok: true, package: pkg, version };
@@ -518,7 +583,15 @@ function verifyInstalledSync(options) {
   const { dir, manifestPath, pkg, version, platformId } = resolved;
 
   for (const target of binaryTargetsForPlatform(platformId)) {
-    const result = verifyOneBinarySync(target, dir, pkg, manifestPath, verify, digestProvider);
+    const result = verifyOneBinarySync(
+      target,
+      dir,
+      pkg,
+      manifestPath,
+      verify,
+      digestProvider,
+      version,
+    );
     if (!result.ok) return result;
   }
   return { ok: true, package: pkg, version };
@@ -529,11 +602,11 @@ function verifyInstalledSync(options) {
 // actionable error pointing the user at `npm install fallow@latest` (since
 // there is no network fallback in lazy mode), and the digestProvider is
 // optional (tests inject one; production callers rely on the embedded digest).
-function verifyOneBinarySync(target, dir, pkg, manifestPath, verifyFn, digestProvider) {
+function verifyOneBinarySync(target, dir, pkg, manifestPath, verifyFn, digestProvider, version) {
   const binaryPath = path.join(dir, target.binary);
   const sigResult = verifyFn(binaryPath);
   if (!sigResult.ok) {
-    return { ...sigResult, binary: binaryPath, package: pkg };
+    return { ...describeSigMissing(sigResult, version), binary: binaryPath, package: pkg };
   }
   let expectedDigest = manifestPath ? readEmbeddedDigest(manifestPath, target.binary) : null;
   if (!expectedDigest && digestProvider) {
@@ -575,6 +648,8 @@ module.exports = {
   verifyInstalled,
   verifyInstalledSync,
   _verifyWithKey,
+  isPreSigningVersion,
+  describeSigMissing,
   normalizeDigest,
   readEmbeddedDigest,
   sha256Hex,

package/scripts/verify-binary.test.js

@@ -7,6 +7,8 @@ const path = require("node:path");
 
 const {
   _verifyWithKey,
+  isPreSigningVersion,
+  describeSigMissing,
   verifyBinaryAt,
   verifyDigestAt,
   verifyInstalled,
@@ -133,6 +135,56 @@ test("_verifyWithKey returns sig-missing when the signature file does not exist"
   }
 });
 
+// The version-aware remediation lives in describeSigMissing (attached by
+// verifyOneBinary{,Sync}), not in the low-level _verifyWithKey result. Refs #944.
+test("isPreSigningVersion is true below 2.77.0 and false at/above it", () => {
+  assert.equal(isPreSigningVersion("2.76.0"), true);
+  assert.equal(isPreSigningVersion("2.73.0"), true);
+  assert.equal(isPreSigningVersion("1.9.0"), true);
+  assert.equal(isPreSigningVersion("2.77.0"), false);
+  assert.equal(isPreSigningVersion("2.83.0"), false);
+  assert.equal(isPreSigningVersion("2.88.2"), false);
+  // Unknown / unparsable versions default to false so the caller uses the
+  // cautious possible-tampering message rather than telling the user to bump.
+  assert.equal(isPreSigningVersion("unknown"), false);
+  assert.equal(isPreSigningVersion(undefined), false);
+});
+
+test("describeSigMissing gives upgrade guidance for a pre-signing version", () => {
+  const base = { ok: false, code: "sig-missing", message: "signature not found at /x/fallow.sig" };
+  const result = describeSigMissing(base, "2.76.0");
+  // The security-critical invariant: enriching the message must never flip the
+  // verdict. A sig-missing result stays a hard failure.
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "sig-missing");
+  assert.match(result.message, /predates signed binaries/);
+  assert.match(result.message, /2\.77\.0/);
+  // Names WHERE the pin lives so the user can act.
+  assert.match(result.message, /package\.json/);
+  // The bypass escape hatch is owned by the caller's trailer + SECURITY.md, not
+  // surfaced inline, so it is not normalized in CI logs.
+  assert.doesNotMatch(result.message, new RegExp(SKIP_ENV));
+  // The original low-level detail is preserved.
+  assert.match(result.message, /signature not found/);
+});
+
+test("describeSigMissing flags possible tampering for a signed-era version", () => {
+  const base = { ok: false, code: "sig-missing", message: "signature not found at /x/fallow.sig" };
+  const result = describeSigMissing(base, "2.83.0");
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "sig-missing");
+  assert.match(result.message, /tampered with or incomplete/);
+  assert.match(result.message, /Reinstall/);
+  // Must NOT nudge a possible-tampering victim toward bypassing verification.
+  assert.doesNotMatch(result.message, new RegExp(SKIP_ENV));
+});
+
+test("describeSigMissing passes non-sig-missing results through untouched", () => {
+  const base = { ok: false, code: "digest-mismatch", message: "digest mismatch" };
+  const result = describeSigMissing(base, "2.76.0");
+  assert.equal(result.message, "digest mismatch");
+});
+
 test("_verifyWithKey returns binary-missing when the binary does not exist", () => {
   const { rawPub } = makeKeypair();
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-vbtest-"));
@@ -343,6 +395,32 @@ test("verifyInstalled with dirOverride reports sig-missing when a .sig is absent
   assert.match(result.binary, /fallow-mcp/);
 });
 
+test("verifyInstalled threads the resolved version into the sig-missing message", async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const preDir = makePlatformDir(privateKey, { skipSigFor: "fallow-mcp" });
+  const eraDir = makePlatformDir(privateKey, { skipSigFor: "fallow-mcp" });
+  t.after(() => {
+    cleanup(preDir);
+    cleanup(eraDir);
+  });
+  const pre = await verifyInstalled({
+    dirOverride: preDir,
+    version: "2.76.0",
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(preDir),
+  });
+  assert.equal(pre.code, "sig-missing");
+  assert.match(pre.message, /predates signed binaries/);
+  const era = await verifyInstalled({
+    dirOverride: eraDir,
+    version: "2.83.0",
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(eraDir),
+  });
+  assert.equal(era.code, "sig-missing");
+  assert.match(era.message, /tampered with or incomplete/);
+});
+
 test("verifyInstalled reports digest-mismatch when SHA-256 disagrees with the provider", async (t) => {
   const { privateKey, rawPub } = makeKeypair();
   const dir = makePlatformDir(privateKey);

package/skills/fallow/SKILL.md

@@ -122,7 +122,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `find_dupes` | Code duplication detection. Set `changed_since` to scope to changed files since a git ref. Set `min_occurrences` (≥ 2, default 2) to hide pair-only clones and focus on widespread copy-paste; JSON gains `stats.clone_groups_below_min_occurrences` when the filter hides anything. Each `clone_groups[]` entry carries a stable `fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions; pass it to `trace_clone` to deep-dive that group |
 | `fix_preview` | Dry-run auto-fix preview |
 | `fix_apply` | Apply auto-fixes (destructive) |
-| `check_health` | Complexity metrics, health scores, hotspots, and refactoring targets. Optional `runtime_coverage` merges a V8 or Istanbul dump; tune it with `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), and `low_traffic_threshold` (default 0.001). When runtime evidence combines with static usage, test coverage, CRAP/complexity, ownership, or change scope, read `coverage_intelligence` for stable `fallow:coverage-intel:<hash>` recommendations. Set `group_by` to `owner`, `directory`, `package`, or `section` for per-group `vital_signs` / `health_score`; SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field |
+| `check_health` | Complexity metrics, health scores, hotspots, and refactoring targets. Set `complexity_breakdown: true` to add a per-decision-point `contributions[]` array to each complexity finding (each `else-if`, nested `if`, boolean operator, loop, `case`, etc. with its source line and cyclomatic/cognitive weight) so you can explain WHY a function scored high and pinpoint refactor targets. Optional `runtime_coverage` merges a V8 or Istanbul dump; tune it with `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), and `low_traffic_threshold` (default 0.001). When runtime evidence combines with static usage, test coverage, CRAP/complexity, ownership, or change scope, read `coverage_intelligence` for stable `fallow:coverage-intel:<hash>` recommendations. Set `group_by` to `owner`, `directory`, `package`, or `section` for per-group `vital_signs` / `health_score`; SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field |
 | `check_runtime_coverage` | Merge V8 or Istanbul runtime-coverage data into the health report. One local capture is free; continuous/cloud or multi-capture runtime monitoring is paid. Required `coverage` param (V8 dir, V8 JSON, or Istanbul `coverage-final.json`). Tuning knobs: `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), `low_traffic_threshold` (default 0.001), `max_crap` (default 30.0), `top`, `group_by`. Cloud runtime rows can expose `resolutionStatus` / `mappingQuality` on function-list JSON and `resolution_status` / `mapping_quality` in runtime-context JSON. Use `coverage_intelligence` and the confidence table below before acting on file-level runtime signals. Long dumps may exceed the 120s MCP timeout; raise `FALLOW_TIMEOUT_SECS`. Pick this over `check_health` when you have a coverage dump. |
 | `get_hot_paths` | Runtime-context slice over the same runtime coverage pipeline. Same params as `check_runtime_coverage`; read `runtime_coverage.hot_paths` for production hot paths. |
 | `get_blast_radius` | Runtime-context slice for blast-radius review. Same params as `check_runtime_coverage`; read `runtime_coverage.blast_radius` for stable `fallow:blast:<hash>` IDs, caller counts, traffic-weighted caller reach, optional cloud deploy touch counts, and low/medium/high risk bands. |

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

@@ -51,7 +51,14 @@ Analyzes the project for unused files, exports, dependencies, types, members, an
 | `--workspace` | string | — | Scope to one or more workspaces. Comma-separated values, globs (`apps/*`, `@scope/*`), and `!`-prefixed negation (`!apps/legacy`) supported. Matched against package name AND workspace path relative to repo root. |
 | `--changed-workspaces` | string (git ref) | — | Git-derived monorepo CI scoping: scope to workspaces containing any file changed since `REF` (e.g. `origin/main`). Auto-derives the workspace set from `git diff`. Mutually exclusive with `--workspace`. Missing ref is a hard error (exit 2), not silent full-scope fallback. |
 | `--include-dupes` | bool | `false` | Cross-reference with duplication findings |
+| `--dupes-mode` | enum | `config` | Override duplicate detection mode in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --mode`. |
+| `--dupes-threshold` | number | `config` | Override the duplication percentage failure threshold in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --threshold`. |
+| `--dupes-min-tokens` | number | `config` | Override the minimum token count for clone detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --min-tokens`. |
+| `--dupes-min-lines` | number | `config` | Override the minimum line count for clone detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --min-lines`. |
 | `--dupes-min-occurrences` | number | `config` | Override the minimum clone occurrences in combined mode (must be >= 2). Falls back to the config value when unset. Mirrors the standalone `dupes --min-occurrences`. |
+| `--dupes-skip-local` | bool | `config` | Only report cross-directory duplicates in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --skip-local`. |
+| `--dupes-cross-language` | bool | `config` | Enable TypeScript to JavaScript duplicate matching in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --cross-language`. |
+| `--dupes-ignore-imports` | bool | `config` | Exclude import declarations from duplicate detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --ignore-imports`. |
 | `--file` | path (multiple) | — | Scope output to specific files. Only issues in the specified files are reported. Project-wide dependency issues are suppressed. Warns on non-existent paths. Useful for lint-staged |
 | `--include-entry-exports` | bool | `false` | Report unused exports in entry files (package.json `main`/`exports`, framework pages). Catches typos like `meatdata` vs `metadata`. Global flag, also accepted on combined mode (`fallow --include-entry-exports`) and `fallow audit`. Also configurable as `includeEntryExports: true` in fallow config |
 | `--trace` | `FILE:EXPORT` | — | Trace export usage chain |
@@ -368,6 +375,7 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--top` | number | — | Only show the top N most complex functions (and file scores/hotspots/targets) |
 | `--sort` | `cyclomatic\|cognitive\|lines\|severity` | `cyclomatic` | Sort order for complexity findings |
 | `--complexity` | bool | `false` | Show only function complexity findings. When no section flags are set, all sections are shown by default. |
+| `--complexity-breakdown` | bool | `false` | Add a per-decision-point `contributions[]` array to each complexity finding in `--format json`. Each entry names the construct (`if`, `else-if`, `ternary`, boolean operator, loop, `case`, `catch`, `optional-chain`, ...) and carries its source line, the metric it adds to (`cyclomatic` or `cognitive`), its weight, and the nesting depth, so a consumer can explain WHY a function scored high. Off by default (no change to existing JSON/SARIF/markdown). Used by the VS Code inline editor breakdown and the MCP `check_health` `complexity_breakdown` param. |
 | `--file-scores` | bool | `false` | Show only per-file health scores (maintainability index, LOC, fan-in, fan-out, dead code ratio, complexity density, CRAP risk). Runs the full analysis pipeline. Sorted by risk-aware triage concern: lower maintainability index and higher CRAP risk first. When no section flags are set, all sections are shown by default. |
 | `--hotspots` | bool | `false` | Show only hotspots: files that are both complex and frequently changing. Combines git churn history with complexity data. Requires a git repository. When no section flags are set, all sections are shown by default. |
 | `--targets` | bool | `false` | Show only refactoring targets: ranked recommendations based on complexity, coupling, churn, and dead code signals. Categories: churn+complexity, circular dep, high impact, dead code, complexity, coupling. When no section flags are set, all sections are shown by default. |
@@ -376,8 +384,9 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--min-score` | number | — | Fail (exit 1) only when the health score is below this threshold. Implies `--score`. Authoritative CI quality gate: when set, complexity findings are demoted to informational and the exit code is driven solely by the score, so `--min-score 0` always exits 0. Composes with `--min-severity`. |
 | `--min-severity` | `moderate\|high\|critical` | — | Only exit with an error for findings at or above this severity. Composes with `--min-score` (the run fails if either gate trips). |
 | `--report-only` | bool | `false` | Print the score and findings but never fail CI (always exit 0). Advisory mode. Mutually exclusive with `--min-score` and `--min-severity`. |
-| `--since` | string | `6m` | Git history window for hotspot analysis. Accepts durations (`6m`, `90d`, `1y`, `2w`) or ISO dates (`2025-06-01`). |
+| `--since` | string | `6m` | Git history window for hotspot analysis. Accepts durations (`6m`, `90d`, `1y`, `2w`) or ISO dates (`2025-06-01`). Ignored when `--churn-file` is set. |
 | `--min-commits` | number | `3` | Minimum number of commits for a file to be included in hotspot ranking. |
+| `--churn-file` | string | (none) | Import change history from a `fallow-churn/v1` JSON file (`{schema, events:[{path, timestamp, author, added, deleted}]}`, one entry per changed file per commit) instead of `git log`, so `--hotspots`/`--ownership`/`--targets` work on non-git VCS (Yandex Arc, Mercurial, Perforce). Resolved relative to `--root`; wins over git. Authoritative for the window, so `--since` then only labels output. Malformed file exits 2; `audit`/`impact`/`--changed-since` still require git. |
 | `--ownership` | bool | `false` | Attach ownership signals to hotspot entries: bus factor (Avelino truck factor), contributor count, top contributor with stale-days, recent contributors (top-3), `suggested_reviewers`, declared CODEOWNERS owner, `ownership_state`, ownership drift, unowned-hotspot detection. Human output gains a project-level summary line. JSON adds `low-bus-factor`, `unowned-hotspot`, `ownership-drift` action types. Test files get a `[test]` tag. Implies `--hotspots`. Requires git. |
 | `--ownership-emails` | `raw\|handle\|anonymized\|hash` | `handle` | Privacy mode for author emails. `handle` shows the local-part only (default, with GitHub noreply unwrap and deterministic same-handle disambiguation). `anonymized` emits stable `xxh3:` pseudonyms; `hash` remains accepted as the legacy spelling. `raw` shows full addresses. Use `anonymized` in regulated environments. Implies `--ownership`. Configure default via `health.ownership.emailMode`. |
 | `--changed-since` | string | — | Only analyze files changed since a git ref |
@@ -486,7 +495,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.89.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -876,7 +885,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.89.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -949,7 +958,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.89.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1389,6 +1398,7 @@ Available on all commands:
 | `FALLOW_EXTENDS_TIMEOUT_SECS` | Timeout for fetching remote config inheritance in seconds (default: `5`). Do not raise this for untrusted sources. |
 | `FALLOW_CACHE_MAX_SIZE` | Maximum on-disk extraction cache (`.fallow/cache.bin`) size in megabytes (default: `256`). Triggers LRU eviction when crossed. Wins over `cache.maxSizeMb` config field. Intended for CI runners with disk quotas. `--no-cache` short-circuits this knob. |
 | `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` | Max age (in days since last reuse or fresh create) of a persistent reusable `fallow audit` base-snapshot worktree cache. Older entries are reclaimed at the top of the next `fallow audit` invocation (default: `30`). Wins over `audit.cacheMaxAgeDays` config field. `0` disables the GC; invalid values silently fall back to config / default. |
+| `FALLOW_UPDATE_CHECK` | Set to `off`, `0`, `false`, `disabled`, or `no` to disable the human-TTY upgrade nudge and its background latest-version check. `DO_NOT_TRACK`, `FALLOW_TELEMETRY_DISABLED`, and CI also suppress it. |
 | `FALLOW_COMMAND` | GitLab CI: command to run (default: `dead-code`). |
 | `FALLOW_FAIL_ON_ISSUES` | GitLab CI: set to `true` to exit 1 if issues found. |
 | `FALLOW_CHANGED_SINCE` | GitLab CI: git ref for incremental analysis. Auto-detected in MR pipelines. |
@@ -1488,7 +1498,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.89.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1648,7 +1658,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.89.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1692,11 +1702,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.89.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.88.2",
+    "version": "2.89.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -353,6 +353,18 @@ export type CoverageTier = ("none" | "partial" | "high")
  * Provenance of a CRAP finding's coverage signal.
  */
 export type CoverageSource = ("istanbul" | "estimated" | "estimated_component_inherited")
+/**
+ * Which complexity metric a [`ComplexityContribution`] adds to.
+ */
+export type ComplexityMetric = ("cyclomatic" | "cognitive")
+/**
+ * The syntactic construct that produced a single complexity increment.
+ *
+ * Mirrors `SonarSource` cognitive-complexity vocabulary where it overlaps.
+ * `Case` means a `case` label carrying a test; a bare `default` adds nothing
+ * 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")
 /**
  * Discriminant for [`HealthFindingAction::kind`]. Mirrors the action types
  * emitted by `build_health_finding_actions`. A single finding's `actions`
@@ -1654,6 +1666,15 @@ line: number
  * 0-based byte column offset of the import that starts the cycle.
  */
 col: number
+/**
+ * Per-file import anchors, one entry per hop in cycle order: `edges[i]`
+ * is the import in `files[i]` pointing to `files[(i + 1) % len]`. Always
+ * the same length as `files`. Drives the per-file LSP diagnostic
+ * squiggly. `#[serde(default)]` so pre-`edges` baselines deserialize;
+ * always emitted on output but intentionally not in the schema's
+ * `required` set (see the struct doc).
+ */
+edges?: CircularDependencyEdge[]
 /**
  * Whether this cycle crosses workspace package boundaries.
  */
@@ -1669,6 +1690,34 @@ actions: IssueAction[]
  */
 introduced?: (AuditIntroduced | null)
 }
+/**
+ * One import hop in a circular dependency: the file containing the import
+ * and where that import statement sits.
+ *
+ * `edges[i]` is the import IN `path` (the hop SOURCE, equal to the cycle's
+ * `files[i]`) that points to the NEXT file in the cycle
+ * (`files[(i + 1) % files.len()]`); the target is not repeated here to keep
+ * the wire compact. Enables a per-file diagnostic squiggly anchored under
+ * the offending import rather than a single squiggly on the first file.
+ *
+ * `col` is a 0-based BYTE column, matching the cycle's top-level `col`;
+ * converting it to a UTF-16 code-unit column for LSP clients is a tracked
+ * follow-up shared with the existing field.
+ */
+export interface CircularDependencyEdge {
+/**
+ * The file containing the import (the hop SOURCE; equal to `files[i]`).
+ */
+path: string
+/**
+ * 1-based line number of the import statement pointing to the next file.
+ */
+line: number
+/**
+ * 0-based byte column offset of the import statement.
+ */
+col: number
+}
 /**
  * Wire-shape envelope for a [`ReExportCycle`] finding. Mirrors
  * [`CircularDependencyFinding`]: flattens the bare finding and carries a
@@ -2200,6 +2249,15 @@ line_count: number
  * each group in the human listing.
  */
 fingerprint: string
+/**
+ * Best-effort human-readable name for the clone: the dominant repeated
+ * identifier across the duplicated fragment (e.g. a shared `parseCsv`
+ * function). `None` when the clone has no clear dominant name (generic or
+ * tied identifiers); consumers then fall back to a file-based label. Lets
+ * editors and agents label a clone by what it is rather than an opaque
+ * ordinal.
+ */
+suggested_name?: (string | null)
 /**
  * Suggested next steps: an `extract-shared` primary and a
  * `suppress-line` secondary. Always emitted (possibly empty for
@@ -2534,6 +2592,13 @@ coverage_tier?: (CoverageTier | null)
 coverage_source?: (CoverageSource | null)
 inherited_from?: (string | null)
 component_rollup?: (ComponentRollup | null)
+/**
+ * Per-decision-point complexity breakdown explaining WHICH constructs drove
+ * the cyclomatic and cognitive scores. Populated only when the caller opts
+ * in via `health --complexity-breakdown`; empty (and omitted from JSON)
+ * otherwise so default and CI output stay lean.
+ */
+contributions?: ComplexityContribution[]
 /**
  * Machine-actionable fix and suppress hints.
  */
@@ -2553,6 +2618,36 @@ template_path: string
 template_cyclomatic: number
 template_cognitive: number
 }
+/**
+ * A single complexity increment, located at its source line/column.
+ *
+ * `weight` is the amount this construct added to `metric`; for nested
+ * cognitive increments `weight == 1 + nesting`. Consumers that render inline
+ * (the VS Code editor breakdown) group contributions by `line` and sum the
+ * weights, deferring the per-kind list to a hover.
+ */
+export interface ComplexityContribution {
+/**
+ * 1-based line number where the construct begins.
+ */
+line: number
+/**
+ * 0-based byte column where the construct begins.
+ */
+col: number
+metric: ComplexityMetric
+kind: ComplexityContributionKind
+/**
+ * The amount added to `metric` at this site (`1 + nesting` for nested
+ * cognitive increments, otherwise `1`).
+ */
+weight: number
+/**
+ * The nesting depth at the increment site (`0` when not nested). Lets a
+ * consumer explain a cognitive `+3` as "+1 base, +2 nesting".
+ */
+nesting: number
+}
 /**
  * Suggested action attached to a [`ComplexityViolation`].
  *