fallow 2.76.0 → 2.77.0

package/scripts/verify-binary.test.js

@@ -0,0 +1,402 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  _verifyWithKey,
+  verifyBinaryAt,
+  verifyDigestAt,
+  verifyInstalled,
+  sha256Hex,
+  normalizeDigest,
+  EMBEDDED_PUBLIC_KEY,
+  ED25519_SPKI_HEADER,
+  SKIP_ENV,
+} = require('./verify-binary');
+const { getPlatformPackage } = require('./platform-package');
+
+function makeDigestProvider(dir) {
+  return ({ assetName, binaryPath }) => {
+    const data = fs.readFileSync(binaryPath);
+    return Promise.resolve('sha256:' + crypto.createHash('sha256').update(data).digest('hex'));
+  };
+}
+
+function makeMismatchedDigestProvider() {
+  return () => Promise.resolve('sha256:' + 'a'.repeat(64));
+}
+
+function makeKeypair() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519');
+  const spki = publicKey.export({ format: 'der', type: 'spki' });
+  const rawPub = spki.subarray(spki.length - 32);
+  return { privateKey, rawPub };
+}
+
+function makeFixture(binaryBytes, signFn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fallow-vbtest-'));
+  const binaryPath = path.join(dir, 'fallow');
+  fs.writeFileSync(binaryPath, binaryBytes);
+  if (signFn) {
+    fs.writeFileSync(`${binaryPath}.sig`, signFn(binaryBytes));
+  }
+  return { dir, binaryPath };
+}
+
+function cleanup(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+test('embedded public key is 32 bytes and SPKI header is 12 bytes', () => {
+  assert.equal(EMBEDDED_PUBLIC_KEY.length, 32);
+  assert.equal(ED25519_SPKI_HEADER.length, 12);
+});
+
+test('embedded public key reconstructs a valid Ed25519 SPKI key', () => {
+  const spki = Buffer.concat([ED25519_SPKI_HEADER, EMBEDDED_PUBLIC_KEY]);
+  const key = crypto.createPublicKey({ key: spki, format: 'der', type: 'spki' });
+  assert.equal(key.asymmetricKeyType, 'ed25519');
+});
+
+test('_verifyWithKey returns ok for a valid signature', () => {
+  const { privateKey, rawPub } = makeKeypair();
+  const content = Buffer.from('hello world');
+  const { dir, binaryPath } = makeFixture(content, (data) =>
+    crypto.sign(null, data, privateKey),
+  );
+  try {
+    const result = _verifyWithKey(binaryPath, rawPub);
+    assert.deepEqual(result, { ok: true });
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('_verifyWithKey returns sig-invalid when the signature is corrupted', () => {
+  const { privateKey, rawPub } = makeKeypair();
+  const content = Buffer.from('hello world');
+  const { dir, binaryPath } = makeFixture(content, (data) =>
+    crypto.sign(null, data, privateKey),
+  );
+  try {
+    const sig = fs.readFileSync(`${binaryPath}.sig`);
+    sig[0] ^= 0xff;
+    fs.writeFileSync(`${binaryPath}.sig`, sig);
+    const result = _verifyWithKey(binaryPath, rawPub);
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'sig-invalid');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('_verifyWithKey returns sig-invalid for the wrong key', () => {
+  const { rawPub } = makeKeypair();
+  const wrongKey = makeKeypair();
+  const content = Buffer.from('hello world');
+  const { dir, binaryPath } = makeFixture(content, (data) =>
+    crypto.sign(null, data, wrongKey.privateKey),
+  );
+  try {
+    const result = _verifyWithKey(binaryPath, rawPub);
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'sig-invalid');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('_verifyWithKey returns sig-invalid when the binary bytes are tampered', () => {
+  const { privateKey, rawPub } = makeKeypair();
+  const original = Buffer.from('hello world');
+  const { dir, binaryPath } = makeFixture(original, (data) =>
+    crypto.sign(null, data, privateKey),
+  );
+  try {
+    fs.writeFileSync(binaryPath, Buffer.from('tampered'));
+    const result = _verifyWithKey(binaryPath, rawPub);
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'sig-invalid');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('_verifyWithKey returns sig-missing when the signature file does not exist', () => {
+  const { rawPub } = makeKeypair();
+  const { dir, binaryPath } = makeFixture(Buffer.from('hello world'));
+  try {
+    const result = _verifyWithKey(binaryPath, rawPub);
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'sig-missing');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('_verifyWithKey returns binary-missing when the binary does not exist', () => {
+  const { rawPub } = makeKeypair();
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fallow-vbtest-'));
+  try {
+    const result = _verifyWithKey(path.join(dir, 'nonexistent'), rawPub);
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'binary-missing');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('_verifyWithKey returns sig-invalid when the signature length is wrong', () => {
+  const { rawPub } = makeKeypair();
+  const { dir, binaryPath } = makeFixture(Buffer.from('hello'));
+  try {
+    fs.writeFileSync(`${binaryPath}.sig`, Buffer.from('short'));
+    const result = _verifyWithKey(binaryPath, rawPub);
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'sig-invalid');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('_verifyWithKey throws when given a non-32-byte raw public key', () => {
+  const { dir, binaryPath } = makeFixture(Buffer.from('hello world'));
+  try {
+    const result = _verifyWithKey(binaryPath, Buffer.from('too short'));
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'sig-missing');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('verifyBinaryAt uses the embedded production public key', () => {
+  // The embedded key cannot sign our test data because we do not have the
+  // private key, so we only assert that verifyBinaryAt returns sig-invalid
+  // for a random signature against the production key, not the underlying
+  // crypto throwing. This locks in that the public API uses the embedded
+  // key path.
+  const { privateKey } = makeKeypair();
+  const content = Buffer.from('hello world');
+  const { dir, binaryPath } = makeFixture(content, (data) =>
+    crypto.sign(null, data, privateKey),
+  );
+  try {
+    const result = verifyBinaryAt(binaryPath);
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'sig-invalid');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+function makePlatformDir(privateKey, options) {
+  const opts = options || {};
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fallow-vbtest-'));
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  for (const base of ['fallow', 'fallow-lsp', 'fallow-mcp']) {
+    const binaryPath = path.join(dir, `${base}${ext}`);
+    const content = Buffer.from(`mock ${base} contents`);
+    fs.writeFileSync(binaryPath, content);
+    if (opts.skipSigFor === base) {
+      continue;
+    }
+    const data = opts.corruptBinaryFor === base ? Buffer.from('tampered') : content;
+    const sig = crypto.sign(null, data, privateKey);
+    if (opts.corruptSigFor === base) {
+      sig[0] ^= 0xff;
+    }
+    fs.writeFileSync(`${binaryPath}.sig`, sig);
+  }
+  return dir;
+}
+
+function currentPlatformPackage() {
+  if (process.platform !== 'linux') {
+    return getPlatformPackage(process.platform, process.arch);
+  }
+  let libcFamily;
+  try {
+    libcFamily = require('detect-libc').familySync();
+  } catch {
+    libcFamily = undefined;
+  }
+  return getPlatformPackage(process.platform, process.arch, libcFamily);
+}
+
+test('normalizeDigest accepts sha256: prefix and bare hex', () => {
+  const sample = 'a'.repeat(64);
+  assert.equal(normalizeDigest('sha256:' + sample), sample);
+  assert.equal(normalizeDigest(sample), sample);
+  assert.equal(normalizeDigest('SHA256:' + sample.toUpperCase()), sample);
+});
+
+test('normalizeDigest rejects malformed digests', () => {
+  assert.equal(normalizeDigest(null), null);
+  assert.equal(normalizeDigest(''), null);
+  assert.equal(normalizeDigest('not-hex'), null);
+  assert.equal(normalizeDigest('a'.repeat(63)), null);
+});
+
+test('sha256Hex returns 64-char hex over file bytes', () => {
+  const { dir, binaryPath } = makeFixture(Buffer.from('hello world'));
+  try {
+    const result = sha256Hex(binaryPath);
+    assert.equal(result.ok, true);
+    assert.equal(result.digest, crypto.createHash('sha256').update(Buffer.from('hello world')).digest('hex'));
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('verifyDigestAt accepts matching digest and rejects mismatched', () => {
+  const { dir, binaryPath } = makeFixture(Buffer.from('hello world'));
+  try {
+    const correct = crypto.createHash('sha256').update(Buffer.from('hello world')).digest('hex');
+    assert.deepEqual(verifyDigestAt(binaryPath, 'sha256:' + correct), { ok: true });
+    const wrong = 'b'.repeat(64);
+    const bad = verifyDigestAt(binaryPath, wrong);
+    assert.equal(bad.ok, false);
+    assert.equal(bad.code, 'digest-mismatch');
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test('verifyInstalled with dirOverride returns ok when every binary verifies', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey);
+  t.after(() => cleanup(dir));
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(dir),
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.package, '<override>');
+});
+
+test('verifyInstalled resolves a global npm install from the fallow package directory', async (t) => {
+  const pkg = currentPlatformPackage();
+  if (!pkg) {
+    t.skip('unsupported platform');
+    return;
+  }
+
+  const { privateKey, rawPub } = makeKeypair();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fallow-vbtest-global-'));
+  t.after(() => cleanup(root));
+
+  const resolveFrom = path.join(root, 'node_modules', 'fallow');
+  const platformDir = path.join(root, 'node_modules', ...pkg.split('/'));
+  fs.mkdirSync(resolveFrom, { recursive: true });
+  fs.mkdirSync(platformDir, { recursive: true });
+  fs.writeFileSync(path.join(platformDir, 'package.json'), JSON.stringify({ name: pkg, version: '9.9.9' }));
+
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  for (const base of ['fallow', 'fallow-lsp', 'fallow-mcp']) {
+    const binaryPath = path.join(platformDir, `${base}${ext}`);
+    const content = Buffer.from(`global install ${base}`);
+    fs.writeFileSync(binaryPath, content);
+    fs.writeFileSync(`${binaryPath}.sig`, crypto.sign(null, content, privateKey));
+  }
+
+  const result = await verifyInstalled({
+    resolveFrom,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: ({ binaryPath }) => crypto.createHash('sha256').update(fs.readFileSync(binaryPath)).digest('hex'),
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.package, pkg);
+  assert.equal(result.version, '9.9.9');
+});
+
+test('verifyInstalled with dirOverride fails fast on the first bad signature', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey, { corruptSigFor: 'fallow-lsp' });
+  t.after(() => cleanup(dir));
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(dir),
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'sig-invalid');
+  assert.match(result.binary, /fallow-lsp/);
+});
+
+test('verifyInstalled with dirOverride reports sig-missing when a .sig is absent', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey, { skipSigFor: 'fallow-mcp' });
+  t.after(() => cleanup(dir));
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(dir),
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'sig-missing');
+  assert.match(result.binary, /fallow-mcp/);
+});
+
+test('verifyInstalled reports digest-mismatch when SHA-256 disagrees with the provider', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey);
+  t.after(() => cleanup(dir));
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeMismatchedDigestProvider(),
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'digest-mismatch');
+});
+
+test('verifyInstalled reports digest-unavailable when the provider rejects', async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey);
+  t.after(() => cleanup(dir));
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: () => Promise.reject(new Error('network down')),
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, 'digest-unavailable');
+  assert.match(result.message, /network down/);
+});
+
+test('verifyInstalled honors FALLOW_SKIP_BINARY_VERIFY', async (t) => {
+  const previous = process.env[SKIP_ENV];
+  process.env[SKIP_ENV] = '1';
+  t.after(() => {
+    if (previous === undefined) delete process.env[SKIP_ENV];
+    else process.env[SKIP_ENV] = previous;
+  });
+  const result = await verifyInstalled({ dirOverride: '/does/not/exist' });
+  assert.equal(result.ok, true);
+  assert.equal(result.skipped, true);
+});
+
+test('verifyInstalled ignores skip env when allowSkipEnv is false', async (t) => {
+  const previous = process.env[SKIP_ENV];
+  process.env[SKIP_ENV] = '1';
+  t.after(() => {
+    if (previous === undefined) delete process.env[SKIP_ENV];
+    else process.env[SKIP_ENV] = previous;
+  });
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = makePlatformDir(privateKey);
+  t.after(() => cleanup(dir));
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(dir),
+    allowSkipEnv: false,
+  });
+  assert.equal(result.ok, true);
+  assert.notEqual(result.skipped, true);
+});

package/skills/fallow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fallow
-description: Codebase intelligence for JavaScript and TypeScript. Free static layer finds unused code (files, exports, types, dependencies), code duplication, circular dependencies, complexity hotspots, architecture boundary violations, and feature flag patterns. Runtime coverage merges production execution data into the same health report for hot-path review, cold-path deletion confidence, and stale-flag evidence - a single local capture is free, while continuous/cloud runtime monitoring is paid. 94 framework plugins, zero configuration, sub-second static analysis. Use when asked to analyze code health, find unused code, detect duplicates, check circular dependencies, audit complexity, check architecture boundaries, detect feature flags, clean up the codebase, auto-fix issues, merge runtime coverage, or run fallow.
+description: Codebase intelligence for JavaScript and TypeScript. Free static layer finds unused code (files, exports, types, dependencies), code duplication, circular dependencies, complexity hotspots, architecture boundary violations, and feature flag patterns. Runtime coverage merges production execution data into the same health report for hot-path review, cold-path deletion confidence, and stale-flag evidence - a single local capture is free, while continuous/cloud runtime monitoring is paid. 95 framework plugins, zero configuration, sub-second static analysis. Use when asked to analyze code health, find unused code, detect duplicates, check circular dependencies, audit complexity, check architecture boundaries, detect feature flags, clean up the codebase, auto-fix issues, merge runtime coverage, or run fallow.
 license: MIT
 metadata:
   author: Bart Waardenburg
@@ -10,7 +10,7 @@ metadata:
 
 # Fallow: codebase intelligence for JavaScript and TypeScript
 
-Codebase intelligence for JavaScript and TypeScript. The free static layer finds unused code, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, and feature flag patterns. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence: a single local capture is free, while continuous/cloud runtime monitoring is paid. 94 framework plugins, zero configuration, sub-second static analysis.
+Codebase intelligence for JavaScript and TypeScript. The free static layer finds unused code, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, and feature flag patterns. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence: a single local capture is free, while continuous/cloud runtime monitoring is paid. 95 framework plugins, zero configuration, sub-second static analysis.
 
 ## When to Use
 
@@ -372,7 +372,7 @@ export const deprecatedHelper = () => {};
 ## Key Gotchas
 
 - **`fix --yes` is required** in non-TTY (agent) environments. Without it, `fix` exits with code 2
-- **Zero config by default.** 94 framework plugins auto-detect, including tap and tsd test entry points. Don't create config unless customization is needed
+- **Zero config by default.** 95 framework plugins auto-detect, including tap and tsd test entry points. Don't create config unless customization is needed
 - **Syntactic analysis only.** No TypeScript compiler, so fully dynamic `import(variable)` is not resolved
 - **Function overloads are deduplicated.** TypeScript function overload signatures are merged into a single export (not reported as separate unused exports)
 - **Re-export chains are resolved.** Exports through barrel files are tracked, not falsely flagged

package/skills/fallow/references/gotchas.md

@@ -297,9 +297,9 @@ This is separate from the dead code suppression tokens. See the full list of val
 
 ---
 
-## Decorated Members Are Skipped
+## Decorated Members Are Skipped By Default
 
-Class members with decorators (NestJS `@Get()`, Angular `@Input()`, TypeORM `@Column()`, etc.) are automatically excluded from unused member detection. Decorator-driven frameworks consume these via reflection at runtime.
+Class members with decorators (NestJS `@Get()`, Angular `@Input()`, TypeORM `@Column()`, etc.) are excluded from unused member detection by default. Decorator-driven frameworks consume these via reflection at runtime, so reporting them as unused would be a false positive.
 
 ```typescript
 class UserController {
@@ -308,7 +308,20 @@ class UserController {
 }
 ```
 
-This is handled automatically. No suppression needed.
+### Opt specific decorators out via `ignoreDecorators`
+
+If you use utility decorators that DO NOT imply reflective use (Playwright's `@step("label")`, internal labeling decorators like `@measure`, `@log`, `@retry`), list their names in the `ignoreDecorators` config option so the methods carrying them are checked for usage like undecorated methods.
+
+```jsonc
+// .fallowrc.json
+{
+  "ignoreDecorators": ["@step"]
+}
+```
+
+Conservative semantics: a method carrying any decorator NOT in the list still gets skipped. So `@step` + `@Inject` on the same method stays treated as framework-managed. Matching rule: entries containing `.` (`"decorators.log"`) match the full dotted path; bare entries (`"step"` or `"decorators"`) match the leftmost segment, so a single bare `"decorators"` entry collapses an entire `@decorators.*` namespace. Both `"@step"` and `"step"` round-trip equivalently. Unmatched entries (a decorator name in the config that never appears in your codebase) surface as a one-time warning at end of run.
+
+The default empty list preserves today's skip-all behavior, so existing NestJS / Angular / TypeORM projects see no change.
 
 ---
 

package/skills/fallow/references/patterns.md

@@ -621,7 +621,7 @@ Focus on findings that are BOTH dead code and duplicated:
 
 ## Custom Plugin Setup
 
-For frameworks not covered by the 94 built-in plugins.
+For frameworks not covered by the 95 built-in plugins.
 
 ### Option 1: Inline framework config