@boyingliu01/xp-gate 0.30.5 → 0.31.1

package/lib/__tests__/gate-runner-verdict.test.js

@@ -0,0 +1,105 @@
+/**
+ * @test REQ-563 runGate must not discard a synchronous gate verdict
+ * @intent `runGate()` reports "passed" for every gate whose `run()` returns a
+ *         number instead of a Promise. Four registry entries — gates 3, 7, 8
+ *         and 9 — reach `runTsGate()`, which returns `result.status` as a plain
+ *         number, and the runner's own code path was:
+ *
+ *             const result = gate.run(targetPath);
+ *             if (result && typeof result.then === 'function') return await result;
+ *             return 0;                      // <-- the number is dropped here
+ *
+ *         So a gate that exits 1 in its child process is reported as 0 by
+ *         `xp-gate check`. `checkAllGates()` counts `code !== 0` as a failure, so
+ *         it faithfully counts whatever `runGate` hands back — which is always
+ *         0 for those four gates. The fail-open is in exactly one place and it
+ *         is silent: nothing in the output says the verdict was manufactured.
+ *
+ *         Gates 4 and 6 escaped this by returning `Promise.resolve(...)`, and
+ *         gate 2 escaped it because `execFileSync` throws on a non-zero exit and
+ *         the `catch` converts that to 1. Both of those are accidents of how
+ *         each handler was written, not a contract — which is why the fix has to
+ *         be in the runner, not in each handler.
+ * @covers AC-563-01, AC-563-02, AC-563-03
+ */
+const gateRunner = require('../gate-runner.js');
+const { runGate, GATE_REGISTRY } = gateRunner;
+
+const STUB_GATE_ID = '__stub_gate__';
+
+/**
+ * Install a throwaway registry entry and return a cleanup function.
+ * @param {object} handler - the `run` implementation to install
+ * @returns {Function} cleanup
+ */
+function withStubGate(handler) {
+  GATE_REGISTRY[STUB_GATE_ID] = {
+    name: 'Stub Gate',
+    description: 'test double',
+    aliases: [],
+    run: handler,
+  };
+  return () => {
+    delete GATE_REGISTRY[STUB_GATE_ID];
+  };
+}
+
+let cleanup = null;
+
+beforeEach(() => {
+  // Keep the console quiet: runGate prints a banner for every invocation.
+  if (!global.__xpGateStubLog) {
+    global.__xpGateStubLog = console.log;
+  }
+  console.log = () => {};
+});
+
+afterEach(() => {
+  if (cleanup) {
+    cleanup();
+    cleanup = null;
+  }
+  console.log = global.__xpGateStubLog;
+});
+
+describe('runGate verdict propagation', () => {
+  test('AC-563-01: a synchronous non-zero verdict is returned, not swallowed', async () => {
+    // This is the exact shape `runTsGate` has: a plain number, no Promise.
+    cleanup = withStubGate(() => 1);
+
+    const code = await runGate(STUB_GATE_ID, '.');
+
+    expect(
+      code,
+      'runGate returned a manufactured 0 for a gate whose synchronous handler ' +
+        'said 1 — the caller (checkAllGates) cannot distinguish pass from fail'
+    ).toBe(1);
+  });
+
+  test('AC-563-02: a synchronous zero verdict still reads as pass', async () => {
+    // The guard against "fix it by always failing": a genuine 0 must stay 0.
+    cleanup = withStubGate(() => 0);
+
+    const code = await runGate(STUB_GATE_ID, '.');
+
+    expect(code).toBe(0);
+  });
+
+  test('AC-563-03: async and throwing handlers keep their existing verdicts', async () => {
+    // Promise-returning handlers already worked; the fix must not regress them.
+    cleanup = withStubGate(() => Promise.resolve(2));
+    expect(await runGate(STUB_GATE_ID, '.')).toBe(2);
+    cleanup();
+
+    cleanup = withStubGate(() => {
+      throw new Error('boom');
+    });
+    expect(await runGate(STUB_GATE_ID, '.')).toBe(1);
+    cleanup();
+
+    // An async handler that REJECTS must also fail closed, not propagate an
+    // unhandled rejection out of runGate.
+    cleanup = withStubGate(() => Promise.reject(new Error('async boom')));
+    expect(await runGate(STUB_GATE_ID, '.')).toBe(1);
+  });
+});

package/lib/__tests__/hook-health-path.test.js

@@ -0,0 +1,101 @@
+/**
+ * @test REQ-566 hook parse check must survive a Windows path
+ * @intent `checkParseable()` ran `spawnSync(bashBin, ['-n', filePath])` with the
+ *         native Windows path. Git bash interprets a backslash in an argument as
+ *         an escape, so `C:\Users\think\.config\xp-gate\hooks\pre-push` reached
+ *         bash as `C:Usersthink.configxp-gatehookspre-push` and every hook above
+ *         the size floor was reported "not parseable".
+ *
+ *         Reproduced on this machine against the real installed hook:
+ *
+ *             findBash()  -> "C:\\Program Files\\Git\\bin\\bash.exe"
+ *             hook path   -> "C:\\Users\\think\\.config\\xp-gate\\hooks\\pre-push"
+ *             verdict     -> "hook is not parseable by bash:
+ *                             /bin/bash: C:Usersthink\\.config\\xp-gate\\hooks\\pre-push:
+ *                             No such file or directory"
+ *
+ *         while `bash -n` on the same file from Git bash reports PARSE_OK. Note
+ *         the mangled basename still shows its separators in some positions —
+ *         the collapse is per-escape, which is why this looked like a missing
+ *         file rather than a path bug for so long.
+ *
+ *         `xp-gate doctor` therefore FAILed on a perfectly healthy hook, and the
+ *         failure text named a path that does not exist, sending the operator to
+ *         look for a missing file.
+ * @covers AC-566-01, AC-566-02, AC-566-03
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { inspectHookFile, toPosixPath } = require('../hook-health');
+
+let TMP;
+
+beforeAll(() => {
+  TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'hook-posix-'));
+});
+
+afterAll(() => {
+  fs.rmSync(TMP, { recursive: true, force: true });
+});
+
+/**
+ * Write a hook file large enough to clear the parse-check size floor.
+ * @param {string} name - file name
+ * @param {string} body - shell source
+ * @returns {string} absolute path
+ */
+function writeHook(name, body) {
+  const abs = path.join(TMP, name);
+  try {
+    // Padding keeps the file above PARSE_CHECK_MIN_BYTES so the probe actually
+    // runs; a stub below the floor would make every assertion here vacuous.
+    fs.writeFileSync(abs, body + '# ' + 'x'.repeat(8192) + '\n');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`fixture setup failed writing ${name}: ${msg}`);
+  }
+  return abs;
+}
+
+describe('bash -n path handling', () => {
+  test('AC-566-01: toPosixPath converts a Windows path without mangling it', () => {
+    // The transform under test, isolated: drive letter preserved, separators
+    // flipped, no characters dropped.
+    expect(toPosixPath('C:\\Users\\think\\.config\\xp-gate\\hooks\\pre-push')).toBe(
+      'C:/Users/think/.config/xp-gate/hooks/pre-push'
+    );
+    // A POSIX path is already correct and must not be doubled over.
+    expect(toPosixPath('/home/user/.config/xp-gate/hooks/pre-push')).toBe(
+      '/home/user/.config/xp-gate/hooks/pre-push'
+    );
+  });
+
+  test('AC-566-02: a healthy hook under a native Windows path is parseable', () => {
+    // The defect, end to end. The path MUST come from path.join, not from a
+    // string literal: path.join produces the single-backslash form that Node
+    // hands to spawnSync, and that is the form bash mangles. A hand-written
+    // fixture path with different escaping would pass before the fix and make
+    // this test vacuous — measured, not assumed.
+    const hook = writeHook('pre-push', '#!/bin/bash\nset -e\necho hi\n');
+    expect(hook).toContain('\\'); // the path really is the Windows form
+
+    const verdict = inspectHookFile(hook, {});
+
+    expect(verdict.problems.join('; ')).not.toMatch(/No such file or directory/);
+    expect(verdict.parseable, 'a syntactically valid hook must parse').toBe(true);
+    expect(verdict.ok, 'a healthy hook must not be reported as broken').toBe(true);
+  });
+
+  test('AC-566-03: a genuinely broken hook is still reported as broken', () => {
+    // Guards against "fix it by never failing": path handling must not turn the
+    // probe into a no-op. This is the anti-vacuity half of AC-566-02.
+    const hook = writeHook('pre-commit', '#!/bin/bash\nif [ 1 -eq 1 ]; then\n  echo hi\n');
+
+    const verdict = inspectHookFile(hook, {});
+
+    expect(verdict.parseable, 'an unterminated if must fail the parse').toBe(false);
+    expect(verdict.ok).toBe(false);
+  });
+});

package/lib/__tests__/principles-directory.test.js

@@ -0,0 +1,87 @@
+/**
+ * @test REQ-565 `xp-gate principles <dir>` must examine the files in the directory
+ * @intent `principles()` forwarded its target straight to
+ *         `principles-checker --files <target>`, and the checker only accepts
+ *         FILE paths — a directory matches no adapter extension and is dropped
+ *         without a word. The reported result was therefore:
+ *
+ *             ✓ No violations found
+ *             Files checked: 0            <-- and exit code 0
+ *
+ *         which is indistinguishable from a directory that genuinely has no
+ *         violations. The CLI's own usage string advertises
+ *         `<file_or_directory>`, so the directory form is not an unsupported
+ *         extra — it is the documented one, silently doing nothing.
+ *
+ *         This is the same defect class as #561 and #563: a gate that reports
+ *         success for work it never performed. Expanding the directory belongs
+ *         in the CLI layer because that is where the `<file_or_directory>`
+ *         contract is declared; the checker's file-list contract is correct.
+ * @covers AC-565-01, AC-565-02, AC-565-03
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { expandTargets } = require('../principles');
+
+let TMP;
+
+beforeAll(() => {
+  TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'principles-expand-'));
+});
+
+afterAll(() => {
+  fs.rmSync(TMP, { recursive: true, force: true });
+});
+
+/**
+ * Write a file inside the temp tree.
+ * @param {string} rel - path relative to TMP
+ * @param {string} content - file body
+ */
+function touch(rel, content) {
+  const abs = path.join(TMP, rel);
+  try {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`fixture setup failed writing ${rel}: ${msg}`);
+  }
+}
+
+describe('principles directory expansion', () => {
+  test('AC-565-01: a directory target expands to the source files inside it', () => {
+    touch('src/a.ts', 'export const a = 1;\n');
+    touch('src/b.js', 'module.exports = 1;\n');
+    touch('src/nested/c.ts', 'export const c = 2;\n');
+    touch('src/readme.md', 'not source\n');
+    touch('src/skip.test.ts', '// test file\n');
+
+    const out = expandTargets([path.join(TMP, 'src')]);
+
+    const names = out.map(p => path.relative(TMP, p).replace(/\\/g, '/')).sort();
+    expect(names).toEqual(['src/a.ts', 'src/b.js', 'src/nested/c.ts']);
+  });
+
+  test('AC-565-02: a file target is passed through untouched', () => {
+    // The file form already worked; expanding must not disturb it.
+    const file = path.join(TMP, 'single.ts');
+    touch('single.ts', 'export const x = 1;\n');
+
+    expect(expandTargets([file])).toEqual([file]);
+  });
+
+  test('AC-565-03: a directory with no source files yields an empty list, not the directory', () => {
+    // The caller must be able to see "nothing to check" and say so, rather than
+    // hand the checker a directory that silently matches nothing.
+    fs.mkdirSync(path.join(TMP, 'empty'), { recursive: true });
+    touch('empty/notes.txt', 'hi\n');
+
+    const out = expandTargets([path.join(TMP, 'empty')]);
+
+    expect(out).toEqual([]);
+    expect(out).not.toContain(path.join(TMP, 'empty'));
+  });
+});

package/lib/check.js

@@ -94,21 +94,75 @@ async function runDefaultChecks(target) {
   return failures === 0 ? 0 : 1;
 }
 
+/**
+ * Render a gate tally as one honest line.
+ *
+ * Deliberately omits any state with a zero count, so a clean run reads
+ * "10 passed / 10 total" and a run with skips reads "5 passed / 5 skipped /
+ * 10 total" — the reader can see which of the two happened. The old
+ * `${ran - failures}/${ran}` form produced the same "10/10" for both (#568).
+ *
+ * @param {{passed: number, skipped: number, failed: number, warned: number, total: number}} tally
+ * @returns {string} e.g. "2 passed / 1 failed / 1 skipped / 4 total"
+ */
+function formatGateTally(tally) {
+  const parts = [`${tally.passed} passed`];
+  if (tally.failed > 0) parts.push(`${tally.failed} failed`);
+  if (tally.warned > 0) parts.push(`${tally.warned} warned`);
+  if (tally.skipped > 0) parts.push(`${tally.skipped} skipped`);
+  parts.push(`${tally.total} total`);
+  return parts.join(' / ');
+}
+
+/**
+ * Run every standalone-invokable gate and report the result honestly.
+ *
+ * `preCommitOnly` entries are NOT invokable from the CLI: `runGate` prints
+ * "SKIPPED - <reason>" and returns 0. Counting that 0 as a pass made
+ * `10/10 gate(s) passed` the summary for a run where five of fifteen gates
+ * never executed (#568, report §5 phase-0 action 0.2). Skips are now counted
+ * separately, still do not fail the run, and always appear in the summary.
+ *
+ * @param {string} target - path to check
+ * @returns {Promise<number>} 0 when nothing failed, 1 otherwise
+ */
 async function checkAllGates(target) {
   const { getAllGates } = require('./gate-runner.js');
-  const invokableGates = getAllGates().filter(g => !g.preCommitOnly);
-  let failures = 0;
-  let ran = 0;
+  const allGates = getAllGates();
+  const invokableGates = allGates.filter(g => !g.preCommitOnly);
+  const skippedGates = allGates.filter(g => g.preCommitOnly);
+
+  const tally = {
+    passed: 0,
+    skipped: skippedGates.length,
+    failed: 0,
+    warned: 0,
+    total: allGates.length,
+  };
+
+  for (const gate of skippedGates) {
+    console.log(`━━━ Gate ${gate.id}: ${gate.name} ━━━`);
+    console.log(`⏭️  SKIPPED (not invokable from the CLI) - ${gate.reason || 'runs during commit'}`);
+    console.log('');
+  }
 
   for (const gate of invokableGates) {
     const code = await runGate(gate.id, target);
-    if (code !== 0) failures += 1;
-    ran += 1;
+    if (code === 0) tally.passed += 1;
+    else tally.failed += 1;
     console.log('');
   }
 
-  console.log(`[xp-gate check --all] ${ran - failures}/${ran} gate(s) passed`);
-  return failures === 0 ? 0 : 1;
+  console.log(`[xp-gate check --all] ${formatGateTally(tally)}`);
+  if (tally.skipped > 0) {
+    // Name them: a bare count hides WHICH work did not happen, and the point of
+    // the fix is that the summary can no longer imply they ran.
+    console.log(
+      `[xp-gate check --all] not run from the CLI: ${skippedGates.map(g => g.id).join(', ')} ` +
+        '(pre-commit only; `git commit` runs them)'
+    );
+  }
+  return tally.failed === 0 ? 0 : 1;
 }
 
 async function runGatesByIds(gateIds, target) {
@@ -183,4 +237,4 @@ function listGates() {
   return 0;
 }
 
-module.exports = { check };
+module.exports = { check, checkAllGates, formatGateTally };

package/lib/gate-runner.js

@@ -360,8 +360,15 @@ async function runGate(gateId, targetPath) {
       if (result && typeof result.then === 'function') {
         return await result;
       }
-      return 0;
+      // A synchronous handler's verdict MUST be propagated (#563). Gates 3, 7,
+      // 8 and 9 reach runTsGate(), which returns a plain number; reporting a
+      // manufactured 0 for them made `xp-gate check` unable to distinguish a
+      // failing gate from a passing one. Handlers that return nothing at all
+      // (gate 2, whose execFileSync throws on a non-zero exit instead) are
+      // still treated as pass, because their failure signal is the throw below.
+      return typeof result === 'number' ? result : 0;
     } catch (err) {
+      // Covers a synchronous throw AND a rejection from the awaited handler.
       console.error(` Gate ${gateId} FAILED: ${err.message}`);
       return 1;
     }

package/lib/hook-health.js

@@ -21,14 +21,43 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
+/**
+ * Ask a bash binary whether it is a Windows bash rather than WSL.
+ *
+ * `bash --version` is not enough: a healthy WSL bash exits 0 for it. The
+ * discriminator is the kernel it reports — Git for Windows builds report a
+ * MINGW / MSYS / CYGWIN kernel name, WSL reports Linux. A Linux bash cannot
+ * open `C:/...`, so selecting one turns every hook-health probe into "No such
+ * file or directory" regardless of how the path is spelled.
+ *
+ * @param {string} bin - candidate binary
+ * @returns {boolean} true when it is a Windows bash
+ */
+function isWindowsBash(bin) {
+  const probe = spawnSync(bin, ['-c', 'uname -s'], { encoding: 'utf8', timeout: 10000 });
+  if (probe.error || probe.status !== 0) return false;
+  return /MINGW|MSYS|CYGWIN/i.test(String(probe.stdout || ''));
+}
+
 /**
  * Locate a bash binary without assuming it is on PATH under that exact name.
+ *
+ * On Windows the Git for Windows installs are probed FIRST and the bare name
+ * `bash` is the last resort (#570). The previous order put `bash` first and
+ * accepted any binary whose `--version` exited 0 — which is every healthy WSL
+ * install. Measured on this machine: `bash` on PATH resolves to
+ * `C:\WINDOWS\system32\bash.exe`, `uname -s` answers `Linux`, and the probe
+ * `bash -n <windows path>` fails with "No such file or directory" no matter how
+ * the path is spelled. `xp-gate doctor` then reported healthy hooks as
+ * unparseable.
+ *
  * @returns {string|null} Path or bare command name, null when none found
  */
 function findBash() {
-  const candidates = ['bash'];
+  const candidates = [];
   if (process.platform === 'win32') {
-    // Git for Windows ships bash outside PATH far more often than inside it.
+    // Git for Windows ships bash outside PATH far more often than inside it,
+    // and PATH's `bash` is usually WSL.
     const pf = process.env.ProgramFiles || 'C:\\Program Files';
     const pf86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
     const local = process.env.LOCALAPPDATA;
@@ -37,13 +66,19 @@ function findBash() {
     candidates.push(path.join(pf86, 'Git', 'bin', 'bash.exe'));
     candidates.push(path.join(pf, 'Git', 'usr', 'bin', 'bash.exe'));
   }
+  // Last resort: whatever PATH offers. On Windows it is only accepted when it
+  // reports a Windows kernel, so a WSL stub can never be returned.
+  candidates.push('bash');
+
   for (const c of candidates) {
     if (path.isAbsolute(c)) {
       if (fs.existsSync(c)) return c;
       continue;
     }
     const probe = spawnSync(c, ['--version'], { encoding: 'utf8', timeout: 10000 });
-    if (!probe.error && probe.status === 0) return c;
+    if (probe.error || probe.status !== 0) continue;
+    if (process.platform === 'win32' && !isWindowsBash(c)) continue;
+    return c;
   }
   return null;
 }
@@ -58,6 +93,25 @@ function countCrlfLines(text) {
   return matches ? matches.length : 0;
 }
 
+/**
+ * Convert a native filesystem path to the form Git bash can open.
+ *
+ * A backslash inside an argument to MSYS bash is an ESCAPE character, so
+ * `C:\Users\think\.config\xp-gate\hooks\pre-push` reaches bash as
+ * `C:Usersthink.configxp-gatehookspre-push` and every candidate path looks
+ * missing. Forward slashes are accepted by Windows APIs too, so this is the one
+ * form that works on both sides.
+ *
+ * Exported because the transform is the thing being tested: asserting only
+ * through `inspectHookFile` would leave the conversion itself unexamined.
+ *
+ * @param {string} p - native path
+ * @returns {string} path with forward slashes
+ */
+function toPosixPath(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
 /**
  * Ask bash whether it can parse the file (`bash -n`).
  * @param {string} filePath - Hook to check
@@ -66,7 +120,13 @@ function countCrlfLines(text) {
  */
 function checkParseable(filePath, bashBin) {
   if (!bashBin) return { checked: false, ok: true, detail: 'bash not found; parse check skipped' };
-  const res = spawnSync(bashBin, ['-n', filePath], { encoding: 'utf8', timeout: 30000 });
+  // Pass a POSIX path (#566). Git bash treats a backslash in its argv as an
+  // escape, which silently collapsed every native Windows path into a
+  // nonexistent one and reported healthy hooks as unparseable.
+  const res = spawnSync(bashBin, ['-n', toPosixPath(filePath)], {
+    encoding: 'utf8',
+    timeout: 30000,
+  });
   if (res.error) return { checked: false, ok: true, detail: `bash -n could not run: ${res.error.message}` };
   if (res.status === 0) return { checked: true, ok: true, detail: 'parses' };
   // bash reports the first syntax error it hits. Under CRLF that line number is
@@ -118,4 +178,4 @@ function inspectHookFile(filePath, options = {}) {
   return { ok: problems.length === 0, crlfLines, parseable: parsed.ok, problems };
 }
 
-module.exports = { inspectHookFile, findBash, countCrlfLines };
+module.exports = { inspectHookFile, findBash, countCrlfLines, toPosixPath };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-21T05:03:41.149Z",
+  "checked_at": "2026-10-22T08:31:44.285Z",
   "source": "network"
 }

package/lib/principles.js

@@ -25,6 +25,95 @@ function findPrinciplesEntry() {
   return null;
 }
 
+// Extensions the principles engine has an adapter for. Kept as a literal rather
+// than imported from src/principles/analyzer.ts because this file must stay
+// loadable by plain Node with no transpile step (the package ships zero runtime
+// dependencies and no build). Must match `getAdapterForFile`'s adapterMap.
+const SOURCE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.py', '.go', '.java', '.kt', '.kts',
+  '.dart', '.swift', '.cpp', '.cc', '.cxx', '.c', '.h', '.hpp',
+  '.m', '.mm',
+]);
+
+// Directories never worth walking: they hold no project source and can be
+// enormous. `node_modules` alone is ~hundreds of MB in this repo.
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'coverage',
+  '.stryker-tmp', '.worktrees', '__pycache__', '.venv', 'venv',
+]);
+
+/**
+ * Walk a directory and collect every source file the engine can analyse.
+ *
+ * Exported for tests: the walk is the part that used to be silently absent, so
+ * it is worth asserting directly rather than only through the CLI.
+ *
+ * @param {string} dir - absolute or relative directory
+ * @returns {string[]} absolute paths, in discovery order
+ */
+function collectSourceFiles(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    // An unreadable directory contributes nothing, but must not crash the run.
+    console.error(`[xp-gate principles] cannot read directory ${dir}: ${err.message}`);
+    return out;
+  }
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out.push(...collectSourceFiles(abs));
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    // Skip test files: their assertions legitimately look like magic numbers,
+    // long functions and missing error handling, so including them would bury
+    // the real findings in noise.
+    if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(entry.name)) continue;
+    if (SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * Turn CLI targets into the flat file list the checker understands (#565).
+ *
+ * `principles-checker --files` only accepts file paths; a directory matches no
+ * adapter extension and is dropped silently, which used to report
+ * "No violations found / Files checked: 0" with exit code 0. Expanding here
+ * keeps that contract in the layer that advertises `<file_or_directory>`.
+ *
+ * A file target is returned untouched even if its extension is unknown, so the
+ * caller can still surface the checker's own opinion about it.
+ *
+ * @param {string[]} targets - paths as given on the command line
+ * @returns {string[]} file paths to hand to the checker
+ */
+function expandTargets(targets) {
+  const out = [];
+  for (const target of targets) {
+    let stat;
+    try {
+      stat = fs.statSync(target);
+    } catch {
+      // Nonexistent path: forward it so the checker reports the missing file
+      // rather than this layer pretending it was fine.
+      out.push(target);
+      continue;
+    }
+    if (stat.isDirectory()) {
+      out.push(...collectSourceFiles(target));
+    } else {
+      out.push(target);
+    }
+  }
+  return out;
+}
+
 function principles(args) {
   const target = args[0];
   if (!target) {
@@ -35,6 +124,20 @@ function principles(args) {
   const formatIdx = args.indexOf('--format');
   const format = formatIdx >= 0 ? args[formatIdx + 1] : 'console';
 
+  // Expand directories before handing them to the checker (#565). Passing a
+  // directory straight through made the checker examine zero files while the
+  // CLI printed "No violations found" and exited 0.
+  const files = expandTargets([target]);
+  if (files.length === 0) {
+    // Nothing to analyse is NOT a pass. Saying so is the whole point: silence
+    // here is indistinguishable from a clean directory. Exit 2 mirrors the
+    // checker's own "examined nothing" contract, which reserves 1 for
+    // "examined files and found violations".
+    console.error(`[xp-gate principles] no analysable source files under: ${target}`);
+    console.error('  Supported: ' + Array.from(SOURCE_EXTENSIONS).join(' '));
+    return Promise.resolve(2);
+  }
+
   const entry = findPrinciplesEntry();
   if (!entry) {
     console.error('[xp-gate principles] ERROR: cannot locate src/principles/index.ts');
@@ -42,7 +145,7 @@ function principles(args) {
     return Promise.resolve(1);
   }
 
-  const result = spawnSync('npx', ['-y', 'tsx', entry, '--files', target, '--format', format], {
+  const result = spawnSync('npx', ['-y', 'tsx', entry, '--files', files.join(' '), '--format', format], {
     stdio: 'inherit',
     shell: process.platform === 'win32',
   });
@@ -50,4 +153,4 @@ function principles(args) {
   return Promise.resolve(result.status === null ? 1 : result.status);
 }
 
-module.exports = { principles };
+module.exports = { principles, expandTargets, collectSourceFiles };

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-10-21
-**Commit:** 4e1f8be0
+**Generated:** 2026-10-22
+**Commit:** 0678b903
 **Branch:** main
-**Version:** 0.30.5.0
+**Version:** 0.31.1.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.