@delegance/claude-autopilot 1.0.0-alpha.5 → 1.0.0-alpha.7

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.0.0-alpha.7
+
+### Added
+
+- **`autopilot hook install`** — writes a `pre-push` git hook that runs `autoregress run` before every push; `hook uninstall` removes it; `hook status` shows current state; `--force` overwrites existing hook
+- **`autoregress diff`** — colored snapshot viewer showing line-by-line JSON diffs between current output and baselines; exits 1 if any diffs found (never modifies baselines — use `update` for that)
+- **`autoregress generate --files <list>`** — explicit comma-separated file list bypasses git detection; generates baselines for any src file on demand
+- **Real baselines** — `tests/snapshots/*.snap.ts` + baselines for `serializer.ts`, `import-scanner.ts`, `impact-selector.ts`, and `sarif.ts` — alpha.6 infrastructure now self-testing via snapshots
+
+## 1.0.0-alpha.6
+
+### Added
+
+- **Auto-regression testing** (`scripts/autoregress.ts generate|run|update`) — autoresearch-inspired snapshot tests for changed source modules
+- **Impact-aware selection** — only fires snapshots whose source modules (or one-hop importers) were touched; high-impact paths (`src/core/pipeline/**`, `src/adapters/**`, `src/core/findings/**`, `src/core/config/**`) and >10-file changes trigger full run
+- **Snapshot serializer** (`src/snapshots/serializer.ts`) — deterministic JSON normalization: sorted keys, `<timestamp>`, `<uuid>`, path stripping
+- **Import scanner** (`src/snapshots/import-scanner.ts`) — static `import`/`export` graph → reverse dependency map
+- **Impact selector** (`src/snapshots/impact-selector.ts`) — merge-base diff + one-hop expansion + overrides
+- **Baseline capture** — `CAPTURE_BASELINE=1` env flag; `autoregress update` rewrites baselines after intentional changes
+- **Staleness detection** — warns and skips snapshots whose `@snapshot-for` source file no longer exists
+- 10 new unit tests (AR1-AR10) for serializer, import scanner, and impact selector
+
 ## 1.0.0-alpha.5 (2026-04-21)
 
 ### New Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.7",
   "type": "module",
   "description": "Claude Code automation pipeline: spec → plan → implement → validate → PR",
   "keywords": ["claude", "autopilot", "ai", "pipeline", "code-review", "cli"],
@@ -20,12 +20,15 @@
     "src/",
     "presets/",
     "scripts/test-runner.mjs",
+    "scripts/autoregress.ts",
+    "tests/snapshots/",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node scripts/test-runner.mjs",
     "typecheck": "tsc --noEmit",
-    "build": "tsc"
+    "build": "tsc",
+    "autoregress": "tsx scripts/autoregress.ts"
   },
   "devDependencies": {
     "@types/js-yaml": "^4",

package/scripts/autoregress.ts

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+// scripts/autoregress.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { execSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { selectSnapshots } from '../src/snapshots/impact-selector.ts';
+import OpenAI from 'openai';
+import { buildImportMap } from '../src/snapshots/import-scanner.ts';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const SNAPSHOTS_DIR = path.join(ROOT, 'tests', 'snapshots');
+const INDEX_PATH = path.join(SNAPSHOTS_DIR, 'index.json');
+const IMPORT_MAP_PATH = path.join(SNAPSHOTS_DIR, 'import-map.json');
+const BASELINES_DIR = path.join(SNAPSHOTS_DIR, 'baselines');
+
+function loadJson<T>(p: string, fallback: T): T {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')) as T; } catch { return fallback; }
+}
+
+export function diffBaselines(baselineJson: string, currentJson: string): string[] {
+  if (baselineJson === currentJson) return [];
+  const baselineLines = baselineJson.split('\n');
+  const currentLines = currentJson.split('\n');
+  const lines: string[] = [];
+  const maxLen = Math.max(baselineLines.length, currentLines.length);
+  for (let i = 0; i < maxLen; i++) {
+    const bLine = baselineLines[i];
+    const cLine = currentLines[i];
+    if (bLine === cLine) continue;
+    if (bLine !== undefined) lines.push(`- ${bLine}`);
+    if (cLine !== undefined) lines.push(`+ ${cLine}`);
+  }
+  return lines;
+}
+
+function getChangedFiles(since?: string): string[] | null {
+  try {
+    const base = since
+      ? since
+      : execSync('git merge-base origin/main HEAD', { cwd: ROOT }).toString().trim();
+    const out = execSync(`git diff ${base} HEAD --name-only`, { cwd: ROOT }).toString();
+    return out.trim().split('\n').filter(Boolean);
+  } catch { return null; }
+}
+
+function allSnapFiles(): string[] {
+  if (!fs.existsSync(SNAPSHOTS_DIR)) return [];
+  return fs.readdirSync(SNAPSHOTS_DIR)
+    .filter(f => f.endsWith('.snap.ts'))
+    .map(f => path.join('tests', 'snapshots', f));
+}
+
+function runSnapshot(snapFile: string, capture: boolean): 'pass' | 'fail' | 'baseline-missing' | 'stale' {
+  const absSnap = path.join(ROOT, snapFile);
+  const content = fs.readFileSync(absSnap, 'utf8');
+  const forMatch = content.match(/@snapshot-for:\s*(.+)/);
+  if (forMatch) {
+    const src = forMatch[1]!.trim();
+    if (!fs.existsSync(path.join(ROOT, src))) {
+      console.warn(`  [warn] stale — source gone: ${src}`);
+      return 'stale';
+    }
+  }
+
+  const slug = path.basename(snapFile, '.snap.ts');
+  const baselinePath = path.join(BASELINES_DIR, `${slug}.json`);
+  if (!capture && !fs.existsSync(baselinePath)) {
+    console.error(`  [fail] baseline missing: ${baselinePath}`);
+    return 'baseline-missing';
+  }
+
+  const env = { ...process.env };
+  if (capture) env.CAPTURE_BASELINE = '1';
+  else delete env.CAPTURE_BASELINE;
+
+  const result = spawnSync('node', ['--test', '--import', 'tsx', absSnap], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    cwd: ROOT,
+    env,
+  });
+
+  if (result.status === 0) return 'pass';
+  if (capture) return 'pass';
+  console.error(`    ${(result.stderr?.toString() ?? '') || (result.stdout?.toString() ?? '')}`);
+  return 'fail';
+}
+
+function cmdRun(args: string[]): number {
+  const runAll = args.includes('--all');
+  const sinceIdx = args.indexOf('--since');
+  const since = sinceIdx >= 0 ? args[sinceIdx + 1] : undefined;
+  const index = loadJson<Record<string, string[]>>(INDEX_PATH, {});
+  const importMap = loadJson<Record<string, string[]>>(IMPORT_MAP_PATH, {});
+  const snapFiles = allSnapFiles();
+
+  let selected: string[];
+  if (runAll || snapFiles.length === 0) {
+    selected = snapFiles;
+    console.log(`[autoregress run] --all: running ${snapFiles.length} snapshot(s)`);
+  } else {
+    const changed = getChangedFiles(since);
+    if (!changed) {
+      console.warn('[autoregress run] merge-base resolution failed — running all');
+      selected = snapFiles;
+    } else {
+      const r = selectSnapshots(changed, snapFiles, index, importMap);
+      selected = r.selected;
+      console.log(`[autoregress run] ${r.reason} (${selected.length}/${snapFiles.length})`);
+    }
+  }
+
+  if (selected.length === 0) {
+    console.log('[autoregress run] no snapshots to run — pass');
+    return 0;
+  }
+
+  let passed = 0, failed = 0, missing = 0, stale = 0;
+  for (const snap of selected) {
+    process.stdout.write(`  ${snap} ... `);
+    const v = runSnapshot(snap, false);
+    if (v === 'pass') { passed++; console.log('pass'); }
+    else if (v === 'fail') { failed++; console.log('FAIL'); }
+    else if (v === 'baseline-missing') { missing++; console.log('BASELINE MISSING'); }
+    else { stale++; console.log('stale (skipped)'); }
+  }
+  console.log(`\n  ${passed} passed  ${failed} failed  ${missing} baseline-missing  ${stale} stale`);
+  return failed > 0 || missing > 0 ? 1 : 0;
+}
+
+function cmdUpdate(args: string[]): number {
+  const snapIdx = args.indexOf('--snapshot');
+  const slug = snapIdx >= 0 ? args[snapIdx + 1] : undefined;
+  const snapFiles = slug
+    ? [path.join('tests', 'snapshots', `${slug}.snap.ts`)]
+    : allSnapFiles();
+  console.log(`[autoregress update] rewriting ${snapFiles.length} baseline(s)`);
+  let failed = 0;
+  for (const snap of snapFiles) {
+    const absSnap = path.join(ROOT, snap);
+    if (!fs.existsSync(absSnap)) {
+      console.error(`  [error] snapshot file not found: ${snap}`);
+      failed++;
+      continue;
+    }
+    process.stdout.write(`  ${snap} ... `);
+    runSnapshot(snap, true);
+    console.log('updated');
+  }
+  return failed > 0 ? 1 : 0;
+}
+
+const GENERATOR_VERSION = '1.0.0-alpha.6';
+
+const GENERATE_PROMPT = `You are generating a behavioral snapshot test for a TypeScript module.
+
+Module path: {filePath}
+Module contents:
+{fileContents}
+
+Write a snapshot test file. Requirements:
+1. Header comments at top:
+   // @snapshot-for: {filePath}
+   // @generated-at: {generatedAt}
+   // @source-commit: {sourceCommit}
+   // @generator-version: {version}
+2. Import the module's exported functions under test
+3. Import { normalizeSnapshot } from '../../src/snapshots/serializer.ts'
+4. Import fs from 'node:fs', describe/it from 'node:test', assert from 'node:assert/strict'
+5. Baseline loading pattern (use slug {slug}):
+   const SLUG = '{slug}';
+   import { fileURLToPath } from 'node:url';
+   import * as path from 'node:path';
+   const baselineRaw = process.env.CAPTURE_BASELINE === '1' ? '{}' : fs.readFileSync(fileURLToPath(new URL('./baselines/{slug}.json', import.meta.url)), 'utf8');
+   const baseline = JSON.parse(baselineRaw);
+   const captured: Record<string, unknown> = {};
+   process.on('exit', () => {
+     if (process.env.CAPTURE_BASELINE === '1') {
+       const p = process.env.AUTOREGRESS_TEMP_BASELINE_DIR
+         ? path.join(process.env.AUTOREGRESS_TEMP_BASELINE_DIR, '{slug}.json')
+         : fileURLToPath(new URL('./baselines/{slug}.json', import.meta.url));
+       fs.writeFileSync(p, JSON.stringify(captured, null, 2), 'utf8');
+     }
+   });
+6. In each test: if (process.env.CAPTURE_BASELINE === '1') { captured['test-name'] = result; return; }
+   Else: assert.equal(normalizeSnapshot(result), normalizeSnapshot(baseline['test-name']));
+7. Write 2-4 it() tests covering representative behaviors
+8. Output ONLY the TypeScript file contents, no markdown fences, no explanation`;
+
+async function cmdGenerate(args: string[]): Promise<number> {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) { console.error('[autoregress generate] OPENAI_API_KEY not set'); return 1; }
+
+  const sinceIdx = args.indexOf('--since');
+  const since = sinceIdx >= 0 ? args[sinceIdx + 1] : undefined;
+  const filesIdx = args.indexOf('--files');
+  const filesArg = filesIdx >= 0 ? args[filesIdx + 1] : undefined;
+
+  let srcFiles: string[];
+  if (filesArg) {
+    srcFiles = filesArg.split(',').map(f => f.trim()).filter(f => f.startsWith('src/') && f.endsWith('.ts'));
+    if (srcFiles.length === 0) {
+      console.error('[autoregress generate] --files must contain at least one src/*.ts path');
+      return 1;
+    }
+  } else {
+    const changed = getChangedFiles(since);
+    if (!changed) { console.error('[autoregress generate] could not determine changed files'); return 1; }
+    srcFiles = changed.filter(f => f.startsWith('src/') && f.endsWith('.ts'));
+    if (srcFiles.length === 0) {
+      console.log('[autoregress generate] no src/*.ts files changed — nothing to generate');
+      return 0;
+    }
+  }
+
+  console.log(`[autoregress generate] generating snapshots for ${srcFiles.length} file(s)`);
+
+  const client = new OpenAI({ apiKey });
+  let sourceCommit = 'unknown';
+  try { sourceCommit = execSync('git rev-parse --short HEAD', { cwd: ROOT }).toString().trim(); } catch {}
+  const generatedAt = new Date().toISOString();
+
+  for (const srcFile of srcFiles) {
+    const absFile = path.join(ROOT, srcFile);
+    if (!fs.existsSync(absFile)) { console.warn(`  skip (not found): ${srcFile}`); continue; }
+
+    const fileContents = fs.readFileSync(absFile, 'utf8');
+    const slug = srcFile.replace(/[/\\]/g, '-').replace(/\.ts$/, '');
+
+    process.stdout.write(`  ${srcFile} → ${slug}.snap.ts ... `);
+
+    const prompt = GENERATE_PROMPT
+      .replace(/{filePath}/g, srcFile)
+      .replace(/{fileContents}/g, fileContents)
+      .replace(/{slug}/g, slug)
+      .replace(/{version}/g, GENERATOR_VERSION)
+      .replace(/{generatedAt}/g, generatedAt)
+      .replace(/{sourceCommit}/g, sourceCommit);
+
+    let snapContent: string;
+    try {
+      const response = await client.responses.create({
+        model: process.env.CODEX_MODEL ?? 'gpt-5.3-codex',
+        instructions: 'You write TypeScript snapshot tests. Output ONLY the file contents, no markdown fences.',
+        input: prompt,
+        max_output_tokens: 2000,
+      });
+      snapContent = (response.output_text ?? '').replace(/^```typescript\n?/m, '').replace(/```$/m, '').trim();
+    } catch (err) {
+      console.error(`LLM error: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+
+    const snapPath = path.join(SNAPSHOTS_DIR, `${slug}.snap.ts`);
+    fs.writeFileSync(snapPath, snapContent + '\n', 'utf8');
+
+    const captureResult = spawnSync('node', ['--test', '--import', 'tsx', snapPath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: ROOT,
+      env: { ...process.env, CAPTURE_BASELINE: '1' },
+    });
+    const baselinePath = path.join(BASELINES_DIR, `${slug}.json`);
+    console.log(fs.existsSync(baselinePath) ? 'generated + baseline captured' :
+      `generated (capture failed: ${captureResult.stderr?.toString().slice(0, 60)})`);
+  }
+
+  // Rebuild index.json from @snapshot-for headers
+  const newIndex: Record<string, string[]> = {};
+  for (const f of fs.readdirSync(SNAPSHOTS_DIR).filter(x => x.endsWith('.snap.ts'))) {
+    const snapRelPath = path.join('tests', 'snapshots', f);
+    const content = fs.readFileSync(path.join(SNAPSHOTS_DIR, f), 'utf8');
+    const sources = [...content.matchAll(/@snapshot-for:\s*(.+)/g)].map(m => m[1]!.trim());
+    if (sources.length) newIndex[snapRelPath] = sources;
+  }
+  fs.writeFileSync(INDEX_PATH, JSON.stringify(newIndex, null, 2) + '\n', 'utf8');
+
+  // Rebuild import-map.json — prefix keys/values with 'src/' to match repo-relative git diff paths
+  const rawImportMap = buildImportMap(path.join(ROOT, 'src'));
+  const newImportMap: Record<string, string[]> = {};
+  for (const [dep, importers] of Object.entries(rawImportMap)) {
+    newImportMap[`src/${dep}`] = importers.map(i => `src/${i}`);
+  }
+  fs.writeFileSync(IMPORT_MAP_PATH, JSON.stringify(newImportMap, null, 2) + '\n', 'utf8');
+
+  console.log('\n[autoregress generate] index.json + import-map.json rebuilt');
+  return 0;
+}
+
+function cmdDiff(args: string[]): number {
+  const runAll = args.includes('--all');
+  const snapIdx = args.indexOf('--snapshot');
+  const slug = snapIdx >= 0 ? args[snapIdx + 1] : undefined;
+  const sinceIdx = args.indexOf('--since');
+  const since = sinceIdx >= 0 ? args[sinceIdx + 1] : undefined;
+
+  const index = loadJson<Record<string, string[]>>(INDEX_PATH, {});
+  const importMap = loadJson<Record<string, string[]>>(IMPORT_MAP_PATH, {});
+  const snapFiles = slug
+    ? [path.join('tests', 'snapshots', `${slug}.snap.ts`)]
+    : allSnapFiles();
+
+  let selected: string[];
+  if (runAll || slug || snapFiles.length === 0) {
+    selected = snapFiles;
+  } else {
+    const changed = getChangedFiles(since);
+    selected = changed ? selectSnapshots(changed, snapFiles, index, importMap).selected : snapFiles;
+  }
+
+  if (selected.length === 0) {
+    console.log('[autoregress diff] no snapshots to diff');
+    return 0;
+  }
+
+  const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+  const red = useColor ? '\x1b[31m' : '';
+  const green = useColor ? '\x1b[32m' : '';
+  const reset = useColor ? '\x1b[0m' : '';
+
+  let changedCount = 0;
+  for (const snap of selected) {
+    const slug_ = path.basename(snap, '.snap.ts');
+    const baselinePath = path.join(BASELINES_DIR, `${slug_}.json`);
+
+    if (!fs.existsSync(baselinePath)) {
+      console.log(`  ${snap} — ${red}no baseline${reset}`);
+      continue;
+    }
+
+    const tmpBaselinesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ar-diff-'));
+    const tmpBaselinePath = path.join(tmpBaselinesDir, `${slug_}.json`);
+    fs.copyFileSync(baselinePath, tmpBaselinePath);
+
+    const absSnap = path.join(ROOT, snap);
+    const captureResult = spawnSync('node', ['--test', '--import', 'tsx', absSnap], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: ROOT,
+      env: { ...process.env, CAPTURE_BASELINE: '1', AUTOREGRESS_TEMP_BASELINE_DIR: tmpBaselinesDir },
+    });
+
+    const baselineJson = fs.readFileSync(baselinePath, 'utf8');
+    const captureOk = fs.existsSync(tmpBaselinePath);
+    const currentJson = captureOk ? fs.readFileSync(tmpBaselinePath, 'utf8') : null;
+    if (!captureOk && captureResult.status !== 0) {
+      const stderr = captureResult.stderr?.toString().trim();
+      if (stderr) console.error(`    ${stderr.slice(0, 120)}`);
+    }
+    fs.rmSync(tmpBaselinesDir, { recursive: true, force: true });
+
+    if (!currentJson) {
+      console.log(`  ${snap} — ${red}capture failed${reset}`);
+      continue;
+    }
+
+    const diffLines = diffBaselines(baselineJson, currentJson);
+    if (diffLines.length === 0) {
+      console.log(`  ${snap} — ${green}✓ no changes${reset}`);
+    } else {
+      changedCount++;
+      console.log(`  ${snap}`);
+      for (const line of diffLines) {
+        if (line.startsWith('-')) console.log(`    ${red}${line}${reset}`);
+        else if (line.startsWith('+')) console.log(`    ${green}${line}${reset}`);
+        else console.log(`    ${line}`);
+      }
+    }
+  }
+
+  return changedCount > 0 ? 1 : 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+  const [,, subcmd, ...rest] = process.argv;
+  switch (subcmd) {
+    case 'run': process.exit(cmdRun(rest)); break;
+    case 'update': process.exit(cmdUpdate(rest)); break;
+    case 'generate': process.exit(await cmdGenerate(rest)); break;
+    case 'diff': process.exit(cmdDiff(rest)); break;
+    default:
+      console.error(`[autoregress] unknown subcommand: ${subcmd ?? '(none)'}`);
+      process.exit(1);
+  }
+}

package/src/cli/hook.ts

@@ -0,0 +1,79 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const HOOK_CONTENT = `#!/bin/sh
+# autopilot pre-push hook — runs impact-selected snapshots before push
+npx tsx scripts/autoregress.ts run
+`;
+
+function findGitDir(cwd: string): string | null {
+  let dir = path.resolve(cwd);
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(dir, '.git');
+    if (fs.existsSync(candidate)) {
+      const stat = fs.statSync(candidate);
+      if (stat.isDirectory()) return candidate;
+      if (stat.isFile()) {
+        const content = fs.readFileSync(candidate, 'utf8');
+        const match = content.match(/^gitdir:\s*(.+)/m);
+        if (match) return path.resolve(dir, match[1]!.trim());
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+export async function runHook(
+  sub: string,
+  options: { cwd?: string; force?: boolean } = {},
+): Promise<number> {
+  const cwd = options.cwd ?? process.cwd();
+  const gitDir = findGitDir(cwd);
+
+  if (!gitDir) {
+    console.error('[hook] not inside a git repository');
+    return 1;
+  }
+
+  const hookPath = path.join(gitDir, 'hooks', 'pre-push');
+
+  switch (sub) {
+    case 'install': {
+      if (fs.existsSync(hookPath) && !options.force) {
+        console.error(`[hook] pre-push hook already exists at ${hookPath}`);
+        console.error('       Use --force to overwrite.');
+        return 1;
+      }
+      fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+      fs.writeFileSync(hookPath, HOOK_CONTENT, 'utf8');
+      fs.chmodSync(hookPath, 0o755);
+      console.log(`[hook] installed pre-push hook at ${hookPath}`);
+      return 0;
+    }
+    case 'uninstall': {
+      if (!fs.existsSync(hookPath)) {
+        console.log('[hook] no pre-push hook installed');
+        return 0;
+      }
+      fs.rmSync(hookPath);
+      console.log(`[hook] removed ${hookPath}`);
+      return 0;
+    }
+    case 'status': {
+      if (fs.existsSync(hookPath)) {
+        console.log(`[hook] installed at ${hookPath}`);
+        console.log(fs.readFileSync(hookPath, 'utf8'));
+      } else {
+        console.log('[hook] not installed');
+      }
+      return 0;
+    }
+    default:
+      console.error(`[hook] unknown subcommand: ${sub}`);
+      console.error('Usage: autopilot hook <install|uninstall|status> [--force]');
+      return 1;
+  }
+}

package/src/cli/index.ts

@@ -118,6 +118,15 @@ switch (subcommand) {
     break;
   }
 
+  case 'hook': {
+    const { runHook } = await import('./hook.ts');
+    const hookSub = args[1] ?? 'status';
+    const force = boolFlag('force');
+    const code = await runHook(hookSub, { force });
+    process.exit(code);
+    break;
+  }
+
   default:
     console.error(`\x1b[31m[autopilot] Unknown subcommand: "${subcommand}"\x1b[0m`);
     printUsage();

package/src/snapshots/impact-selector.ts

@@ -0,0 +1,60 @@
+const HIGH_IMPACT_PATTERNS = [
+  /^src\/core\/pipeline\//,
+  /^src\/adapters\//,
+  /^src\/core\/findings\//,
+  /^src\/core\/config\//,
+];
+
+export interface SelectResult {
+  selected: string[];
+  fullRun: boolean;
+  reason: string;
+}
+
+export function selectSnapshots(
+  changedFiles: string[],
+  allSnapshotFiles: string[],
+  index: Record<string, string[]>,
+  importMap: Record<string, string[]>,
+  options: { highImpactPatterns?: RegExp[]; volumeThreshold?: number } = {},
+): SelectResult {
+  const patterns = options.highImpactPatterns ?? HIGH_IMPACT_PATTERNS;
+  const volumeThreshold = options.volumeThreshold ?? 10;
+
+  if (changedFiles.length > volumeThreshold) {
+    return { selected: allSnapshotFiles, fullRun: true, reason: 'volume override (>10 files changed)' };
+  }
+
+  for (const f of changedFiles) {
+    for (const p of patterns) {
+      if (p.test(f)) {
+        return { selected: allSnapshotFiles, fullRun: true, reason: `high-impact path matched: ${f}` };
+      }
+    }
+  }
+
+  // Build: sourceFile → snapFiles that cover it
+  const sourceToSnaps: Record<string, string[]> = {};
+  for (const [snapFile, sources] of Object.entries(index)) {
+    for (const src of sources) {
+      if (!sourceToSnaps[src]) sourceToSnaps[src] = [];
+      sourceToSnaps[src]!.push(snapFile);
+    }
+  }
+
+  const selected = new Set<string>();
+  for (const changed of changedFiles) {
+    for (const snap of sourceToSnaps[changed] ?? []) selected.add(snap);
+    for (const importer of importMap[changed] ?? []) {
+      for (const snap of sourceToSnaps[importer] ?? []) selected.add(snap);
+    }
+  }
+
+  return {
+    selected: [...selected],
+    fullRun: false,
+    reason: selected.size === 0
+      ? 'no snapshots matched changed files'
+      : `${selected.size} snapshot(s) selected`,
+  };
+}

package/src/snapshots/import-scanner.ts

@@ -0,0 +1,44 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const IMPORT_RE = /^(?:import|export)\s+(?:.*?from\s+)?['"]([^'"]+)['"]/gm;
+
+function allTsFiles(dir: string): string[] {
+  const results: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) results.push(...allTsFiles(full));
+    else if (entry.isFile() && entry.name.endsWith('.ts')) results.push(full);
+  }
+  return results;
+}
+
+function resolveImport(importer: string, specifier: string, srcDir: string): string | null {
+  if (!specifier.startsWith('.')) return null;
+  const abs = path.resolve(path.dirname(importer), specifier);
+  const withExt = abs.endsWith('.ts') ? abs : abs + '.ts';
+  const rel = path.relative(srcDir, withExt).replace(/\\/g, '/');
+  if (rel.startsWith('..')) return null;
+  return rel;
+}
+
+export function buildImportMap(srcDir: string): Record<string, string[]> {
+  const absDir = path.resolve(srcDir);
+  const files = allTsFiles(absDir);
+  const map: Record<string, string[]> = {};
+
+  for (const file of files) {
+    const relImporter = path.relative(absDir, file).replace(/\\/g, '/');
+    const content = fs.readFileSync(file, 'utf8');
+    let m: RegExpExecArray | null;
+    IMPORT_RE.lastIndex = 0;
+    while ((m = IMPORT_RE.exec(content)) !== null) {
+      const resolved = resolveImport(file, m[1]!, absDir);
+      if (!resolved) continue;
+      if (!map[resolved]) map[resolved] = [];
+      if (!map[resolved]!.includes(relImporter)) map[resolved]!.push(relImporter);
+    }
+  }
+
+  return map;
+}

package/src/snapshots/serializer.ts

@@ -0,0 +1,24 @@
+const ISO_TS_RE = /^\d{4}-\d{2}-\d{2}T/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-/i;
+
+function normalizeValue(value: unknown, cwd?: string): unknown {
+  if (typeof value === 'string') {
+    if (ISO_TS_RE.test(value)) return '<timestamp>';
+    if (UUID_RE.test(value)) return '<uuid>';
+    if (cwd && value.startsWith(cwd + '/')) return value.slice(cwd.length + 1);
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(v => normalizeValue(v, cwd));
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value as object).sort()) {
+      sorted[key] = normalizeValue((value as Record<string, unknown>)[key], cwd);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+export function normalizeSnapshot(value: unknown, cwd?: string): string {
+  return JSON.stringify(normalizeValue(value, cwd), null, 2);
+}