ai-spec-dev 0.38.0 → 0.42.0

package/core/codegen/helpers.ts

@@ -0,0 +1,219 @@
+import chalk from "chalk";
+import { execSync } from "child_process";
+import { ProjectContext } from "../context-loader";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface FileAction {
+  file: string;
+  action: "create" | "modify";
+  description: string;
+}
+
+// ─── Shared Config Helper ───────────────────────────────────────────────────
+
+export function buildSharedConfigSection(context?: ProjectContext): string {
+  if (!context?.sharedConfigFiles || context.sharedConfigFiles.length === 0) return "";
+
+  const lines: string[] = [
+    "\n=== Existing Shared Config Files (study these to learn project conventions) ===",
+    "These are real files from the project. Use them as ground truth for naming, structure, and registration patterns.",
+    "Modify them in-place when adding new entries. Do NOT create parallel files for the same purpose.\n",
+  ];
+
+  for (const f of context.sharedConfigFiles) {
+    lines.push(`--- File: ${f.path}  [${f.category}] ---`);
+    lines.push(f.preview);
+    lines.push("");
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function buildInstalledPackagesSection(context?: ProjectContext): string {
+  if (!context?.dependencies || context.dependencies.length === 0) return "";
+  return `\n=== Installed Packages (ONLY use packages from this list — NEVER import anything not listed here) ===\n${context.dependencies.join(", ")}\n`;
+}
+
+// ─── Behavioral Contract Extractor ──────────────────────────────────────────
+
+/**
+ * Extract a behavioral contract summary from a generated file.
+ *
+ * Captures:
+ * - export interface / type / enum — full multi-line blocks (the actual TS contracts)
+ * - export function / const / class — opening signature line
+ * - Throw statements — error codes & validation constraints
+ *
+ * Multi-line blocks (interface, type alias with {}) are captured in full so
+ * downstream tasks see complete method signatures and field shapes, not just
+ * a single-line "export interface Foo {" that conveys nothing.
+ *
+ * Falls back to first 3000 chars for CommonJS files with no explicit exports.
+ */
+export function extractBehavioralContract(content: string): string {
+  const lines = content.split("\n");
+  const contractLines: string[] = [];
+  const throwLines: string[] = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // ── Multi-line block exports: interface / type X = { / class / enum ──────
+    if (/^export\s+(interface|type|class|abstract\s+class|enum)\s/.test(trimmed)) {
+      contractLines.push(line.trimEnd());
+      if (trimmed.includes("{")) {
+        let depth =
+          (trimmed.match(/\{/g) ?? []).length -
+          (trimmed.match(/\}/g) ?? []).length;
+        i++;
+        while (i < lines.length && depth > 0) {
+          const inner = lines[i];
+          contractLines.push(inner.trimEnd());
+          depth += (inner.match(/\{/g) ?? []).length;
+          depth -= (inner.match(/\}/g) ?? []).length;
+          i++;
+        }
+      } else {
+        i++;
+      }
+      continue;
+    }
+
+    // ── export const X = defineStore(...) — capture full block ───────────────
+    if (/^export\s+const\s+\w+\s*=\s*(defineStore|createStore|createSlice)\s*\(/.test(trimmed)) {
+      contractLines.push(line.trimEnd());
+      let depth = (trimmed.match(/\(/g) ?? []).length - (trimmed.match(/\)/g) ?? []).length;
+      i++;
+      while (i < lines.length && depth > 0) {
+        const inner = lines[i];
+        contractLines.push(inner.trimEnd());
+        depth += (inner.match(/\(/g) ?? []).length;
+        depth -= (inner.match(/\)/g) ?? []).length;
+        i++;
+      }
+      continue;
+    }
+
+    // ── return { ... } — composable/store public API surface ─────────────────
+    if (/^return\s*\{/.test(trimmed)) {
+      contractLines.push("// public API (return object):");
+      contractLines.push(line.trimEnd());
+      let depth = (trimmed.match(/\{/g) ?? []).length - (trimmed.match(/\}/g) ?? []).length;
+      i++;
+      while (i < lines.length && depth > 0) {
+        const inner = lines[i];
+        contractLines.push(inner.trimEnd());
+        depth += (inner.match(/\{/g) ?? []).length;
+        depth -= (inner.match(/\}/g) ?? []).length;
+        i++;
+      }
+      continue;
+    }
+
+    // ── export default function/class — capture full block ───────────────────
+    if (/^export\s+default\s+(async\s+)?(function|class)\b/.test(trimmed)) {
+      contractLines.push(line.trimEnd());
+      if (trimmed.includes("{")) {
+        let depth =
+          (trimmed.match(/\{/g) ?? []).length -
+          (trimmed.match(/\}/g) ?? []).length;
+        i++;
+        while (i < lines.length && depth > 0) {
+          const inner = lines[i];
+          contractLines.push(inner.trimEnd());
+          depth += (inner.match(/\{/g) ?? []).length;
+          depth -= (inner.match(/\}/g) ?? []).length;
+          i++;
+        }
+      } else {
+        i++;
+      }
+      continue;
+    }
+
+    // ── Single-line export declarations (functions, consts, re-exports) ───────
+    if (/^export\s/.test(trimmed)) {
+      contractLines.push(line.trimEnd());
+    }
+
+    // ── Throw patterns — validation constraints and named error codes ─────────
+    if (
+      /throw\s+(new\s+)?\w*[Ee]rror\b|throw\s+create[A-Z]\w*|@throws/.test(line) &&
+      throwLines.length < 20
+    ) {
+      throwLines.push("  // " + trimmed);
+    }
+
+    i++;
+  }
+
+  if (contractLines.length === 0 && throwLines.length === 0) {
+    return content.slice(0, 3000);
+  }
+
+  const parts: string[] = [...contractLines];
+  if (throwLines.length > 0) {
+    parts.push("", "// Error contracts (throws / validation):", ...throwLines);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Build a context section from files already written in this generation run.
+ */
+export function buildGeneratedFilesSection(cache: Map<string, string>): string {
+  if (cache.size === 0) return "";
+  const lines = [
+    "\n=== Files Already Generated in This Run — USE EXACT EXPORTS (do not rename or invent alternatives) ===",
+    "// CRITICAL: function/action names and file paths below are ground truth. Copy them EXACTLY.",
+    "// Do NOT add suffixes (List, Data, All, Info) or change casing.",
+    "// For '// exists:' entries: use the EXACT filename shown — do NOT substitute index.vue or other defaults.",
+  ];
+  for (const [filePath, content] of cache) {
+    const isViewFile = /src[\\/](views?|pages?)[\\/]/i.test(filePath);
+    if (isViewFile) {
+      lines.push(`\n// exists: ${filePath}`);
+      continue;
+    }
+    lines.push(`\n--- ${filePath} ---`);
+    const isStoreOrComposable = /src[\\/](stores?|composables?)[\\/]/i.test(filePath);
+    lines.push(isStoreOrComposable ? content : extractBehavioralContract(content));
+  }
+  return lines.join("\n") + "\n";
+}
+
+// ─── RTK Helper ────────────────────────────────────────────────────────────────
+
+export function isRtkAvailable(): boolean {
+  try {
+    execSync("rtk --version", { stdio: "ignore", timeout: 10_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Parser Helpers ──────────────────────────────────────────────────────────
+
+export function stripCodeFences(output: string): string {
+  const fenced = output.match(/^```(?:\w+)?\n([\s\S]*?)```\s*$/m);
+  if (fenced) return fenced[1].trim();
+  const lines = output.split("\n");
+  if (lines[0].startsWith("```")) lines.shift();
+  if (lines[lines.length - 1].trim() === "```") lines.pop();
+  return lines.join("\n").trim();
+}
+
+export function parseJsonArray(text: string): FileAction[] {
+  const fenced = text.match(/```(?:json)?\n(\[[\s\S]*?\])\n```/);
+  const raw = fenced ? fenced[1] : text.match(/\[[\s\S]*?\]/)?.[0] ?? "";
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed as FileAction[];
+  } catch {
+    // fall through
+  }
+  return [];
+}

package/core/codegen/topo-sort.ts

@@ -0,0 +1,98 @@
+import chalk from "chalk";
+import { SpecTask } from "../task-generator";
+
+// ─── Topological Batch Sort ────────────────────────────────────────────────────
+
+/**
+ * Partition tasks within a layer into ordered batches that respect the
+ * `dependencies` field.  Tasks in the same batch have no intra-layer
+ * dependencies on each other and can run in parallel.  Tasks in later batches
+ * wait for earlier batches to complete.
+ *
+ * Only intra-layer dependencies (i.e. deps whose IDs also appear in `tasks`)
+ * are considered — cross-layer ordering is already handled by LAYER_ORDER.
+ *
+ * Returns at least one batch.  On circular-dependency detection the remaining
+ * tasks are dumped into a final batch so execution always completes.
+ */
+export function topoSortLayerTasks(tasks: SpecTask[]): SpecTask[][] {
+  if (tasks.length <= 1) return [tasks];
+
+  const idSet = new Set(tasks.map((t) => t.id));
+  const taskById = new Map(tasks.map((t) => [t.id, t]));
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>(); // dep → tasks that depend on it
+
+  for (const task of tasks) {
+    inDegree.set(task.id, 0);
+    dependents.set(task.id, []);
+  }
+
+  for (const task of tasks) {
+    const intraDeps = task.dependencies.filter((dep) => idSet.has(dep));
+    inDegree.set(task.id, intraDeps.length);
+    for (const dep of intraDeps) {
+      dependents.get(dep)!.push(task.id);
+    }
+  }
+
+  const batches: SpecTask[][] = [];
+  const remaining = new Set(tasks.map((t) => t.id));
+
+  while (remaining.size > 0) {
+    const batch = [...remaining]
+      .filter((id) => inDegree.get(id) === 0)
+      .map((id) => taskById.get(id)!);
+
+    if (batch.length === 0) {
+      // Circular dependency — run all remaining tasks in parallel to avoid deadlock
+      batches.push([...remaining].map((id) => taskById.get(id)!));
+      break;
+    }
+
+    batches.push(batch);
+    for (const task of batch) {
+      remaining.delete(task.id);
+      for (const dependent of dependents.get(task.id)!) {
+        inDegree.set(dependent, inDegree.get(dependent)! - 1);
+      }
+    }
+  }
+
+  return batches;
+}
+
+// ─── Progress Bar Helper ───────────────────────────────────────────────────────
+
+export const LAYER_ICONS: Record<string, string> = {
+  data: "💾",
+  infra: "⚙️ ",
+  service: "🔧",
+  api: "🌐",
+  view: "🖥️ ",
+  route: "🗺️ ",
+  test: "🧪",
+};
+
+export function printTaskProgress(
+  completed: number,
+  total: number,
+  task: SpecTask,
+  mode: "run" | "skip"
+): void {
+  const pct = total > 0 ? Math.round((completed / total) * 100) : 0;
+  const barWidth = 20;
+  const filled = Math.round((pct / 100) * barWidth);
+  const bar = chalk.green("█".repeat(filled)) + chalk.gray("░".repeat(barWidth - filled));
+  const icon = LAYER_ICONS[task.layer] ?? "  ";
+
+  if (mode === "skip") {
+    console.log(
+      chalk.gray(`\n  [${bar}] ${pct}% ✓ ${task.id} ${icon} ${task.title} — already done`)
+    );
+  } else {
+    console.log(
+      chalk.bold(`\n  [${bar}] ${pct}% → ${task.id} ${icon} ${task.title}`)
+    );
+  }
+}

package/core/constitution-consolidator.ts

@@ -108,8 +108,8 @@ export class ConstitutionConsolidator {
     // ── Show diff ───────────────────────────────────────────────────────────
     const diff = computeDiff(original, consolidated);
     console.log(chalk.blue("\n  Changes preview:"));
-    printDiff(diff, 4);
-    printDiffSummary(diff);
+    printDiff(diff);
+    printDiffSummary(diff, "consolidation");
 
     console.log(chalk.cyan("\n  After consolidation:"));
     console.log(chalk.gray(`  Size    : ${after.totalLines} lines (was ${before.totalLines})`));

package/core/dsl-coverage-checker.ts

@@ -0,0 +1,298 @@
+/**
+ * dsl-coverage-checker.ts — Verify that DSL covers all Spec requirements.
+ *
+ * Extracts User Stories and Functional Requirements from Spec markdown,
+ * then checks each against DSL endpoints/models/behaviors using keyword
+ * matching. Uncovered requirements are reported as DslGap entries.
+ */
+
+import { SpecDSL } from "./dsl-types";
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+export interface SpecRequirement {
+  id: string;
+  text: string;
+  section: "user_story" | "functional_req" | "boundary_condition";
+}
+
+export interface CoverageResult {
+  covered: SpecRequirement[];
+  uncovered: SpecRequirement[];
+  coverageRatio: number;
+}
+
+// ─── Keyword Extraction ─────────────────────────────────────────────────────────
+
+/** CJK character range regex. */
+const CJK_RANGE = /[\u4e00-\u9fff\u3400-\u4dbf]/g;
+
+/** Common stopwords to ignore (Chinese + English). */
+const STOPWORDS = new Set([
+  // Chinese
+  "的", "了", "在", "是", "我", "有", "和", "就", "不", "人", "都", "一",
+  "一个", "上", "也", "到", "说", "要", "去", "你", "会", "着", "没有",
+  "看", "好", "自己", "这", "他", "她", "它", "我们", "可以", "能", "能够",
+  "需要", "应该", "作为", "希望", "以便", "通过", "使用", "进行", "支持",
+  "包括", "提供", "实现", "系统", "功能", "用户",
+  // English
+  "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "could",
+  "should", "may", "might", "can", "shall", "to", "of", "in", "for",
+  "on", "with", "at", "by", "from", "as", "into", "through", "during",
+  "before", "after", "and", "or", "but", "not", "no", "if", "then",
+  "than", "so", "that", "this", "these", "those", "it", "its",
+  "i", "we", "you", "they", "he", "she", "my", "our", "your",
+  "able", "want", "need", "use", "make", "get", "set",
+]);
+
+/**
+ * Extract meaningful keywords from text (handles mixed CJK + English).
+ * CJK: split into individual characters and bigrams.
+ * English: split by non-alpha, filter stopwords, lowercase.
+ */
+export function extractKeywords(text: string): Set<string> {
+  const keywords = new Set<string>();
+
+  // Extract CJK characters and form bigrams
+  const cjkChars = text.match(CJK_RANGE) ?? [];
+  for (const ch of cjkChars) {
+    if (!STOPWORDS.has(ch)) keywords.add(ch);
+  }
+  for (let i = 0; i < cjkChars.length - 1; i++) {
+    const bigram = cjkChars[i] + cjkChars[i + 1];
+    if (!STOPWORDS.has(bigram)) keywords.add(bigram);
+  }
+
+  // Extract English words
+  const englishWords = text
+    .replace(CJK_RANGE, " ")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length >= 2 && !STOPWORDS.has(w));
+  for (const w of englishWords) keywords.add(w);
+
+  return keywords;
+}
+
+// ─── Spec Requirement Extraction ────────────────────────────────────────────────
+
+/**
+ * Parse User Stories from Spec markdown.
+ * Matches patterns like: "作为 **角色**，我希望 **动作**，以便 **目的**"
+ * and English "As a **role**, I want **action**, so that **purpose**"
+ */
+function extractUserStories(spec: string): SpecRequirement[] {
+  const reqs: SpecRequirement[] = [];
+  const lines = spec.split("\n");
+  let storyIdx = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Chinese format: "- 作为 ..." or "1. 作为 ..." or "作为 ..."
+    if (/^[-*]\s+作为\s/.test(trimmed) || /^\d+[.)]\s*作为\s/.test(trimmed) || /^作为\s/.test(trimmed)) {
+      storyIdx++;
+      reqs.push({
+        id: `US-${storyIdx}`,
+        text: trimmed.replace(/^[-*]\s+/, "").replace(/^\d+[.)]\s*/, ""),
+        section: "user_story",
+      });
+      continue;
+    }
+    // English format: "- As a ..." or "1. As a ..." or "As a ..."
+    if (/^[-*]\s+As an?\s/i.test(trimmed) || /^\d+[.)]\s*As an?\s/i.test(trimmed) || /^As an?\s/i.test(trimmed)) {
+      storyIdx++;
+      reqs.push({
+        id: `US-${storyIdx}`,
+        text: trimmed.replace(/^[-*]\s+/, "").replace(/^\d+[.)]\s*/, ""),
+        section: "user_story",
+      });
+    }
+  }
+
+  return reqs;
+}
+
+/**
+ * Parse Functional Requirements from Spec markdown.
+ * Matches checklist items: "- [ ] requirement text" and numbered items under §4.
+ */
+function extractFunctionalReqs(spec: string): SpecRequirement[] {
+  const reqs: SpecRequirement[] = [];
+  let inSection4 = false;
+  let reqIdx = 0;
+  const lines = spec.split("\n");
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Detect section 4 heading (functional requirements)
+    if (/^#{1,3}\s*(4\.|四|功能需求|Functional\s+Req)/i.test(trimmed)) {
+      inSection4 = true;
+      continue;
+    }
+    // Next section heading exits section 4
+    if (inSection4 && /^#{1,3}\s*(\d+\.|五|六|七|八|九|API|Data|Non-Func)/i.test(trimmed)) {
+      inSection4 = false;
+      continue;
+    }
+
+    if (!inSection4) continue;
+
+    // Checklist items: - [ ] or - [x]
+    const checklistMatch = trimmed.match(/^-\s*\[[ x]\]\s*(.+)/i);
+    if (checklistMatch) {
+      reqIdx++;
+      reqs.push({
+        id: `FR-${reqIdx}`,
+        text: checklistMatch[1],
+        section: "functional_req",
+      });
+      continue;
+    }
+
+    // Numbered sub-items: 4.1.1, 4.2.3, etc.
+    const numberedMatch = trimmed.match(/^(\d+\.)+\d*\s+(.+)/);
+    if (numberedMatch) {
+      reqIdx++;
+      reqs.push({
+        id: `FR-${reqIdx}`,
+        text: numberedMatch[2],
+        section: "functional_req",
+      });
+    }
+  }
+
+  return reqs;
+}
+
+/**
+ * Parse Boundary Conditions from Spec markdown (section 4.2 or edge cases).
+ */
+function extractBoundaryConditions(spec: string): SpecRequirement[] {
+  const reqs: SpecRequirement[] = [];
+  let inBoundary = false;
+  let bcIdx = 0;
+  const lines = spec.split("\n");
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (/边界|boundary|edge\s+case|异常|错误处理/i.test(trimmed) && /^#{1,4}/.test(trimmed)) {
+      inBoundary = true;
+      continue;
+    }
+    if (inBoundary && /^#{1,3}\s/.test(trimmed)) {
+      inBoundary = false;
+      continue;
+    }
+
+    if (!inBoundary) continue;
+
+    const itemMatch = trimmed.match(/^[-*]\s+(.+)/) || trimmed.match(/^\d+[.)]\s*(.+)/);
+    if (itemMatch && itemMatch[1].length > 5) {
+      bcIdx++;
+      reqs.push({
+        id: `BC-${bcIdx}`,
+        text: itemMatch[1],
+        section: "boundary_condition",
+      });
+    }
+  }
+
+  return reqs;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────────
+
+/**
+ * Extract all requirements from a Spec markdown document.
+ */
+export function extractSpecRequirements(spec: string): SpecRequirement[] {
+  return [
+    ...extractUserStories(spec),
+    ...extractFunctionalReqs(spec),
+    ...extractBoundaryConditions(spec),
+  ];
+}
+
+/**
+ * Build a keyword index from all DSL elements for fast matching.
+ */
+function buildDslKeywordIndex(dsl: SpecDSL): Set<string> {
+  const allText: string[] = [];
+
+  // Feature
+  allText.push(dsl.feature.title, dsl.feature.description);
+
+  // Models
+  for (const m of dsl.models) {
+    allText.push(m.name, m.description ?? "");
+    for (const f of m.fields) allText.push(f.name, f.description ?? "");
+    for (const r of m.relations ?? []) allText.push(r);
+  }
+
+  // Endpoints
+  for (const ep of dsl.endpoints) {
+    allText.push(ep.description, ep.path);
+    if (ep.request?.body) allText.push(...Object.keys(ep.request.body));
+    if (ep.request?.query) allText.push(...Object.keys(ep.request.query));
+    for (const err of ep.errors ?? []) allText.push(err.code, err.description);
+  }
+
+  // Behaviors
+  for (const b of dsl.behaviors) {
+    allText.push(b.description, b.trigger ?? "");
+    for (const c of b.constraints ?? []) allText.push(c);
+  }
+
+  // Components
+  for (const c of dsl.components ?? []) {
+    allText.push(c.name, c.description);
+    for (const p of c.props) allText.push(p.name, p.description ?? "");
+    for (const e of c.events) allText.push(e.name, e.payload ?? "");
+  }
+
+  return extractKeywords(allText.join(" "));
+}
+
+/** Minimum keyword overlap to consider a requirement "covered". */
+const MIN_KEYWORD_OVERLAP = 2;
+
+/**
+ * Check how well the DSL covers the Spec requirements.
+ * Uses keyword overlap: a requirement is "covered" if it shares
+ * ≥ MIN_KEYWORD_OVERLAP significant keywords with any DSL element.
+ */
+export function checkDslCoverage(
+  requirements: SpecRequirement[],
+  dsl: SpecDSL
+): CoverageResult {
+  if (requirements.length === 0) {
+    return { covered: [], uncovered: [], coverageRatio: 1.0 };
+  }
+
+  const dslKeywords = buildDslKeywordIndex(dsl);
+  const covered: SpecRequirement[] = [];
+  const uncovered: SpecRequirement[] = [];
+
+  for (const req of requirements) {
+    const reqKeywords = extractKeywords(req.text);
+    let overlap = 0;
+    for (const kw of reqKeywords) {
+      if (dslKeywords.has(kw)) overlap++;
+    }
+
+    if (overlap >= MIN_KEYWORD_OVERLAP) {
+      covered.push(req);
+    } else {
+      uncovered.push(req);
+    }
+  }
+
+  return {
+    covered,
+    uncovered,
+    coverageRatio: covered.length / requirements.length,
+  };
+}