@boyingliu01/xp-gate 0.32.3 → 0.33.1

package/gates/python-health.ts

@@ -0,0 +1,266 @@
+/**
+ * Python Environment Health Check
+ * Provides comprehensive Python environment diagnostics.
+ * Layer 2 of #356: full diagnostics via CLI/doctor (not pre-commit hot path).
+ *
+ * Reuses common.ts infrastructure (isToolAvailable, runTool).
+ */
+import {
+  isToolAvailable, runTool,
+} from './common';
+
+// ── Types ──
+
+export interface PythonHealthResult {
+  healthy: boolean;
+  python: { available: boolean; version: string; exe: string };
+  pip: { available: boolean; version: string };
+  environment: { type: 'system' | 'venv' | 'conda' | 'pyenv' | 'uv'; path: string | null };
+  tools: Array<{ name: string; available: boolean; version: string; required: boolean }>;
+  issues: string[];
+}
+
+// ── Python Tool Registry (sync with language-tools.js LANGUAGE_REGISTRY.python) ──
+
+const PYTHON_REQUIRED_TOOLS = ['mypy', 'pytest'];
+const PYTHON_OPTIONAL_TOOLS = ['ruff', 'flake8', 'black'];
+
+// ── Python Detection ──
+
+/**
+ * Detect Python executable, filtering Windows Store stubs.
+ * Order: python3 → python → py (Windows)
+ */
+export function detectPython(): { available: boolean; exe: string; version: string } {
+  const candidates = process.platform === 'win32'
+    ? ['python3', 'python', 'py']
+    : ['python3', 'python'];
+
+  for (const exe of candidates) {
+    // Check if executable exists
+    const whichCheck = isToolAvailable(exe);
+    if (!whichCheck.available) continue;
+
+    const exePath = whichCheck.path;
+
+    // Filter Windows Store stubs (heuristic: path contains WindowsApps)
+    if (exePath.toLowerCase().includes('windowsapps')) continue;
+
+    // Verify it's a real Python (not a stub that opens Store)
+    const verResult = runTool(exePath, ['--version'], { timeoutMs: 3000 });
+    if (verResult.exitCode !== 0 || verResult.timedOut) continue;
+
+    const output = (verResult.stdout + verResult.stderr).trim();
+    const versionMatch = output.match(/^Python\s+(\d+\.\d+\.\d+)/);
+    if (!versionMatch) continue;
+
+    return { available: true, exe: exePath, version: versionMatch[1] };
+  }
+
+  return { available: false, exe: '', version: '' };
+}
+
+/**
+ * Check if Python version meets minimum requirement.
+ */
+export function checkPythonVersion(version: string, minVersion = '3.8.0'): boolean {
+  const parts = version.split('.').map(Number);
+  const minParts = minVersion.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const v = parts[i] || 0;
+    const m = minParts[i] || 0;
+    if (v > m) return true;
+    if (v < m) return false;
+  }
+  return true; // equal
+}
+
+// ── pip Detection ──
+
+/**
+ * Check pip availability via <python-exe> -m pip (ensures consistency).
+ */
+export function detectPip(pythonExe: string): { available: boolean; version: string } {
+  if (!pythonExe) return { available: false, version: '' };
+
+  const result = runTool(pythonExe, ['-m', 'pip', '--version'], { timeoutMs: 5000 });
+  if (result.exitCode !== 0) return { available: false, version: '' };
+
+  const output = result.stdout.trim();
+  const versionMatch = output.match(/pip\s+(\d+\.\d+(?:\.\d+)?)/);
+  return {
+    available: true,
+    version: versionMatch ? versionMatch[1] : 'unknown',
+  };
+}
+
+// ── Environment Detection ──
+
+/**
+ * Detect Python environment type.
+ */
+export function detectEnvironment(cwd?: string): { type: PythonHealthResult['environment']['type']; path: string | null } {
+  const env = process.env;
+
+  // conda
+  if (env.CONDA_PREFIX) return { type: 'conda', path: env.CONDA_PREFIX };
+  if (env.CONDA_DEFAULT_ENV) return { type: 'conda', path: env.CONDA_DEFAULT_ENV };
+
+  // venv / virtualenv
+  if (env.VIRTUAL_ENV) return { type: 'venv', path: env.VIRTUAL_ENV };
+
+  // uv
+  const dir = cwd || process.cwd();
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    if (fs.existsSync(path.join(dir, 'uv.lock'))) return { type: 'uv', path: dir };
+    if (fs.existsSync(path.join(dir, '.python-version'))) return { type: 'pyenv', path: dir };
+    if (fs.existsSync(path.join(dir, '.venv'))) return { type: 'venv', path: path.join(dir, '.venv') };
+  } catch { /* ignore */ }
+
+  return { type: 'system', path: null };
+}
+
+// ── Tool Checking ──
+
+/**
+ * Check availability of Python tools using common.ts infrastructure.
+ */
+export function checkTools(pythonExe: string, cwd?: string): PythonHealthResult['tools'] {
+  const tools: PythonHealthResult['tools'] = [];
+
+  for (const name of PYTHON_REQUIRED_TOOLS) {
+    const tool = checkPythonTool(name, pythonExe, cwd);
+    tools.push({ ...tool, required: true });
+  }
+
+  for (const name of PYTHON_OPTIONAL_TOOLS) {
+    const tool = checkPythonTool(name, pythonExe, cwd);
+    tools.push({ ...tool, required: false });
+  }
+
+  return tools;
+}
+
+function checkPythonTool(
+  name: string,
+  pythonExe: string,
+  cwd?: string
+): { name: string; available: boolean; version: string } {
+  // Try via <python-exe> -m <tool> --version first (ensures correct env)
+  if (pythonExe) {
+    const result = runTool(pythonExe, ['-m', name, '--version'], { timeoutMs: 5000, cwd });
+    if (result.exitCode === 0) {
+      const output = (result.stdout + result.stderr).trim();
+      const versionMatch = output.match(/(\d+\.\d+(?:\.\d+)?)/);
+      return { name, available: true, version: versionMatch ? versionMatch[1] : 'unknown' };
+    }
+  }
+
+  // Fallback: direct tool detection via common.ts
+  const tool = isToolAvailable(name, cwd);
+  if (tool.available) {
+    const verResult = runTool(tool.path === `npx ${name}` ? 'npx' : tool.path,
+      tool.path === `npx ${name}` ? ['-y', name, '--version'] : ['--version'],
+      { timeoutMs: 5000, cwd });
+    const output = (verResult.stdout + verResult.stderr).trim();
+    const versionMatch = output.match(/(\d+\.\d+(?:\.\d+)?)/);
+    return { name, available: true, version: versionMatch ? versionMatch[1] : 'unknown' };
+  }
+
+  return { name, available: false, version: '' };
+}
+
+// ── Main Health Check ──
+
+/**
+ * Run comprehensive Python environment health check.
+ */
+export function checkPythonHealth(cwd?: string): PythonHealthResult {
+  const issues: string[] = [];
+
+  // 1. Detect Python
+  const python = detectPython();
+  if (!python.available) {
+    issues.push('Python 3 not found. Install from https://python.org/downloads');
+    return {
+      healthy: false,
+      python,
+      pip: { available: false, version: '' },
+      environment: { type: 'system', path: null },
+      tools: [],
+      issues,
+    };
+  }
+
+  // 2. Check version
+  if (!checkPythonVersion(python.version)) {
+    issues.push(`Python ${python.version} < 3.8.0 minimum. Upgrade recommended.`);
+  }
+
+  // 3. Detect pip
+  const pip = detectPip(python.exe);
+  if (!pip.available) {
+    issues.push(`pip not available. Install: ${python.exe} -m ensurepip`);
+  }
+
+  // 4. Detect environment
+  const environment = detectEnvironment(cwd);
+  if (environment.type === 'system') {
+    issues.push('No virtual environment detected. Consider using venv/conda/uv.');
+  }
+
+  // 5. Check tools
+  const tools = checkTools(python.exe, cwd);
+  const missingRequired = tools.filter(t => t.required && !t.available);
+  if (missingRequired.length > 0) {
+    const names = missingRequired.map(t => t.name).join(', ');
+    issues.push(`Required tools missing: ${names}. Install: ${python.exe} -m pip install ${names}`);
+  }
+
+  const healthy = issues.filter(i => i.includes('not found') || i.includes('minimum')).length === 0
+    && missingRequired.length === 0;
+
+  return { healthy, python, pip, environment, tools, issues };
+}
+
+// ── CLI Entry Point ──
+
+if (process.argv.includes('--run')) {
+  const cwdIdx = process.argv.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 ? process.argv[cwdIdx + 1] : process.cwd();
+  const result = checkPythonHealth(cwd);
+
+  console.log('');
+  console.log('━━━ Python Environment Health Check ━━━');
+  console.log('');
+  console.log(`  Python:    ${result.python.available ? `✅ ${result.python.exe} (${result.python.version})` : '❌ Not found'}`);
+  console.log(`  pip:       ${result.pip.available ? `✅ ${result.pip.version}` : '❌ Not available'}`);
+  console.log(`  Env:       ${result.environment.type}${result.environment.path ? ` (${result.environment.path})` : ''}`);
+  console.log('');
+
+  if (result.tools.length > 0) {
+    console.log('  Tools:');
+    for (const t of result.tools) {
+      const icon = t.available ? '✅' : (t.required ? '❌' : '⚠️');
+      const req = t.required ? '(required)' : '(optional)';
+      console.log(`    ${icon} ${t.name} ${t.available ? t.version : 'not installed'} ${req}`);
+    }
+    console.log('');
+  }
+
+  if (result.issues.length > 0) {
+    console.log('  Issues:');
+    result.issues.forEach(i => console.log(`    ⚠️  ${i}`));
+    console.log('');
+  }
+
+  if (result.healthy) {
+    console.log('  ✅ Python environment is healthy.');
+  } else {
+    console.log('  ❌ Python environment has issues.');
+  }
+
+  process.exit(result.healthy ? 0 : 1);
+}

package/gates/test-layers.ts

@@ -0,0 +1,312 @@
+/**
+ * Test Layer Analytics — reports test distribution across unit/integration/e2e layers.
+ * Implements #359: layered test protection network (analytics/report mode).
+ *
+ * Does NOT block commits/pushes. Provides visibility into test coverage distribution.
+ */
+import fs from 'fs';
+import path from 'path';
+
+// ── Types ──
+
+export interface TestLayerReport {
+  summary: {
+    totalSources: number;
+    totalTests: number;
+    unitTests: number;
+    integrationTests: number;
+    e2eTests: number;
+  };
+  layer1: {
+    pairedSources: number;
+    unpairedSources: string[];
+    pairRate: number;
+  };
+  layer2: {
+    integrationFiles: number;
+  };
+  layer3: {
+    e2eFiles: number;
+  };
+  verdict: 'INFO';
+  messages: string[];
+}
+
+// ── File Classification ──
+
+/** Files excluded from source counting (not implementation files). */
+const EXCLUDED_PATTERNS = [
+  /\.d\.ts$/,
+  /\.test\.ts$/,
+  /\.spec\.ts$/,
+  /\.e2e\.test\.ts$/,
+  /\.integration\.test\.ts$/,
+  /\/__tests__\//,
+  /\/__mocks__\//,
+  /\/node_modules\//,
+];
+
+/** Source files that don't need tests (pure declarations, configs, types). */
+const EXEMPT_FILENAMES = [
+  'types.ts', 'interfaces.ts', 'constants.ts', 'config.ts',
+  'index.ts', 'main.ts', 'app.ts',
+];
+
+function isExcluded(filePath: string): boolean {
+  const normalized = filePath.replace(/\\/g, '/');
+  return EXCLUDED_PATTERNS.some(p => p.test(normalized));
+}
+
+function isExempt(filename: string): boolean {
+  return EXEMPT_FILENAMES.includes(filename);
+}
+
+function isTestFile(filePath: string): boolean {
+  const normalized = filePath.replace(/\\/g, '/');
+  return /\.test\.(ts|js)$/.test(normalized) || /\.spec\.(ts|js)$/.test(normalized);
+}
+
+function classifyTestLayer(filePath: string): 'unit' | 'integration' | 'e2e' | 'unknown' {
+  const normalized = filePath.replace(/\\/g, '/');
+  if (/\.e2e\.test\./.test(normalized) || /\/e2e\//.test(normalized)) return 'e2e';
+  if (/\.integration\.test\./.test(normalized) || /\/integration\//.test(normalized)) return 'integration';
+  if (isTestFile(filePath)) return 'unit';
+  return 'unknown';
+}
+
+/**
+ * Find the expected test file for a source file.
+ * Convention: src/foo/bar.ts → src/__tests__/bar.test.ts or src/foo/bar.test.ts
+ */
+function findExpectedTest(sourcePath: string, allFiles: string[]): string | null {
+  const basename = path.basename(sourcePath, '.ts');
+  const dir = path.dirname(sourcePath);
+
+  // Check adjacent test file: src/foo/bar.ts → src/foo/bar.test.ts
+  const adjacentTest = path.join(dir, `${basename}.test.ts`);
+  if (allFiles.includes(adjacentTest)) return adjacentTest;
+
+  // Check __tests__ directory: src/foo/bar.ts → src/foo/__tests__/bar.test.ts
+  const testsDirTest = path.join(dir, '__tests__', `${basename}.test.ts`);
+  if (allFiles.includes(testsDirTest)) return testsDirTest;
+
+  // Check parent __tests__: src/foo/bar.ts → src/__tests__/bar.test.ts
+  const parentDir = path.dirname(dir);
+  const parentTestsTest = path.join(parentDir, '__tests__', `${basename}.test.ts`);
+  if (allFiles.includes(parentTestsTest)) return parentTestsTest;
+
+  return null;
+}
+
+// ── Directory Scanner ──
+
+/**
+ * Directories that never hold hand-written source, so scanning them inflates
+ * the source count and fabricates "unpaired" entries (#636 follow-up).
+ *
+ * `coverage` matters most: `src/npm-package/coverage/` is a gitignored istanbul
+ * output directory (`.gitignore:99`), so it is untracked yet full of `.js`
+ * files. Counting `block-navigation.js` / `prettify.js` / `sorter.js` as sources
+ * understated the pairing rate and pushed three phantom files into the unpaired
+ * list — the metric was measuring a build artifact.
+ *
+ * Kept as a Set for O(1) lookup; names are matched exactly, not by substring,
+ * so a real source directory called e.g. `coverage-rules/` stays scanned.
+ */
+const SKIPPED_DIRECTORIES = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'coverage',
+  '__pycache__',
+  '.next',
+  '.turbo',
+  'build',
+  'out',
+]);
+
+/**
+ * Read a directory, tolerating the ways it can be unreadable.
+ *
+ * An unreadable directory (EACCES, ENOENT from a racing delete, a broken
+ * symlink) must not abort the whole scan: this runs inside gate reporting, where
+ * a partial answer beats a crash. Returning an empty list skips the subtree
+ * instead of throwing.
+ */
+function readDirectoryEntries(dir: string): fs.Dirent[] {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function scanDirectory(dir: string, basePath?: string): string[] {
+  const results: string[] = [];
+  const base = basePath || dir;
+
+  if (!fs.existsSync(dir)) return results;
+
+  for (const entry of readDirectoryEntries(dir)) {
+    const fullPath = path.join(dir, entry.name);
+    const relativePath = path.relative(base, fullPath).replace(/\\/g, '/');
+
+    if (entry.isDirectory()) {
+      if (SKIPPED_DIRECTORIES.has(entry.name)) continue;
+      results.push(...scanDirectory(fullPath, base));
+    } else if (entry.name.endsWith('.ts') || entry.name.endsWith('.js')) {
+      results.push(relativePath);
+    }
+  }
+
+  return results;
+}
+
+// ── Main Analysis ──
+
+/** How many unpaired sources are listed individually before summarising. */
+const UNPAIRED_DISPLAY_LIMIT = 10;
+
+/** The per-layer counts one scan produces, before formatting. */
+interface LayerCounts {
+  sourceFiles: string[];
+  testFiles: string[];
+  unitTests: string[];
+  integrationTests: string[];
+  e2eTests: string[];
+  unpairedSources: string[];
+  pairedCount: number;
+}
+
+/**
+ * Append the Layer 1 block: pairing rate plus the unpaired list, truncated once
+ * it gets long enough that printing every path would bury the summary (#620).
+ */
+function appendPairingLines(messages: string[], counts: LayerCounts, totalNeedingTests: number): void {
+  const pairRate = totalNeedingTests > 0
+    ? Math.round((counts.pairedCount / totalNeedingTests) * 100)
+    : 100;
+  messages.push('  Layer 1 (Unit Pairing):');
+  messages.push(`    Paired:    ${counts.pairedCount}/${totalNeedingTests} (${pairRate}%)`);
+
+  const unpaired = counts.unpairedSources;
+  if (unpaired.length === 0 || unpaired.length > UNPAIRED_DISPLAY_LIMIT) {
+    if (unpaired.length > 0) {
+      messages.push(`    Unpaired:  ${unpaired.length} files (showing first 10)`);
+      unpaired.slice(0, UNPAIRED_DISPLAY_LIMIT).forEach(f => messages.push(`      - ${f}`));
+    }
+    return;
+  }
+  messages.push(`    Unpaired:  ${unpaired.join(', ')}`);
+}
+
+/** Format the console block for one analysis. */
+function buildLayerMessages(counts: LayerCounts, totalNeedingTests: number): string[] {
+  const messages: string[] = [
+    '',
+    '━━━ Test Layer Analytics ━━━',
+    '',
+    `  Sources:     ${counts.sourceFiles.length} files`,
+    `  Tests:       ${counts.testFiles.length} total`,
+    `    Unit:      ${counts.unitTests.length}`,
+    `    Integra:   ${counts.integrationTests.length}`,
+    `    E2E:       ${counts.e2eTests.length}`,
+    '',
+  ];
+
+  appendPairingLines(messages, counts, totalNeedingTests);
+
+  // Layers 2 and 3 only earn a section when they have content.
+  if (counts.integrationTests.length > 0) {
+    messages.push('', `  Layer 2 (Integration): ${counts.integrationTests.length} files`);
+  }
+  if (counts.e2eTests.length > 0) {
+    messages.push('', `  Layer 3 (E2E): ${counts.e2eTests.length} files`);
+  }
+  messages.push('');
+
+  return messages;
+}
+
+/**
+ * Layer 1 pairing: split sources into paired and unpaired against the sibling
+ * test that should cover each one. Works on src-relative paths because
+ * findExpectedTest resolves a source path against that root.
+ */
+function computePairing(
+  sourceFiles: string[],
+  allFiles: string[],
+): { unpairedSources: string[]; pairedCount: number } {
+  const allSourceRelative = allFiles.map(f => path.join('src', f));
+  const unpairedSources: string[] = [];
+  let pairedCount = 0;
+
+  for (const source of sourceFiles) {
+    if (isExempt(path.basename(source))) continue;
+    if (findExpectedTest(path.join('src', source), allSourceRelative)) {
+      pairedCount++;
+    } else {
+      unpairedSources.push(source);
+    }
+  }
+
+  return { unpairedSources, pairedCount };
+}
+
+/**
+ * Analyze test layer distribution for a project.
+ */
+export function analyzeTestLayers(cwd?: string): TestLayerReport {
+  const dir = cwd || process.cwd();
+  const allFiles = scanDirectory(path.join(dir, 'src'));
+
+  const sourceFiles = allFiles.filter(f => !isExcluded(f) && !isTestFile(f));
+  const testFiles = allFiles.filter(f => isTestFile(f));
+  const byLayer = (layer: string): string[] => testFiles.filter(f => classifyTestLayer(f) === layer);
+
+  const { unpairedSources, pairedCount } = computePairing(sourceFiles, allFiles);
+
+  const counts: LayerCounts = {
+    sourceFiles,
+    testFiles,
+    unitTests: byLayer('unit'),
+    integrationTests: byLayer('integration'),
+    e2eTests: byLayer('e2e'),
+    unpairedSources,
+    pairedCount,
+  };
+  const totalNeedingTests = sourceFiles.filter(f => !isExempt(path.basename(f))).length;
+
+  return {
+    summary: {
+      totalSources: sourceFiles.length,
+      totalTests: testFiles.length,
+      unitTests: counts.unitTests.length,
+      integrationTests: counts.integrationTests.length,
+      e2eTests: counts.e2eTests.length,
+    },
+    layer1: {
+      pairedSources: pairedCount,
+      unpairedSources,
+      pairRate: totalNeedingTests > 0 ? Math.round((pairedCount / totalNeedingTests) * 100) : 100,
+    },
+    layer2: {
+      integrationFiles: counts.integrationTests.length,
+    },
+    layer3: {
+      e2eFiles: counts.e2eTests.length,
+    },
+    verdict: 'INFO',
+    messages: buildLayerMessages(counts, totalNeedingTests),
+  };
+}
+
+// ── CLI Entry Point ──
+
+if (process.argv.includes('--run')) {
+  const cwdIdx = process.argv.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 ? process.argv[cwdIdx + 1] : process.cwd();
+  const report = analyzeTestLayers(cwd);
+  report.messages.forEach(m => console.log(m));
+  process.exit(0);
+}

package/lib/__tests__/check-changed-brief.test.js

@@ -0,0 +1,63 @@
+/**
+ * @test check-changed-brief
+ * @intent Prove `xp-gate check --changed --brief` scopes to the current diff, prints one honest verdict per gate, and never reports a gate as PASS when it did not run
+ * @covers AC-DSH-019
+ */
+const { fileExtension, printBriefSummary } = require('../check.js');
+
+describe('check --changed --brief helpers', () => {
+  describe('fileExtension', () => {
+    it('returns the lowercased extension without the dot', () => {
+      expect(fileExtension('src/a/B.TS')).toBe('ts');
+      expect(fileExtension('x/y/z.mjs')).toBe('mjs');
+    });
+
+    it('returns empty string for a path without an extension', () => {
+      expect(fileExtension('Makefile')).toBe('');
+      expect(fileExtension('docs/README')).toBe('');
+    });
+  });
+
+  describe('printBriefSummary', () => {
+    function capture(fn) {
+      const lines = [];
+      const spy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
+      const ret = fn();
+      spy.mockRestore();
+      return { out: lines.join('\n'), ret };
+    }
+
+    it('reports one PASS line per passing gate and returns 0 failures', () => {
+      const { out, ret } = capture(() =>
+        printBriefSummary(['a.ts'], ['a.ts'], [{ id: '3', code: 0 }, { id: '4', code: 0 }], 12),
+      );
+      expect(out).toMatch(/Gate 3 Complexity\s+PASS/);
+      expect(out).toMatch(/Gate 4 Principles\s+PASS/);
+      expect(out).toMatch(/✅ clear/);
+      expect(ret).toBe(0);
+    });
+
+    it('reports BLOCK and counts failures when a gate fails', () => {
+      const { out, ret } = capture(() =>
+        printBriefSummary(['a.ts'], ['a.ts'], [{ id: '3', code: 0 }, { id: '4', code: 1 }], 12),
+      );
+      expect(out).toMatch(/Gate 4 Principles\s+BLOCK/);
+      expect(out).toMatch(/❌ 1 blocking/);
+      expect(ret).toBe(1);
+    });
+
+    it('never prints PASS for a gate that did not run (NOT_RUN -> SKIP)', () => {
+      const { out, ret } = capture(() =>
+        printBriefSummary(['a.ts'], ['a.ts'], [{ id: '3', code: 'NOT_RUN' }], 5),
+      );
+      expect(out).toMatch(/Gate 3 Complexity\s+SKIP/);
+      expect(out).not.toMatch(/Gate 3 Complexity\s+PASS/);
+      expect(ret).toBe(0);
+    });
+
+    it('states docs/config-only diffs apply no blocking source gate', () => {
+      const { out } = capture(() => printBriefSummary(['README.md'], [], [], 3));
+      expect(out).toMatch(/No source files changed/);
+    });
+  });
+});

package/lib/__tests__/check-normalize-exit.test.js

@@ -0,0 +1,24 @@
+/**
+ * @test check-normalize-exit
+ * @intent Prove the CLI never hands a non-numeric verdict to process.exit (the #657 crash) and that ONLY the GATE_NOT_RUN sentinel is coerced to 0
+ * @covers AC-DSH-019
+ */
+const { normalizeGateExit } = require('../check.js');
+
+describe('normalizeGateExit (#657)', () => {
+  it('coerces the GATE_NOT_RUN string sentinel to 0 (honest skip, not a crash)', () => {
+    expect(normalizeGateExit('NOT_RUN')).toBe(0);
+  });
+
+  it('passes real numeric verdicts through unchanged', () => {
+    expect(normalizeGateExit(0)).toBe(0);
+    expect(normalizeGateExit(1)).toBe(1);
+    expect(normalizeGateExit(2)).toBe(2);
+  });
+
+  it('never returns a non-number for any input', () => {
+    for (const v of ['NOT_RUN', 0, 1, undefined, null]) {
+      expect(typeof normalizeGateExit(v)).toBe('number');
+    }
+  });
+});

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

@@ -109,4 +109,25 @@ describe('shared-utils', () => {
     });
   });
 
+  describe('copyHooks ships hook-module-resolution.sh (#655/#631)', () => {
+    it('@covers gate-script deployment: copyHooks installs hook-module-resolution.sh so pre-commit does not FATAL', () => {
+      // pre-commit loads hook-module-resolution.sh before any tier decision and
+      // fails closed. It was absent from copyHooks, so every fresh `init` /
+      // `setup-global` produced hooks that FATAL'd on every commit.
+      const pkgRoot = path.join(tmpRoot, 'node_modules', '@boyingliu01', 'xp-gate');
+      const hooksSrc = path.join(pkgRoot, 'hooks');
+      fs.mkdirSync(hooksSrc, { recursive: true });
+      for (const h of ['pre-commit', 'pre-push', 'post-commit', 'post-merge', 'hook-module-resolution.sh']) {
+        fs.writeFileSync(path.join(hooksSrc, h), `# ${h}`);
+      }
+      const destDir = path.join(tmpRoot, 'dest-hooks');
+      fs.mkdirSync(destDir, { recursive: true });
+
+      const { copyHooks } = require('../shared-utils');
+      copyHooks(pkgRoot, destDir);
+
+      expect(fs.existsSync(path.join(destDir, 'hook-module-resolution.sh'))).toBe(true);
+    });
+  });
+
 });