ai-spec-dev 0.36.1 → 0.37.0

package/RELEASE_LOG.md

@@ -5,6 +5,26 @@
 
 ---
 
+## v0.37.0 — 2026-04-02 — P1 测试覆盖：Mock Server / Types Generator / VCR
+
+### 新增测试（Phase 1 收尾）
+
+**Test 7 — `mock-server-generator.test.ts`（28 tests）**
+
+覆盖 `generateMockAssets`（Express server.js 生成、README.md 端点表格、auth 中间件条件生成、DELETE 204 sendStatus、错误模拟注释、自定义端口、自定义输出目录、列表端点分页 fixture、MSW handlers/browser 生成、proxy 配置生成）、前端框架检测（Vite/Next.js/CRA/Webpack）、fixture 启发式（email/boolean/DateTime 字段类型）、`findLatestDslFile`（不存在目录、无匹配文件、最新文件选择、嵌套目录扫描）、`applyMockProxy`/`restoreMockProxy`（Vite 配置写入+dev:mock 脚本注入+还原、CRA proxy 字段注入+还原、Next.js 手动提示、无 lock 文件容错）。
+
+**Test 8 — `types-generator.test.ts`（28 tests）**
+
+覆盖类型映射（String→string、Int/Float→number、Boolean→boolean、DateTime→string、Json→Record、数组类型、PascalCase 模型引用保留、未知类型回退 string、nullable 标记剥离）、模型接口渲染（export interface、必填/可选字段、模型描述 JSDoc、字段描述 JSDoc）、端点类型（请求体接口、查询参数可选接口、路径参数接口、includeEndpointTypes 开关、无 schema 端点跳过）、端点常量表（API_ENDPOINTS const、method/path/auth 字段、ApiEndpointKey 类型、includeEndpointMap 开关）、自定义 header、前端组件 Props 接口、`saveTypescriptTypes`（默认路径写入、自定义路径写入）。
+
+**Test 9 — `vcr.test.ts`（22 tests）**
+
+覆盖 `VcrRecordingProvider`（透传 generate 调用、元数据记录含 callHash/promptPreview/duration/provider/model、providerName/modelName 代理、无 systemInstruction 时省略字段、promptPreview 截断 200 字符、保存至 .ai-spec-vcr 目录、双 recorder 合并按时间排序+重建索引、多 provider 记录）、`VcrReplayProvider`（按序回放、providerName=vcr-replay、modelName=runId、remaining/consumed 计数、exhausted 抛错、忽略 prompt 内容纯按索引回放）、`loadVcrRecording`（正常加载、不存在返回 null、损坏 JSON 返回 null）、`listVcrRecordings`（不存在目录返回空、逆序排列、跳过损坏文件、忽略非 JSON 文件、summary 字段正确性）。
+
+**测试覆盖率提升：37.5% → 45%（15 → 18 个模块有测试，331 → 409 test cases）**
+
+---
+
 ## v0.36.1 — 2026-04-02 — P0 测试覆盖 + 质量硬门禁 + 错误体验优化
 
 ### 新增测试（Week 2）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.36.1",
+  "version": "0.37.0",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/tests/mock-server-generator.test.ts

@@ -0,0 +1,404 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as path from "path";
+import * as fs from "fs-extra";
+import * as os from "os";
+import type { SpecDSL, ApiEndpoint } from "../core/dsl-types";
+
+// ─── We need to import the module under test ────────────────────────────────
+// Some functions are not exported — we test via the public API (generateMockAssets)
+// and exported helpers (findLatestDslFile, applyMockProxy, restoreMockProxy).
+
+import {
+  generateMockAssets,
+  findLatestDslFile,
+  applyMockProxy,
+  restoreMockProxy,
+  MockServerOptions,
+} from "../core/mock-server-generator";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+function makeDsl(overrides: Partial<SpecDSL> = {}): SpecDSL {
+  return {
+    version: "1.0",
+    feature: { id: "user-crud", title: "User CRUD", description: "Basic user management" },
+    models: [
+      {
+        name: "User",
+        fields: [
+          { name: "id", type: "String", required: true, unique: true },
+          { name: "email", type: "String", required: true },
+          { name: "name", type: "String", required: true },
+          { name: "age", type: "Int", required: false },
+          { name: "isActive", type: "Boolean", required: true },
+          { name: "createdAt", type: "DateTime", required: true },
+        ],
+      },
+    ],
+    endpoints: [
+      {
+        id: "EP-001",
+        method: "GET",
+        path: "/api/users",
+        description: "List all users",
+        auth: true,
+        successStatus: 200,
+        successDescription: "Returns list of users",
+      },
+      {
+        id: "EP-002",
+        method: "POST",
+        path: "/api/users",
+        description: "Create a new user",
+        auth: true,
+        request: { body: { email: "String", name: "String" } },
+        successStatus: 201,
+        successDescription: "User created",
+        errors: [
+          { status: 400, code: "INVALID_INPUT", description: "Bad request" },
+          { status: 409, code: "DUPLICATE_EMAIL", description: "Email already exists" },
+        ],
+      },
+      {
+        id: "EP-003",
+        method: "GET",
+        path: "/api/users/:id",
+        description: "Get user by ID",
+        auth: true,
+        request: { params: { id: "String" } },
+        successStatus: 200,
+        successDescription: "Returns user",
+      },
+      {
+        id: "EP-004",
+        method: "DELETE",
+        path: "/api/users/:id",
+        description: "Delete a user",
+        auth: true,
+        successStatus: 204,
+        successDescription: "User deleted",
+      },
+    ],
+    behaviors: [],
+    ...overrides,
+  };
+}
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "mock-gen-test-"));
+});
+
+afterEach(async () => {
+  await fs.remove(tmpDir);
+});
+
+// ─── generateMockAssets ──────────────────────────────────────────────────────
+
+describe("generateMockAssets", () => {
+  it("generates server.js and README.md by default", async () => {
+    const dsl = makeDsl();
+    const result = await generateMockAssets(dsl, tmpDir);
+
+    expect(result.files.length).toBe(2);
+    expect(result.files[0].path).toBe("mock/server.js");
+    expect(result.files[1].path).toBe("mock/README.md");
+
+    // server.js should exist on disk
+    const serverContent = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    expect(serverContent).toContain("express");
+    expect(serverContent).toContain("User CRUD");
+    expect(serverContent).toContain("/api/users");
+  });
+
+  it("server.js includes auth middleware when endpoints have auth", async () => {
+    const dsl = makeDsl();
+    const result = await generateMockAssets(dsl, tmpDir);
+    const serverContent = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+
+    expect(serverContent).toContain("requireAuth");
+    expect(serverContent).toContain("Authorization");
+  });
+
+  it("server.js omits auth middleware when no endpoints need auth", async () => {
+    const dsl = makeDsl({
+      endpoints: [
+        {
+          id: "EP-001",
+          method: "GET",
+          path: "/api/health",
+          description: "Health check",
+          auth: false,
+          successStatus: 200,
+          successDescription: "OK",
+        },
+      ],
+    });
+    await generateMockAssets(dsl, tmpDir);
+    const serverContent = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    expect(serverContent).not.toContain("requireAuth");
+  });
+
+  it("generates DELETE 204 endpoints with sendStatus", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir);
+    const serverContent = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    expect(serverContent).toContain("sendStatus(204)");
+  });
+
+  it("includes error simulation comment for endpoints with errors", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir);
+    const serverContent = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    expect(serverContent).toContain("simulate_error=INVALID_INPUT");
+  });
+
+  it("uses custom port", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir, { port: 4000 });
+    const serverContent = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    expect(serverContent).toContain("4000");
+  });
+
+  it("uses custom output directory", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir, { outputDir: "mocks" });
+    expect(await fs.pathExists(path.join(tmpDir, "mocks/server.js"))).toBe(true);
+  });
+
+  it("generates list endpoint fixtures with data array for GET list endpoints", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir);
+    const serverContent = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    // EP-001 is "List all users" — should produce paginated fixture
+    expect(serverContent).toContain('"total"');
+    expect(serverContent).toContain('"page"');
+    expect(serverContent).toContain('"pageSize"');
+  });
+
+  it("README.md contains endpoint table", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir);
+    const readme = await fs.readFile(path.join(tmpDir, "mock/README.md"), "utf-8");
+    expect(readme).toContain("GET");
+    expect(readme).toContain("`/api/users`");
+    expect(readme).toContain("DELETE");
+  });
+
+  // ─── MSW option ─────────────────────────────────────────────────────────
+
+  it("generates MSW handlers when msw option is true", async () => {
+    const dsl = makeDsl();
+    const result = await generateMockAssets(dsl, tmpDir, { msw: true });
+
+    const handlerFile = result.files.find((f) => f.path.includes("handlers.ts"));
+    expect(handlerFile).toBeTruthy();
+
+    const handlersContent = await fs.readFile(
+      path.join(tmpDir, "src/mocks/handlers.ts"),
+      "utf-8"
+    );
+    expect(handlersContent).toContain("import { http, HttpResponse }");
+    expect(handlersContent).toContain("http.get");
+    expect(handlersContent).toContain("http.post");
+    expect(handlersContent).toContain("http.delete");
+  });
+
+  it("generates MSW browser setup file", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir, { msw: true });
+    const browserContent = await fs.readFile(
+      path.join(tmpDir, "src/mocks/browser.ts"),
+      "utf-8"
+    );
+    expect(browserContent).toContain("setupWorker");
+  });
+
+  // ─── Proxy option ───────────────────────────────────────────────────────
+
+  it("generates proxy config when proxy option is true", async () => {
+    const dsl = makeDsl();
+    const result = await generateMockAssets(dsl, tmpDir, { proxy: true });
+    const proxyFile = result.files.find((f) => f.path.includes("proxy"));
+    expect(proxyFile).toBeTruthy();
+  });
+
+  it("detects Vite framework for proxy config", async () => {
+    // Create a vite.config.ts to trigger vite detection
+    await fs.writeFile(path.join(tmpDir, "vite.config.ts"), "export default {}", "utf-8");
+    const dsl = makeDsl();
+    const result = await generateMockAssets(dsl, tmpDir, { proxy: true });
+    const proxyFile = result.files.find((f) => f.path.includes("proxy"));
+    expect(proxyFile?.path).toContain("vite");
+  });
+
+  it("detects Next.js framework for proxy config", async () => {
+    await fs.writeFile(path.join(tmpDir, "next.config.js"), "module.exports = {}", "utf-8");
+    const dsl = makeDsl();
+    const result = await generateMockAssets(dsl, tmpDir, { proxy: true });
+    const proxyFile = result.files.find((f) => f.path.includes("proxy"));
+    expect(proxyFile?.path).toContain("next");
+  });
+
+  it("detects CRA framework via react-scripts", async () => {
+    await fs.writeJson(path.join(tmpDir, "package.json"), {
+      dependencies: { "react-scripts": "5.0.0" },
+    });
+    const dsl = makeDsl();
+    const result = await generateMockAssets(dsl, tmpDir, { proxy: true });
+    const proxyFile = result.files.find((f) => f.path.includes("proxy"));
+    expect(proxyFile?.path).toContain("cra");
+  });
+});
+
+// ─── Fixture value heuristics ────────────────────────────────────────────────
+// We test these indirectly by checking generated server.js content
+
+describe("fixture heuristics", () => {
+  it("generates email fixtures for email fields", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir);
+    const content = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    expect(content).toContain("user@example.com");
+  });
+
+  it("generates boolean fixtures for boolean fields", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir);
+    const content = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    // isActive: Boolean → true
+    expect(content).toContain('"isActive": true');
+  });
+
+  it("generates date fixtures for DateTime fields", async () => {
+    const dsl = makeDsl();
+    await generateMockAssets(dsl, tmpDir);
+    const content = await fs.readFile(path.join(tmpDir, "mock/server.js"), "utf-8");
+    expect(content).toContain("2024-01-15T10:30:00.000Z");
+  });
+});
+
+// ─── findLatestDslFile ───────────────────────────────────────────────────────
+
+describe("findLatestDslFile", () => {
+  it("returns null when .ai-spec directory does not exist", async () => {
+    const result = await findLatestDslFile(tmpDir);
+    expect(result).toBeNull();
+  });
+
+  it("returns null when no .dsl.json files exist", async () => {
+    await fs.ensureDir(path.join(tmpDir, ".ai-spec"));
+    await fs.writeFile(path.join(tmpDir, ".ai-spec/readme.md"), "hi");
+    const result = await findLatestDslFile(tmpDir);
+    expect(result).toBeNull();
+  });
+
+  it("returns the most recently modified .dsl.json file", async () => {
+    const specDir = path.join(tmpDir, ".ai-spec");
+    await fs.ensureDir(specDir);
+
+    // Create two DSL files with different mtimes
+    const older = path.join(specDir, "old.dsl.json");
+    const newer = path.join(specDir, "new.dsl.json");
+    await fs.writeJson(older, { version: "1.0" });
+
+    // Small delay to ensure different mtime
+    await new Promise((r) => setTimeout(r, 50));
+    await fs.writeJson(newer, { version: "1.0" });
+
+    const result = await findLatestDslFile(tmpDir);
+    expect(result).toBe(newer);
+  });
+
+  it("scans nested directories", async () => {
+    const nestedDir = path.join(tmpDir, ".ai-spec", "v1");
+    await fs.ensureDir(nestedDir);
+    await fs.writeJson(path.join(nestedDir, "feature.dsl.json"), { version: "1.0" });
+
+    const result = await findLatestDslFile(tmpDir);
+    expect(result).toBe(path.join(nestedDir, "feature.dsl.json"));
+  });
+});
+
+// ─── applyMockProxy / restoreMockProxy ───────────────────────────────────────
+
+describe("applyMockProxy / restoreMockProxy", () => {
+  it("applies Vite proxy: writes mock config + adds dev:mock script", async () => {
+    await fs.writeFile(path.join(tmpDir, "vite.config.ts"), "export default {}", "utf-8");
+    await fs.writeJson(path.join(tmpDir, "package.json"), { scripts: { dev: "vite" } });
+
+    const endpoints: ApiEndpoint[] = [
+      {
+        id: "EP-001", method: "GET", path: "/api/users", description: "List",
+        auth: false, successStatus: 200, successDescription: "OK",
+      },
+    ];
+    const result = await applyMockProxy(tmpDir, 3001, endpoints);
+
+    expect(result.framework).toBe("vite");
+    expect(result.applied).toBe(true);
+    expect(result.devCommand).toBe("npm run dev:mock");
+
+    // Check that vite mock config was created
+    expect(await fs.pathExists(path.join(tmpDir, "vite.config.ai-spec-mock.ts"))).toBe(true);
+
+    // Check that package.json has dev:mock script
+    const pkg = await fs.readJson(path.join(tmpDir, "package.json"));
+    expect(pkg.scripts["dev:mock"]).toContain("vite.config.ai-spec-mock.ts");
+  });
+
+  it("applies CRA proxy: patches package.json proxy field", async () => {
+    await fs.writeJson(path.join(tmpDir, "package.json"), {
+      dependencies: { "react-scripts": "5.0.0" },
+    });
+
+    const result = await applyMockProxy(tmpDir, 3001);
+
+    expect(result.framework).toBe("cra");
+    expect(result.applied).toBe(true);
+
+    const pkg = await fs.readJson(path.join(tmpDir, "package.json"));
+    expect(pkg.proxy).toBe("http://localhost:3001");
+  });
+
+  it("restoreMockProxy undoes Vite changes", async () => {
+    await fs.writeFile(path.join(tmpDir, "vite.config.ts"), "export default {}", "utf-8");
+    await fs.writeJson(path.join(tmpDir, "package.json"), { scripts: { dev: "vite" } });
+
+    await applyMockProxy(tmpDir, 3001);
+    const restoreResult = await restoreMockProxy(tmpDir);
+
+    expect(restoreResult.restored).toBe(true);
+    expect(await fs.pathExists(path.join(tmpDir, "vite.config.ai-spec-mock.ts"))).toBe(false);
+
+    const pkg = await fs.readJson(path.join(tmpDir, "package.json"));
+    expect(pkg.scripts["dev:mock"]).toBeUndefined();
+  });
+
+  it("restoreMockProxy undoes CRA proxy change", async () => {
+    await fs.writeJson(path.join(tmpDir, "package.json"), {
+      dependencies: { "react-scripts": "5.0.0" },
+    });
+
+    await applyMockProxy(tmpDir, 3001);
+    await restoreMockProxy(tmpDir);
+
+    const pkg = await fs.readJson(path.join(tmpDir, "package.json"));
+    expect(pkg.proxy).toBeUndefined();
+  });
+
+  it("restoreMockProxy returns restored:false when no lock file", async () => {
+    const result = await restoreMockProxy(tmpDir);
+    expect(result.restored).toBe(false);
+    expect(result.note).toContain("No lock file");
+  });
+
+  it("returns note for Next.js (no auto-patch)", async () => {
+    await fs.writeFile(path.join(tmpDir, "next.config.js"), "module.exports = {}", "utf-8");
+    const result = await applyMockProxy(tmpDir, 3001);
+    expect(result.framework).toBe("next");
+    expect(result.applied).toBe(false);
+    expect(result.note).toContain("next.config.js");
+  });
+});