ai-spec-dev 0.37.0 → 0.41.0

package/tests/constitution-consolidator.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import {
+  ConstitutionConsolidator,
+  checkConsolidationNeeded,
+} from "../core/constitution-consolidator";
+import { CONSTITUTION_FILE } from "../core/constitution-generator";
+
+describe("checkConsolidationNeeded", () => {
+  it("prints warning when lessonCount >= threshold", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    checkConsolidationNeeded("/tmp", 10);
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("ai-spec init --consolidate"));
+    spy.mockRestore();
+  });
+
+  it("does not print when lessonCount < threshold", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    checkConsolidationNeeded("/tmp", 3);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it("uses custom threshold", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    checkConsolidationNeeded("/tmp", 5, 5);
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("ConstitutionConsolidator", () => {
+  let tmpDir: string;
+  const mockProvider = {
+    generate: vi.fn(),
+    providerName: "test",
+    modelName: "test-model",
+  };
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `cc-test-${Date.now()}`);
+    await fs.ensureDir(tmpDir);
+    mockProvider.generate.mockReset();
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it("throws when constitution file does not exist", async () => {
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    await expect(consolidator.consolidate(tmpDir)).rejects.toThrow("No constitution file");
+  });
+
+  it("skips when lesson count is below threshold", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      "# Constitution\n## 1. Architecture\nSome rules.\n## 9. 积累教训 (Accumulated Lessons)\n- lesson 1\n- lesson 2\n"
+    );
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { minLessons: 5 });
+    expect(result.written).toBe(false);
+    expect(mockProvider.generate).not.toHaveBeenCalled();
+  });
+
+  it("consolidates when lesson count meets threshold", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson number ${i + 1} with enough detail`
+    ).join("\n");
+    const constitution = `# Constitution\n## 1. Architecture\nRules.\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`;
+    await fs.writeFile(path.join(tmpDir, CONSTITUTION_FILE), constitution);
+
+    mockProvider.generate.mockResolvedValueOnce(
+      "# Constitution\n## 1. Architecture\nRules + consolidated lessons.\n\n## 9. 积累教训 (Accumulated Lessons)\n- 📝 **[2026-04-02]** Consolidated lesson\n"
+    );
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { minLessons: 5 });
+
+    expect(result.written).toBe(true);
+    expect(result.backupPath).not.toBeNull();
+    expect(await fs.pathExists(result.backupPath!)).toBe(true);
+    expect(result.before.lessonCount).toBe(6);
+  });
+
+  it("dry-run does not write changes", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson ${i + 1} with detail text here`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockResolvedValueOnce("# Consolidated");
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { dryRun: true, minLessons: 5 });
+
+    expect(result.written).toBe(false);
+    expect(result.backupPath).toBeNull();
+    const content = await fs.readFile(path.join(tmpDir, CONSTITUTION_FILE), "utf-8");
+    expect(content).toContain("积累教训"); // original unchanged
+  });
+
+  it("creates backup before writing", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson ${i + 1} with details here`
+    ).join("\n");
+    const original = `# Constitution\n\n## 9. 积累教训\n${lessons}\n`;
+    await fs.writeFile(path.join(tmpDir, CONSTITUTION_FILE), original);
+
+    mockProvider.generate.mockResolvedValueOnce("# New constitution");
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { minLessons: 5 });
+
+    expect(result.backupPath).not.toBeNull();
+    const backup = await fs.readFile(result.backupPath!, "utf-8");
+    expect(backup).toBe(original);
+  });
+
+  it("strips markdown fences from AI output", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson ${i + 1} for testing fences`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockResolvedValueOnce("```markdown\n# Clean Constitution\n```");
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { minLessons: 5 });
+
+    const content = await fs.readFile(path.join(tmpDir, CONSTITUTION_FILE), "utf-8");
+    expect(content).not.toContain("```");
+    expect(content).toContain("Clean Constitution");
+  });
+
+  it("throws when AI call fails", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson ${i + 1} text for error test`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockRejectedValueOnce(new Error("API error"));
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    await expect(
+      consolidator.consolidate(tmpDir, { minLessons: 5 })
+    ).rejects.toThrow("AI consolidation failed");
+  });
+});

package/tests/constitution-generator.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import {
+  ConstitutionGenerator,
+  CONSTITUTION_FILE,
+  loadConstitution,
+  printConstitutionHint,
+} from "../core/constitution-generator";
+
+describe("CONSTITUTION_FILE", () => {
+  it("is .ai-spec-constitution.md", () => {
+    expect(CONSTITUTION_FILE).toBe(".ai-spec-constitution.md");
+  });
+});
+
+describe("ConstitutionGenerator", () => {
+  let tmpDir: string;
+  const mockProvider = {
+    generate: vi.fn(),
+    providerName: "test",
+    modelName: "test-model",
+  };
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `cg-test-${Date.now()}`);
+    await fs.ensureDir(tmpDir);
+    mockProvider.generate.mockReset();
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it("generate() calls provider with context from project", async () => {
+    await fs.writeJson(path.join(tmpDir, "package.json"), {
+      dependencies: { express: "4.0.0" },
+    });
+    mockProvider.generate.mockResolvedValueOnce("# Constitution\n## 1. Architecture");
+
+    const gen = new ConstitutionGenerator(mockProvider);
+    const result = await gen.generate(tmpDir);
+    expect(result).toContain("Constitution");
+    expect(mockProvider.generate).toHaveBeenCalledOnce();
+  });
+
+  it("saveConstitution() writes file to project root", async () => {
+    const gen = new ConstitutionGenerator(mockProvider);
+    const filePath = await gen.saveConstitution(tmpDir, "# My Constitution");
+    expect(filePath).toBe(path.join(tmpDir, CONSTITUTION_FILE));
+    expect(await fs.readFile(filePath, "utf-8")).toBe("# My Constitution");
+  });
+});
+
+describe("loadConstitution", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `cg-load-${Date.now()}`);
+    await fs.ensureDir(tmpDir);
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it("returns content when file exists", async () => {
+    await fs.writeFile(path.join(tmpDir, CONSTITUTION_FILE), "rules here");
+    const content = await loadConstitution(tmpDir);
+    expect(content).toBe("rules here");
+  });
+
+  it("returns undefined when file does not exist", async () => {
+    const content = await loadConstitution(tmpDir);
+    expect(content).toBeUndefined();
+  });
+});
+
+describe("printConstitutionHint", () => {
+  it("prints hint when exists is false", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    printConstitutionHint(false);
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("ai-spec init"));
+    spy.mockRestore();
+  });
+
+  it("does not print when exists is true", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    printConstitutionHint(true);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});

package/tests/contract-bridge.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect } from "vitest";
+import { buildFrontendApiContract, buildContractContextSection } from "../core/contract-bridge";
+import { SpecDSL } from "../core/dsl-types";
+
+// ─── Minimal DSL fixture ─────────────────────────────────────────────────────
+
+function makeDsl(overrides?: Partial<SpecDSL>): SpecDSL {
+  return {
+    feature: { title: "Order Management", description: "CRUD for orders" },
+    models: [
+      {
+        name: "Order",
+        fields: [
+          { name: "id", type: "Int", required: true, unique: true },
+          { name: "total", type: "Float", required: true, unique: false },
+          { name: "status", type: "String", required: true, unique: false },
+          { name: "createdAt", type: "DateTime", required: false, unique: false },
+        ],
+      },
+    ],
+    endpoints: [
+      {
+        id: "createOrder",
+        method: "POST",
+        path: "/api/orders",
+        auth: true,
+        description: "Create a new order",
+        request: { body: { total: "number", items: "string[]" }, params: {}, query: {} },
+        successStatus: 201,
+        successDescription: "Created order with id",
+        errors: [
+          { status: 400, code: "INVALID_INPUT", description: "Bad request" },
+          { status: 401, code: "UNAUTHORIZED", description: "Not authenticated" },
+        ],
+      },
+      {
+        id: "listOrders",
+        method: "GET",
+        path: "/api/orders",
+        auth: true,
+        description: "List all orders",
+        request: { body: {}, params: {}, query: { page: "number", limit: "number" } },
+        successStatus: 200,
+        successDescription: "Returns list of orders",
+        errors: [],
+      },
+      {
+        id: "deleteOrder",
+        method: "DELETE",
+        path: "/api/orders/:id",
+        auth: true,
+        description: "Delete an order",
+        request: { body: {}, params: { id: "string" }, query: {} },
+        successStatus: 204,
+        successDescription: "No content",
+        errors: [{ status: 404, code: "NOT_FOUND", description: "Order not found" }],
+      },
+    ],
+    behaviors: [],
+    ...overrides,
+  } as SpecDSL;
+}
+
+// ─── buildFrontendApiContract ────────────────────────────────────────────────
+
+describe("buildFrontendApiContract", () => {
+  it("returns correct number of endpoints", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints).toHaveLength(3);
+  });
+
+  it("preserves method and path", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].method).toBe("POST");
+    expect(contract.endpoints[0].path).toBe("/api/orders");
+  });
+
+  it("preserves auth flag", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].auth).toBe(true);
+  });
+
+  it("extracts error codes", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].errorCodes).toEqual(["INVALID_INPUT", "UNAUTHORIZED"]);
+    expect(contract.endpoints[2].errorCodes).toEqual(["NOT_FOUND"]);
+  });
+
+  it("generates request shape as TypeScript interface", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].requestShape).toContain("interface");
+    expect(contract.endpoints[0].requestShape).toContain("total");
+    expect(contract.endpoints[0].requestShape).toContain("items");
+  });
+
+  it("generates response shape as TypeScript interface", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].responseShape).toContain("interface");
+  });
+
+  it("uses model fields for GET response on matching path", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const listEndpoint = contract.endpoints[1]; // GET /api/orders
+    expect(listEndpoint.responseShape).toContain("id");
+    expect(listEndpoint.responseShape).toContain("total");
+    expect(listEndpoint.responseShape).toContain("status");
+  });
+
+  it("generates 204 No Content interface for DELETE", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const deleteEndpoint = contract.endpoints[2];
+    expect(deleteEndpoint.responseShape).toContain("204 No Content");
+  });
+
+  it("generates type definitions block", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.typeDefinitions).toContain("interface");
+    expect(contract.typeDefinitions.length).toBeGreaterThan(50);
+  });
+
+  it("generates summary with feature title", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.summary).toContain("Order Management");
+    expect(contract.summary).toContain("3"); // 3 endpoints
+    expect(contract.summary).toContain("Order"); // model name
+  });
+
+  it("summary shows auth label per endpoint", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.summary).toContain("[auth required]");
+  });
+
+  it("handles empty errors array", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const listEndpoint = contract.endpoints[1];
+    expect(listEndpoint.errorCodes).toEqual([]);
+  });
+
+  it("handles DSL with no models", () => {
+    const contract = buildFrontendApiContract(makeDsl({ models: [] }));
+    expect(contract.endpoints).toHaveLength(3);
+    expect(contract.summary).not.toContain("Data models:");
+  });
+
+  it("infers TS types correctly in request shape", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    // Query params — page and limit should be number
+    const listReq = contract.endpoints[1].requestShape;
+    expect(listReq).toContain("number");
+  });
+
+  it("handles endpoint with token response description", () => {
+    const dsl = makeDsl({
+      endpoints: [
+        {
+          id: "login",
+          method: "POST",
+          path: "/api/auth/login",
+          auth: false,
+          description: "Login",
+          request: { body: { email: "string", password: "string" }, params: {}, query: {} },
+          successStatus: 200,
+          successDescription: "Returns JWT token",
+          errors: [],
+        },
+      ],
+    });
+    const contract = buildFrontendApiContract(dsl);
+    expect(contract.endpoints[0].responseShape).toContain("token");
+  });
+});
+
+// ─── buildContractContextSection ─────────────────────────────────────────────
+
+describe("buildContractContextSection", () => {
+  it("wraps contract in boundary markers", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const section = buildContractContextSection(contract);
+    expect(section).toContain("=== Backend API Contract");
+    expect(section).toContain("=== End of Backend API Contract ===");
+  });
+
+  it("includes summary", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const section = buildContractContextSection(contract);
+    expect(section).toContain("Order Management");
+  });
+
+  it("includes TypeScript definitions", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const section = buildContractContextSection(contract);
+    expect(section).toContain("TypeScript Interface Definitions");
+    expect(section).toContain("interface");
+  });
+
+  it("includes instruction not to change paths/methods", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const section = buildContractContextSection(contract);
+    expect(section).toContain("do NOT change paths");
+  });
+});

package/tests/design-dialogue.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { DesignDialogue } from "../core/design-dialogue";
+
+// Mock @inquirer/prompts
+vi.mock("@inquirer/prompts", () => ({
+  select: vi.fn(),
+}));
+
+import { select } from "@inquirer/prompts";
+const mockedSelect = vi.mocked(select);
+
+const mockProvider = {
+  generate: vi.fn(),
+  providerName: "test",
+  modelName: "test-model",
+};
+
+const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+beforeEach(() => {
+  mockProvider.generate.mockReset();
+  mockedSelect.mockReset();
+});
+
+const contextHints = {
+  techStack: ["express", "prisma"],
+  repoType: "node-express",
+};
+
+describe("DesignDialogue", () => {
+  it("returns selectedApproach when user picks an option", async () => {
+    const optionsText = "### Option A — REST approach\nUse REST.\n### Option B — GraphQL\nUse GraphQL.\n### Option C — gRPC\nUse gRPC.";
+    mockProvider.generate.mockResolvedValueOnce(optionsText);
+    mockedSelect.mockResolvedValueOnce("Option A — REST approach");
+
+    const dialogue = new DesignDialogue(mockProvider);
+    const result = await dialogue.run("Build user service", contextHints);
+
+    expect(result.optionsText).toBe(optionsText);
+    expect(result.selectedApproach).toContain("Option A");
+  });
+
+  it("returns null selectedApproach when user skips", async () => {
+    mockProvider.generate.mockResolvedValueOnce("### Option A — REST\n### Option B — GraphQL");
+    mockedSelect.mockResolvedValueOnce("__skip__");
+
+    const dialogue = new DesignDialogue(mockProvider);
+    const result = await dialogue.run("Build API", contextHints);
+
+    expect(result.selectedApproach).toBeNull();
+  });
+
+  it("blends approaches when user selects blend", async () => {
+    mockProvider.generate.mockResolvedValueOnce("### Option A — REST\nDetails\n### Option B — GraphQL\nDetails");
+    mockedSelect.mockResolvedValueOnce("__blend__");
+    mockProvider.generate.mockResolvedValueOnce("Use REST for CRUD and GraphQL for complex queries.");
+
+    const dialogue = new DesignDialogue(mockProvider);
+    const result = await dialogue.run("Build API", contextHints);
+
+    expect(result.selectedApproach).toContain("Blended approach");
+    expect(result.selectedApproach).toContain("REST for CRUD");
+  });
+
+  it("returns null when blend fails", async () => {
+    mockProvider.generate.mockResolvedValueOnce("### Option A — REST\n### Option B — GraphQL");
+    mockedSelect.mockResolvedValueOnce("__blend__");
+    mockProvider.generate.mockRejectedValueOnce(new Error("fail"));
+
+    const dialogue = new DesignDialogue(mockProvider);
+    const result = await dialogue.run("Build API", contextHints);
+
+    expect(result.selectedApproach).toBeNull();
+  });
+
+  it("returns null when AI options generation fails", async () => {
+    mockProvider.generate.mockRejectedValueOnce(new Error("timeout"));
+
+    const dialogue = new DesignDialogue(mockProvider);
+    const result = await dialogue.run("Build API", contextHints);
+
+    expect(result.optionsText).toBe("");
+    expect(result.selectedApproach).toBeNull();
+  });
+
+  it("extracts full option text when user selects a specific option", async () => {
+    const optionsText = "### Option A — Monolith\nKeep it simple.\n### Option B — Microservices\nScale independently.\n---";
+    mockProvider.generate.mockResolvedValueOnce(optionsText);
+    mockedSelect.mockResolvedValueOnce("Option A — Monolith");
+
+    const dialogue = new DesignDialogue(mockProvider);
+    const result = await dialogue.run("Build system", contextHints);
+
+    expect(result.selectedApproach).toContain("Keep it simple");
+  });
+
+  it("caps selected approach to 400 chars", async () => {
+    const longDesc = "A".repeat(500);
+    const optionsText = `### Option A — Long\n${longDesc}\n### Option B — Short\nShort.`;
+    mockProvider.generate.mockResolvedValueOnce(optionsText);
+    mockedSelect.mockResolvedValueOnce("Option A — Long");
+
+    const dialogue = new DesignDialogue(mockProvider);
+    const result = await dialogue.run("Build", contextHints);
+
+    expect(result.selectedApproach!.length).toBeLessThanOrEqual(400);
+  });
+});