fallow 2.77.0 → 2.78.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.77.0",
+  "version": "2.78.1",
   "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": {
@@ -74,13 +74,13 @@
     "@tanstack/intent": "0.0.41"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.77.0",
-    "@fallow-cli/darwin-x64": "2.77.0",
-    "@fallow-cli/linux-x64-gnu": "2.77.0",
-    "@fallow-cli/linux-arm64-gnu": "2.77.0",
-    "@fallow-cli/linux-x64-musl": "2.77.0",
-    "@fallow-cli/linux-arm64-musl": "2.77.0",
-    "@fallow-cli/win32-arm64-msvc": "2.77.0",
-    "@fallow-cli/win32-x64-msvc": "2.77.0"
+    "@fallow-cli/darwin-arm64": "2.78.1",
+    "@fallow-cli/darwin-x64": "2.78.1",
+    "@fallow-cli/linux-x64-gnu": "2.78.1",
+    "@fallow-cli/linux-arm64-gnu": "2.78.1",
+    "@fallow-cli/linux-x64-musl": "2.78.1",
+    "@fallow-cli/linux-arm64-musl": "2.78.1",
+    "@fallow-cli/win32-arm64-msvc": "2.78.1",
+    "@fallow-cli/win32-x64-msvc": "2.78.1"
   }
 }

package/schema.json

@@ -1142,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"

package/scripts/verify-binary.js

@@ -2,18 +2,27 @@
 //
 // 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
+// against an expected SHA-256 digest. 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.
 //
+// SHA-256 digest source (in order of preference, refs #465 and #597):
+//   1. `fallowDigests` field in the platform package's package.json, written
+//      at release time by the `npm-prep` job. This is the steady-state path:
+//      no network traffic, immune to GitHub API rate limits.
+//   2. Fallback: GitHub Release asset digest via the public REST API. Kept
+//      for backwards compatibility with platform packages published before
+//      #597 that lack the embedded field. Shared-IP CI runners (Buildkite,
+//      pooled GHA runners) can exceed the 60 req/hr unauthenticated limit;
+//      that failure mode is what motivated #597.
+//
 // 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.
+// No external dependencies: uses node:crypto and node:fs only.
 
 const crypto = require('node:crypto');
 const fs = require('node:fs');
@@ -211,6 +220,31 @@ function platformPackageDir(pkg, resolveFrom) {
   return { dir: path.dirname(manifestPath), manifestPath };
 }
 
+// Read the SHA-256 digest for a binary embedded in the platform package's
+// package.json (written by the npm-prep job at release time as
+// `fallowDigests[<filename>]`). Returns the normalized digest hex or null
+// when the manifest does not exist, cannot be parsed, lacks the field, or
+// the value is malformed. Refs #597.
+function readEmbeddedDigest(manifestPath, binaryFileName) {
+  if (typeof manifestPath !== 'string' || manifestPath.length === 0) {
+    return null;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!manifest || typeof manifest !== 'object') {
+    return null;
+  }
+  const digests = manifest.fallowDigests;
+  if (!digests || typeof digests !== 'object') {
+    return null;
+  }
+  return normalizeDigest(digests[binaryFileName]);
+}
+
 function binaryTargetsForPlatform(platformId) {
   const isWindows = process.platform === 'win32';
   const ext = isWindows ? '.exe' : '';
@@ -265,6 +299,9 @@ async function verifyInstalled(options) {
     pkg = '<override>';
     version = opts.version || '0.0.0';
     platformId = opts.platformId || 'test-platform';
+    // Lets tests drop a package.json next to the binaries to exercise the
+    // embedded-digest path. readEmbeddedDigest returns null when missing.
+    manifestPath = path.join(dir, 'package.json');
   } else {
     if (process.platform !== 'linux') {
       pkg = getPlatformPackage(process.platform, process.arch);
@@ -308,22 +345,33 @@ async function verifyInstalled(options) {
     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,
-      };
+    // Prefer the digest embedded in the platform package's package.json
+    // (written at release time by `npm-prep`). Falling back to the GitHub
+    // release API only when no embedded digest is present preserves
+    // backwards compatibility with platform packages published before #597.
+    // The shared-IP CI rate-limit failure mode that motivated #597 only
+    // affects the fallback path, so the steady-state install path is now
+    // fully offline.
+    let expectedDigest = manifestPath
+      ? readEmbeddedDigest(manifestPath, target.binary)
+      : null;
+    if (!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) {
@@ -340,6 +388,7 @@ module.exports = {
   _verifyWithKey,
   fetchReleaseDigest,
   normalizeDigest,
+  readEmbeddedDigest,
   sha256Hex,
   EMBEDDED_PUBLIC_KEY,
   ED25519_SPKI_HEADER,

package/scripts/verify-binary.test.js

@@ -12,6 +12,7 @@ const {
   verifyInstalled,
   sha256Hex,
   normalizeDigest,
+  readEmbeddedDigest,
   EMBEDDED_PUBLIC_KEY,
   ED25519_SPKI_HEADER,
   SKIP_ENV,
@@ -381,6 +382,141 @@ test('verifyInstalled honors FALLOW_SKIP_BINARY_VERIFY', async (t) => {
   assert.equal(result.skipped, true);
 });
 
+function computeDigestsForDir(dir) {
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  const out = {};
+  for (const base of ['fallow', 'fallow-lsp', 'fallow-mcp']) {
+    const fileName = `${base}${ext}`;
+    const full = path.join(dir, fileName);
+    out[fileName] = 'sha256:' + crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex');
+  }
+  return out;
+}
+
+function writeManifest(dir, body) {
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(body));
+}
+
+test('readEmbeddedDigest returns null when manifest is missing', () => {
+  assert.equal(readEmbeddedDigest('/does/not/exist/package.json', 'fallow'), null);
+});
+
+test('readEmbeddedDigest returns null when fallowDigests field is absent', (t) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fallow-vbtest-emb-'));
+  t.after(() => cleanup(dir));
+  writeManifest(dir, { name: '@fallow-cli/x', version: '1.0.0' });
+  assert.equal(readEmbeddedDigest(path.join(dir, 'package.json'), 'fallow'), null);
+});
+
+test('readEmbeddedDigest returns null when the per-binary entry is malformed', (t) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fallow-vbtest-emb-'));
+  t.after(() => cleanup(dir));
+  writeManifest(dir, {
+    name: '@fallow-cli/x',
+    version: '1.0.0',
+    fallowDigests: { fallow: 'not-a-real-digest' },
+  });
+  assert.equal(readEmbeddedDigest(path.join(dir, 'package.json'), 'fallow'), null);
+});
+
+test('readEmbeddedDigest returns normalized hex for a valid sha256: prefixed entry', (t) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fallow-vbtest-emb-'));
+  t.after(() => cleanup(dir));
+  const hex = 'a'.repeat(64);
+  writeManifest(dir, {
+    name: '@fallow-cli/x',
+    version: '1.0.0',
+    fallowDigests: { fallow: 'sha256:' + hex },
+  });
+  assert.equal(readEmbeddedDigest(path.join(dir, 'package.json'), 'fallow'), hex);
+});
+
+test('verifyInstalled uses the embedded digest without calling the provider', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey);
+  t.after(() => cleanup(dir));
+  writeManifest(dir, {
+    name: '@fallow-cli/x',
+    version: '1.0.0',
+    fallowDigests: computeDigestsForDir(dir),
+  });
+  let providerCalls = 0;
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: () => {
+      providerCalls += 1;
+      return Promise.reject(new Error('provider should not be called'));
+    },
+  });
+  assert.equal(result.ok, true, JSON.stringify(result));
+  assert.equal(providerCalls, 0);
+});
+
+test('verifyInstalled falls back to the provider when the embedded digest is missing', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey);
+  t.after(() => cleanup(dir));
+  // No package.json at all; legacy platform package shape.
+  let providerCalls = 0;
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: ({ binaryPath }) => {
+      providerCalls += 1;
+      return Promise.resolve('sha256:' + crypto.createHash('sha256').update(fs.readFileSync(binaryPath)).digest('hex'));
+    },
+  });
+  assert.equal(result.ok, true);
+  assert.equal(providerCalls, 3);
+});
+
+test('verifyInstalled falls back to the provider when fallowDigests is partial / malformed', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey);
+  t.after(() => cleanup(dir));
+  writeManifest(dir, {
+    name: '@fallow-cli/x',
+    version: '1.0.0',
+    fallowDigests: { fallow: 'not-a-real-digest' },
+  });
+  let providerCalls = 0;
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: ({ binaryPath }) => {
+      providerCalls += 1;
+      return Promise.resolve('sha256:' + crypto.createHash('sha256').update(fs.readFileSync(binaryPath)).digest('hex'));
+    },
+  });
+  assert.equal(result.ok, true);
+  // One call per binary because all three entries fail to normalize.
+  assert.equal(providerCalls, 3);
+});
+
+test('verifyInstalled returns digest-mismatch when the embedded digest disagrees with the binary', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey);
+  t.after(() => cleanup(dir));
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  writeManifest(dir, {
+    name: '@fallow-cli/x',
+    version: '1.0.0',
+    fallowDigests: {
+      [`fallow${ext}`]: 'sha256:' + 'a'.repeat(64),
+      [`fallow-lsp${ext}`]: 'sha256:' + 'a'.repeat(64),
+      [`fallow-mcp${ext}`]: 'sha256:' + 'a'.repeat(64),
+    },
+  });
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: () => Promise.reject(new Error('should not be reached')),
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'digest-mismatch');
+});
+
 test('verifyInstalled ignores skip env when allowSkipEnv is false', async (t) => {
   const previous = process.env[SKIP_ENV];
   process.env[SKIP_ENV] = '1';

package/types/output-contract.d.ts

@@ -2169,6 +2169,12 @@ export interface Meta {
  * URL to the documentation page for this command.
  */
 docs?: (string | null)
+/**
+ * Per-field definitions for envelope fields and action payload fields.
+ */
+field_definitions?: {
+[k: string]: string
+}
 /**
  * Per-metric definitions: name, description, range, interpretation.
  */
@@ -4033,15 +4039,15 @@ export interface TargetEvidence {
 /**
  * Names of unused exports (populated for `RemoveDeadCode` targets).
  */
-unused_exports: string[]
+unused_exports?: string[]
 /**
  * Complex functions with line numbers and cognitive scores (populated for `ExtractComplexFunctions`).
  */
-complex_functions: EvidenceFunction[]
+complex_functions?: EvidenceFunction[]
 /**
  * Files forming the import cycle (populated for `BreakCircularDependency` targets).
  */
-cycle_path: string[]
+cycle_path?: string[]
 }
 /**
  * A function referenced in target evidence.
@@ -5479,6 +5485,12 @@ export interface CombinedOutput {
 schema_version: SchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
+/**
+ * Sectioned `_meta` block emitted only when `--explain` is passed.
+ * Contains `check`, `dupes`, and/or `health` keys matching the analyses
+ * enabled for the combined run.
+ */
+_meta?: (CombinedMeta | null)
 /**
  * Dead-code analysis sub-envelope. Absent when `--skip check`.
  */
@@ -5496,6 +5508,23 @@ dupes?: (DupesReportPayload | null)
  */
 health?: (HealthReport | null)
 }
+/**
+ * Sectioned `_meta` block for the bare combined JSON envelope.
+ */
+export interface CombinedMeta {
+/**
+ * Dead-code metadata from `crate::explain::check_meta()`.
+ */
+check?: (Meta | null)
+/**
+ * Duplication metadata from `crate::explain::dupes_meta()`.
+ */
+dupes?: (Meta | null)
+/**
+ * Health metadata from `crate::explain::health_meta()`.
+ */
+health?: (Meta | null)
+}
 /**
  * Single CodeClimate-compatible issue inside [`CodeClimateOutput`].
  */