ai-spec-dev 0.38.0 → 0.42.0

package/core/spec-updater.ts

@@ -15,6 +15,7 @@ import {
   buildAffectedFilesPrompt,
 } from "../prompts/update.prompt";
 import { getCodeGenSystemPrompt } from "../prompts/codegen.prompt";
+import { parseJsonFromAiOutput } from "./safe-json";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -44,27 +45,10 @@ export interface SpecUpdaterOptions {
   repoType?: string;
 }
 
-// ─── JSON parser (same pattern as requirement-decomposer.ts) ─────────────────
-
-function parseJsonFromOutput(raw: string): unknown {
-  const trimmed = raw.trim();
-  if (trimmed.startsWith("{")) return JSON.parse(trimmed);
-  const fenceStart = trimmed.indexOf("```");
-  if (fenceStart !== -1) {
-    const afterFence = trimmed.slice(fenceStart + 3);
-    const newlinePos = afterFence.indexOf("\n");
-    const jsonStart = newlinePos !== -1 ? newlinePos + 1 : 0;
-    const fenceEnd = afterFence.lastIndexOf("```");
-    if (fenceEnd > jsonStart) return JSON.parse(afterFence.slice(jsonStart, fenceEnd).trim());
-  }
-  const objStart = trimmed.indexOf("{");
-  const arrStart = trimmed.indexOf("[");
-  const start = objStart !== -1 && (arrStart === -1 || objStart < arrStart) ? objStart : arrStart;
-  const isObj = start === objStart && objStart !== -1;
-  const end = isObj ? trimmed.lastIndexOf("}") : trimmed.lastIndexOf("]");
-  if (start !== -1 && end > start) return JSON.parse(trimmed.slice(start, end + 1));
-  throw new SyntaxError("No JSON found in output");
-}
+// ─── JSON Parser ─────────────────────────────────────────────────────────────
+
+// Uses shared parseJsonFromAiOutput from safe-json.ts
+const parseJsonFromOutput = parseJsonFromAiOutput;
 
 function parseAffectedFiles(raw: string): AffectedFile[] {
   try {

package/core/token-budget.ts

@@ -0,0 +1,124 @@
+/**
+ * token-budget.ts — Lightweight token estimation and priority-based context assembly.
+ *
+ * Prevents silent context window overflow by estimating tokens and
+ * trimming lower-priority sections when the budget is exceeded.
+ */
+
+import chalk from "chalk";
+
+// ─── Token Estimation ────────────────────────────────────────────────────────
+
+/** CJK character range. */
+const CJK_RANGE = /[\u4e00-\u9fff\u3400-\u4dbf\u3000-\u303f\uff00-\uffef]/g;
+
+/**
+ * Estimate token count for a string.
+ * CJK characters ≈ 1 token each; English/code ≈ 1 token per 4 characters.
+ * This is deliberately conservative (over-estimates slightly) to avoid
+ * exceeding the actual context window.
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  const cjkCount = (text.match(CJK_RANGE) ?? []).length;
+  const nonCjkLength = text.length - cjkCount;
+  return Math.ceil(cjkCount + nonCjkLength / 4);
+}
+
+// ─── Budget Assembly ────────────────────────────────────────────────────────
+
+/**
+ * A named section of context with a priority level.
+ * Lower priority number = higher importance (trimmed last).
+ */
+export interface BudgetSection {
+  /** Section name for logging. */
+  name: string;
+  /** The actual text content. */
+  content: string;
+  /** Priority: 1 = highest (never trim), 5 = lowest (trim first). */
+  priority: number;
+}
+
+export interface BudgetResult {
+  /** The assembled prompt text (all included sections concatenated). */
+  assembledPrompt: string;
+  /** Total estimated tokens in the assembled prompt. */
+  totalTokens: number;
+  /** Names of sections that were trimmed or dropped. */
+  trimmedSections: string[];
+}
+
+/**
+ * Assemble context sections within a token budget.
+ *
+ * Sections are added in priority order (P1 first). When the budget is
+ * exceeded, lower-priority sections are truncated or dropped entirely.
+ *
+ * @param sections - Context sections to assemble.
+ * @param maxTokens - Maximum token budget.
+ */
+export function assembleSections(
+  sections: BudgetSection[],
+  maxTokens: number
+): BudgetResult {
+  // Sort by priority (ascending = most important first)
+  const sorted = [...sections].sort((a, b) => a.priority - b.priority);
+
+  const included: string[] = [];
+  const trimmedSections: string[] = [];
+  let usedTokens = 0;
+
+  for (const section of sorted) {
+    if (!section.content) continue;
+
+    const sectionTokens = estimateTokens(section.content);
+
+    if (usedTokens + sectionTokens <= maxTokens) {
+      // Fits entirely
+      included.push(section.content);
+      usedTokens += sectionTokens;
+    } else {
+      const remainingBudget = maxTokens - usedTokens;
+      if (remainingBudget <= 100) {
+        // Not enough room even for a truncated version
+        trimmedSections.push(section.name);
+        continue;
+      }
+
+      // Truncate to fit remaining budget (approximate: 4 chars per token for safety)
+      const charBudget = Math.floor(remainingBudget * 3);
+      const truncated = section.content.slice(0, charBudget);
+      included.push(truncated + `\n\n... [${section.name} truncated — context budget reached]`);
+      trimmedSections.push(section.name);
+      usedTokens = maxTokens; // budget exhausted
+    }
+  }
+
+  const assembledPrompt = included.join("\n\n");
+
+  if (trimmedSections.length > 0) {
+    console.log(
+      chalk.yellow(
+        `  ⚠ Token budget: ${usedTokens}/${maxTokens} tokens. Trimmed: ${trimmedSections.join(", ")}`
+      )
+    );
+  }
+
+  return { assembledPrompt, totalTokens: usedTokens, trimmedSections };
+}
+
+// ─── Default Budgets ─────────────────────────────────────────────────────────
+
+/** Default context token budgets per provider. */
+export const DEFAULT_TOKEN_BUDGETS: Record<string, number> = {
+  gemini: 900_000,
+  claude: 180_000,
+  openai: 120_000,
+  deepseek: 60_000,
+  default: 100_000,
+};
+
+export function getDefaultBudget(providerName: string): number {
+  return DEFAULT_TOKEN_BUDGETS[providerName] ?? DEFAULT_TOKEN_BUDGETS.default;
+}

package/core/vcr.ts

@@ -141,13 +141,14 @@ export class VcrRecordingProvider implements AIProvider {
  */
 export class VcrReplayProvider implements AIProvider {
   private index = 0;
+  private _mismatches: Array<{ index: number; expected: string; actual: string }> = [];
 
   constructor(private readonly recording: VcrRecording) {}
 
   get providerName() { return "vcr-replay"; }
   get modelName()    { return this.recording.runId; }
 
-  async generate(_prompt: string, _systemInstruction?: string): Promise<string> {
+  async generate(prompt: string, systemInstruction?: string): Promise<string> {
     const entry = this.recording.entries[this.index++];
     if (!entry) {
       throw new Error(
@@ -155,11 +156,29 @@ export class VcrReplayProvider implements AIProvider {
         `responses have been consumed. The pipeline made more AI calls than the recording has.`
       );
     }
+
+    // Validate prompt hash to detect pipeline drift
+    const actualHash = createHash("sha256")
+      .update(prompt + "\x00" + (systemInstruction ?? ""))
+      .digest("hex")
+      .slice(0, 8);
+    if (actualHash !== entry.callHash) {
+      this._mismatches.push({
+        index: entry.index,
+        expected: entry.callHash,
+        actual: actualHash,
+      });
+    }
+
     return entry.response;
   }
 
   get remaining() { return this.recording.entries.length - this.index; }
   get consumed()  { return this.index; }
+
+  /** Returns prompt hash mismatches detected during replay. */
+  get mismatches() { return this._mismatches; }
+  get hasMismatches() { return this._mismatches.length > 0; }
 }
 
 // ─── Loader helpers ───────────────────────────────────────────────────────────

package/demo-backend/.ai-spec-constitution.md

@@ -0,0 +1,65 @@
+# Project Constitution
+
+## 1. 架构规则 (Architecture Rules)
+- **分层架构**：项目采用三层架构 `routes → controllers → services → database`。
+- **禁止跨层调用**：
+  - `routes` 层仅负责定义路由和中间件，不能包含业务逻辑。
+  - `controllers` 层负责接收请求、调用 `services` 和返回响应，不能直接操作数据库。
+  - `services` 层封装核心业务逻辑，是唯一允许直接调用数据访问层（如 Prisma）的层级。
+- **模块组织**：功能模块按领域划分，每个模块包含独立的 `routes.ts`, `controller.ts`, `service.ts` 文件。
+
+## 2. 命名规范 (Naming Conventions)
+- **文件命名**：使用 `kebab-case`（如 `user-profile.controller.ts`）。
+- **变量/函数**：使用 `camelCase`（如 `getUserById`）。
+- **类/接口**：使用 `PascalCase`（如 `UserService`）。
+- **路由路径**：使用 `kebab-case`，资源名词复数（如 `/api/v1/user-profiles`）。
+
+## 3. API 规范 (API Patterns)
+- **路由前缀**：
+  - 客户端 API：`/api/v1/...`
+  - 管理端 API：`/api/v1/admin/...`
+- **统一响应结构**：
+  ```json
+  {
+    "code": 200,
+    "message": "success",
+    "data": {}
+  }
+  ```
+- **错误码规范**：
+  - `400`：客户端请求错误（参数错误、验证失败）
+  - `401`：未认证
+  - `403`：无权限
+  - `404`：资源不存在
+  - `500`：服务器内部错误
+- **认证/鉴权**：使用 `auth.middleware.ts` 保护需要认证的路由，位于 `middleware/` 目录。
+
+## 4. 数据层规范 (Data Layer Rules)
+- **数据库访问**：仅允许在 `service` 层使用 Prisma Client 进行数据库操作。
+- **模型命名**：Prisma model 使用 `PascalCase`（如 `UserProfile`），表名使用 `snake_case`（如 `user_profiles`）。
+- **事务处理**：复杂业务逻辑使用 Prisma 的 `$transaction` API 保证数据一致性。
+
+## 5. 错误处理规范 (Error Handling Patterns)
+- **统一错误中间件**：使用 `error.middleware.ts` 捕获所有错误，位于 `middleware/` 目录。
+- **错误抛出**：在 `service` 或 `controller` 中抛出 `AppError`（自定义错误类，包含 `code` 和 `message`）。
+- **已知错误码**：
+  - `VALIDATION_ERROR` (400)
+  - `UNAUTHORIZED` (401)
+  - `FORBIDDEN` (403)
+  - `NOT_FOUND` (404)
+  - `INTERNAL_ERROR` (500)
+
+## 6. 禁区 (Red Lines — Never Violate)
+- [ ] **禁止**在 `controller` 或 `route` 层直接操作数据库（必须通过 `service`）。
+- [ ] **禁止**创建重复的配置文件（如错误码、路由定义），必须追加到现有文件。
+- [ ] **禁止**使用 `any` 类型，必须定义明确的接口或类型。
+- [ ] **禁止**提交未通过 `vitest` 测试的代码。
+
+## 7. 测试规范 (Testing Rules)
+- **测试文件位置**：与源文件同目录，命名规则为 `*.test.ts` 或 `*.spec.ts`。
+- **测试覆盖**：必须为所有 `service` 和 `controller` 方法编写单元测试，关键业务流程需包含集成测试。
+- **测试框架**：使用 `vitest` 进行单元测试和集成测试，使用 `supertest` 进行 HTTP 接口测试。
+
+## 8. 共享配置文件清单 (Shared Config Files — Append-Only)
+
+(No shared config files detected — will be populated on first run)

package/demo-backend/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "demo-backend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "cors": "^2.8.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17",
+    "ts-node": "^10.9.2",
+    "vitest": "^2.1.0"
+  }
+}

package/demo-backend/prisma/schema.prisma

@@ -0,0 +1,22 @@
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model Bookmark {
+  id        String   @id @default(uuid())
+  title     String
+  url       String
+  tags      String[]
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@map("bookmarks")
+}

package/demo-backend/specs/feature-1-bookmark-id-uuid-title-string-required-url-str-v1.dsl.json

@@ -0,0 +1,186 @@
+{
+  "version": "1.0",
+  "feature": {
+    "id": "bookmark-management-system",
+    "title": "Bookmark 管理系统",
+    "description": "实现个人书签管理系统，支持创建、查看、编辑、删除网页书签，通过标签分类和分页浏览。"
+  },
+  "models": [
+    {
+      "name": "Bookmark",
+      "description": "书签数据模型，包含标题、URL和标签等信息",
+      "fields": [
+        {
+          "name": "id",
+          "type": "String",
+          "required": true,
+          "unique": true,
+          "description": ""
+        },
+        {
+          "name": "title",
+          "type": "String",
+          "required": true,
+          "unique": false,
+          "description": "书签标题"
+        },
+        {
+          "name": "url",
+          "type": "String",
+          "required": true,
+          "unique": false,
+          "description": "书签URL，需为有效URL格式"
+        },
+        {
+          "name": "tags",
+          "type": "String[]",
+          "required": false,
+          "unique": false,
+          "description": "标签数组"
+        },
+        {
+          "name": "createdAt",
+          "type": "DateTime",
+          "required": true,
+          "unique": false,
+          "description": "创建时间"
+        },
+        {
+          "name": "updatedAt",
+          "type": "DateTime",
+          "required": true,
+          "unique": false,
+          "description": "更新时间"
+        }
+      ],
+      "relations": []
+    }
+  ],
+  "endpoints": [
+    {
+      "id": "EP-001",
+      "method": "GET",
+      "path": "/api/v1/bookmarks",
+      "description": "获取书签分页列表",
+      "auth": false,
+      "request": {
+        "body": {},
+        "query": {
+          "limit": "integer (positive, default 20)",
+          "offset": "integer (non-negative, default 0)"
+        },
+        "params": {}
+      },
+      "successStatus": 200,
+      "successDescription": "返回书签数组及总数",
+      "errors": [
+        {
+          "status": 400,
+          "code": "VALIDATION_ERROR",
+          "description": "查询参数验证失败，如 limit 或 offset 无效"
+        },
+        {
+          "status": 500,
+          "code": "INTERNAL_ERROR",
+          "description": "服务器内部错误"
+        }
+      ]
+    },
+    {
+      "id": "EP-002",
+      "method": "POST",
+      "path": "/api/v1/bookmarks",
+      "description": "创建新书签",
+      "auth": false,
+      "request": {
+        "body": {
+          "title": "string (required, non-empty)",
+          "url": "string (required, valid URL format)",
+          "tags": "string array (optional)"
+        },
+        "query": {},
+        "params": {}
+      },
+      "successStatus": 201,
+      "successDescription": "返回新创建的书签信息",
+      "errors": [
+        {
+          "status": 400,
+          "code": "VALIDATION_ERROR",
+          "description": "请求体验证失败，如 title 为空或 url 格式无效"
+        },
+        {
+          "status": 500,
+          "code": "INTERNAL_ERROR",
+          "description": "服务器内部错误"
+        }
+      ]
+    },
+    {
+      "id": "EP-003",
+      "method": "PUT",
+      "path": "/api/v1/bookmarks/:id",
+      "description": "全量更新指定书签",
+      "auth": false,
+      "request": {
+        "body": {
+          "title": "string (required)",
+          "url": "string (required, valid URL format)",
+          "tags": "string array (required)"
+        },
+        "query": {},
+        "params": {
+          "id": "string (UUID format)"
+        }
+      },
+      "successStatus": 200,
+      "successDescription": "返回更新后的书签信息",
+      "errors": [
+        {
+          "status": 400,
+          "code": "VALIDATION_ERROR",
+          "description": "请求体验证失败"
+        },
+        {
+          "status": 404,
+          "code": "NOT_FOUND",
+          "description": "书签未找到"
+        },
+        {
+          "status": 500,
+          "code": "INTERNAL_ERROR",
+          "description": "服务器内部错误"
+        }
+      ]
+    },
+    {
+      "id": "EP-004",
+      "method": "DELETE",
+      "path": "/api/v1/bookmarks/:id",
+      "description": "删除指定书签",
+      "auth": false,
+      "request": {
+        "body": {},
+        "query": {},
+        "params": {
+          "id": "string (UUID format)"
+        }
+      },
+      "successStatus": 204,
+      "successDescription": "无响应体",
+      "errors": [
+        {
+          "status": 404,
+          "code": "NOT_FOUND",
+          "description": "书签未找到"
+        },
+        {
+          "status": 500,
+          "code": "INTERNAL_ERROR",
+          "description": "服务器内部错误"
+        }
+      ]
+    }
+  ],
+  "behaviors": []
+}