@boyingliu01/xp-gate 0.8.9 → 0.8.11

package/lib/init.js

@@ -37,6 +37,18 @@ function copyAdapters(srcDir, destDir) {
   }
 }
 
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    fs.readdirSync(src).forEach(entry => {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    });
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
 function logDeps(depCheck) {
   if (!depCheck.ok) {
     console.warn('Warning: Missing dependencies');
@@ -304,6 +316,18 @@ async function installLocal(args) {
   copyAdapters(srcDir, path.join(projectRoot, 'githooks'));
   console.log(`  adapter-common.sh + adapters -> ${projectRoot}/githooks/`);
 
+  // Install principles/, mutation/, mock-policy/ to .xp-gate/modules/
+  const modulesDir = path.join(projectRoot, '.xp-gate', 'modules');
+  ['principles', 'mutation', 'mock-policy'].forEach(module => {
+    const moduleSrc = path.join(srcDir, module);
+    const moduleDest = path.join(modulesDir, module);
+    if (fs.existsSync(moduleSrc)) {
+      fs.mkdirSync(path.dirname(moduleDest), { recursive: true });
+      copyRecursive(moduleSrc, moduleDest);
+      console.log(`  ${module}/ -> .xp-gate/modules/${module}/`);
+    }
+  });
+
   fs.mkdirSync(TEMPLATE_DIR, { recursive: true });
   copyHooks(srcDir, TEMPLATE_DIR);
   fs.mkdirSync(path.join(TEMPLATE_DIR, 'adapters'), { recursive: true });
@@ -341,6 +365,18 @@ async function setupGlobal(args) {
   copyAdapters(srcDir, GLOBAL_ADAPTERS_DIR);
   console.log(`  adapter-common.sh + adapters -> ${GLOBAL_ADAPTERS_DIR}`);
 
+  // Install principles/, mutation/, mock-policy/ to global modules dir
+  const globalModulesDir = path.join(CONFIG_DIR, 'modules');
+  ['principles', 'mutation', 'mock-policy'].forEach(module => {
+    const moduleSrc = path.join(srcDir, module);
+    const moduleDest = path.join(globalModulesDir, module);
+    if (fs.existsSync(moduleSrc)) {
+      fs.mkdirSync(path.dirname(moduleDest), { recursive: true });
+      copyRecursive(moduleSrc, moduleDest);
+      console.log(`  ${module}/ -> ${globalModulesDir}/${module}/`);
+    }
+  });
+
   const { execSync } = require('child_process');
   try {
     execSync(`git config --global core.hooksPath "${GLOBAL_HOOKS_DIR}"`);

package/mock-policy/AGENTS.md

@@ -0,0 +1,94 @@
+# SRC/MOCK-POLICY KNOWLEDGE BASE
+
+**Generated:** 2026-06-14
+**Commit:** 348c405
+**Branch:** main
+**Version:** 0.8.11.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.
+
+## STRUCTURE
+```
+src/mock-policy/
+├── types.ts                    # Type definitions (MockStrategy, ProjectScope, MockDecision, etc.)
+├── schema.ts                   # Zod schema for MockPolicyConfig validation
+├── config.ts                   # loadMockPolicyConfig — loads from .mockpolicyrc / .xp-gate/mock-policy.yaml
+├── scope-scanner.ts            # scanProjectScope — classifies imports as internal/external/pending
+├── mock-decision-engine.ts     # MockDecisionEngine — decides mock vs real per import + test layer
+├── gate-m3.ts                  # runGateM3 — orchestrator: filter test files → scan scope → validate
+└── __tests__/
+    ├── config.test.ts          # Config loader unit tests
+    ├── scope-scanner.test.ts   # Scope scanner unit + tmpdir integration tests
+    ├── mock-decision-engine.test.ts  # Decision engine unit tests
+    └── integration.test.ts     # Full pipeline integration test
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Types/Interfaces | types.ts | MockStrategy, ProjectScope, MockPolicyConfig, MockPolicyResult |
+| Config loading | config.ts | .mockpolicyrc (JSON) > .xp-gate/mock-policy.yaml (YAML) > DEFAULT_CONFIG |
+| Schema validation | schema.ts | Zod schema for full config validation |
+| Scope scanning | scope-scanner.ts | scanProjectScope, classifyDependency, isExternalImport, loadExternalDependencies |
+| Mock decisions | mock-decision-engine.ts | MockDecisionEngine.decide() — decision matrix per test layer |
+| Gate runner | gate-m3.ts | runGateM3, validateFile, collectImports, detectMockUsage |
+| Integration tests | __tests__/integration.test.ts | End-to-end pipeline with temp project directories |
+
+## CODE MAP
+| Symbol | Type | Location | Role |
+|--------|------|----------|------|
+| runGateM3 | Function | gate-m3.ts | Orchestrator: filter test files → scan scope → validate → return MockPolicyResult |
+| validateFile | Function | gate-m3.ts | Per-file validation: read content → detect layer → check imports → compare decision vs usage |
+| collectImports | Function | gate-m3.ts | Regex-based import extraction (static + dynamic) |
+| detectMockUsage | Function | gate-m3.ts | Checks for vi.mock/jest.mock/vi.doMock calls matching an import |
+| MockDecisionEngine | Class | mock-decision-engine.ts | decide(importPath, layer) → MockDecision with strategy/reason/pendingRemoval |
+| scanProjectScope | Function | scope-scanner.ts | Classifies imports into implemented/unimplemented/external |
+| classifyDependency | Function | scope-scanner.ts | Single dependency scope classification with optional existCache |
+| isExternalImport | Function | scope-scanner.ts | Checks Node.js builtins, bare npm packages, boundary patterns |
+| loadExternalDependencies | Function | scope-scanner.ts | Reads package.json dependencies (skips workspace:* protocol) |
+| loadMockPolicyConfig | Function | config.ts | Config loader with fallback chain and Zod validation |
+| detectTestLayer | Function | src/mutation/detect-ai-test.ts | Classifies test file path as unit/integration/e2e/unknown |
+
+## CONVENTIONS
+- Decision matrix: e2e=always real, unit(lenient)=always mock, unit(strict)=integration-like, integration=scope-based
+- Pending dependencies in integration tests require `@mock-justified` annotation
+- Default severity: `warning` (does NOT block push)
+- Default boundary: `['src/**']`
+- Default integration policy: strict, requireRealForImplemented=true, allowExternalMock=true, requirePendingRemoval=true
+- Default e2e policy: strict, allowExternalMock=false, maxMockDensity=0
+- Unit tests with lenient policy are not checked — all mocks allowed
+- Config resolution: `.mockpolicyrc` (JSON) > `.xp-gate/mock-policy.yaml` (YAML) > `DEFAULT_CONFIG`
+- Config validated via Zod schema before use
+
+## ANTI-PATTERNS (THIS PROJECT)
+- Do NOT use `as any` or `@ts-ignore` in mock-policy code
+- Do NOT set severity to `error` without verifying integration test suite
+- Do NOT disable mock checks entirely by setting zero thresholds
+- Do NOT import from `gate-m3.ts` private functions — they are deliberately not exported
+
+## UNIQUE STYLES
+- Gate M3 is the third pre-push gate (after Gate M mutation + Gate M2 AI test detection)
+- Pipeline: filterTestFiles → loadConfig → collectAllImports → scanProjectScope → MockDecisionEngine → validateFile per file → aggregate violations
+- Uses real filesystem for scope scanning (no virtual filesystem abstraction)
+- Integration tests use tmpdir with real package.json + source files
+- Test layer detection delegates to `src/mutation/detect-ai-test.ts`
+
+## COMMANDS
+```bash
+# Run Gate M3 directly on changed files
+npx tsx src/mock-policy/gate-m3.ts <test-file-1> <test-file-2> ...
+
+# Run all mock-policy unit tests
+npx vitest run src/mock-policy/__tests__/
+
+# Run just the integration test
+npx vitest run src/mock-policy/__tests__/integration.test.ts
+```
+
+## NOTES
+- Gate M3 is invoked by pre-push hook after Gate M (mutation) and Gate M2 (AI test detection)
+- push limits: max 20 files or 500 LOC per push — Gate M3 respects this via the changed files input
+- Coverage exclude: src/mock-policy/ controlled by vitest config
+- The integration test creates real temporary directories under os.tmpdir()
+- Dependencies on: `src/mutation/detect-ai-test.ts` (detectTestLayer)

package/mock-policy/__tests__/config.test.ts

@@ -0,0 +1,292 @@
+/**
+ * @test config.ts - Mock Policy config loader
+ * @intent Verify config loads and validates correctly from .mockpolicyrc and .xp-gate/mock-policy.yaml
+ * @covers mock-policy-config-loader
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Shared mock state — each test sets these before re-importing the module
+let mockExistsSync: (path: string) => boolean;
+let mockReadFile: (path: string) => Promise<string>;
+
+vi.mock('fs', () => ({
+  existsSync: vi.fn((path: string) => mockExistsSync(path)),
+}));
+
+vi.mock('fs/promises', () => ({
+  readFile: vi.fn((path: string) => mockReadFile(path)),
+}));
+
+const MOCK_DEFAULT_CONFIG = {
+  version: 1 as const,
+  layers: {
+    unit: {
+      mockPolicy: 'lenient' as const,
+      requireRealForImplemented: false,
+      allowExternalMock: true,
+      requirePendingRemoval: false,
+      maxMockDensity: 100,
+    },
+    integration: {
+      mockPolicy: 'strict' as const,
+      requireRealForImplemented: true,
+      allowExternalMock: true,
+      requirePendingRemoval: true,
+      maxMockDensity: 30,
+    },
+    e2e: {
+      mockPolicy: 'strict' as const,
+      requireRealForImplemented: true,
+      allowExternalMock: false,
+      requirePendingRemoval: false,
+      maxMockDensity: 0,
+    },
+  },
+  projectBoundary: ['src/**'],
+  severity: 'warning' as const,
+};
+
+describe('loadMockPolicyConfig', () => {
+  let loadMockPolicyConfig: typeof import('../config').loadMockPolicyConfig;
+  let DEFAULT_CONFIG: typeof import('../config').DEFAULT_CONFIG;
+
+  beforeEach(async () => {
+    // Default: no config files exist
+    mockExistsSync = () => false;
+    mockReadFile = () => Promise.reject(new Error('ENOENT'));
+
+    // Re-import after mock state is set
+    vi.resetModules();
+    const mod = await import('../config');
+    loadMockPolicyConfig = mod.loadMockPolicyConfig;
+    DEFAULT_CONFIG = mod.DEFAULT_CONFIG;
+  });
+
+  describe('DEFAULT_CONFIG', () => {
+    it('should have correct default values', () => {
+      expect(DEFAULT_CONFIG).toEqual(MOCK_DEFAULT_CONFIG);
+    });
+
+    it('should have lenient unit policy', () => {
+      expect(DEFAULT_CONFIG.layers.unit.mockPolicy).toBe('lenient');
+      expect(DEFAULT_CONFIG.layers.unit.allowExternalMock).toBe(true);
+    });
+
+    it('should have strict integration policy', () => {
+      expect(DEFAULT_CONFIG.layers.integration.mockPolicy).toBe('strict');
+      expect(DEFAULT_CONFIG.layers.integration.requirePendingRemoval).toBe(true);
+      expect(DEFAULT_CONFIG.layers.integration.maxMockDensity).toBe(30);
+    });
+
+    it('should have strict e2e policy forbidding external mocks', () => {
+      expect(DEFAULT_CONFIG.layers.e2e.allowExternalMock).toBe(false);
+      expect(DEFAULT_CONFIG.layers.e2e.maxMockDensity).toBe(0);
+    });
+
+    it('should have projectBoundary and warning severity', () => {
+      expect(DEFAULT_CONFIG.projectBoundary).toEqual(['src/**']);
+      expect(DEFAULT_CONFIG.severity).toBe('warning');
+    });
+  });
+
+  describe('no config files exist', () => {
+    it('should return default config when no files found', async () => {
+      const config = await loadMockPolicyConfig('/fake/project');
+      expect(config).toEqual(DEFAULT_CONFIG);
+    });
+  });
+
+  describe('JSON config (.mockpolicyrc)', () => {
+    it('should merge partial JSON config with defaults', async () => {
+      mockExistsSync = (path: string) => path.endsWith('.mockpolicyrc');
+      mockReadFile = (path: string) => {
+        if (path.endsWith('.mockpolicyrc')) {
+          return Promise.resolve(JSON.stringify({
+            severity: 'error',
+            layers: {
+              unit: { mockPolicy: 'strict', maxMockDensity: 50 },
+            },
+          }));
+        }
+        return Promise.reject(new Error('file not found'));
+      };
+
+      vi.resetModules();
+      const mod = await import('../config');
+      loadMockPolicyConfig = mod.loadMockPolicyConfig;
+
+      const config = await loadMockPolicyConfig('/fake/project');
+
+      expect(config.severity).toBe('error');
+      expect(config.layers.unit.mockPolicy).toBe('strict');
+      expect(config.layers.unit.maxMockDensity).toBe(50);
+      // Defaults preserved for non-overridden fields
+      expect(config.layers.unit.requireRealForImplemented).toBe(false);
+      expect(config.layers.unit.allowExternalMock).toBe(true);
+      expect(config.layers.integration).toEqual(MOCK_DEFAULT_CONFIG.layers.integration);
+      expect(config.layers.e2e).toEqual(MOCK_DEFAULT_CONFIG.layers.e2e);
+      expect(config.projectBoundary).toEqual(MOCK_DEFAULT_CONFIG.projectBoundary);
+    });
+
+    it('should load full JSON config correctly', async () => {
+      const fullConfig = {
+        version: 1,
+        layers: {
+          unit: {
+            mockPolicy: 'strict' as const,
+            requireRealForImplemented: true,
+            allowExternalMock: false,
+            requirePendingRemoval: true,
+            maxMockDensity: 80,
+          },
+          integration: {
+            mockPolicy: 'strict' as const,
+            requireRealForImplemented: true,
+            allowExternalMock: false,
+            requirePendingRemoval: true,
+            maxMockDensity: 20,
+          },
+          e2e: {
+            mockPolicy: 'strict' as const,
+            requireRealForImplemented: true,
+            allowExternalMock: false,
+            requirePendingRemoval: true,
+            maxMockDensity: 5,
+          },
+        },
+        projectBoundary: ['src/**', '!src/external/**'],
+        severity: 'error' as const,
+      };
+
+      mockExistsSync = (path: string) => path.endsWith('.mockpolicyrc');
+      mockReadFile = (path: string) => {
+        if (path.endsWith('.mockpolicyrc')) {
+          return Promise.resolve(JSON.stringify(fullConfig));
+        }
+        return Promise.reject(new Error('file not found'));
+      };
+
+      vi.resetModules();
+      const mod = await import('../config');
+      loadMockPolicyConfig = mod.loadMockPolicyConfig;
+
+      const config = await loadMockPolicyConfig('/fake/project');
+
+      expect(config.layers.unit.maxMockDensity).toBe(80);
+      expect(config.layers.integration.mockPolicy).toBe('strict');
+      expect(config.layers.e2e.maxMockDensity).toBe(5);
+      expect(config.projectBoundary).toEqual(['src/**', '!src/external/**']);
+      expect(config.severity).toBe('error');
+    });
+  });
+
+  describe('YAML config (.xp-gate/mock-policy.yaml)', () => {
+    it('should load YAML config as fallback', async () => {
+      mockExistsSync = (path: string) => path.endsWith('mock-policy.yaml');
+      mockReadFile = (path: string) => {
+        if (path.endsWith('mock-policy.yaml')) {
+          return Promise.resolve(`
+version: 1
+severity: error
+layers:
+  unit:
+    mockPolicy: strict
+    maxMockDensity: 60
+projectBoundary:
+  - src/**
+          `);
+        }
+        return Promise.reject(new Error('file not found'));
+      };
+
+      vi.resetModules();
+      const mod = await import('../config');
+      loadMockPolicyConfig = mod.loadMockPolicyConfig;
+
+      const config = await loadMockPolicyConfig('/fake/project');
+
+      expect(config.severity).toBe('error');
+      expect(config.layers.unit.mockPolicy).toBe('strict');
+      expect(config.layers.unit.maxMockDensity).toBe(60);
+      expect(config.projectBoundary).toEqual(['src/**']);
+    });
+
+    it('should prefer JSON over YAML when both exist', async () => {
+      mockExistsSync = (path: string) =>
+        path.endsWith('.mockpolicyrc') || path.endsWith('mock-policy.yaml');
+      mockReadFile = (path: string) => {
+        if (path.endsWith('.mockpolicyrc')) {
+          return Promise.resolve(JSON.stringify({ severity: 'error' }));
+        }
+        if (path.endsWith('mock-policy.yaml')) {
+          return Promise.resolve('severity: warning');
+        }
+        return Promise.reject(new Error('file not found'));
+      };
+
+      vi.resetModules();
+      const mod = await import('../config');
+      loadMockPolicyConfig = mod.loadMockPolicyConfig;
+
+      const config = await loadMockPolicyConfig('/fake/project');
+
+      // JSON has higher priority
+      expect(config.severity).toBe('error');
+    });
+  });
+
+  describe('validation', () => {
+    it('should throw on invalid version', async () => {
+      mockExistsSync = (path: string) => path.endsWith('.mockpolicyrc');
+      mockReadFile = () =>
+        Promise.resolve(JSON.stringify({ version: 999 }));
+
+      vi.resetModules();
+      const mod = await import('../config');
+      loadMockPolicyConfig = mod.loadMockPolicyConfig;
+
+      await expect(loadMockPolicyConfig('/fake/project')).rejects.toThrow();
+    });
+
+    it('should throw on invalid mockPolicy value', async () => {
+      mockExistsSync = (path: string) => path.endsWith('.mockpolicyrc');
+      mockReadFile = () =>
+        Promise.resolve(
+          JSON.stringify({
+            layers: { unit: { mockPolicy: 'invalid' } },
+          }),
+        );
+
+      vi.resetModules();
+      const mod = await import('../config');
+      loadMockPolicyConfig = mod.loadMockPolicyConfig;
+
+      await expect(loadMockPolicyConfig('/fake/project')).rejects.toThrow();
+    });
+
+    it('should throw on empty projectBoundary', async () => {
+      mockExistsSync = (path: string) => path.endsWith('.mockpolicyrc');
+      mockReadFile = () =>
+        Promise.resolve(JSON.stringify({ projectBoundary: [] }));
+
+      vi.resetModules();
+      const mod = await import('../config');
+      loadMockPolicyConfig = mod.loadMockPolicyConfig;
+
+      await expect(loadMockPolicyConfig('/fake/project')).rejects.toThrow();
+    });
+
+    it('should throw on invalid severity', async () => {
+      mockExistsSync = (path: string) => path.endsWith('.mockpolicyrc');
+      mockReadFile = () =>
+        Promise.resolve(JSON.stringify({ severity: 'critical' }));
+
+      vi.resetModules();
+      const mod = await import('../config');
+      loadMockPolicyConfig = mod.loadMockPolicyConfig;
+
+      await expect(loadMockPolicyConfig('/fake/project')).rejects.toThrow();
+    });
+  });
+});