fallow 2.76.0 → 2.78.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fallow",
-  "version": "2.76.0",
-  "description": "Codebase intelligence for TypeScript and JavaScript. Finds unused code, duplication, circular dependencies, complexity hotspots, and architecture drift. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, 94 framework plugins.",
+  "version": "2.78.0",
+  "description": "Codebase intelligence for TypeScript and JavaScript. Finds unused code, duplication, circular dependencies, complexity hotspots, and architecture drift. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, 95 framework plugins.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -64,22 +64,23 @@
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
-    "test:platform": "node --test scripts/platform-package.test.js"
+    "test:platform": "node --test scripts/platform-package.test.js",
+    "test:verify": "node --test scripts/verify-binary.test.js"
   },
   "dependencies": {
     "detect-libc": "2.1.2"
   },
   "devDependencies": {
-    "@tanstack/intent": "0.0.40"
+    "@tanstack/intent": "0.0.41"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.76.0",
-    "@fallow-cli/darwin-x64": "2.76.0",
-    "@fallow-cli/linux-x64-gnu": "2.76.0",
-    "@fallow-cli/linux-arm64-gnu": "2.76.0",
-    "@fallow-cli/linux-x64-musl": "2.76.0",
-    "@fallow-cli/linux-arm64-musl": "2.76.0",
-    "@fallow-cli/win32-arm64-msvc": "2.76.0",
-    "@fallow-cli/win32-x64-msvc": "2.76.0"
+    "@fallow-cli/darwin-arm64": "2.78.0",
+    "@fallow-cli/darwin-x64": "2.78.0",
+    "@fallow-cli/linux-x64-gnu": "2.78.0",
+    "@fallow-cli/linux-arm64-gnu": "2.78.0",
+    "@fallow-cli/linux-x64-musl": "2.78.0",
+    "@fallow-cli/linux-arm64-musl": "2.78.0",
+    "@fallow-cli/win32-arm64-msvc": "2.78.0",
+    "@fallow-cli/win32-x64-msvc": "2.78.0"
   }
 }

package/schema.json

@@ -91,6 +91,13 @@
       "$ref": "#/$defs/IgnoreExportsUsedInFileConfig",
       "default": false
     },
+    "ignoreDecorators": {
+      "description": "Decorators that fallow should NOT treat as evidence of reflective use.\nMembers carrying only these decorators are checked for usage as if they\nwere undecorated. Members carrying any decorator NOT in this list stay\nskipped (frameworks like NestJS, Angular, TypeORM rely on reflection so\nthe conservative default is to keep skipping).\n\nMatching rule: entries containing `.` (e.g. `\"decorators.log\"`) match\nthe full dotted path of a decorator. Bare entries (e.g. `\"step\"` or\n`\"decorators\"`) match the leftmost segment; a bare `\"decorators\"` entry\nthus collapses every `@decorators.*` decorator. Both `\"@step\"` and\n`\"step\"` round-trip equivalently (a leading `@` is stripped before\nmatching).\n\nEntries that never match a decorator in the analyzed codebase produce\na one-time warning at end of run, mirroring the existing\n`usedClassMembers` warn-on-unmatched-pattern behavior. See issue #471.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "usedClassMembers": {
       "description": "Class member method/property rules that should never be flagged as\nunused. Supports plain member names for global suppression and scoped\nobjects with `extends` / `implements` constraints for framework-invoked\nmethods that should only be suppressed on matching classes.",
       "type": "array",
@@ -160,6 +167,7 @@
         "type-only-dependencies": "warn",
         "test-only-dependencies": "warn",
         "circular-dependencies": "error",
+        "re-export-cycle": "warn",
         "boundary-violation": "error",
         "coverage-gaps": "off",
         "feature-flags": "off",
@@ -268,6 +276,10 @@
       "description": "Report unused exports in entry files instead of auto-marking them as\nused. Catches typos in framework exports (e.g. `meatdata` instead of\n`metadata`). The CLI flag `--include-entry-exports` (global) overrides\nthis when set; otherwise the config value is used.",
       "type": "boolean",
       "default": false
+    },
+    "cache": {
+      "description": "Incremental cache tuning. Today the only knob is `maxSizeMb`, which\ncaps the on-disk cache and triggers LRU eviction during save. See\n[`CacheConfig`].",
+      "$ref": "#/$defs/CacheConfig"
     }
   },
   "additionalProperties": false,
@@ -943,6 +955,10 @@
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
+        "re-export-cycle": {
+          "$ref": "#/$defs/Severity",
+          "default": "warn"
+        },
         "boundary-violation": {
           "$ref": "#/$defs/Severity",
           "default": "error"
@@ -1126,7 +1142,7 @@
       "type": "object",
       "properties": {
         "sdkPatterns": {
-          "description": "Additional SDK call patterns to detect as feature flags.\nThese are merged with the built-in patterns (LaunchDarkly, Statsig, Unleash, GrowthBook).",
+          "description": "Additional SDK call patterns to detect as feature flags.\nThese are merged with the built-in patterns for common providers\nincluding LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog,\nVercel Flags, ConfigCat, Flagsmith, Optimizely, and Eppo.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/SdkPattern"
@@ -1440,6 +1456,16 @@
             }
           ]
         },
+        "re-export-cycle": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "boundary-violation": {
           "anyOf": [
             {
@@ -1631,6 +1657,12 @@
           "minimum": 0,
           "default": 0
         },
+        "reExportCycles": {
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0,
+          "default": 0
+        },
         "typeOnlyDependencies": {
           "type": "integer",
           "format": "uint",
@@ -1679,6 +1711,15 @@
             "string",
             "null"
           ]
+        },
+        "cacheMaxAgeDays": {
+          "description": "Maximum age (in days since last reuse or fresh create) of a persistent\nreusable base-snapshot worktree cache entry. Older entries are removed\nat the top of the next `fallow audit` invocation. The env var\n`FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` wins over this field. Unset on both\nsides defaults to 30 days. Setting either source to `0` disables the\nsweep entirely (escape hatch for CI runners that prune caches\nout-of-band). Invalid env var values (non-integer, negative) silently\nfall back to this field / default rather than failing the audit.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0
         }
       }
     },
@@ -1696,6 +1737,22 @@
           "const": "all"
         }
       ]
+    },
+    "CacheConfig": {
+      "description": "Incremental cache configuration.\n\nToday only `maxSizeMb` is exposed. The env var `FALLOW_CACHE_MAX_SIZE`\n(also in MB) wins over this field when both are set. The default cap is\n256 MB; values are interpreted as whole megabytes.",
+      "type": "object",
+      "properties": {
+        "maxSizeMb": {
+          "description": "Maximum on-disk cache size in megabytes. When the serialized cache\nexceeds 80% of this cap during save, the oldest entries are evicted\ndown to 60% of the cap. Default: 256 MB.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
     }
   }
 }

package/scripts/postinstall.js

@@ -1,4 +1,5 @@
 const { getPlatformPackage } = require('./platform-package');
+const { verifyInstalled, SKIP_ENV } = require('./verify-binary');
 
 const pkg = (() => {
   if (process.platform !== 'linux') {
@@ -22,11 +23,41 @@ if (!pkg) {
 }
 
 try {
-  require.resolve(pkg);
+  require.resolve(`${pkg}/package.json`);
 } catch {
   console.warn(
     `fallow: Platform package ${pkg} not installed. ` +
     `This may happen if you used --no-optional. ` +
     `Run 'npm install' to fix.`
   );
+  // Without the platform package there is nothing to verify; keep the existing
+  // soft-fail behavior for --no-optional installs.
+  process.exit(0);
+}
+
+async function main() {
+  const result = await verifyInstalled();
+  if (result.skipped) {
+    console.warn(
+      `fallow: binary verification skipped (${SKIP_ENV}=${process.env[SKIP_ENV]}). ` +
+      `Only set this when you are deliberately replacing the published binary. ` +
+      `See https://github.com/fallow-rs/fallow/blob/main/SECURITY.md for details.`
+    );
+    process.exit(0);
+  }
+  if (!result.ok) {
+    const where = result.binary ? ` ${result.binary}` : '';
+    console.error(
+      `fallow: binary verification failed${where} (${result.code}): ${result.message}. ` +
+      `This usually means the published platform package was tampered with. ` +
+      `See https://github.com/fallow-rs/fallow/blob/main/SECURITY.md for details. ` +
+      `Set ${SKIP_ENV}=1 only if you are deliberately replacing the binary.`
+    );
+    process.exit(1);
+  }
 }
+
+main().catch((err) => {
+  console.error(`fallow: binary verification failed (internal-error): ${err.message}`);
+  process.exit(1);
+});

package/scripts/verify-binary.js

@@ -0,0 +1,347 @@
+// Ed25519 + SHA-256 binary verification for the fallow npm wrapper.
+//
+// Verifies each platform binary against a .sig file shipped alongside it in
+// the @fallow-cli/<platform> package, then cross-checks the binary bytes
+// against the SHA-256 digest published by GitHub Releases for the matching
+// version/platform asset. The .sig is produced at release time by
+// `.github/scripts/sign-binary.mjs` using the workflow's
+// ED25519_BINARY_SIGNING_PRIVATE_KEY secret. The matching public key (32 raw
+// bytes) is embedded below and is identical to the value already trusted by
+// the VS Code extension at editors/vscode/src/download.ts:19-22.
+//
+// Triggered from scripts/postinstall.js and from the GitHub Action installer
+// at action/scripts/install.sh. The escape hatch FALLOW_SKIP_BINARY_VERIFY=1
+// is documented in SECURITY.md.
+//
+// No external dependencies: uses node:crypto and node:fs only. Refs #465.
+
+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 GITHUB_REPO = 'fallow-rs/fallow';
+const DIGEST_TIMEOUT_MS = 10000;
+
+// 32-byte Ed25519 public key, identical to BINARY_SIGNING_PUBLIC_KEY in
+// editors/vscode/src/download.ts:19-22 and to the ED25519_BINARY_SIGNING_PUBLIC_KEY
+// repo variable on fallow-rs/fallow. Embedded rather than fetched so verification
+// works offline and cannot be silently downgraded by tampering with the network
+// path.
+const EMBEDDED_PUBLIC_KEY = Buffer.from([
+  131, 78, 111, 215, 115, 51, 230, 238, 223, 119, 147, 71, 199, 16, 172, 180, 3, 210, 216, 35,
+  77, 85, 159, 94, 215, 200, 126, 85, 42, 222, 11, 209,
+]);
+
+// SPKI DER header for Ed25519 (RFC 8410). 12 bytes prepended to a 32-byte raw
+// public key produces a complete SPKI structure that node:crypto.createPublicKey
+// accepts directly.
+const ED25519_SPKI_HEADER = Buffer.from([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+]);
+
+const SKIP_ENV = 'FALLOW_SKIP_BINARY_VERIFY';
+
+function buildPublicKey(rawPubKey) {
+  if (!Buffer.isBuffer(rawPubKey) || rawPubKey.length !== 32) {
+    throw new Error('expected 32-byte raw Ed25519 public key');
+  }
+  const spki = Buffer.concat([ED25519_SPKI_HEADER, rawPubKey]);
+  return crypto.createPublicKey({ key: spki, format: 'der', type: 'spki' });
+}
+
+function _verifyWithKey(binaryPath, rawPubKey) {
+  let binaryBytes;
+  try {
+    binaryBytes = fs.readFileSync(binaryPath);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { ok: false, code: 'binary-missing', message: `binary not found at ${binaryPath}` };
+    }
+    return { ok: false, code: 'read-error', message: `cannot read binary at ${binaryPath}: ${err.message}` };
+  }
+
+  const sigPath = `${binaryPath}.sig`;
+  let signature;
+  try {
+    signature = fs.readFileSync(sigPath);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { ok: false, code: 'sig-missing', message: `signature not found at ${sigPath}` };
+    }
+    return { ok: false, code: 'read-error', message: `cannot read signature at ${sigPath}: ${err.message}` };
+  }
+
+  if (signature.length !== 64) {
+    return { ok: false, code: 'sig-invalid', message: `signature at ${sigPath} has unexpected length ${signature.length} (want 64)` };
+  }
+
+  let publicKey;
+  try {
+    publicKey = buildPublicKey(rawPubKey);
+  } catch (err) {
+    return { ok: false, code: 'key-invalid', message: `cannot construct public key: ${err.message}` };
+  }
+
+  let valid;
+  try {
+    valid = crypto.verify(null, binaryBytes, publicKey, signature);
+  } catch (err) {
+    return { ok: false, code: 'sig-invalid', message: `crypto.verify threw: ${err.message}` };
+  }
+  if (!valid) {
+    return { ok: false, code: 'sig-invalid', message: `Ed25519 verification failed for ${binaryPath}` };
+  }
+  return { ok: true };
+}
+
+function verifyBinaryAt(binaryPath) {
+  return _verifyWithKey(binaryPath, EMBEDDED_PUBLIC_KEY);
+}
+
+function normalizeDigest(digest) {
+  if (typeof digest !== 'string') {
+    return null;
+  }
+  const lower = digest.trim().toLowerCase();
+  const value = lower.startsWith('sha256:') ? lower.slice('sha256:'.length) : lower;
+  return /^[0-9a-f]{64}$/.test(value) ? value : null;
+}
+
+function sha256Hex(binaryPath) {
+  try {
+    return { ok: true, digest: crypto.createHash('sha256').update(fs.readFileSync(binaryPath)).digest('hex') };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { ok: false, code: 'binary-missing', message: `binary not found at ${binaryPath}` };
+    }
+    return { ok: false, code: 'read-error', message: `cannot read binary at ${binaryPath}: ${err.message}` };
+  }
+}
+
+function verifyDigestAt(binaryPath, expectedDigest) {
+  const normalized = normalizeDigest(expectedDigest);
+  if (!normalized) {
+    return { ok: false, code: 'digest-invalid', message: `invalid SHA-256 digest '${expectedDigest}'` };
+  }
+
+  const actual = sha256Hex(binaryPath);
+  if (!actual.ok) {
+    return actual;
+  }
+  if (actual.digest !== normalized) {
+    return {
+      ok: false,
+      code: 'digest-mismatch',
+      message: `SHA-256 digest mismatch for ${binaryPath}: got ${actual.digest}, want ${normalized}`,
+    };
+  }
+  return { ok: true };
+}
+
+function httpsJson(url, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(
+      url,
+      { headers: { 'User-Agent': 'fallow-binary-verifier' }, timeout: DIGEST_TIMEOUT_MS },
+      (response) => {
+        if (
+          response.statusCode &&
+          response.statusCode >= 300 &&
+          response.statusCode < 400 &&
+          response.headers.location &&
+          redirects < 5
+        ) {
+          response.resume();
+          httpsJson(response.headers.location, redirects + 1).then(resolve, reject);
+          return;
+        }
+
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => {
+          const body = Buffer.concat(chunks).toString('utf8');
+          if (!response.statusCode || response.statusCode >= 400) {
+            reject(new Error(`GitHub release API returned HTTP ${response.statusCode || 'unknown'}: ${body.slice(0, 200)}`));
+            return;
+          }
+          try {
+            resolve(JSON.parse(body));
+          } catch (err) {
+            reject(new Error(`GitHub release API returned invalid JSON: ${err.message}`));
+          }
+        });
+      },
+    );
+    request.on('timeout', () => request.destroy(new Error(`timed out after ${DIGEST_TIMEOUT_MS}ms`)));
+    request.on('error', reject);
+  });
+}
+
+const releaseDigestCache = new Map();
+
+async function fetchReleaseDigest(version, assetName) {
+  const key = version;
+  let release = releaseDigestCache.get(key);
+  if (!release) {
+    const url = `https://api.github.com/repos/${GITHUB_REPO}/releases/tags/v${version}`;
+    release = await httpsJson(url);
+    releaseDigestCache.set(key, release);
+  }
+  const asset = Array.isArray(release.assets)
+    ? release.assets.find((candidate) => candidate && candidate.name === assetName)
+    : null;
+  if (!asset) {
+    throw new Error(`release v${version} does not contain asset ${assetName}`);
+  }
+  const digest = normalizeDigest(asset.digest);
+  if (!digest) {
+    throw new Error(`release asset ${assetName} is missing a valid SHA-256 digest`);
+  }
+  return digest;
+}
+
+function platformPackageDir(pkg, resolveFrom) {
+  // require.resolve('<pkg>/package.json') is reliable across npm, pnpm, yarn,
+  // bun. It returns the absolute path to the package's package.json; the
+  // binaries sit next to it.
+  const options = resolveFrom ? { paths: [resolveFrom] } : undefined;
+  const manifestPath = require.resolve(`${pkg}/package.json`, options);
+  return { dir: path.dirname(manifestPath), manifestPath };
+}
+
+function binaryTargetsForPlatform(platformId) {
+  const isWindows = process.platform === 'win32';
+  const ext = isWindows ? '.exe' : '';
+  return [
+    { binary: `fallow${ext}`, asset: `fallow-${platformId}${ext}` },
+    { binary: `fallow-lsp${ext}`, asset: `fallow-lsp-${platformId}${ext}` },
+    { binary: `fallow-mcp${ext}`, asset: `fallow-mcp-${platformId}${ext}` },
+  ];
+}
+
+function isSkipRequested() {
+  const v = process.env[SKIP_ENV];
+  return v === '1' || v === 'true' || v === 'yes';
+}
+
+// Locate the platform package the wrapper would use at runtime and verify
+// each of its three binaries. Returns the same result shape as
+// verifyBinaryAt, with `binary` populated on failure so callers can produce
+// a useful error.
+//
+// options:
+//   allowSkipEnv  - if false, ignore FALLOW_SKIP_BINARY_VERIFY. Default true.
+//   dirOverride   - absolute path to a directory containing the binaries.
+//                   Skips platform-package resolution entirely. Test-only
+//                   knob; production call sites must not pass it.
+//   verifyFn      - function (binaryPath) -> result. Replaces verifyBinaryAt
+//                   for tests that need to inject a non-production key.
+//   digestProvider - function ({ assetName, binaryPath, packageName, version })
+//                   -> sha256 digest. Replaces GitHub Release API lookup in tests.
+//   resolveFrom    - module resolution base for locating platform packages.
+//                   The GitHub Action passes the global npm root so verifier
+//                   code from the action checkout does not trust installed code.
+async function verifyInstalled(options) {
+  const opts = options || {};
+  const skipEnvAllowed = opts.allowSkipEnv !== false;
+  if (skipEnvAllowed && isSkipRequested()) {
+    return { ok: true, skipped: true, reason: `${SKIP_ENV} is set` };
+  }
+
+  const verify = typeof opts.verifyFn === 'function' ? opts.verifyFn : verifyBinaryAt;
+  const digestProvider = typeof opts.digestProvider === 'function'
+    ? opts.digestProvider
+    : ({ assetName, version }) => fetchReleaseDigest(version, assetName);
+
+  let dir;
+  let manifestPath;
+  let pkg;
+  let version;
+  let platformId;
+  if (typeof opts.dirOverride === 'string' && opts.dirOverride.length > 0) {
+    dir = opts.dirOverride;
+    pkg = '<override>';
+    version = opts.version || '0.0.0';
+    platformId = opts.platformId || 'test-platform';
+  } else {
+    if (process.platform !== 'linux') {
+      pkg = getPlatformPackage(process.platform, process.arch);
+    } else {
+      let libcFamily;
+      try {
+        libcFamily = require('detect-libc').familySync();
+      } catch {
+        // detect-libc is a dependency, but tolerate its absence the same way
+        // postinstall.js already does.
+        libcFamily = undefined;
+      }
+      pkg = getPlatformPackage(process.platform, process.arch, libcFamily);
+    }
+
+    if (!pkg) {
+      return { ok: false, code: 'platform-unsupported', message: `no prebuilt binary for ${process.platform}-${process.arch}` };
+    }
+
+    try {
+      ({ dir, manifestPath } = platformPackageDir(pkg, opts.resolveFrom));
+    } catch (err) {
+      return { ok: false, code: 'platform-package-missing', message: `platform package ${pkg} not installed: ${err.message}`, package: pkg };
+    }
+
+    platformId = pkg.replace(/^@fallow-cli\//, '');
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      version = manifest.version;
+    } catch (err) {
+      return { ok: false, code: 'manifest-invalid', message: `cannot read platform package manifest for ${pkg}: ${err.message}`, package: pkg };
+    }
+    if (typeof version !== 'string' || !version.trim()) {
+      return { ok: false, code: 'manifest-invalid', message: `platform package ${pkg} does not declare a version`, package: pkg };
+    }
+  }
+
+  for (const target of binaryTargetsForPlatform(platformId)) {
+    const binaryPath = path.join(dir, target.binary);
+    const result = verify(binaryPath);
+    if (!result.ok) {
+      return { ...result, binary: binaryPath, package: pkg };
+    }
+    let expectedDigest;
+    try {
+      expectedDigest = await digestProvider({
+        assetName: target.asset,
+        binaryPath,
+        packageName: pkg,
+        version,
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        code: 'digest-unavailable',
+        message: `cannot load SHA-256 digest for ${target.asset}: ${err.message}`,
+        binary: binaryPath,
+        package: pkg,
+      };
+    }
+    const digestResult = verifyDigestAt(binaryPath, expectedDigest);
+    if (!digestResult.ok) {
+      return { ...digestResult, binary: binaryPath, package: pkg };
+    }
+  }
+  return { ok: true, package: pkg, version };
+}
+
+module.exports = {
+  verifyBinaryAt,
+  verifyDigestAt,
+  verifyInstalled,
+  _verifyWithKey,
+  fetchReleaseDigest,
+  normalizeDigest,
+  sha256Hex,
+  EMBEDDED_PUBLIC_KEY,
+  ED25519_SPKI_HEADER,
+  SKIP_ENV,
+};