fallow 2.75.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/cli-reference.md

@@ -203,9 +203,10 @@ Auto-removes unused exports, dependencies, enum members, and pnpm catalog entrie
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--dry-run` | bool | `false` | Show what would be removed without modifying files |
+| `--dry-run` | bool | `false` | Show what would be removed without modifying files. For `add-to-config` actions, prints a unified-diff preview of the proposed config write; JSON mode includes the diff under a `proposed_diff` field on the fix entry. |
 | `--yes` | bool | `false` | Skip confirmation prompt (**required** in non-TTY) |
 | `--force` | bool | `false` | Alias for `--yes` |
+| `--no-create-config` | bool | `false` | Refuse to create a new `.fallowrc.json` when none exists. The duplicate-export config-add path is skipped with `skip_reason: "no_create_config"`; source-file edits proceed normally. Use in pre-commit hooks, CI bots, and `fallow watch` where silently materialising a new top-level file would surprise the user. |
 | `--format` | `human\|json` | `human` | Output format |
 | `--quiet` | bool | `false` | Suppress progress bars |
 
@@ -214,7 +215,8 @@ Auto-removes unused exports, dependencies, enum members, and pnpm catalog entrie
 - Unused exports (removes the `export` keyword; whole-enum block when every member is unused)
 - Unused dependencies (removed from `package.json`)
 - Unused enum members (removed from the declaration)
-- Unused pnpm catalog entries (removed from `pnpm-workspace.yaml` by line-aware deletion; comments preserved). When the last entry of a catalog group is removed, the header is rewritten to `catalog: {}` / `<name>: {}` so pnpm doesn't reject the resulting null value. Entries with non-empty `hardcoded_consumers` are skipped to avoid breaking `pnpm install`; the skip is surfaced in the JSON fix output as `{"type": "remove_catalog_entry", "applied": false, "skipped": true, "skip_reason": "hardcoded_consumers", "consumers": [...]}`. After a successful catalog edit the CLI emits a one-line `Run pnpm install to refresh pnpm-lock.yaml` reminder. The JSON envelope carries a top-level `"skipped"` count alongside `"total_fixed"` for partial-fix gating.
+- Unused pnpm catalog entries (removed from `pnpm-workspace.yaml` by line-aware deletion). Object-form entries are removed as one block. By default, fallow also removes a contiguous YAML comment block immediately above the entry when it clearly belongs to that entry; configure this with `fix.catalog.deletePrecedingComments` (`"auto"`, `"always"`, or `"never"`). Two escape hatches keep curated comments safe regardless of policy: a `# fallow-keep` marker on any line in the block preserves it, and the `auto` policy additionally preserves section-banner blocks whose body starts with three or more `=`, `-`, `*`, `_`, `~`, `+`, or `#` characters (e.g. `# === React 18 production pins ===`). Other comments and stylistic choices are preserved. When the last entry of a catalog group is removed, the header is rewritten to `catalog: {}` / `<name>: {}` so pnpm doesn't reject the resulting null value. Entries with non-empty `hardcoded_consumers` are skipped to avoid breaking `pnpm install`; the skip is surfaced in the JSON fix output as `{"type": "remove_catalog_entry", "applied": false, "skipped": true, "skip_reason": "hardcoded_consumers", "consumers": [...]}`. The JSON action carries both `line` (first deleted line, the leading comment when policy absorbs one) and `entry_line` (the catalog entry's original 1-based line); use `entry_line` as a stable anchor across policy changes. After a successful catalog edit the CLI emits a one-line `Run pnpm install to refresh pnpm-lock.yaml` reminder, and the human stderr summary appends `(+M catalog comment lines)` to the fixed-issue count when comment lines were absorbed. The JSON envelope carries a top-level `"skipped"` count alongside `"total_fixed"` for partial-fix gating.
+- Duplicate exports (appends an `ignoreExports` rule to your fallow config file). When no fallow config file exists, `.fallowrc.json` is created using the same scaffolding `fallow init` would emit (framework detection, `$schema`, `entry`, `ignorePatterns`, etc.) and the rules are layered on top. Inside a monorepo subpackage (`pnpm-workspace.yaml`, `package.json#workspaces`, `turbo.json`, `lerna.json`, or `rush.json` above the invocation directory) the create-fallback refuses to fire and emits `skip_reason: "monorepo_subpackage"` with a relative `workspace_root` path pointing at the workspace root. The applied entry carries `created_files: [".fallowrc.json"]` so consumers can detect file-creation side effects programmatically.
 
 ### Examples
 
@@ -239,7 +241,7 @@ Inspect discovered files, entry points, detected frameworks, and architecture bo
 | `--files` | bool | List all discovered files |
 | `--entry-points` | bool | List detected entry points |
 | `--plugins` | bool | List active framework plugins |
-| `--boundaries` | bool | Show architecture boundary zones, rules, and per-zone file counts |
+| `--boundaries` | bool | Show architecture boundary zones, rules, per-zone file counts, and `logical_groups[]` for `autoDiscover` parents |
 | `--format` | `human\|json` | Output format |
 | `--quiet` | bool | Suppress progress bars |
 
@@ -252,6 +254,8 @@ fallow list --plugins --format json --quiet
 fallow list --boundaries --format json --quiet
 ```
 
+The `--boundaries` JSON output carries `boundaries.logical_groups[]` alongside the existing `zones[]` / `rules[]` arrays. Each logical-group entry surfaces a user-authored `autoDiscover` parent zone (which expansion otherwise flattens into per-child zones like `features/auth` / `features/billing`): `name`, `children`, `auto_discover` (verbatim user strings), `status` (`ok` / `empty` / `invalid_path`), `source_zone_index`, summed `file_count`, optional `authored_rule` (the pre-expansion `{ allow, allowTypeOnly }` keyed on the parent), optional `fallback_zone` cross-reference when the parent also kept its own `patterns` (Bulletproof case), optional `merged_from` (parent zone indices when the user declared the same parent name twice; surfaces the duplicate in JSON instead of only in `tracing::warn!`), optional `original_zone_root` (echo of the parent's `root` subtree scope for monorepo patchers), and optional `child_source_indices` (parallel to `children`, attributing each child to a specific `auto_discover` entry when multiple paths were authored). The full shape is documented in `docs/output-schema.json` under `ListBoundariesOutput`.
+
 ---
 
 ## `init`: Config Generation
@@ -437,7 +441,7 @@ fallow health --format json --quiet --trend
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -823,7 +827,7 @@ fallow audit \
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -896,7 +900,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1131,7 +1135,7 @@ Coverage CI helper for bundled/minified runtime coverage. It scans a build direc
 | `--dir <PATH>` | path | `dist` | Directory scanned recursively. |
 | `--include <GLOB>` | glob | `**/*.map` | Include glob relative to `--dir`. |
 | `--exclude <GLOB>` | glob | `**/node_modules/**` | Exclude glob, repeatable. |
-| `--repo <NAME>` | string | `package.json` `repository.url`, then `git remote get-url origin` | Repo name used in the source-map API path. |
+| `--repo <NAME>` | string | `package.json` `repository.url`, then `git remote get-url origin` parsed to `owner/repo` | Repo identifier used in the source-map API path. Must match the beacon's `projectId` (and `upload-inventory`'s `--project-id`); pass `--repo <bare-name>` explicitly if the beacon reports a bare name. |
 | `--git-sha <SHA>` | string | `$GITHUB_SHA` -> `$CI_COMMIT_SHA` -> `$COMMIT_SHA` -> `git rev-parse HEAD` | Commit SHA, 7-40 hex chars. |
 | `--endpoint <URL>` | string | `$FALLOW_API_URL` or `https://api.fallow.cloud` | Override for staging / on-prem. |
 | `--strip-path <BOOL>` | bool | `true` | Upload basename-only `fileName` values. Use `--strip-path=false` when runtime coverage reports paths like `assets/app.js`. |
@@ -1315,7 +1319,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1367,7 +1371,7 @@ Every issue in `dead-code` JSON output includes an `actions` array with structur
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `type` | string | yes | Action type in kebab-case (for example `remove-export`, `remove-file`, `remove-dependency`, `move-dependency`, `suppress-line`, `add-to-config`) |
-| `auto_fixable` | bool | yes | `true` if `fallow fix` handles this action automatically |
+| `auto_fixable` | bool | yes | `true` if `fallow fix` handles this action automatically. Evaluated PER FINDING, not per action type: the same `type` may carry `true` on one finding and `false` on another when per-instance guards in the applier discriminate. Filter on this bool of each individual action, not on `type` alone. |
 | `description` | string | yes | Human-readable description of the action |
 | `comment` | string | no | Suppression comment text (on `suppress-line` actions) |
 | `note` | string | no | Additional context on non-auto-fixable items |
@@ -1424,6 +1428,14 @@ Dependency issues use `add-to-config` with `config_key` and `value`:
 
 When a dependency action is `move-dependency`, `auto_fixable` is `false`; the package is imported from another workspace and needs a package.json ownership move rather than removal.
 
+Per-instance `auto_fixable` flips today (the same action `type` flipping between findings):
+
+- `remove-catalog-entry` (unused-catalog-entries): `true` only when `hardcoded_consumers` is empty; `false` otherwise (the applier skips the entry to avoid breaking `pnpm install`).
+- `remove-dependency` vs `move-dependency` (dependency findings): primary action flips between `remove-dependency` (`true`) and `move-dependency` (`false`) on `used_in_workspaces`.
+- `add-to-config` for `ignoreExports` (duplicate-exports): `true` when `fallow fix` can safely apply the action, which today means EITHER a fallow config file already exists OR no config exists and the working directory is NOT inside a monorepo subpackage. In the second case the applier creates `.fallowrc.json` using `fallow init`'s framework-aware scaffolding and layers the new rules on top. `false` inside a monorepo subpackage with no workspace-root config (the applier refuses to fragment per-package configs). Pass `--no-create-config` to `fallow fix` from pre-commit hooks, CI bots, and `fallow watch` to opt out of the create-fallback; the action then surfaces with `auto_fixable: false`.
+- `update-catalog-reference` (unresolved-catalog-references): always `false` today; non-singleton on the wire so a future applier can promote it without a schema change.
+- All `suppress-line` and `suppress-file` actions are uniformly `false`.
+
 #### Health `actions` array (CRAP findings)
 
 Health findings (`fallow health` JSON output) include an `actions` array. Primary action selection is formula-aware: the rule first checks whether full coverage CAN bring CRAP under threshold (CRAP bottoms out at `cyclomatic` at 100% coverage, so `cyclomatic < maxCrap` means coverage is a viable remediation), then uses `coverage_tier` to choose the description.
@@ -1437,6 +1449,8 @@ Health findings (`fallow health` JSON output) include an `actions` array. Primar
 
 The `coverage_tier` field is `"none"` (file not test-reachable / Istanbul 0%), `"partial"` (Istanbul `(0, 70)` / estimated 40%), or `"high"` (Istanbul `>= 70` / estimated 85%).
 
+Each CRAP finding also carries a `coverage_source` discriminator: `"istanbul"` (direct fnMap match for this function), `"estimated"` (graph-based estimate evaluated against the finding's own file), or `"estimated_component_inherited"` (graph-based estimate inherited from an Angular component `.ts` reached via the inverse `templateUrl` edge). Synthetic `<template>` findings on Angular `.html` templates use the `estimated_component_inherited` source and ship an `inherited_from` field with the project-relative path to the owning `.component.ts`. When the inherit path applies, the primary `increase-coverage` action targets that `.ts` file (description names the component path explicitly and includes a `target_path` field) so AI agents add component tests rather than scaffolding tests against a structurally untestable `.html` path. The human `fallow health` output renders `(inherited from foo.component.ts)` after the CRAP score on those rows. This is the JIT-test fallback (Angular's runtime renders templates via `ɵɵconditional` / `ɵɵrepeaterCreate` calls; Istanbul never has `fnMap` entries keyed at `.html` paths). AOT-compiled coverage with source-map back-mapping is planned as a tier 2 follow-up; when it lands, `coverage_source` will gain a `"measured_aot_source_map"` variant.
+
 When CRAP-only with cyclomatic count within 5 of `maxCyclomatic` AND cognitive at or above `maxCognitive / 2`, a secondary `refactor-function` is appended. The cognitive floor suppresses false positives on flat type-tag dispatchers and JSX render maps (high CC, near-zero cog). A single finding can carry multiple action types: e.g. a finding that exceeds both cyclomatic and CRAP at `coverage_tier=partial` gets `increase-coverage` AND `refactor-function`. Treat the first non-`suppress-line` action as primary.
 
 The `suppress-line` action is auto-omitted when `--baseline`/`--save-baseline` is set, OR when `health.suggestInlineSuppression: false` in config. The report root carries an `actions_meta: { suppression_hints_omitted: true, reason: "baseline-active" | "config-disabled" }` breadcrumb in that case.
@@ -1462,7 +1476,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1506,7 +1520,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "check": {
     "schema_version": 3,
-    "version": "2.74.0",
+    "version": "2.75.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],
@@ -1528,7 +1542,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
   },
   "dupes": {
     "schema_version": 3,
-    "version": "2.74.0",
+    "version": "2.75.0",
     "elapsed_ms": 82,
     "total_clones": 15,
     "total_lines_duplicated": 230,
@@ -1537,7 +1551,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
   },
   "health": {
     "schema_version": 3,
-    "version": "2.74.0",
+    "version": "2.75.0",
     "elapsed_ms": 32,
     "summary": {},
     "findings": [],
@@ -1621,17 +1635,20 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
 
   // Architecture boundaries (preset, custom zones/rules, or auto-discovered feature zones)
   // Presets: "layered", "hexagonal", "feature-sliced", "bulletproof"
+  // Rules accept an optional `allowTypeOnly: [zones]` list that admits type-only imports
+  // (`import type`, inline `{ type Foo }`, namespace type imports, and `export type` re-exports)
+  // to the listed zones even when not present in `allow`. Mixed-specifier imports still fire.
   "boundaries": {
     "preset": "bulletproof"
     // Or:
     // "zones": [
     //   { "name": "app", "patterns": ["src/app/**"] },
-    //   { "name": "features", "autoDiscover": ["src/features"] },
+    //   { "name": "features", "patterns": ["src/features/**"], "autoDiscover": ["src/features"] },
     //   { "name": "shared", "patterns": ["src/shared/**"] }
     // ],
     // "rules": [
     //   { "from": "app", "allow": ["features", "shared"] },
-    //   { "from": "features", "allow": ["shared"] }
+    //   { "from": "features", "allow": ["shared"], "allowTypeOnly": ["features"] }
     // ]
   },
 

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