@boyingliu01/xp-gate 0.35.16 → 0.35.18

package/lib/__tests__/gate-numbering.test.js

@@ -0,0 +1,52 @@
+/**
+ * @test REQ-686
+ * @intent 验证 CLI 的门禁编号与钩子一致——钩子把 9 号门叫 Build integrity、
+ *         10 号门叫 SAST，而 CLI 注册表把两者对调了；用户按报错提示单跑对应门
+ *         会跑到另一道门上去（#677）
+ * @covers AC-686-01, AC-686-02, AC-686-03
+ *
+ * 为什么必须直接断言注册表：这个错误的表现是「跑起来了、报告绿了」。
+ * `xp-gate check --gates 9` 在编号错位时不会报错，它跑的是 semgrep 并如实报告
+ * semgrep 的结果——只有拿它和钩子里的门名对照才能看出跑错了门。
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { GATE_REGISTRY, resolveAlias } = require('../gate-runner');
+
+const REPO_ROOT = path.join(__dirname, '../../../..');
+
+describe('gate numbering matches the hook (#677)', () => {
+  it('AC-686-01: gate 9 is Build Integrity and gate 10 is SAST Security', () => {
+    expect(GATE_REGISTRY['9'].name).toBe('Build Integrity');
+    expect(GATE_REGISTRY['10'].name).toBe('SAST Security');
+  });
+
+  it('AC-686-02: the hook agrees — its own output names 9 as Build integrity', () => {
+    // Reads the hook rather than restating the constant: if the hook ever
+    // renumbers again, this fails and points at which side moved.
+    const hook = fs.readFileSync(path.join(REPO_ROOT, 'githooks/pre-commit'), 'utf8');
+    expect(hook).toMatch(/→ Gate 9: Build integrity/);
+    expect(hook).toMatch(/GATE 10: Semgrep SAST/);
+  });
+
+  it('AC-686-03: aliases resolve to the gate the user meant', () => {
+    expect(resolveAlias('sast')).toBe('10');
+    expect(resolveAlias('semgrep')).toBe('10');
+    expect(resolveAlias('build')).toBe('9');
+  });
+
+  it('AC-686-03: gates 12 and 13 are registered instead of "Unknown gate(s)"', () => {
+    // Both block commits in the hook. Answering "Unknown gate" for a gate that just
+    // blocked the user is the same category of wrong as running the wrong one.
+    expect(GATE_REGISTRY['12'].name).toBe('File Hygiene');
+    expect(GATE_REGISTRY['13'].name).toBe('Compiler Strictness');
+    // They are registered as hook-only, with a stated reason -- not as runnable
+    // stubs that would answer PASS without doing the work.
+    expect(GATE_REGISTRY['12'].preCommitOnly).toBe(true);
+    expect(GATE_REGISTRY['13'].preCommitOnly).toBe(true);
+    expect(GATE_REGISTRY['12'].reason).toBeTruthy();
+    expect(GATE_REGISTRY['13'].reason).toBeTruthy();
+  });
+});

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

@@ -9,6 +9,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { execFileSync, spawnSync } = require('node:child_process');
+const { findConsumerGateVariant } = require('../gate-runner');
 
 let tmpProject;
 let tmpAdapters;
@@ -25,15 +26,26 @@ afterEach(() => {
   }
 });
 
+// Fixture writers run in every `beforeAll`; swallowing their failure would turn a
+// broken fixture into "the gate under test misbehaved", which is the opposite of
+// what the assertion is checking. Report which file could not be written.
+function writeFixture(filePath, content) {
+  try {
+    fs.writeFileSync(filePath, content);
+  } catch (err) {
+    throw new Error(`Cannot write test fixture ${filePath}: ${err.message}`);
+  }
+}
+
 function writeAdapterCommon() {
-  fs.writeFileSync(
+  writeFixture(
     path.join(tmpAdapters, 'adapter-common.sh'),
     'detect_project_lang() { echo "typescript"; }'
   );
 }
 
 function writeGateFragment(fragmentLines) {
-  fs.writeFileSync(
+  writeFixture(
     path.join(tmpAdapters, 'gate-9.sh'),
     ['# gate-9 fragment', ...fragmentLines, 'exit 0'].join('\n')
   );
@@ -55,14 +67,21 @@ function hostilePathSegment() {
 }
 
 function initializeGitProject() {
-  execFileSync('git', ['init', '-q'], { cwd: tmpProject });
-  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: tmpProject });
-  execFileSync('git', ['config', 'user.name', 'XP-Gate Test'], { cwd: tmpProject });
-  fs.writeFileSync(path.join(tmpProject, 'tracked.ts'), 'const value = 1;\n');
-  execFileSync('git', ['add', 'tracked.ts'], { cwd: tmpProject });
-  execFileSync('git', ['-c', 'core.hooksPath=/dev/null', 'commit', '-qm', 'initial'], {
-    cwd: tmpProject,
-  });
+  try {
+    execFileSync('git', ['init', '-q'], { cwd: tmpProject });
+    execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: tmpProject });
+    execFileSync('git', ['config', 'user.name', 'XP-Gate Test'], { cwd: tmpProject });
+    writeFixture(path.join(tmpProject, 'tracked.ts'), 'const value = 1;\n');
+    execFileSync('git', ['add', 'tracked.ts'], { cwd: tmpProject });
+    execFileSync('git', ['-c', 'core.hooksPath=/dev/null', 'commit', '-qm', 'initial'], {
+      cwd: tmpProject,
+    });
+  } catch (err) {
+    // Without this the failure surfaces as a downstream assertion on the gate's
+    // output. Name the setup step instead: a repo fixture that never initialised
+    // is not a gate defect.
+    throw new Error(`Cannot initialise the fixture git repo at ${tmpProject}: ${err.message}`);
+  }
 }
 
 // Runs runGateAdapter in a child node process (worker threads forbid process
@@ -188,7 +207,7 @@ describe('gate-runner.js — runGateAdapter', () => {
       ].join('\n')
     );
 
-    const result = spawnSync(process.execPath, [cliPath, 'check', '9'], {
+    const result = spawnSync(process.execPath, [cliPath, 'check', '10'], {
       cwd: tmpProject,
       encoding: 'utf8',
       timeout: 30000,
@@ -225,7 +244,7 @@ describe('gate-runner.js — runGateAdapter', () => {
 
     const result = spawnSync(
       process.execPath,
-      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9', targetProject],
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '10', targetProject],
       {
         cwd: callerProject,
         encoding: 'utf8',
@@ -283,7 +302,7 @@ describe('gate-runner.js — runGateAdapter', () => {
 
     const result = spawnSync(
       process.execPath,
-      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9'],
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '10'],
       { cwd: tmpProject, encoding: 'utf8', timeout: 30000 }
     );
 
@@ -301,10 +320,36 @@ describe('gate-runner.js — runGateAdapter', () => {
 
     const result = spawnSync(
       process.execPath,
-      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '9', targetProject],
+      [path.join(packageFixture, 'bin', 'xp-gate.js'), 'check', '10', targetProject],
       { cwd: tmpProject, encoding: 'utf8', timeout: 30000 }
     );
 
     expect(result.status).toBe(1);
   }, 30000);
+
+  // The mirror image of the tests above, asserted on the resolver rather than on
+  // CLI output. A project that declares no variant must resolve to nothing, so
+  // the built-in implementation still runs.
+  //
+  // Asserted here, not through `check 9`: BOTH implementations print "Semgrep"
+  // (githooks/gate-9.sh says it five times too), and a bash fallback that finds
+  // no script prints neither banner, so every stdout-based assertion passed even
+  // with the TypeScript module hard-disabled -- the guard proved nothing.
+  it('resolves no variant when the project declares none (REQ-standalone-gates-05)', () => {
+    const plainProject = path.join(tmpProject, 'plain-target');
+    fs.mkdirSync(plainProject, { recursive: true });
+
+    expect(findConsumerGateVariant('gate-9', plainProject)).toBe(null);
+  });
+
+  it('resolves the declared variant when the project has one (REQ-standalone-gates-05)', () => {
+    const variantProject = path.join(tmpProject, 'variant-target');
+    const gatesDir = path.join(variantProject, 'githooks', 'gates');
+    fs.mkdirSync(gatesDir, { recursive: true });
+    const variantPath = path.join(gatesDir, 'gate-9-project-choice.sh');
+    fs.writeFileSync(variantPath, 'exit 0\n');
+
+    const resolved = findConsumerGateVariant('gate-9', variantProject);
+    expect(resolved).toBe(variantPath);
+  });
 });

package/lib/__tests__/shared-utils.test.js

@@ -130,4 +130,51 @@ describe('shared-utils', () => {
     });
   });
 
+  describe('copyDirRecursive (#640 concurrency)', () => {
+    // The mirrored trees this walks are rewritten in place by
+    // scripts/sync-package-content.js. A concurrent init enumerates the
+    // directory, then finds an entry gone -- ENOENT on a file that reappears
+    // microseconds later. That must not abort the install.
+    it('skips a file that disappears between enumeration and copy', () => {
+      const src = path.join(tmpRoot, 'src');
+      const dest = path.join(tmpRoot, 'dest');
+      fs.mkdirSync(src, { recursive: true });
+      fs.writeFileSync(path.join(src, 'stable.sh'), 'stable');
+      fs.writeFileSync(path.join(src, 'vanishing.sh'), 'vanishing');
+
+      const realReadFileSync = fs.readFileSync;
+      vi.spyOn(fs, 'readFileSync').mockImplementation((p, ...rest) => {
+        if (String(p).endsWith('vanishing.sh')) {
+          const err = new Error('ENOENT: no such file or directory');
+          err.code = 'ENOENT';
+          throw err;
+        }
+        return realReadFileSync(p, ...rest);
+      });
+
+      const { copyDirRecursive } = require('../shared-utils');
+      expect(() => copyDirRecursive(src, dest)).not.toThrow();
+      expect(fs.existsSync(path.join(dest, 'stable.sh'))).toBe(true);
+      expect(fs.existsSync(path.join(dest, 'vanishing.sh'))).toBe(false);
+    });
+
+    it('still surfaces a real read error instead of silently skipping', () => {
+      // Only ENOENT means "being replaced". A permission or disk error is a real
+      // failure, and swallowing it would ship a half-installed hook set.
+      const src = path.join(tmpRoot, 'src2');
+      const dest = path.join(tmpRoot, 'dest2');
+      fs.mkdirSync(src, { recursive: true });
+      fs.writeFileSync(path.join(src, 'locked.sh'), 'locked');
+
+      vi.spyOn(fs, 'readFileSync').mockImplementation(() => {
+        const err = new Error('EACCES: permission denied');
+        err.code = 'EACCES';
+        throw err;
+      });
+
+      const { copyDirRecursive } = require('../shared-utils');
+      expect(() => copyDirRecursive(src, dest)).toThrow(/EACCES/);
+    });
+  });
+
 });

package/lib/gate-runner.js

@@ -361,16 +361,69 @@ function resolveNpxInvocation(args) {
   return ['npx', args];
 }
 
+/**
+ * A project-local gate variant, if the project declares one.
+ *
+ * `<consumer cwd>/githooks/gates/gate-<n>-<name>.sh` is where a PROJECT puts its
+ * own variant of a gate: the hyphenated name is the point, because it lets one
+ * project keep several variants where a flat `gate-<n>.sh` cannot express the
+ * choice (#672, restored by 7b43666a). `xp-gate init` never creates that
+ * directory, so a stock project simply falls through to the built-in
+ * implementation and nothing changes for it.
+ *
+ * This is deliberately NOT the same as `<project>/src/gates/<gate>.ts`, which
+ * `findTsGateEntry` refuses to read (#672): that path let the party being
+ * checked supply the implementation, so `process.exit(0)` passed every gate.
+ * Declaring a variant under `githooks/gates/` is an explicit, named opt-in;
+ * dropping a file into `src/gates/` is not.
+ *
+ * @param {string} gateModule e.g. 'gate-9'
+ * @param {string} cwd project root to search
+ * @returns {string|null}
+ */
+function findConsumerGateVariant(gateModule, cwd) {
+  const gateNum = gateModule.replace('gate-', '');
+  // Strictly the project's own declaration. `resolveGateScript` additionally
+  // probes the flat `githooks/gate-<n>.sh` and the global install
+  // (~/.config/xp-gate/adapters/); treating either as "the project declared a
+  // variant" would hand every gate to whichever bash copy happens to be
+  // installed -- on a machine with a global install that is *always*. A variant
+  // is a file the project deliberately named, so only `githooks/gates/` counts.
+  const gatesDir = path.join(cwd, 'githooks', 'gates');
+  const declared = matchGateFileIn(gatesDir, gateNum);
+  return declared ? path.join(gatesDir, declared) : null;
+}
+
+/**
+ * Which implementation runs this gate: a project-declared variant, the built-in
+ * TypeScript module, or a bash fallback.
+ *
+ * Split out of `runTsGate` so that function stays about running the gate. The
+ * precedence is a contract with two sides -- `githooks/gates/` is the project's
+ * opt-in, and the built-in module must remain reachable when nobody opted in --
+ * so it is named here rather than inlined in the runner.
+ *
+ * @returns {{kind: 'variant', script: string} | {kind: 'module', entry: string} | {kind: 'fallback', script: string} | {kind: 'none'}}
+ */
+function resolveGateImplementation(gateModule, targetCwd) {
+  const variant = findConsumerGateVariant(gateModule, targetCwd);
+  if (variant) return { kind: 'variant', script: variant };
+
+  const entry = findTsGateEntry(gateModule);
+  if (entry) return { kind: 'module', entry };
+
+  const script = resolveGateScript(gateModule.replace('gate-', ''), targetCwd);
+  return script ? { kind: 'fallback', script } : { kind: 'none' };
+}
+
 function runTsGate(gateModule, targetPath, opts = {}) {
   const targetCwd = resolveGateCwd(targetPath);
-  const entry = findTsGateEntry(gateModule);
-  if (!entry) {
-    // Fallback to bash script
-    const gateNum = gateModule.replace('gate-', '');
-    const script = resolveGateScript(gateNum, targetCwd);
-    if (script) {
-      return runGateAdapter(script, targetCwd, opts);
-    }
+  const impl = resolveGateImplementation(gateModule, targetCwd);
+
+  if (impl.kind === 'variant' || impl.kind === 'fallback') {
+    return runGateAdapter(impl.script, targetCwd, opts);
+  }
+  if (impl.kind === 'none') {
     // #618: nothing ran. Before this, the function fell through to `return 0`
     // and the --all summary counted the gate as passed.
     console.log(`Gate ${gateModule}: TypeScript module not found and no bash fallback available.`);
@@ -378,7 +431,7 @@ function runTsGate(gateModule, targetPath, opts = {}) {
     return GATE_NOT_RUN;
   }
 
-  const args = ['-y', 'tsx', entry, '--run'];
+  const args = ['-y', 'tsx', impl.entry, '--run'];
   if (targetPath) args.push('--cwd', targetPath);
 
   // spawnSync reports a spawn failure (npx missing) on `error`, throws only on a
@@ -508,21 +561,28 @@ const GATE_REGISTRY = {
       return runTsGate('gate-8', targetPath);
     },
   },
+  // Numbering follows the HOOK, which is where gates actually execute (#677).
+  // These two were swapped here: the CLI called 9 "SAST" and 10 "Build Integrity"
+  // while the hook runs 9=Build integrity and 10=Semgrep SAST. A user reading
+  // "❌ BLOCKED - Gate 9: Build integrity check failed" in their commit output and
+  // then running `xp-gate check --gates 9` got semgrep -- a different gate, reported
+  // green. The hook is the majority implementation and the one the error message
+  // names, so its numbering wins.
   '9': {
+    name: 'Build Integrity',
+    description: 'TypeScript compilation, npm pack, and import validation',
+    aliases: ['build', '9'],
+    preCommitOnly: true,
+    reason: 'Build integrity checks require language detection and build tool context',
+  },
+  '10': {
     name: 'SAST Security',
     description: 'semgrep static application security testing',
-    aliases: ['sast', 'semgrep', '9'],
+    aliases: ['sast', 'semgrep', '10'],
     run: (targetPath) => {
       return runTsGate('gate-9', targetPath);
     },
   },
-  '10': {
-    name: 'Build Integrity',
-    description: 'TypeScript compilation, npm pack, and import validation',
-    aliases: ['build', '10'],
-    preCommitOnly: true,
-    reason: 'Build integrity checks require language detection and build tool context',
-  },
   '11': {
     name: 'Sprint Flow Enforcement',
     description: 'Sprint state and delphi-review validation',
@@ -530,6 +590,26 @@ const GATE_REGISTRY = {
     preCommitOnly: true,
     reason: 'Requires sprint state (.sprint-state/) and git branch context',
   },
+  // Gates 12 and 13 block commits in the hook but were absent here entirely, so
+  // `xp-gate check --gates 12` answered "Unknown gate(s)" for a gate that had just
+  // blocked the user (#677). Registered with an explicit reason rather than
+  // pretending to re-implement them: both need the staged-diff and per-language
+  // build context the hook assembles, and a half-correct reimplementation that
+  // answered PASS would be worse than saying so.
+  '12': {
+    name: 'File Hygiene',
+    description: 'conflict markers (blocking) + YAML/JSON syntax (blocking) + whitespace warnings',
+    aliases: ['hygiene', 'file-hygiene', '12'],
+    preCommitOnly: true,
+    reason: 'File hygiene inspects the staged diff, which only exists inside the hook',
+  },
+  '13': {
+    name: 'Compiler Strictness',
+    description: 'gcc/g++ -Wall -Wextra, javac -Xlint, Maven/Gradle warnings on changed files',
+    aliases: ['compiler', 'strictness', '13'],
+    preCommitOnly: true,
+    reason: 'Compiler strictness needs the changed-file set and a discovered toolchain',
+  },
   'python-health': {
     name: 'Python Environment Health',
     description: 'Comprehensive Python environment diagnostics',
@@ -718,4 +798,4 @@ async function runGate(gateId, targetPath, opts = {}) {
   return 1;
 }
 
-module.exports = { GATE_REGISTRY, GATE_NOT_RUN, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript, SOURCE_FILE_EXTENSIONS, resolveAllModeChangedFiles, describeEmptyChangedFiles, describeChangedFilesScope };
+module.exports = { findConsumerGateVariant, GATE_REGISTRY, GATE_NOT_RUN, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript, SOURCE_FILE_EXTENSIONS, resolveAllModeChangedFiles, describeEmptyChangedFiles, describeChangedFilesScope };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-31T05:05:10.442Z",
+  "checked_at": "2026-10-31T16:53:19.066Z",
   "source": "network"
 }

package/lib/shared-utils.js

@@ -8,6 +8,19 @@ const path = require('path');
 /**
  * Recursively copy a directory.
  * Pure function: only uses fs/path params, no global config.
+ *
+ * A file that disappears between `readdirSync` and `copyFileSync` is skipped
+ * rather than crashing the whole copy. That is not defensive padding: the
+ * mirrored trees this walks (`hooks/`, `adapters/`) are rewritten in place by
+ * `scripts/sync-package-content.js`, which unlinks and recreates each entry. A
+ * concurrent `xp-gate init` (or a test suite that runs init while another test
+ * invokes the sync) enumerates the directory, then finds the entry gone --
+ * `ENOENT` on a file that will exist again microseconds later. Aborting the
+ * install there would report a broken package for a transient race.
+ *
+ * Copies the CONTENT instead of `copyFileSync` so the read and the write both
+ * see a consistent snapshot, and only ENOENT is tolerated -- permission and
+ * disk errors still surface, because those are real failures.
  */
 function copyDirRecursive(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -18,11 +31,24 @@ function copyDirRecursive(src, dest) {
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
     } else {
-      fs.copyFileSync(srcPath, destPath);
+      copyFileContents(srcPath, destPath);
     }
   }
 }
 
+/** Copy one file, treating "vanished mid-copy" as a skip. @returns {boolean} whether it was copied */
+function copyFileContents(srcPath, destPath) {
+  let data;
+  try {
+    data = fs.readFileSync(srcPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+  fs.writeFileSync(destPath, data);
+  return true;
+}
+
 function readXpGateConfig() {
   const cfgPath = path.join(require('os').homedir(), '.xp-gate', 'config.json');
   try {

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 3aa988e7
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.16.0
+**Version:** 0.35.18.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.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
 **Generated:** 2026-10-31
-**Commit:** 3aa988e7
+**Commit:** 97e3c2ec
 **Branch:** main
-**Version:** 0.35.16.0
+**Version:** 0.35.18.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.