fallow 3.41.0 → 3.43.0

package/scripts/platform-package.js

@@ -23,6 +23,31 @@ function getPlatformPackage(platform, arch, libcFamily) {
   return null;
 }
 
+// The platform packages declare `libc`, so npm installs only the package for
+// the libc that it detects at install time. The musl binaries are statically
+// linked and also run on glibc, so a glibc host accepts an installed musl
+// package (for example a node_modules tree that was built on Alpine). A glibc
+// binary does not run on musl, so there is no fallback in that direction.
+function getPlatformPackageCandidates(platform, arch, libcFamily) {
+  const primary = getPlatformPackage(platform, arch, libcFamily);
+  if (primary === null) return [];
+  if (primary.endsWith("-gnu")) return [primary, primary.replace(/-gnu$/, "-musl")];
+  return [primary];
+}
+
+function resolveInstalledPlatformPackage(candidates, resolve = require.resolve) {
+  for (const pkg of candidates) {
+    try {
+      return { pkg, manifestPath: resolve(`${pkg}/package.json`) };
+    } catch {
+      // Not installed; try the next candidate.
+    }
+  }
+  return null;
+}
+
 module.exports = {
   getPlatformPackage,
+  getPlatformPackageCandidates,
+  resolveInstalledPlatformPackage,
 };

package/scripts/run-binary.js

@@ -13,20 +13,23 @@ const path = require("node:path");
 const fs = require("node:fs");
 const os = require("node:os");
 
-const { getPlatformPackage } = require("./platform-package");
+const {
+  getPlatformPackageCandidates,
+  resolveInstalledPlatformPackage,
+} = require("./platform-package");
 const { ensureVerified } = require("./lazy-verify");
 const { isPreSigningVersion } = require("./verify-binary");
 
-function resolvePlatformPackageName() {
-  if (process.platform !== "linux") {
-    return getPlatformPackage(process.platform, process.arch);
-  }
+const SIMILAR_CODE_PROVIDER_ENV = "FALLOW_SIMILAR_CODE_PROVIDER";
+
+function detectLibcFamily() {
+  if (process.platform !== "linux") return undefined;
   try {
-    const { familySync } = require("detect-libc");
-    return getPlatformPackage(process.platform, process.arch, familySync());
+    return require("detect-libc").familySync();
   } catch {
-    // musl binaries are statically linked and work on both glibc and musl
-    return getPlatformPackage(process.platform, process.arch, "musl");
+    // Unknown libc selects the musl package: musl binaries are statically
+    // linked and work on both glibc and musl.
+    return null;
   }
 }
 
@@ -77,20 +80,28 @@ function describeVerifiedStatus(result) {
 // Resolve the platform package directory + manifest path, or print an
 // actionable error and exit. Keeps `runBinary` a flat top-level sequence.
 function resolvePlatformPaths() {
-  const pkg = resolvePlatformPackageName();
-  if (!pkg) {
+  const libcFamily = detectLibcFamily();
+  const candidates = getPlatformPackageCandidates(process.platform, process.arch, libcFamily);
+  if (candidates.length === 0) {
     process.stderr.write(`Unsupported platform: ${process.platform}-${process.arch}\n`);
     process.exit(1);
   }
-  try {
-    const manifestPath = require.resolve(`${pkg}/package.json`);
-    return { pkg, manifestPath, platformPkgDir: path.dirname(manifestPath) };
-  } catch {
-    process.stderr.write(
-      `Could not find ${pkg}. Run 'npm install' to install the platform-specific binary.\n`,
-    );
+  const resolved = resolveInstalledPlatformPackage(candidates);
+  if (resolved === null) {
+    process.stderr.write(missingPlatformPackageMessage(candidates[0], libcFamily));
     process.exit(1);
   }
+  return { ...resolved, platformPkgDir: path.dirname(resolved.manifestPath) };
+}
+
+// npm installs a Linux platform package only for the libc that it detects at
+// install time, so a tree installed for another libc, or from macOS or
+// Windows without `--libc`, has no matching binary.
+function missingPlatformPackageMessage(pkg, libcFamily) {
+  const hint = libcFamily
+    ? ` This host uses ${libcFamily}. When node_modules was installed on another libc or OS, reinstall with \`npm install --os=linux --cpu=${process.arch} --libc=${libcFamily}\`.`
+    : "";
+  return `Could not find ${pkg}. Run 'npm install' to install the platform-specific binary.${hint}\n`;
 }
 
 function printVerifyError(verifyResult) {
@@ -134,22 +145,113 @@ function readResolvedVersion(manifestPath) {
   }
 }
 
+// `fallow` does not depend on its companions (`fallow-type-aware`,
+// `fallow-similar-code`): a project installs one at the same version when it
+// uses it. npm and Yarn hoist it next to `fallow`. pnpm links it only into the
+// project node_modules, so a second lookup starts at the project root. That
+// lookup accepts a companion only when it is in the same node_modules tree as
+// the running `fallow` package, so a global `fallow` never runs a companion
+// that a cloned project ships. Only an exact version match is accepted.
+function resolveCompanionManifest(
+  packageName,
+  fallowVersion,
+  {
+    resolvePackage = require.resolve,
+    readFile = fs.readFileSync,
+    projectRoot = process.cwd(),
+    launcherDir = __dirname,
+  } = {},
+) {
+  const local = matchingManifest(packageName, fallowVersion, resolvePackage, readFile, undefined);
+  if (local !== undefined) return local;
+  const project = matchingManifest(packageName, fallowVersion, resolvePackage, readFile, {
+    paths: [projectRoot],
+  });
+  if (project === undefined) return undefined;
+  const tree = installTree(launcherDir);
+  return tree !== null && tree === installTree(project) ? project : undefined;
+}
+
+function matchingManifest(packageName, fallowVersion, resolvePackage, readFile, options) {
+  try {
+    const manifestPath = resolvePackage(`${packageName}/package.json`, options);
+    const manifest = JSON.parse(readFile(manifestPath, "utf8"));
+    return manifest.version === fallowVersion ? manifestPath : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// The outermost node_modules directory of a real path, or null outside one.
+function installTree(file) {
+  let real;
+  try {
+    real = fs.realpathSync.native(file);
+  } catch {
+    return null;
+  }
+  const parts = real.split(path.sep);
+  const index = parts.indexOf("node_modules");
+  return index === -1 ? null : parts.slice(0, index + 1).join(path.sep);
+}
+
 function resolveTypeAwareCompanion(
   fallowVersion,
   resolvePackage = require.resolve,
   readFile = fs.readFileSync,
+  projectRoot = process.cwd(),
+  launcherDir = __dirname,
 ) {
+  const manifestPath = resolveCompanionManifest("fallow-type-aware", fallowVersion, {
+    resolvePackage,
+    readFile,
+    projectRoot,
+    launcherDir,
+  });
+  if (manifestPath === undefined) return undefined;
+  const companion = path.join(path.dirname(manifestPath), "fallow-type-aware.mjs");
+  return fs.existsSync(companion) ? companion : undefined;
+}
+
+// The binary of the exact-version `fallow-similar-code` package, after its own
+// resolver and verifier accept it (the Node API loader uses the same pair).
+// The Rust code checks the signature again before it runs the binary.
+function resolveSimilarCodeProvider(fallowVersion, options = {}) {
+  const { report = reportToStderr } = options;
+  const manifestPath = resolveCompanionManifest("fallow-similar-code", fallowVersion, options);
+  if (manifestPath === undefined) return undefined;
+  const scripts = path.join(path.dirname(manifestPath), "scripts");
   try {
-    const manifestPath = resolvePackage("fallow-type-aware/package.json");
-    const manifest = JSON.parse(readFile(manifestPath, "utf8"));
-    if (manifest.version !== fallowVersion) return undefined;
-    const companion = path.join(path.dirname(manifestPath), "fallow-type-aware.mjs");
-    return fs.existsSync(companion) ? companion : undefined;
+    const { resolveBinaryArtifact, resolvePlatformPackage } = require(
+      path.join(scripts, "run-binary.js"),
+    );
+    const { verifyBinary } = require(path.join(scripts, "verify-binary.js"));
+    const artifact = resolveBinaryArtifact(resolvePlatformPackage());
+    const verification = verifyBinary(artifact);
+    if (verification.ok) return artifact.binaryPath;
+    report(`fallow: the similar-code companion failed verification: ${verification.message}\n`);
+  } catch (error) {
+    report(`fallow: the similar-code companion failed verification: ${error.message}\n`);
+  }
+  return undefined;
+}
+
+// Write to fd 2 directly: under Bun, `process.stderr` makes the pipes that the
+// child inherits non-blocking (issue #3276). A failed write is ignored.
+function reportToStderr(message) {
+  try {
+    fs.writeSync(2, message);
   } catch {
-    return undefined;
+    // Best effort.
   }
 }
 
+// Only these commands start the similar-code provider, so other runs skip the
+// lookup and its digest check.
+function usesSimilarCode(args) {
+  return args.includes("similar-code") || args.includes("mcp-server");
+}
+
 function typeAwareCommand(
   companion,
   { platform = process.platform, execPath = process.execPath } = {},
@@ -163,14 +265,27 @@ function childEnvironment(
   resolvedVersion,
   resolveCompanion = resolveTypeAwareCompanion,
   commandOptions,
+  { args = [], resolveProvider = resolveSimilarCodeProvider } = {},
 ) {
-  if (process.env.FALLOW_TYPE_AWARE_BIN) return process.env;
-  const companion = resolveCompanion(resolvedVersion);
-  if (companion === undefined) return process.env;
+  let environment = process.env;
+  if (!process.env.FALLOW_TYPE_AWARE_BIN) {
+    const companion = resolveCompanion(resolvedVersion);
+    if (companion !== undefined) {
+      environment = typeAwareEnvironment(environment, typeAwareCommand(companion, commandOptions));
+    }
+  }
+  if (!process.env[SIMILAR_CODE_PROVIDER_ENV] && usesSimilarCode(args)) {
+    const provider = resolveProvider(resolvedVersion);
+    if (provider !== undefined) {
+      environment = { ...environment, [SIMILAR_CODE_PROVIDER_ENV]: provider };
+    }
+  }
+  return environment;
+}
 
-  const command = typeAwareCommand(companion, commandOptions);
+function typeAwareEnvironment(base, command) {
   const environment = {
-    ...process.env,
+    ...base,
     FALLOW_TYPE_AWARE_BIN: command.binary,
     // Marks the wiring as launcher-provided node_modules resolution so
     // `type-aware status` does not report it as a user-set override.
@@ -232,7 +347,9 @@ function runBinary(binaryBaseName, options = {}) {
   try {
     execFileSync(binaryPath, [...prependArgs, ...process.argv.slice(2)], {
       stdio: "inherit",
-      env: childEnvironment(resolvedVersion),
+      env: childEnvironment(resolvedVersion, undefined, undefined, {
+        args: [...prependArgs, ...process.argv.slice(2)],
+      }),
     });
   } catch (e) {
     if (e.status === undefined) throw e;
@@ -254,6 +371,8 @@ module.exports = {
   isVersionQuery, // test-only
   guardBrokenStdout, // test-only
   exitCodeForChildFailure, // test-only
+  missingPlatformPackageMessage, // test-only
   resolveTypeAwareCompanion, // test-only
+  resolveSimilarCodeProvider, // test-only
   childEnvironment, // test-only
 };

package/scripts/verify-binary.js

@@ -31,7 +31,10 @@ const crypto = require("node:crypto");
 const fs = require("node:fs");
 const https = require("node:https");
 const path = require("node:path");
-const { getPlatformPackage } = require("./platform-package");
+const {
+  getPlatformPackageCandidates,
+  resolveInstalledPlatformPackage,
+} = require("./platform-package");
 
 const GITHUB_REPO = "fallow-rs/fallow";
 const DIGEST_TIMEOUT_MS = 10000;
@@ -296,16 +299,10 @@ function binaryTargetsForPlatform(platformId) {
   // and tests can synthesize a Windows verify without running on Windows.
   const isWindows = typeof platformId === "string" && platformId.startsWith("win32");
   const ext = isWindows ? ".exe" : "";
-  // The platform package ships the multicall CLI plus the local-only
-  // similar-code provider. Both are signed and digest-pinned. Verifying them
-  // together keeps the Rust sibling lookup free of project or PATH overrides.
-  return [
-    { binary: `fallow${ext}`, asset: `fallow-${platformId}${ext}` },
-    {
-      binary: `fallow-similar-code${ext}`,
-      asset: `fallow-similar-code-${platformId}${ext}`,
-    },
-  ];
+  // The platform package ships only the multicall CLI. The similar-code
+  // provider ships in the `fallow-similar-code` package, whose own verifier
+  // checks it.
+  return [{ binary: `fallow${ext}`, asset: `fallow-${platformId}${ext}` }];
 }
 
 function isSkipRequested(env = process.env) {
@@ -313,17 +310,24 @@ function isSkipRequested(env = process.env) {
   return v === "1" || v === "true" || v === "yes";
 }
 
-function currentPlatformPackageName() {
-  if (process.platform !== "linux") {
-    return getPlatformPackage(process.platform, process.arch);
-  }
+// The same selection as the launcher in run-binary.js, so that verification
+// checks the binary that the launcher runs.
+function currentPlatformPackageName(resolveFrom) {
   let libcFamily;
-  try {
-    libcFamily = require("detect-libc").familySync();
-  } catch {
-    libcFamily = undefined;
+  if (process.platform === "linux") {
+    try {
+      libcFamily = require("detect-libc").familySync();
+    } catch {
+      libcFamily = undefined;
+    }
   }
-  return getPlatformPackage(process.platform, process.arch, libcFamily);
+  const candidates = getPlatformPackageCandidates(process.platform, process.arch, libcFamily);
+  if (candidates.length === 0) return null;
+  const options = resolveFrom ? { paths: [resolveFrom] } : undefined;
+  const installed = resolveInstalledPlatformPackage(candidates, (request) =>
+    require.resolve(request, options),
+  );
+  return installed ? installed.pkg : candidates[0];
 }
 
 function readManifestForPackage(manifestPath, pkg) {
@@ -366,7 +370,7 @@ function resolvePlatformPackageForVerify(opts) {
     };
   }
 
-  const pkg = currentPlatformPackageName();
+  const pkg = currentPlatformPackageName(opts.resolveFrom);
   if (!pkg) {
     return {
       ok: false,

package/skills/fallow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fallow
-description: Codebase intelligence for TypeScript and JavaScript. Static analysis reports changed-code risk, cleanup opportunities, duplication, circular dependencies, complexity hotspots, architecture boundaries, design-system drift, feature flags, and opt-in security candidates. Optional local similar-code discovery finds functions that may implement the same intent despite different syntax. Runtime coverage can merge production execution data. Use when asked to audit PR risk, find unused code or dependencies, compare semantically similar functions, detect duplicates, inspect architecture boundaries, merge runtime coverage, auto-fix supported issues, or run fallow.
+description: Codebase intelligence for TypeScript and JavaScript. Static analysis reports changed-code risk, cleanup opportunities, duplication, circular dependencies, complexity hotspots, architecture boundaries, design-system drift, feature flags, and opt-in security candidates. Opt-in mutation testing reports the code changes that no test detects. Optional local similar-code discovery finds functions that may implement the same intent despite different syntax. Runtime coverage can merge production execution data. Use when asked to audit PR risk, find unused code or dependencies, compare semantically similar functions, detect duplicates, inspect architecture boundaries, merge runtime coverage, improve or check the tests of a change, auto-fix supported issues, or run fallow.
 license: MIT
 ---
 
@@ -19,6 +19,7 @@ Fallow analyzes code and styles for changed-code risk, cleanup opportunities, ci
 - Investigate why a specific export, dependency, file, or issue type was reported.
 - Surface local security candidates for an agent to verify (`fallow security`).
 - Find untested but runtime-reachable code (`fallow health --coverage-gaps`).
+- Improve or check the tests of a change: find the small code changes (mutants) that no test detects (`fallow mutation`, opt-in, because a run executes the project tests).
 - Rank complexity hotspots, owners, and refactoring targets (`fallow health --hotspots --ownership --targets`).
 - Review what fallow has surfaced over time (`fallow impact`).
 - Confirm exact TypeScript symbol use, affected tests, API leaks, or public type coupling when syntactic evidence is insufficient (`--type-aware`).
@@ -92,6 +93,7 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | prioritize refactoring | `fallow health --hotspots --targets` |
 | ask who owns code | `fallow health --ownership` |
 | check untested-but-reachable code | `fallow health --coverage-gaps` |
+| improve or check the tests of a change | `fallow mutation --plan --base <ref>`; The plan runs no code. Without `--plan`, the command runs the project tests against each mutant, so ask the user first. |
 | consolidate duplication | `fallow dupes --trace dup:<fingerprint>` |
 | find feature flags | `fallow flags` |
 | check which architecture rules apply to a file before changing it | `fallow guard <files>` |
@@ -183,6 +185,17 @@ Step 3 is your review. Read `digest.decisions[]` and `change_anchors[]` in the g
 
 Fallow validates the judgment against the live graph. It rejects an id that it did not emit. It refuses the whole file as `stale` when the hash no longer matches. Report only the `accepted` judgments. Keep the guide outside the project: a new file in the tree changes the hash. Do not create `.fallow/` for it, because a folder that you create has no ignore file. On `stale: true`, fetch the guide again.
 
+### Improve the tests of a change
+```bash
+fallow mutation --plan --base main --format json --quiet   # the plan: runs no code
+fallow mutation --base main --format json --quiet          # the run: executes the project tests
+fallow mutation tasks --format json --quiet                # the open mutants: runs no code
+fallow mutation inspect <mutant_id> --format json --quiet  # one mutant: runs no code
+fallow mutation --recheck --format json --quiet            # after new tests: runs only the open mutants
+```
+
+Start the run when the user asks for better tests or for mutation testing. In each other task, show the plan and ask. A run exits 2 on uncommitted files: pass `--allow-dirty`, and do not commit for the user. A `survived` mutant is a code change that no test detects. Write a behavior test for each one that a caller can observe, then recheck. Do not write a test that only pins an implementation detail, and do not pass `--allow-side-effects` unless the user asks. The runners are Vitest, `node:test` and `bun test`. The Fallow plugin has a `fallow-mutation` skill with the full method.
+
 ### Find code duplication
 ```bash
 fallow dupes --format json --quiet
@@ -215,6 +228,13 @@ fallow dead-code --format json --quiet --production
 
 Excludes test/dev files (`*.test.*`, `*.spec.*`, `*.stories.*`) and only analyzes production scripts.
 
+### Review parameters that each call passes in one way
+```bash
+fallow dead-code --constant-parameters --production --format json --quiet
+```
+
+The opt-in rule reports a function parameter that each visible call passes the same value (`identical-argument`), or an optional parameter that no call passes (`never-passed`). The same value is the same literal, or the same `const` with a literal initializer or enum member (`value.kind` is `binding`). A finding with `option_key` is about one key of an object-pattern parameter, such as `retries` in `{ retries = 3 }`. It reports only when it sees each caller, and it never reports a function that a test file declares. Start with findings where `condition_reads` is above 0: a condition tests the constant, so a branch cannot run. Read the `inspected_call_sites` and the intent before a change. Keep a deliberate option, a test seam, or a parameter that matches a sibling API. `--production` drops test callers. With `--type-aware`, the rule also reports `unused-default` (each call passes a value whose type excludes `undefined`, so the default never applies) and reads the methods of exported classes (`function_name` is `Class.method`). These findings carry `evidence: "type-aware"`: a type does not prove a run-time value, so check that no `any` value or cast reaches the parameter. There is no auto-fix.
+
 ### Analyze specific workspaces
 ```bash
 fallow dead-code --format json --quiet --workspace my-package                # single package (lists: web,admin)
@@ -355,7 +375,9 @@ fallow dead-code --type-aware --symbol-impact src/api.ts:Client --format json --
 fallow health --type-aware --type-coupling --format json --quiet
 ```
 
-The optional companion must match the installed Fallow version. Semantic
+The `fallow-type-aware` companion is an install on demand
+(`npm install --save-dev fallow-type-aware@<fallow version>`), and it must
+match the installed Fallow version. Semantic
 results expose completeness, per-candidate decisions, and omissions.
 `confirmed-used` and `contract-preserved` remove syntactic false positives.
 `confirmed-no-static-references` retains the finding and only enables a guarded
@@ -375,7 +397,7 @@ Auto-detects `knip.json`, `knip.jsonc`, `.knip.json`, `.knip.jsonc`, `.jscpd.jso
 ```bash
 fallow init              # creates .fallowrc.json, adds .fallow/ to .gitignore (--toml for fallow.toml)
 fallow init --agents     # scaffolds a starter AGENTS.md prefilled from detected project info (never overwrites)
-fallow hooks install --target git   # pre-commit gate; --branch <ref> sets the fallback base branch
+fallow hooks install --target git   # pre-commit gate: audits the staged index (fallow audit --staged)
 ```
 
 ## Exit Codes