ai-spec-dev 0.46.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.46.0",
+  "version": "0.55.0",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
     "gemini",
     "claude"
   ],
-  "author": "",
+  "author": "hongzhong",
   "license": "MIT",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.38.0",

package/tests/cross-stack-verifier.test.ts

@@ -0,0 +1,301 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import {
+  extractApiCallsFromSource,
+  normalizePathSegments,
+  pathsMatch,
+  verifyCrossStackContract,
+} from "../core/cross-stack-verifier";
+import type { SpecDSL } from "../core/dsl-types";
+
+// ─── extractApiCallsFromSource ────────────────────────────────────────────────
+
+describe("extractApiCallsFromSource", () => {
+  it("extracts axios.get calls", () => {
+    const src = `import axios from 'axios';\nconst r = await axios.get('/api/users');`;
+    const calls = extractApiCallsFromSource(src, "src/api/user.ts");
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({ method: "GET", path: "/api/users", file: "src/api/user.ts" });
+  });
+
+  it("extracts axios.post with template literal path", () => {
+    const src = "await axios.post(`/api/users/${id}/roles`, body);";
+    const calls = extractApiCallsFromSource(src, "a.ts");
+    expect(calls).toHaveLength(1);
+    expect(calls[0].method).toBe("POST");
+    expect(calls[0].path).toBe("/api/users/${id}/roles");
+  });
+
+  it("extracts fetch with inline method option", () => {
+    const src = `const r = await fetch('/api/orders', { method: 'POST', body });`;
+    const calls = extractApiCallsFromSource(src, "a.ts");
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({ method: "POST", path: "/api/orders" });
+  });
+
+  it("defaults fetch to GET when no method option", () => {
+    const src = `const r = await fetch('/api/orders');`;
+    const calls = extractApiCallsFromSource(src, "a.ts");
+    expect(calls[0].method).toBe("GET");
+  });
+
+  it("extracts useRequest calls with method option", () => {
+    const src = `const { data } = useRequest('/api/items', { method: 'DELETE' });`;
+    const calls = extractApiCallsFromSource(src, "a.ts");
+    expect(calls[0]).toMatchObject({ method: "DELETE", path: "/api/items" });
+  });
+
+  it("extracts generic request('/path', 'POST') helper", () => {
+    const src = `await request('/api/login', 'POST')`;
+    const calls = extractApiCallsFromSource(src, "a.ts");
+    expect(calls[0]).toMatchObject({ method: "POST", path: "/api/login" });
+  });
+
+  it("skips non-API string literals (CSS imports, assets)", () => {
+    const src = `import css from './style.css';\nconst logo = '/images/logo.png';`;
+    const calls = extractApiCallsFromSource(src, "a.ts");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("finds multiple calls in one file with correct line numbers", () => {
+    const src = [
+      "// line 1",
+      "import axios from 'axios';",
+      "axios.get('/api/users');",        // line 3
+      "",
+      "axios.post('/api/users', body);", // line 5
+    ].join("\n");
+    const calls = extractApiCallsFromSource(src, "x.ts");
+    expect(calls).toHaveLength(2);
+    expect(calls[0].line).toBe(3);
+    expect(calls[1].line).toBe(5);
+  });
+
+  it("marks pure request('/path') calls as UNKNOWN method", () => {
+    const src = `await request('/api/raw');`;
+    const calls = extractApiCallsFromSource(src, "a.ts");
+    expect(calls[0].method).toBe("UNKNOWN");
+  });
+});
+
+// ─── Path normalization & matching ────────────────────────────────────────────
+
+describe("normalizePathSegments", () => {
+  it("wildcards :id segments", () => {
+    expect(normalizePathSegments("/api/users/:id")).toEqual(["api", "users", "*"]);
+  });
+
+  it("wildcards template literal slots", () => {
+    expect(normalizePathSegments("/api/users/${id}/roles")).toEqual(["api", "users", "*", "roles"]);
+  });
+
+  it("wildcards numeric id segments", () => {
+    expect(normalizePathSegments("/api/users/123")).toEqual(["api", "users", "*"]);
+  });
+
+  it("strips querystring", () => {
+    expect(normalizePathSegments("/api/search?q=foo")).toEqual(["api", "search"]);
+  });
+
+  it("preserves static segments lowercased", () => {
+    expect(normalizePathSegments("/API/Users")).toEqual(["api", "users"]);
+  });
+});
+
+describe("pathsMatch", () => {
+  it("matches DSL :id against frontend ${id}", () => {
+    expect(pathsMatch("/api/users/:id", "/api/users/${userId}")).toBe(true);
+  });
+
+  it("matches DSL :id against numeric literal", () => {
+    expect(pathsMatch("/api/users/:id", "/api/users/42")).toBe(true);
+  });
+
+  it("rejects different lengths", () => {
+    expect(pathsMatch("/api/users", "/api/users/:id")).toBe(false);
+  });
+
+  it("rejects different static segments", () => {
+    expect(pathsMatch("/api/users/:id", "/api/orders/:id")).toBe(false);
+  });
+
+  it("rejects singular vs plural", () => {
+    expect(pathsMatch("/api/users/:id", "/api/user/:id")).toBe(false);
+  });
+});
+
+// ─── verifyCrossStackContract (end-to-end with tmp dir) ───────────────────────
+
+describe("verifyCrossStackContract", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "xstack-"));
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  const buildDsl = (endpoints: Array<{ id: string; method: string; path: string }>): SpecDSL => ({
+    version: "1.0",
+    feature: { id: "f", title: "T", description: "D" },
+    models: [],
+    endpoints: endpoints.map((e) => ({
+      id: e.id,
+      method: e.method as "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+      path: e.path,
+      description: "",
+      auth: false,
+      successStatus: 200,
+      successDescription: "ok",
+    })),
+  });
+
+  it("reports fully matched contract when frontend uses all endpoints correctly", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "api.ts"),
+      `axios.get('/api/users');\naxios.post('/api/users', body);`
+    );
+    const dsl = buildDsl([
+      { id: "EP-1", method: "GET", path: "/api/users" },
+      { id: "EP-2", method: "POST", path: "/api/users" },
+    ]);
+
+    const report = await verifyCrossStackContract(dsl, tmpDir);
+    expect(report.matched).toHaveLength(2);
+    expect(report.phantom).toHaveLength(0);
+    expect(report.methodMismatch).toHaveLength(0);
+    expect(report.unused).toHaveLength(0);
+  });
+
+  it("flags phantom endpoints when frontend calls a path not in DSL", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "api.ts"),
+      `axios.get('/api/ghost');\naxios.get('/api/users');`
+    );
+    const dsl = buildDsl([{ id: "EP-1", method: "GET", path: "/api/users" }]);
+
+    const report = await verifyCrossStackContract(dsl, tmpDir);
+    expect(report.phantom).toHaveLength(1);
+    expect(report.phantom[0].path).toBe("/api/ghost");
+    expect(report.matched).toHaveLength(1);
+  });
+
+  it("flags method mismatch when path matches but method differs", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "api.ts"),
+      `axios.get('/api/users');` // DSL says POST
+    );
+    const dsl = buildDsl([{ id: "EP-1", method: "POST", path: "/api/users" }]);
+
+    const report = await verifyCrossStackContract(dsl, tmpDir);
+    expect(report.methodMismatch).toHaveLength(1);
+    expect(report.methodMismatch[0].expectedMethod).toBe("POST");
+    expect(report.methodMismatch[0].call.method).toBe("GET");
+    expect(report.phantom).toHaveLength(0);
+  });
+
+  it("flags unused endpoints when DSL declares more than frontend consumes", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "api.ts"),
+      `axios.get('/api/users');`
+    );
+    const dsl = buildDsl([
+      { id: "EP-1", method: "GET", path: "/api/users" },
+      { id: "EP-2", method: "POST", path: "/api/users" },
+      { id: "EP-3", method: "DELETE", path: "/api/users/:id" },
+    ]);
+
+    const report = await verifyCrossStackContract(dsl, tmpDir);
+    expect(report.matched).toHaveLength(1);
+    expect(report.unused).toHaveLength(2);
+    expect(report.unused.map((u) => u.id).sort()).toEqual(["EP-2", "EP-3"]);
+  });
+
+  it("matches DSL :id endpoints against template-literal and numeric frontend calls", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "api.ts"),
+      "axios.get(`/api/users/${id}`);\naxios.delete('/api/users/42');"
+    );
+    const dsl = buildDsl([
+      { id: "EP-1", method: "GET", path: "/api/users/:id" },
+      { id: "EP-2", method: "DELETE", path: "/api/users/:id" },
+    ]);
+
+    const report = await verifyCrossStackContract(dsl, tmpDir);
+    expect(report.matched).toHaveLength(2);
+    expect(report.phantom).toHaveLength(0);
+    expect(report.unused).toHaveLength(0);
+  });
+
+  it("skips node_modules and dist folders", async () => {
+    await fs.ensureDir(path.join(tmpDir, "node_modules/foo"));
+    await fs.writeFile(
+      path.join(tmpDir, "node_modules/foo/index.ts"),
+      `axios.get('/api/should-be-ignored');`
+    );
+    await fs.writeFile(
+      path.join(tmpDir, "real.ts"),
+      `axios.get('/api/users');`
+    );
+    const dsl = buildDsl([{ id: "EP-1", method: "GET", path: "/api/users" }]);
+
+    const report = await verifyCrossStackContract(dsl, tmpDir);
+    expect(report.matched).toHaveLength(1);
+    expect(report.phantom).toHaveLength(0);
+  });
+
+  it("scopedFiles: only scans the listed files, ignoring pre-existing repo code", async () => {
+    // Pre-existing frontend code with unrelated API calls (simulates rushbuy case)
+    await fs.writeFile(
+      path.join(tmpDir, "legacy.ts"),
+      `axios.post('/api/youpin/deposit/service');`
+    );
+    await fs.writeFile(
+      path.join(tmpDir, "legacy2.ts"),
+      `axios.get('/api/refund/records/export');`
+    );
+    // Newly generated file (in scope) that correctly uses the DSL endpoint
+    const generated = path.join(tmpDir, "src/apis/task/index.ts");
+    await fs.ensureDir(path.dirname(generated));
+    await fs.writeFile(generated, `axios.get('/admin/tasks');`);
+
+    const dsl = buildDsl([{ id: "EP-1", method: "GET", path: "/admin/tasks" }]);
+
+    // Without scoping, the 2 legacy calls show as phantom
+    const unscoped = await verifyCrossStackContract(dsl, tmpDir);
+    expect(unscoped.phantom.length).toBeGreaterThanOrEqual(2);
+
+    // With scoping, only the generated file is checked — clean report
+    const scoped = await verifyCrossStackContract(dsl, tmpDir, {
+      scopedFiles: [generated],
+    });
+    expect(scoped.phantom).toHaveLength(0);
+    expect(scoped.matched).toHaveLength(1);
+    expect(scoped.totalScannedFiles).toBe(1);
+  });
+
+  it("scopedFiles: accepts relative paths resolved against frontendRoot", async () => {
+    await fs.ensureDir(path.join(tmpDir, "src"));
+    await fs.writeFile(path.join(tmpDir, "src/x.ts"), `axios.get('/api/users');`);
+    const dsl = buildDsl([{ id: "EP-1", method: "GET", path: "/api/users" }]);
+
+    const report = await verifyCrossStackContract(dsl, tmpDir, {
+      scopedFiles: ["src/x.ts"],
+    });
+    expect(report.matched).toHaveLength(1);
+    expect(report.totalScannedFiles).toBe(1);
+  });
+
+  it("scopedFiles: empty list falls back to full scan", async () => {
+    await fs.writeFile(path.join(tmpDir, "a.ts"), `axios.get('/api/users');`);
+    const dsl = buildDsl([{ id: "EP-1", method: "GET", path: "/api/users" }]);
+
+    const report = await verifyCrossStackContract(dsl, tmpDir, { scopedFiles: [] });
+    // Empty list is treated as "no scope" → walks whole tree
+    expect(report.matched).toHaveLength(1);
+  });
+});

package/tests/fix-history.test.ts

@@ -0,0 +1,335 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import {
+  FIX_HISTORY_FILE,
+  FIX_HISTORY_VERSION,
+  computePatternKey,
+  loadFixHistory,
+  appendFixEntry,
+  pruneFixHistory,
+  aggregateFixPatterns,
+  buildHallucinationAvoidanceSection,
+  detectPromotionCandidates,
+  computeFixHistoryStats,
+  FixHistoryEntry,
+} from "../core/fix-history";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "fix-hist-"));
+});
+
+afterEach(async () => {
+  await fs.remove(tmpDir);
+});
+
+function makeEntry(overrides: Partial<FixHistoryEntry> = {}): Omit<FixHistoryEntry, "patternKey"> {
+  return {
+    ts: overrides.ts ?? new Date().toISOString(),
+    runId: overrides.runId ?? "run-001",
+    brokenImport: overrides.brokenImport ?? {
+      source: "@/apis/task/type",
+      names: ["Task"],
+      reason: "file_not_found",
+      file: "src/stores/task.ts",
+      line: 4,
+    },
+    fix: overrides.fix ?? {
+      kind: "create_file",
+      target: "src/apis/task/type.ts",
+      stage: "deterministic",
+    },
+  };
+}
+
+// ─── computePatternKey ────────────────────────────────────────────────────────
+
+describe("computePatternKey", () => {
+  it("produces the same key for identical source + names", () => {
+    const a = computePatternKey("@/apis/task/type", ["Task"]);
+    const b = computePatternKey("@/apis/task/type", ["Task"]);
+    expect(a).toBe(b);
+    expect(a).toHaveLength(12);
+  });
+
+  it("is order-independent for names", () => {
+    const a = computePatternKey("@/apis/foo", ["A", "B"]);
+    const b = computePatternKey("@/apis/foo", ["B", "A"]);
+    expect(a).toBe(b);
+  });
+
+  it("differs when source differs", () => {
+    const a = computePatternKey("@/apis/task/type", ["Task"]);
+    const b = computePatternKey("@/apis/task/types", ["Task"]);
+    expect(a).not.toBe(b);
+  });
+
+  it("differs when names differ", () => {
+    const a = computePatternKey("@/x", ["A"]);
+    const b = computePatternKey("@/x", ["B"]);
+    expect(a).not.toBe(b);
+  });
+});
+
+// ─── loadFixHistory / appendFixEntry ──────────────────────────────────────────
+
+describe("loadFixHistory + appendFixEntry", () => {
+  it("returns empty history when file does not exist", async () => {
+    const history = await loadFixHistory(tmpDir);
+    expect(history.version).toBe(FIX_HISTORY_VERSION);
+    expect(history.entries).toHaveLength(0);
+  });
+
+  it("appends and reads back a single entry", async () => {
+    await appendFixEntry(tmpDir, makeEntry());
+    const history = await loadFixHistory(tmpDir);
+    expect(history.entries).toHaveLength(1);
+    expect(history.entries[0].patternKey).toBeDefined();
+    expect(history.entries[0].brokenImport.source).toBe("@/apis/task/type");
+  });
+
+  it("computes a stable patternKey for each entry", async () => {
+    const result = await appendFixEntry(tmpDir, makeEntry());
+    const expected = computePatternKey("@/apis/task/type", ["Task"]);
+    expect(result.patternKey).toBe(expected);
+  });
+
+  it("preserves append order across multiple entries", async () => {
+    await appendFixEntry(tmpDir, makeEntry({ ts: "2026-04-07T10:00:00.000Z", runId: "r1" }));
+    await appendFixEntry(tmpDir, makeEntry({ ts: "2026-04-07T11:00:00.000Z", runId: "r2" }));
+    const history = await loadFixHistory(tmpDir);
+    expect(history.entries).toHaveLength(2);
+    expect(history.entries[0].runId).toBe("r1");
+    expect(history.entries[1].runId).toBe("r2");
+  });
+
+  it("gracefully handles corrupted ledger file", async () => {
+    await fs.writeFile(path.join(tmpDir, FIX_HISTORY_FILE), "not valid json{{{");
+    const history = await loadFixHistory(tmpDir);
+    expect(history.entries).toHaveLength(0);
+  });
+
+  it("handles ledger file missing `entries` array", async () => {
+    await fs.writeJson(path.join(tmpDir, FIX_HISTORY_FILE), { version: "1.0" });
+    const history = await loadFixHistory(tmpDir);
+    expect(history.entries).toHaveLength(0);
+  });
+});
+
+// ─── pruneFixHistory ──────────────────────────────────────────────────────────
+
+describe("pruneFixHistory", () => {
+  it("removes entries older than maxAgeDays", async () => {
+    const oldTs = new Date(Date.now() - 40 * 24 * 60 * 60 * 1000).toISOString();
+    const freshTs = new Date().toISOString();
+    await appendFixEntry(tmpDir, makeEntry({ ts: oldTs, runId: "old" }));
+    await appendFixEntry(tmpDir, makeEntry({ ts: freshTs, runId: "new" }));
+
+    const removed = await pruneFixHistory(tmpDir, 30);
+    expect(removed).toBe(1);
+
+    const history = await loadFixHistory(tmpDir);
+    expect(history.entries).toHaveLength(1);
+    expect(history.entries[0].runId).toBe("new");
+  });
+
+  it("returns 0 when nothing is old enough to prune", async () => {
+    await appendFixEntry(tmpDir, makeEntry());
+    const removed = await pruneFixHistory(tmpDir, 30);
+    expect(removed).toBe(0);
+  });
+
+  it("returns 0 on empty history", async () => {
+    const removed = await pruneFixHistory(tmpDir, 30);
+    expect(removed).toBe(0);
+  });
+});
+
+// ─── aggregateFixPatterns ─────────────────────────────────────────────────────
+
+describe("aggregateFixPatterns", () => {
+  it("groups entries by patternKey", async () => {
+    // Same pattern, seen in 3 different runs
+    await appendFixEntry(tmpDir, makeEntry({ runId: "r1", ts: "2026-04-01T10:00:00.000Z" }));
+    await appendFixEntry(tmpDir, makeEntry({ runId: "r2", ts: "2026-04-02T10:00:00.000Z" }));
+    await appendFixEntry(tmpDir, makeEntry({ runId: "r3", ts: "2026-04-03T10:00:00.000Z" }));
+
+    const history = await loadFixHistory(tmpDir);
+    const patterns = aggregateFixPatterns(history);
+
+    expect(patterns).toHaveLength(1);
+    expect(patterns[0].count).toBe(3);
+    expect(patterns[0].uniqueRunIds).toBe(3);
+    expect(patterns[0].firstSeen).toBe("2026-04-01T10:00:00.000Z");
+    expect(patterns[0].lastSeen).toBe("2026-04-03T10:00:00.000Z");
+  });
+
+  it("sorts by count descending", async () => {
+    // Pattern A: 3 hits
+    for (let i = 0; i < 3; i++) {
+      await appendFixEntry(tmpDir, makeEntry({
+        runId: `a${i}`,
+        brokenImport: { source: "@/a", names: ["A"], reason: "file_not_found", file: "x", line: 1 },
+      }));
+    }
+    // Pattern B: 1 hit
+    await appendFixEntry(tmpDir, makeEntry({
+      runId: "b1",
+      brokenImport: { source: "@/b", names: ["B"], reason: "file_not_found", file: "y", line: 1 },
+    }));
+
+    const history = await loadFixHistory(tmpDir);
+    const patterns = aggregateFixPatterns(history);
+    expect(patterns).toHaveLength(2);
+    expect(patterns[0].source).toBe("@/a");
+    expect(patterns[0].count).toBe(3);
+    expect(patterns[1].source).toBe("@/b");
+  });
+
+  it("counts unique runIds correctly when same run has multiple entries", async () => {
+    // One run, same pattern hit in 2 files
+    await appendFixEntry(tmpDir, makeEntry({ runId: "same-run", brokenImport: { source: "@/x", names: ["X"], reason: "file_not_found", file: "a.ts", line: 1 } }));
+    await appendFixEntry(tmpDir, makeEntry({ runId: "same-run", brokenImport: { source: "@/x", names: ["X"], reason: "file_not_found", file: "b.ts", line: 1 } }));
+
+    const history = await loadFixHistory(tmpDir);
+    const patterns = aggregateFixPatterns(history);
+    expect(patterns).toHaveLength(1);
+    expect(patterns[0].count).toBe(2);
+    expect(patterns[0].uniqueRunIds).toBe(1);
+  });
+});
+
+// ─── buildHallucinationAvoidanceSection ───────────────────────────────────────
+
+describe("buildHallucinationAvoidanceSection", () => {
+  it("returns null for empty history", async () => {
+    const history = await loadFixHistory(tmpDir);
+    expect(buildHallucinationAvoidanceSection(history)).toBeNull();
+  });
+
+  it("produces a section with the broken import and frequency", async () => {
+    await appendFixEntry(tmpDir, makeEntry({
+      ts: "2026-04-07T10:00:00.000Z",
+      brokenImport: { source: "@/apis/task/type", names: ["Task"], reason: "file_not_found", file: "s", line: 1 },
+    }));
+    await appendFixEntry(tmpDir, makeEntry({
+      ts: "2026-04-07T11:00:00.000Z",
+      brokenImport: { source: "@/apis/task/type", names: ["Task"], reason: "file_not_found", file: "s", line: 1 },
+    }));
+
+    const history = await loadFixHistory(tmpDir);
+    const section = buildHallucinationAvoidanceSection(history);
+
+    expect(section).toBeTruthy();
+    expect(section).toContain("DO NOT REPEAT");
+    expect(section).toContain("@/apis/task/type");
+    expect(section).toContain("Task");
+    expect(section).toContain("seen 2x");
+    expect(section).toContain("2026-04-07");
+  });
+
+  it("respects minCount filter", async () => {
+    // Only 1 entry → below minCount of 2 → should return null
+    await appendFixEntry(tmpDir, makeEntry());
+    const history = await loadFixHistory(tmpDir);
+    const section = buildHallucinationAvoidanceSection(history, { minCount: 2 });
+    expect(section).toBeNull();
+  });
+
+  it("respects maxItems cap", async () => {
+    // Create 15 distinct patterns
+    for (let i = 0; i < 15; i++) {
+      await appendFixEntry(tmpDir, makeEntry({
+        brokenImport: { source: `@/p${i}`, names: ["X"], reason: "file_not_found", file: "s", line: 1 },
+      }));
+    }
+    const history = await loadFixHistory(tmpDir);
+    const section = buildHallucinationAvoidanceSection(history, { maxItems: 5 });
+    expect(section).toBeTruthy();
+    expect(section).toContain("10 more pattern(s) hidden");
+    // Should only contain 5 DO NOT lines
+    const notCount = (section!.match(/❌ Do NOT/g) ?? []).length;
+    expect(notCount).toBe(5);
+  });
+});
+
+// ─── detectPromotionCandidates ────────────────────────────────────────────────
+
+describe("detectPromotionCandidates", () => {
+  it("returns empty when no pattern meets threshold", async () => {
+    for (let i = 0; i < 3; i++) {
+      await appendFixEntry(tmpDir, makeEntry({ runId: `r${i}` }));
+    }
+    const history = await loadFixHistory(tmpDir);
+    const candidates = detectPromotionCandidates(history, 5);
+    expect(candidates).toHaveLength(0);
+  });
+
+  it("returns patterns above threshold with lesson text", async () => {
+    for (let i = 0; i < 6; i++) {
+      await appendFixEntry(tmpDir, makeEntry({ runId: `r${i}` }));
+    }
+    const history = await loadFixHistory(tmpDir);
+    const candidates = detectPromotionCandidates(history, 5);
+    expect(candidates).toHaveLength(1);
+    expect(candidates[0].aggregate.count).toBe(6);
+    expect(candidates[0].lessonText).toContain("@/apis/task/type");
+    expect(candidates[0].lessonText).toContain("6 次");
+  });
+
+  it("distinguishes file_not_found vs missing_export in lesson text", async () => {
+    for (let i = 0; i < 5; i++) {
+      await appendFixEntry(tmpDir, makeEntry({
+        runId: `r${i}`,
+        brokenImport: { source: "@/a", names: ["X"], reason: "missing_export", file: "s", line: 1 },
+      }));
+    }
+    const history = await loadFixHistory(tmpDir);
+    const candidates = detectPromotionCandidates(history, 5);
+    expect(candidates[0].lessonText).toContain("未导出");
+  });
+});
+
+// ─── computeFixHistoryStats ───────────────────────────────────────────────────
+
+describe("computeFixHistoryStats", () => {
+  it("counts entries, patterns, runs, and stage/reason breakdown", async () => {
+    await appendFixEntry(tmpDir, makeEntry({
+      runId: "r1",
+      fix: { kind: "create_file", target: "a.ts", stage: "deterministic" },
+    }));
+    await appendFixEntry(tmpDir, makeEntry({
+      runId: "r1",
+      brokenImport: { source: "@/b", names: ["B"], reason: "missing_export", file: "x", line: 1 },
+      fix: { kind: "create_file", target: "b.ts", stage: "ai" },
+    }));
+    await appendFixEntry(tmpDir, makeEntry({
+      runId: "r2",
+      fix: { kind: "create_file", target: "a.ts", stage: "deterministic" },
+    }));
+
+    const history = await loadFixHistory(tmpDir);
+    const stats = computeFixHistoryStats(history);
+
+    expect(stats.totalEntries).toBe(3);
+    expect(stats.uniquePatterns).toBe(2);
+    expect(stats.uniqueRunIds).toBe(2);
+    expect(stats.byStage.deterministic).toBe(2);
+    expect(stats.byStage.ai).toBe(1);
+    expect(stats.byReason.file_not_found).toBe(2);
+    expect(stats.byReason.missing_export).toBe(1);
+  });
+
+  it("returns zeros for empty history", async () => {
+    const history = await loadFixHistory(tmpDir);
+    const stats = computeFixHistoryStats(history);
+    expect(stats.totalEntries).toBe(0);
+    expect(stats.uniquePatterns).toBe(0);
+    expect(stats.lastEntryTs).toBeUndefined();
+  });
+});