@boyingliu01/xp-gate 0.8.8 → 0.8.10

package/mock-policy/gate-m3.ts

@@ -0,0 +1,233 @@
+import { readFile } from 'fs/promises';
+import { isAbsolute, join } from 'path';
+import { loadMockPolicyConfig } from './config';
+import { scanProjectScope } from './scope-scanner';
+import MockDecisionEngine from './mock-decision-engine';
+import { MockPolicyResult, MockPolicyViolation, MockStrategy } from './types';
+import { detectTestLayer } from '../mutation/detect-ai-test';
+
+function filterTestFiles(files: string[]): string[] {
+  return files.filter(f => f.endsWith('.test.ts') || f.endsWith('.spec.ts'));
+}
+
+const IMPORT_REGEXES = [
+  /import\s*(?:type\s*)?(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)?\s*(?:from\s*)?['"]([^'"]+)['"]/g,
+  /(?:const|let|var)\s+(?:\{[^}]*\}|\w+)\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /export\s+(?:type\s+)?(?:\{[^}]*\}|\*\s+as\s+\w+|\*|\w+)\s+from\s+['"]([^'"]+)['"]/g,
+];
+
+function extractMatches(regex: RegExp, content: string): string[] {
+  const results: string[] = [];
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(content)) !== null) {
+    results.push(match[1]);
+  }
+  return results;
+}
+
+function collectImports(testContent: string): string[] {
+  const imports: string[] = [];
+  for (const regex of IMPORT_REGEXES) {
+    imports.push(...extractMatches(regex, testContent));
+  }
+  return [...new Set(imports)];
+}
+
+function detectMockUsage(testContent: string, importPath: string): MockStrategy {
+  const escaped = importPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const mockPatterns = [
+    new RegExp(`(?:vi|jest)\\.(?:do)?mock\\(['"]${escaped}['"]`),
+    new RegExp(`(?:vi|jest)\\.spyOn\\([^,]+,['"]${escaped}['"]`),
+  ];
+  return mockPatterns.some(p => p.test(testContent)) ? 'mock' : 'real';
+}
+
+interface StrategyViolationInput {
+  testFile: string;
+  importPath: string;
+  actualStrategy: MockStrategy;
+  expectedStrategy: MockStrategy;
+  reason: string;
+  severity: 'warning' | 'error';
+}
+
+function buildStrategyViolation(input: StrategyViolationInput): MockPolicyViolation {
+  return {
+    file: input.testFile,
+    line: 0,
+    dependency: input.importPath,
+    actualStrategy: input.actualStrategy,
+    expectedStrategy: input.expectedStrategy,
+    reason: input.reason,
+    severity: input.severity,
+  };
+}
+
+function buildPendingRemovalViolation(
+  testFile: string,
+  importPath: string,
+  severity: 'warning' | 'error',
+): MockPolicyViolation {
+  return buildStrategyViolation({
+    testFile,
+    importPath,
+    actualStrategy: 'mock',
+    expectedStrategy: 'mock',
+    reason: `Pending dependency "${importPath}" requires @mock-justified annotation with removal plan`,
+    severity,
+  });
+}
+
+interface ValidateImportInput {
+  testFile: string;
+  content: string;
+  importPath: string;
+  engine: MockDecisionEngine;
+  layer: ReturnType<typeof detectTestLayer>;
+  severity: 'warning' | 'error';
+}
+
+function validateImport(input: ValidateImportInput): MockPolicyViolation[] {
+  const { testFile, content, importPath, engine, layer, severity } = input;
+  const decision = engine.decide(importPath, layer);
+  const actualStrategy = detectMockUsage(content, importPath);
+  const violations: MockPolicyViolation[] = [];
+
+  if (decision.strategy !== actualStrategy) {
+    violations.push(buildStrategyViolation({
+      testFile,
+      importPath,
+      actualStrategy,
+      expectedStrategy: decision.strategy,
+      reason: decision.reason,
+      severity,
+    }));
+  }
+
+  if (decision.pendingRemoval && actualStrategy === 'mock' && !content.includes('@mock-justified')) {
+    violations.push(buildPendingRemovalViolation(testFile, importPath, severity));
+  }
+
+  return violations;
+}
+
+async function validateFile(
+  testFile: string,
+  engine: MockDecisionEngine,
+  projectRoot: string,
+  severity: 'warning' | 'error',
+): Promise<MockPolicyViolation[]> {
+  const fullPath = isAbsolute(testFile) ? testFile : join(projectRoot, testFile);
+  const content = await readFile(fullPath, 'utf-8');
+  const layer = detectTestLayer(testFile);
+  const imports = collectImports(content);
+
+  return imports.flatMap(importPath => validateImport({
+    testFile,
+    content,
+    importPath,
+    engine,
+    layer,
+    severity,
+  }));
+}
+
+export async function runGateM3(
+  changedFiles: string[],
+  projectRoot: string = process.cwd(),
+): Promise<MockPolicyResult> {
+  const testFiles = filterTestFiles(changedFiles);
+
+  if (testFiles.length === 0) {
+    return {
+      exitCode: 0,
+      status: 'skip',
+      violations: [],
+      scores: { totalTests: 0, integrationTests: 0, mockDensity: 0, pendingMocks: 0 },
+    };
+  }
+
+  const config = await loadMockPolicyConfig(projectRoot);
+  const severity: 'warning' | 'error' = config.severity;
+
+  // Collect all imports from all test files
+  const allImports: string[] = [];
+  for (const testFile of testFiles) {
+    try {
+      const fullPath = isAbsolute(testFile) ? testFile : join(projectRoot, testFile);
+      const content = await readFile(fullPath, 'utf-8');
+      allImports.push(...collectImports(content));
+    } catch {
+      // File not readable — skip
+    }
+  }
+
+  const scope = await scanProjectScope({
+    projectRoot,
+    imports: [...new Set(allImports)],
+    boundary: config.projectBoundary,
+  });
+
+  const engine = new MockDecisionEngine(scope, config, projectRoot);
+  const allViolations: MockPolicyViolation[] = [];
+
+  let integrationCount = 0;
+  for (const testFile of testFiles) {
+    const layer = detectTestLayer(testFile);
+    if (layer === 'integration') integrationCount++;
+
+    const violations = await validateFile(testFile, engine, projectRoot, severity);
+    allViolations.push(...violations);
+  }
+
+  const hasBlockableViolations = allViolations.some(v => v.severity === 'error');
+  const blocked = severity === 'error' && hasBlockableViolations;
+
+  return {
+    exitCode: blocked ? 1 : 0,
+    status: blocked ? 'block' : 'pass',
+    violations: allViolations,
+    scores: {
+      totalTests: testFiles.length,
+      integrationTests: integrationCount,
+      mockDensity: 0,
+      pendingMocks: allViolations.filter(v => v.reason.includes('pending')).length,
+    },
+  };
+}
+
+export async function main(args: string[]): Promise<number> {
+  if (args.length === 0) {
+    console.error('Usage: npx tsx src/mock-policy/gate-m3.ts <file1> <file2> ...');
+    return 1;
+  }
+
+  console.log('Gate M3: Mock Layering Validation');
+  console.log(`  Changed files: ${args.length}`);
+
+  const result = await runGateM3(args);
+
+  if (result.violations.length > 0) {
+    console.log('\nViolations:');
+    for (const v of result.violations) {
+      const icon = v.severity === 'error' ? String.fromCodePoint(0x2717) : String.fromCodePoint(0x26A0);
+      console.log(`  ${icon} ${v.file}: ${v.reason}`);
+    }
+  }
+
+  const label = result.status === 'block' ? `${String.fromCodePoint(0x2717)} BLOCK` : `${String.fromCodePoint(0x2713)} PASS`;
+  console.log(`\n${label}  Integration tests: ${result.scores.integrationTests}  Pending mocks: ${result.scores.pendingMocks}`);
+
+  return result.exitCode;
+}
+
+// Entry point — process.argv detection for ESM compatibility
+const scriptIndex = process.argv.findIndex(a => a.endsWith('gate-m3.ts'));
+const cliArgs = scriptIndex >= 0 ? process.argv.slice(scriptIndex + 1) : process.argv.slice(2);
+
+if (cliArgs.length > 0) {
+  main(cliArgs)
+    .then(exitCode => { if (exitCode !== 0) process.exit(exitCode); })
+    .catch(err => { console.error('Gate M3 failed:', err.message); process.exit(1); });
+}

package/mock-policy/mock-decision-engine.ts

@@ -0,0 +1,155 @@
+import { ProjectScope, MockDecision, MockPolicyConfig, TestLayer, MockPolicyLayerRules } from './types';
+import { classifyDependency } from './scope-scanner';
+
+type DecisionFn = (importPath: string, layer: TestLayer, layerRules: MockPolicyLayerRules, scope: ProjectScope) => MockDecision;
+
+function internalDecision(
+  importPath: string,
+  layer: TestLayer,
+  layerRules: MockPolicyLayerRules,
+  scope: ProjectScope,
+): MockDecision {
+  const isImplemented = scope.implementedModules.some(
+    mod => importPath === mod || importPath.endsWith('/' + mod) || importPath.startsWith(mod),
+  );
+  if (isImplemented && layerRules.requireRealForImplemented) {
+    return {
+      strategy: 'real',
+      reason: `Internal and implemented dependency '${importPath}' should use real implementation`,
+      layer,
+    };
+  }
+  return {
+    strategy: 'mock',
+    reason: `Internal dependency '${importPath}' should be mocked for isolation`,
+    layer,
+  };
+}
+
+function externalDecision(
+  importPath: string,
+  layer: TestLayer,
+  layerRules: MockPolicyLayerRules,
+): MockDecision {
+  if (layerRules.allowExternalMock) {
+    return {
+      strategy: 'mock',
+      reason: `External dependency '${importPath}' should be mocked per policy`,
+      layer,
+    };
+  }
+  return {
+    strategy: 'real',
+    reason: `External dependency '${importPath}' allowed as real (allowExternalMock is disabled)`,
+    layer,
+  };
+}
+
+function pendingDecision(
+  importPath: string,
+  layer: TestLayer,
+  layerRules: MockPolicyLayerRules,
+  scope: ProjectScope,
+): MockDecision {
+  const pendingTicket = scope.unimplementedModules.find(
+    mod => importPath === mod || importPath.endsWith('/' + mod) || importPath.startsWith(mod),
+  );
+  if (layerRules.requirePendingRemoval && pendingTicket) {
+    return {
+      strategy: 'mock',
+      reason: `Pending dependency '${importPath}' must be mocked until implemented`,
+      layer,
+      pendingRemoval: {
+        ticket: pendingTicket,
+        reason: `Pending dependency '${importPath}' is not yet implemented; mock will be removed once the real implementation is available`,
+      },
+    };
+  }
+  return {
+    strategy: 'mock',
+    reason: `Pending dependency '${importPath}' should be mocked (not yet implemented)`,
+    layer,
+  };
+}
+
+function unknownDecision(importPath: string, layer: TestLayer): MockDecision {
+  return {
+    strategy: 'mock',
+    reason: `Unknown dependency '${importPath}' should be mocked for safety`,
+    layer,
+  };
+}
+
+/**
+ * Determines whether a given dependency should be mocked or used as-is
+ * for a specific test layer, based on the project scope and policy configuration.
+ *
+ * Decision matrix:
+ * - **e2e**: Always returns `real` — no mocks in end-to-end tests.
+ * - **unit** with `lenient` policy: Always returns `mock` for all dependencies.
+ * - **unit** with `strict` policy: Applies integration-like rules.
+ * - **integration**: Applies rules based on dependency scope and policy flags.
+ */
+class MockDecisionEngine {
+  private readonly scope: ProjectScope;
+  private readonly config: MockPolicyConfig;
+  private readonly projectRoot: string;
+
+  constructor(scope: ProjectScope, config: MockPolicyConfig, projectRoot?: string) {
+    this.scope = scope;
+    this.config = config;
+    this.projectRoot = projectRoot || process.cwd();
+  }
+
+  /**
+   * Decide the mock strategy for a given import path in the specified test layer.
+   *
+   * @param importPath - The dependency import path to evaluate
+   * @param layer - The test layer (unit, integration, or e2e)
+   * @returns A MockDecision with strategy, reason, and optional pending removal info
+   */
+  decide(importPath: string, layer: TestLayer): MockDecision {
+    if (layer === 'e2e') {
+      return {
+        strategy: 'real',
+        reason: `E2E tests must use real dependencies; no mocks allowed in ${layer} layer`,
+        layer,
+      };
+    }
+
+    const layerRules = this.config.layers[layer === 'unknown' ? 'unit' : layer];
+
+    if (layer === 'unit' && layerRules.mockPolicy === 'lenient') {
+      return {
+        strategy: 'mock',
+        reason: `Unit tests with lenient policy: all dependencies should be mocked`,
+        layer,
+      };
+    }
+
+    const depScope = classifyDependency(
+      importPath,
+      this.scope,
+      {
+        projectRoot: this.projectRoot,
+        imports: [importPath],
+        boundary: this.config.projectBoundary,
+      },
+    );
+
+    const decider: Record<string, DecisionFn> = {
+      internal: internalDecision,
+      external: externalDecision,
+      pending: pendingDecision,
+    };
+
+    const handler = decider[depScope];
+    if (handler) {
+      return handler(importPath, layer, layerRules, this.scope);
+    }
+
+    return unknownDecision(importPath, layer);
+  }
+}
+
+export default MockDecisionEngine;

package/mock-policy/schema.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+export const MockPolicyLayerRulesSchema = z.object({
+  mockPolicy: z.enum(['strict', 'lenient']),
+  requireRealForImplemented: z.boolean(),
+  allowExternalMock: z.boolean(),
+  requirePendingRemoval: z.boolean(),
+  maxMockDensity: z.number().min(0).max(100).optional(),
+});
+
+export const MockPolicyConfigSchema = z.object({
+  version: z.literal(1),
+  layers: z.object({
+    unit: MockPolicyLayerRulesSchema,
+    integration: MockPolicyLayerRulesSchema,
+    e2e: MockPolicyLayerRulesSchema,
+  }),
+  projectBoundary: z.array(z.string()).min(1),
+  severity: z.enum(['error', 'warning']),
+});
+
+export type MockPolicyConfig = z.infer<typeof MockPolicyConfigSchema>;

package/mock-policy/scope-scanner.ts

@@ -0,0 +1,288 @@
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { isAbsolute, join, resolve } from 'path';
+import type { ProjectScope, DependencyScope } from './types';
+
+/**
+ * Options for the scope scanner.
+ */
+export interface ScanOptions {
+  /** Root directory of the project */
+  projectRoot: string;
+  /** List of import paths to classify */
+  imports: string[];
+  /** Boundary patterns (glob-style) that define the project boundary */
+  boundary: string[];
+}
+
+/**
+ * Convert a glob pattern to a RegExp.
+ * - `**` matches across directory separators → `.*`
+ * - `*` matches within a single path segment → `[^/]*`
+ *
+ * @param pattern - Glob pattern to convert
+ * @returns RegExp equivalent of the glob pattern
+ */
+type GlobCharResult = { regex: string; advance: number };
+
+function globCharToRegex(ch: string, nextCh: string): GlobCharResult {
+  if (ch === '*' && nextCh === '*') return { regex: '.*', advance: 2 };
+  if (ch === '*') return { regex: '[^/]*', advance: 1 };
+  if (ch === '.') return { regex: '\\.', advance: 1 };
+  if (ch === '?') return { regex: '[^/]', advance: 1 };
+  if (ch === '/') return { regex: '/', advance: 1 };
+  const special = '.+^${}()|[]\\';
+  if (special.includes(ch)) return { regex: '\\' + ch, advance: 1 };
+  return { regex: ch, advance: 1 };
+}
+
+export function simpleGlobMatch(pattern: string, inputPath: string): boolean {
+  let regexStr = '';
+  let i = 0;
+  while (i < pattern.length) {
+    const result = globCharToRegex(pattern[i], pattern[i + 1] || '');
+    regexStr += result.regex;
+    i += result.advance;
+  }
+
+  try {
+    const re = new RegExp(`^${regexStr}$`);
+    return re.test(inputPath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Map of all Node.js built-in module names.
+ */
+const NODE_BUILTINS = new Set([
+  'fs', 'path', 'os', 'http', 'https', 'crypto', 'stream',
+  'events', 'util', 'url', 'querystring', 'assert', 'buffer',
+  'child_process', 'cluster', 'dns', 'net', 'tls', 'readline',
+  'process', 'v8', 'vm', 'zlib',
+]);
+
+/**
+ * Check whether an import path is external (not part of the project).
+ *
+ * An import is considered external if:
+ * 1. It is a Node.js built-in module
+ * 2. It is a bare npm package (not starting with `.`, `/`, or `@/`)
+ * 3. It matches any boundary pattern
+ *
+ * @param importPath - The import path to check
+ * @param options - Scan options with boundary patterns
+ * @returns `true` if the import is external
+ */
+export function isExternalImport(importPath: string, options: ScanOptions): boolean {
+  // Node.js builtins are always external
+  const bareName = importPath.startsWith('node:') ? importPath.slice(5) : importPath;
+  if (NODE_BUILTINS.has(bareName)) {
+    return true;
+  }
+
+  // Relative imports (starting with .) are internal
+  if (importPath.startsWith('.')) {
+    return false;
+  }
+
+  // @/ alias is internal (project path alias)
+  if (importPath.startsWith('@/')) {
+    return false;
+  }
+
+  // Absolute imports (Unix /... or Windows C:\...) are internal
+  if (isAbsolute(importPath)) {
+    return false;
+  }
+
+  // Check boundary patterns — if any pattern matches, it's within the project boundary
+  for (const pattern of options.boundary) {
+    if (simpleGlobMatch(pattern, importPath)) {
+      return false;
+    }
+  }
+
+  // Bare import (npm package) — external
+  return true;
+}
+
+/**
+ * Resolve a `@/` path alias to a real file path.
+ * `@/` maps to `src/` by default.
+ *
+ * @param importPath - Import path (may start with `@/`)
+ * @param projectRoot - Root of the project
+ * @returns Resolved absolute file path
+ */
+export function resolveToRealPath(importPath: string, projectRoot: string): string {
+  const normalized = importPath.replace(/^@\//, 'src/');
+  return resolve(projectRoot, normalized);
+}
+
+/**
+ * Load external dependencies from the project's package.json.
+ * Reads `dependencies`, `devDependencies`, and `peerDependencies`,
+ * skipping `workspace:*` protocol packages.
+ *
+ * @param projectRoot - Root of the project
+ * @returns Array of external package names
+ */
+export async function loadExternalDependencies(projectRoot: string): Promise<string[]> {
+  const pkgPath = join(projectRoot, 'package.json');
+
+  if (!existsSync(pkgPath)) {
+    return [];
+  }
+
+  try {
+    const content = await readFile(pkgPath, 'utf-8');
+    const pkg = JSON.parse(content) as Record<string, unknown>;
+
+    const deps: Record<string, string> = pkg.dependencies as Record<string, string> || {};
+    const devDeps: Record<string, string> = pkg.devDependencies as Record<string, string> || {};
+    const peerDeps: Record<string, string> = pkg.peerDependencies as Record<string, string> || {};
+
+    const allDeps = { ...deps, ...devDeps, ...peerDeps };
+    const packages: string[] = [];
+
+    for (const [name, version] of Object.entries(allDeps)) {
+      // Skip workspace:* protocol packages — they are internal monorepo references
+      if (typeof version === 'string' && version.startsWith('workspace:')) {
+        continue;
+      }
+      packages.push(name);
+    }
+
+    return packages.sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if an import path matches any module in a list.
+ * Matches: exact name, subpath (ends with /module), or prefix (starts with module).
+ */
+function matchesModule(importPath: string, modules: string[]): boolean {
+  return modules.some(
+    (mod) => importPath === mod || importPath.endsWith('/' + mod) || importPath.startsWith(mod),
+  );
+}
+
+/**
+ * Check filesystem existence with optional cache.
+ * Returns [exists, resolvedPath].
+ */
+function checkExists(
+  importPath: string,
+  projectRoot: string,
+  existCache?: Map<string, boolean>,
+): [boolean, string] {
+  const resolved = resolveToRealPath(importPath, projectRoot);
+  const exists = existCache?.get(resolved) ?? existsSync(resolved);
+  if (existCache) existCache.set(resolved, exists);
+  return [exists, resolved];
+}
+
+function isExternalPackage(importPath: string, packages: string[]): boolean {
+  return packages.some(
+    (pkg) => importPath === pkg || importPath.startsWith(pkg + '/'),
+  );
+}
+
+/**
+ * Classify a single dependency as internal, external, or pending.
+ *
+ * - **internal**: The import resolves to a file within the project boundary,
+ *   or it's a relative/aliased import that exists on disk.
+ * - **external**: The import is a Node.js builtin or npm package.
+ * - **pending**: The import cannot be resolved yet (checked via existCache or filesystem).
+ *
+ * @param importPath - The import path to classify
+ * @param scope - The project scope information
+ * @param options - Scan options (used for boundary checks)
+ * @param existCache - Cache of filesystem existence checks (path → boolean)
+ * @returns The dependency scope classification
+ */
+export function classifyDependency(
+  importPath: string,
+  scope: ProjectScope,
+  options: ScanOptions,
+  existCache: Map<string, boolean> = new Map(),
+): DependencyScope {
+  if (matchesModule(importPath, scope.implementedModules)) return 'internal';
+  if (matchesModule(importPath, scope.unimplementedModules)) return 'pending';
+  if (isExternalPackage(importPath, scope.externalPackages)) return 'external';
+
+  for (const pattern of options.boundary) {
+    if (simpleGlobMatch(pattern, importPath)) {
+      const [exists] = checkExists(importPath, options.projectRoot, existCache);
+      if (exists) return 'internal';
+      return 'pending';
+    }
+  }
+
+  if (isExternalImport(importPath, options)) return 'external';
+
+  const [exists] = checkExists(importPath, options.projectRoot, existCache);
+  if (exists) return 'internal';
+  return 'pending';
+}
+
+function isAlreadyClassified(
+  importPath: string,
+  implemented: string[],
+  unimplemented: string[],
+  external: string[],
+): boolean {
+  return implemented.includes(importPath)
+    || unimplemented.includes(importPath)
+    || external.includes(importPath);
+}
+
+/**
+ * Scan the project scope — classify a list of imports into
+ * implemented, unimplemented, and external categories.
+ *
+ * Uses a filesystem existence cache (`existCache` Map) to
+ * avoid repeated `existsSync` calls for the same path.
+ *
+ * @param options - Scan options
+ * @returns The project scope with classified modules
+ */
+export async function scanProjectScope(options: ScanOptions): Promise<ProjectScope> {
+  const { projectRoot, imports, boundary } = options;
+  const existCache = new Map<string, boolean>();
+
+  const implemented: string[] = [];
+  const unimplemented: string[] = [];
+  const external: string[] = [];
+
+  for (const importPath of imports) {
+    if (isAlreadyClassified(importPath, implemented, unimplemented, external)) continue;
+
+    if (isExternalImport(importPath, options)) {
+      external.push(importPath);
+      continue;
+    }
+
+    const resolved = resolveToRealPath(importPath, projectRoot);
+    const exists = existCache.get(resolved) ?? existsSync(resolved);
+    existCache.set(resolved, exists);
+
+    if (exists) {
+      implemented.push(importPath);
+    } else {
+      unimplemented.push(importPath);
+    }
+  }
+
+  return {
+    implementedModules: [...new Set(implemented)],
+    unimplementedModules: [...new Set(unimplemented)],
+    externalPackages: [...new Set(external)],
+    projectBoundary: [...boundary],
+  };
+}