ai-spec-dev 0.31.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,9 @@
   },
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch"
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "ai",
@@ -41,6 +43,7 @@
     "glob": "^13.0.6",
     "ts-node": "^10.9.2",
     "tsup": "^8.4.0",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.0"
   }
 }

package/tests/dsl-extractor.test.ts

@@ -0,0 +1,264 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  dslFilePath,
+  buildDslContextSection,
+  DslExtractor,
+} from "../core/dsl-extractor";
+import type { SpecDSL } from "../core/dsl-types";
+import type { AIProvider } from "../core/spec-generator";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const VALID_DSL: SpecDSL = {
+  version: "1.0",
+  feature: {
+    id: "user-login",
+    title: "User Login",
+    description: "Authenticate users with email and password",
+  },
+  models: [
+    {
+      name: "User",
+      fields: [
+        { name: "id", type: "String", required: true },
+        { name: "email", type: "String", required: true, unique: true },
+      ],
+      relations: ["has many Session"],
+    },
+  ],
+  endpoints: [
+    {
+      id: "EP-001",
+      method: "POST",
+      path: "/api/auth/login",
+      description: "Authenticate and return JWT",
+      auth: false,
+      successStatus: 200,
+      successDescription: "JWT token",
+      request: { body: { email: "string", password: "string" } },
+      errors: [
+        { status: 401, code: "INVALID_CREDENTIALS", description: "Bad password" },
+      ],
+    },
+  ],
+  behaviors: [
+    {
+      id: "BHV-001",
+      description: "Rate-limit login to 5 attempts per minute",
+      trigger: "POST /api/auth/login",
+      constraints: ["block after 5 failures"],
+    },
+  ],
+};
+
+function makeProvider(response: string): AIProvider {
+  return { generate: vi.fn().mockResolvedValue(response) };
+}
+
+// ─── dslFilePath ──────────────────────────────────────────────────────────────
+
+describe("dslFilePath", () => {
+  it("replaces .md extension with .dsl.json", () => {
+    expect(dslFilePath("/specs/feature-login-v1.md")).toBe("/specs/feature-login-v1.dsl.json");
+  });
+
+  it("works with relative paths", () => {
+    expect(dslFilePath("specs/my-feature-v2.md")).toBe("specs/my-feature-v2.dsl.json");
+  });
+
+  it("handles files in the current directory", () => {
+    expect(dslFilePath("feature.md")).toBe("feature.dsl.json");
+  });
+
+  it("preserves directory structure", () => {
+    const result = dslFilePath("/a/b/c/feature-v3.md");
+    expect(result).toContain("/a/b/c/");
+    expect(result.endsWith(".dsl.json")).toBe(true);
+  });
+});
+
+// ─── buildDslContextSection ───────────────────────────────────────────────────
+
+describe("buildDslContextSection", () => {
+  it("includes the section header and footer", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("=== Feature DSL");
+    expect(result).toContain("=== End of DSL ===");
+  });
+
+  it("lists model names and fields", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("User:");
+    expect(result).toContain("email: String");
+  });
+
+  it("marks required fields", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("required");
+  });
+
+  it("marks unique fields", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("unique");
+  });
+
+  it("includes model relations", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("has many Session");
+  });
+
+  it("includes endpoint method, path, and auth", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("POST");
+    expect(result).toContain("/api/auth/login");
+    expect(result).toContain("auth: false");
+  });
+
+  it("includes endpoint error codes", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("INVALID_CREDENTIALS");
+  });
+
+  it("includes request body fields", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("email");
+    expect(result).toContain("password");
+  });
+
+  it("includes behaviors with trigger and constraints", () => {
+    const result = buildDslContextSection(VALID_DSL);
+    expect(result).toContain("Rate-limit login");
+    expect(result).toContain("POST /api/auth/login");
+    expect(result).toContain("block after 5 failures");
+  });
+
+  it("handles empty models array gracefully", () => {
+    const dsl: SpecDSL = { ...VALID_DSL, models: [] };
+    const result = buildDslContextSection(dsl);
+    expect(result).not.toContain("-- Data Models --");
+  });
+
+  it("handles empty endpoints array gracefully", () => {
+    const dsl: SpecDSL = { ...VALID_DSL, endpoints: [] };
+    const result = buildDslContextSection(dsl);
+    expect(result).not.toContain("-- API Endpoints --");
+  });
+
+  it("handles empty behaviors array gracefully", () => {
+    const dsl: SpecDSL = { ...VALID_DSL, behaviors: [] };
+    const result = buildDslContextSection(dsl);
+    expect(result).not.toContain("-- Business Behaviors --");
+  });
+
+  it("includes UI components section when components are present", () => {
+    const dsl: SpecDSL = {
+      ...VALID_DSL,
+      components: [
+        {
+          id: "CMP-001",
+          name: "LoginForm",
+          description: "Login form component",
+          props: [{ name: "onSuccess", type: "() => void", required: true }],
+          events: [{ name: "onSubmit", payload: "FormData" }],
+          state: { isLoading: "boolean" },
+          apiCalls: ["EP-001"],
+        },
+      ],
+    };
+    const result = buildDslContextSection(dsl);
+    expect(result).toContain("-- UI Components --");
+    expect(result).toContain("LoginForm");
+    expect(result).toContain("onSuccess");
+    expect(result).toContain("onSubmit");
+    expect(result).toContain("isLoading:boolean");
+    expect(result).toContain("EP-001");
+  });
+});
+
+// ─── DslExtractor.extract — success path ─────────────────────────────────────
+
+describe("DslExtractor.extract — success", () => {
+  it("returns a valid SpecDSL when AI output is bare JSON", async () => {
+    const provider = makeProvider(JSON.stringify(VALID_DSL));
+    const extractor = new DslExtractor(provider);
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const result = await extractor.extract("spec content", { auto: true });
+    consoleSpy.mockRestore();
+    expect(result).not.toBeNull();
+    expect(result?.feature.id).toBe("user-login");
+  });
+
+  it("returns a valid SpecDSL when AI wraps output in a JSON fence", async () => {
+    const fenced = "```json\n" + JSON.stringify(VALID_DSL) + "\n```";
+    const provider = makeProvider(fenced);
+    const extractor = new DslExtractor(provider);
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const result = await extractor.extract("spec content", { auto: true });
+    consoleSpy.mockRestore();
+    expect(result?.feature.title).toBe("User Login");
+  });
+
+  it("sanitizes empty error entries before validation", async () => {
+    const dslWithEmptyErrors = {
+      ...VALID_DSL,
+      endpoints: [
+        {
+          ...VALID_DSL.endpoints[0],
+          errors: [
+            { status: 400, code: "", description: "" }, // invalid — should be stripped
+            { status: 401, code: "INVALID_CREDENTIALS", description: "Bad password" },
+          ],
+        },
+      ],
+    };
+    const provider = makeProvider(JSON.stringify(dslWithEmptyErrors));
+    const extractor = new DslExtractor(provider);
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const result = await extractor.extract("spec content", { auto: true });
+    consoleSpy.mockRestore();
+    expect(result).not.toBeNull();
+    // The empty error entry should have been stripped
+    expect(result?.endpoints[0].errors).toHaveLength(1);
+    expect(result?.endpoints[0].errors?.[0].code).toBe("INVALID_CREDENTIALS");
+  });
+});
+
+// ─── DslExtractor.extract — failure paths ────────────────────────────────────
+
+describe("DslExtractor.extract — failure / auto mode", () => {
+  it("returns null in auto mode when AI returns invalid JSON", async () => {
+    const provider = makeProvider("Not JSON at all");
+    const extractor = new DslExtractor(provider);
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const result = await extractor.extract("spec", { auto: true });
+    consoleSpy.mockRestore();
+    expect(result).toBeNull();
+  });
+
+  it("returns null in auto mode when provider throws", async () => {
+    const provider: AIProvider = { generate: vi.fn().mockRejectedValue(new Error("network")) };
+    const extractor = new DslExtractor(provider);
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const result = await extractor.extract("spec", { auto: true });
+    consoleSpy.mockRestore();
+    expect(result).toBeNull();
+  });
+
+  it("retries when first attempt produces invalid DSL (missing required field)", async () => {
+    // First response: invalid DSL (missing feature.description)
+    const badDsl = { ...VALID_DSL, feature: { id: "x", title: "X", description: "" } };
+    // Second response: valid DSL
+    const provider: AIProvider = {
+      generate: vi.fn()
+        .mockResolvedValueOnce(JSON.stringify(badDsl))
+        .mockResolvedValueOnce(JSON.stringify(VALID_DSL)),
+    };
+    const extractor = new DslExtractor(provider);
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const result = await extractor.extract("spec", { auto: true });
+    consoleSpy.mockRestore();
+    // Should have retried — provider called at least twice
+    expect((provider.generate as ReturnType<typeof vi.fn>).mock.calls.length).toBeGreaterThanOrEqual(2);
+    expect(result?.feature.id).toBe("user-login");
+  });
+});

package/tests/dsl-feedback.test.ts

@@ -0,0 +1,266 @@
+import { describe, it, expect } from "vitest";
+import {
+  assessDslRichness,
+  extractStructuralFindings,
+  buildDslGapRefinementPrompt,
+  buildStructuralAmendmentPrompt,
+} from "../core/dsl-feedback";
+import type { SpecDSL } from "../core/dsl-types";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+function makeEndpoint(overrides: Partial<SpecDSL["endpoints"][0]> = {}): SpecDSL["endpoints"][0] {
+  return {
+    id: "EP-001",
+    method: "GET",
+    path: "/api/items",
+    description: "Returns a paginated list of items with filtering support",
+    auth: true,
+    successStatus: 200,
+    successDescription: "List of items returned",
+    errors: [{ status: 401, code: "UNAUTHORIZED", description: "Missing auth token" }],
+    ...overrides,
+  };
+}
+
+function makeModel(overrides: Partial<SpecDSL["models"][0]> = {}): SpecDSL["models"][0] {
+  return {
+    name: "Item",
+    description: "An inventory item",
+    fields: [
+      { name: "id", type: "String", required: true },
+      { name: "name", type: "String", required: true },
+      { name: "price", type: "Float", required: true },
+    ],
+    ...overrides,
+  };
+}
+
+function makeDsl(overrides: Partial<SpecDSL> = {}): SpecDSL {
+  return {
+    version: "1.0",
+    feature: { id: "items", title: "Items", description: "Item management" },
+    models: [makeModel()],
+    endpoints: [makeEndpoint()],
+    behaviors: [],
+    ...overrides,
+  };
+}
+
+// ─── assessDslRichness ────────────────────────────────────────────────────────
+
+describe("assessDslRichness", () => {
+  it("returns no_models_no_endpoints when DSL is completely empty", () => {
+    const dsl = makeDsl({ endpoints: [], models: [] });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps).toHaveLength(1);
+    expect(gaps[0].code).toBe("no_models_no_endpoints");
+  });
+
+  it("returns early with only no_models_no_endpoints when empty (no further checks)", () => {
+    const dsl = makeDsl({ endpoints: [], models: [] });
+    const gaps = assessDslRichness(dsl);
+    // Should not also report sparse_model / missing_errors when empty
+    expect(gaps.every((g) => g.code === "no_models_no_endpoints")).toBe(true);
+  });
+
+  it("returns no gaps for a well-formed DSL", () => {
+    const dsl = makeDsl();
+    const gaps = assessDslRichness(dsl);
+    expect(gaps).toHaveLength(0);
+  });
+
+  it("detects generic_endpoint_desc when description is too short", () => {
+    const dsl = makeDsl({
+      endpoints: [makeEndpoint({ description: "Get items" })], // < 15 chars
+    });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "generic_endpoint_desc")).toBe(true);
+  });
+
+  it("detects generic_endpoint_desc when description starts with 'handles'", () => {
+    const dsl = makeDsl({
+      endpoints: [makeEndpoint({ description: "Handles the item request and processing" })],
+    });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "generic_endpoint_desc")).toBe(true);
+  });
+
+  it("detects generic_endpoint_desc for Chinese generic verbs (管理)", () => {
+    const dsl = makeDsl({
+      endpoints: [makeEndpoint({ description: "管理商品列表的接口调用和返回" })],
+    });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "generic_endpoint_desc")).toBe(true);
+  });
+
+  it("does NOT flag a sufficiently descriptive endpoint", () => {
+    const dsl = makeDsl({
+      endpoints: [makeEndpoint({ description: "Returns paginated list of active inventory items filtered by category" })],
+    });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "generic_endpoint_desc")).toBe(false);
+  });
+
+  it("detects missing_errors when all endpoints lack error definitions (≥2 endpoints)", () => {
+    const ep = makeEndpoint({ errors: undefined });
+    const dsl = makeDsl({ endpoints: [ep, { ...ep, id: "EP-002", path: "/api/items/:id" }] });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "missing_errors")).toBe(true);
+  });
+
+  it("does NOT flag missing_errors when there is only one endpoint", () => {
+    const dsl = makeDsl({
+      endpoints: [makeEndpoint({ errors: undefined })],
+    });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "missing_errors")).toBe(false);
+  });
+
+  it("does NOT flag missing_errors when at least one endpoint has errors", () => {
+    const withErrors = makeEndpoint();
+    const withoutErrors = makeEndpoint({ id: "EP-002", path: "/api/items/:id", errors: undefined });
+    const dsl = makeDsl({ endpoints: [withErrors, withoutErrors] });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "missing_errors")).toBe(false);
+  });
+
+  it("detects sparse_model when model has fewer than 2 fields", () => {
+    const dsl = makeDsl({
+      models: [makeModel({ fields: [{ name: "id", type: "String", required: true }] })],
+    });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "sparse_model")).toBe(true);
+  });
+
+  it("detects sparse_model when model has zero fields", () => {
+    const dsl = makeDsl({ models: [makeModel({ fields: [] })] });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "sparse_model")).toBe(true);
+  });
+
+  it("does NOT flag sparse_model when model has 2 or more fields", () => {
+    const dsl = makeDsl({
+      models: [makeModel({
+        fields: [
+          { name: "id", type: "String", required: true },
+          { name: "name", type: "String", required: true },
+        ],
+      })],
+    });
+    const gaps = assessDslRichness(dsl);
+    expect(gaps.some((g) => g.code === "sparse_model")).toBe(false);
+  });
+
+  it("can detect multiple gaps simultaneously", () => {
+    const dsl = makeDsl({
+      endpoints: [makeEndpoint({ description: "处理", errors: undefined }), makeEndpoint({ id: "EP-002", path: "/b", errors: undefined })],
+      models: [makeModel({ fields: [{ name: "id", type: "String", required: true }] })],
+    });
+    const codes = assessDslRichness(dsl).map((g) => g.code);
+    expect(codes).toContain("generic_endpoint_desc");
+    expect(codes).toContain("missing_errors");
+    expect(codes).toContain("sparse_model");
+  });
+
+  it("gap hint is a non-empty string", () => {
+    const dsl = makeDsl({ endpoints: [], models: [] });
+    const gaps = assessDslRichness(dsl);
+    for (const gap of gaps) {
+      expect(typeof gap.hint).toBe("string");
+      expect(gap.hint.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+// ─── extractStructuralFindings ────────────────────────────────────────────────
+
+describe("extractStructuralFindings", () => {
+  const SEP = "─".repeat(52);
+
+  it("returns empty array for empty review text", () => {
+    expect(extractStructuralFindings("")).toHaveLength(0);
+  });
+
+  it("returns empty array when Pass 1 scores ≥ 8", () => {
+    const reviewText = `Architecture looks solid.\nScore: 9/10\n${SEP}\nimpl stuff`;
+    expect(extractStructuralFindings(reviewText)).toHaveLength(0);
+  });
+
+  it("detects auth_design finding from Chinese pattern", () => {
+    const pass1 = `The endpoint /api/users/create 缺少认证，应该加上 JWT 验证。\nScore: 5/10`;
+    const reviewText = `${pass1}\n${SEP}\nimpl notes`;
+    const findings = extractStructuralFindings(reviewText);
+    expect(findings.some((f) => f.category === "auth_design")).toBe(true);
+  });
+
+  it("detects auth_design finding from English pattern", () => {
+    const pass1 = `The POST /orders endpoint is missing auth — it should require authentication.\nScore: 6/10`;
+    const reviewText = `${pass1}\n${SEP}\nimpl notes`;
+    const findings = extractStructuralFindings(reviewText);
+    expect(findings.some((f) => f.category === "auth_design")).toBe(true);
+  });
+
+  it("detects api_contract finding", () => {
+    const pass1 = `接口设计问题：response 缺少 pagination 字段。\nScore: 6/10`;
+    const reviewText = `${pass1}\n${SEP}\nimpl notes`;
+    const findings = extractStructuralFindings(reviewText);
+    expect(findings.some((f) => f.category === "api_contract")).toBe(true);
+  });
+
+  it("detects model_design finding", () => {
+    const pass1 = `模型缺少字段：Order model 没有 status 和 total 字段。\nScore: 5/10`;
+    const reviewText = `${pass1}\n${SEP}\nimpl notes`;
+    const findings = extractStructuralFindings(reviewText);
+    expect(findings.some((f) => f.category === "model_design")).toBe(true);
+  });
+
+  it("detects layer_violation finding", () => {
+    const pass1 = `分层问题：business logic 直接写在 Controller 里，违反了 Service 层设计。\nScore: 4/10`;
+    const reviewText = `${pass1}\n${SEP}\nimpl notes`;
+    const findings = extractStructuralFindings(reviewText);
+    expect(findings.some((f) => f.category === "layer_violation")).toBe(true);
+  });
+
+  it("returns empty when review text has no structural keywords but low score", () => {
+    const pass1 = `Code is a bit messy but structurally OK. Some variable names are unclear.\nScore: 6/10`;
+    const reviewText = `${pass1}\n${SEP}\nimpl notes`;
+    const findings = extractStructuralFindings(reviewText);
+    expect(findings).toHaveLength(0);
+  });
+
+  it("each finding has a non-empty description", () => {
+    const pass1 = `缺少认证在 /api/admin endpoint 上。模型缺少字段 role。\nScore: 5/10`;
+    const reviewText = `${pass1}\n${SEP}\nimpl`;
+    const findings = extractStructuralFindings(reviewText);
+    for (const f of findings) {
+      expect(typeof f.description).toBe("string");
+      expect(f.description.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+// ─── Prompt builders (smoke tests) ────────────────────────────────────────────
+
+describe("buildDslGapRefinementPrompt", () => {
+  it("includes each gap hint in the output prompt", () => {
+    const dsl = makeDsl({ endpoints: [], models: [] });
+    const gaps = assessDslRichness(dsl);
+    const prompt = buildDslGapRefinementPrompt("# My Spec", gaps);
+    for (const gap of gaps) {
+      expect(prompt).toContain(gap.hint.slice(0, 30));
+    }
+    expect(prompt).toContain("# My Spec");
+  });
+});
+
+describe("buildStructuralAmendmentPrompt", () => {
+  it("includes each finding description in the output prompt", () => {
+    const findings = [
+      { category: "auth_design" as const, description: "POST /users is missing authentication" },
+    ];
+    const prompt = buildStructuralAmendmentPrompt("# My Spec", findings);
+    expect(prompt).toContain("POST /users is missing authentication");
+    expect(prompt).toContain("# My Spec");
+  });
+});