ai-spec-dev 0.1.0 → 0.17.0

package/core/spec-updater.ts

@@ -0,0 +1,227 @@
+import chalk from "chalk";
+import * as path from "path";
+import * as fs from "fs-extra";
+import { AIProvider } from "./spec-generator";
+import { ProjectContext, FRONTEND_FRAMEWORKS } from "./context-loader";
+import { SpecDSL } from "./dsl-types";
+import { DslExtractor } from "./dsl-extractor";
+import { nextVersionPath } from "./spec-versioning";
+import { findLatestDslFile } from "./mock-server-generator";
+import {
+  specUpdateSystemPrompt,
+  dslUpdateSystemPrompt,
+  buildSpecUpdatePrompt,
+  buildDslUpdatePrompt,
+  buildAffectedFilesPrompt,
+} from "../prompts/update.prompt";
+import { getCodeGenSystemPrompt } from "../prompts/codegen.prompt";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface SpecUpdateResult {
+  /** Path of the new spec version written to disk */
+  newSpecPath: string;
+  /** New version number */
+  newVersion: number;
+  /** Path of the updated DSL, or null if extraction failed */
+  newDslPath: string | null;
+  /** Files identified as needing updates */
+  affectedFiles: AffectedFile[];
+  /** Updated DSL, or null */
+  updatedDsl: SpecDSL | null;
+}
+
+export interface AffectedFile {
+  file: string;
+  action: "create" | "modify";
+  description: string;
+}
+
+export interface SpecUpdaterOptions {
+  /** Skip generating the affected-files list */
+  skipAffectedFiles?: boolean;
+  /** Repo language type — for DSL extraction front detection */
+  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");
+}
+
+function parseAffectedFiles(raw: string): AffectedFile[] {
+  try {
+    const parsed = parseJsonFromOutput(raw);
+    if (Array.isArray(parsed)) return parsed as AffectedFile[];
+  } catch { /* ignore */ }
+  return [];
+}
+
+// ─── Spec Updater ─────────────────────────────────────────────────────────────
+
+export class SpecUpdater {
+  private extractor: DslExtractor;
+
+  constructor(private provider: AIProvider) {
+    this.extractor = new DslExtractor(provider);
+  }
+
+  /**
+   * Find the latest spec version for a given specs directory.
+   * Returns all .md spec files sorted newest-first.
+   */
+  static async findLatestSpec(specsDir: string): Promise<{
+    filePath: string;
+    version: number;
+    slug: string;
+    content: string;
+  } | null> {
+    if (!(await fs.pathExists(specsDir))) return null;
+
+    const files = await fs.readdir(specsDir);
+    const pattern = /^feature-(.+)-v(\d+)\.md$/;
+
+    let latest: { filePath: string; version: number; slug: string; content: string } | null = null;
+
+    for (const file of files) {
+      const m = file.match(pattern);
+      if (!m) continue;
+      const version = parseInt(m[2], 10);
+      if (!latest || version > latest.version) {
+        const filePath = path.join(specsDir, file);
+        const content = await fs.readFile(filePath, "utf-8");
+        latest = { filePath, version, slug: m[1], content };
+      }
+    }
+
+    return latest;
+  }
+
+  /**
+   * Update an existing spec with a change request.
+   * Generates a new version of the spec, re-extracts the DSL, and identifies affected files.
+   */
+  async update(
+    changeRequest: string,
+    existingSpecPath: string,
+    projectDir: string,
+    context?: ProjectContext,
+    opts: SpecUpdaterOptions = {}
+  ): Promise<SpecUpdateResult> {
+    // ── Load existing spec ──────────────────────────────────────────────────
+    const existingSpec = await fs.readFile(existingSpecPath, "utf-8");
+
+    // ── Load existing DSL (may be absent) ──────────────────────────────────
+    let existingDsl: SpecDSL | null = null;
+    const dslFile = await findLatestDslFile(projectDir);
+    if (dslFile) {
+      try {
+        existingDsl = await fs.readJson(dslFile);
+      } catch { /* ignore */ }
+    }
+
+    // ── Step 1: Generate updated spec ──────────────────────────────────────
+    console.log(chalk.blue("  [1/3] Generating updated spec..."));
+    const updatePrompt = buildSpecUpdatePrompt(changeRequest, existingSpec, existingDsl, context);
+
+    let updatedSpecContent: string;
+    try {
+      updatedSpecContent = await this.provider.generate(updatePrompt, specUpdateSystemPrompt);
+      // Strip markdown fences if present
+      updatedSpecContent = updatedSpecContent.replace(/^```(?:markdown|md)?\n?/im, "").replace(/\n?```\s*$/im, "").trim();
+    } catch (err) {
+      throw new Error(`Spec update generation failed: ${(err as Error).message}`);
+    }
+
+    // ── Step 2: Write new spec version ─────────────────────────────────────
+    // Extract slug from existing spec path: feature-<slug>-v<N>.md
+    const specBasename = path.basename(existingSpecPath);
+    const slugMatch = specBasename.match(/^feature-(.+)-v\d+\.md$/);
+    const slug = slugMatch ? slugMatch[1] : "feature";
+
+    const specsDir = path.dirname(existingSpecPath);
+    const { filePath: newSpecPath, version: newVersion } = await nextVersionPath(specsDir, slug);
+
+    await fs.ensureDir(specsDir);
+    await fs.writeFile(newSpecPath, updatedSpecContent, "utf-8");
+    console.log(chalk.green(`  ✔ New spec written: ${path.relative(projectDir, newSpecPath)}`));
+
+    // ── Step 3: Update DSL ─────────────────────────────────────────────────
+    console.log(chalk.blue("  [2/3] Updating DSL..."));
+    let updatedDsl: SpecDSL | null = null;
+    let newDslPath: string | null = null;
+
+    if (existingDsl) {
+      // Use targeted DSL update prompt
+      const dslUpdatePrompt = buildDslUpdatePrompt(changeRequest, existingDsl, updatedSpecContent);
+      try {
+        const rawDsl = await this.provider.generate(dslUpdatePrompt, dslUpdateSystemPrompt);
+        const parsed = parseJsonFromOutput(rawDsl) as SpecDSL;
+        if (parsed && parsed.endpoints && parsed.models) {
+          updatedDsl = parsed;
+        }
+      } catch {
+        // Fall back to full extraction
+        console.log(chalk.gray("  Targeted DSL update failed — falling back to full extraction."));
+      }
+    }
+
+    if (!updatedDsl) {
+      // Full extraction from updated spec
+      const isFrontend = opts.repoType
+        ? (FRONTEND_FRAMEWORKS as readonly string[]).includes(opts.repoType)
+        : false;
+      updatedDsl = await this.extractor.extract(updatedSpecContent, { auto: true, isFrontend });
+    }
+
+    if (updatedDsl) {
+      // Save DSL alongside spec
+      const dslPath = newSpecPath.replace(/\.md$/, ".dsl.json");
+      await fs.writeJson(dslPath, updatedDsl, { spaces: 2 });
+      newDslPath = dslPath;
+      console.log(chalk.green(`  ✔ DSL updated: ${path.relative(projectDir, dslPath)}`));
+    } else {
+      console.log(chalk.yellow("  ⚠ DSL update failed — continuing without DSL."));
+    }
+
+    // ── Step 4: Identify affected files ────────────────────────────────────
+    let affectedFiles: AffectedFile[] = [];
+
+    if (!opts.skipAffectedFiles && updatedDsl && existingDsl && context) {
+      console.log(chalk.blue("  [3/3] Identifying affected files..."));
+      const systemPrompt = getCodeGenSystemPrompt(opts.repoType);
+      const affectedPrompt = buildAffectedFilesPrompt(
+        changeRequest,
+        existingDsl,
+        updatedDsl,
+        context.fileStructure
+      );
+      try {
+        const affectedRaw = await this.provider.generate(affectedPrompt, systemPrompt);
+        affectedFiles = parseAffectedFiles(affectedRaw);
+        console.log(chalk.green(`  ✔ ${affectedFiles.length} file(s) identified for update`));
+      } catch {
+        console.log(chalk.gray("  Could not identify affected files — use manual selection."));
+      }
+    }
+
+    return { newSpecPath, newVersion, newDslPath, affectedFiles, updatedDsl };
+  }
+}

package/core/spec-versioning.ts

@@ -0,0 +1,213 @@
+import chalk from "chalk";
+import * as fs from "fs-extra";
+import * as path from "path";
+
+// ─── Slug ────────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a free-form idea string into a safe, concise filename slug.
+ * e.g. "用户登录 with OAuth2" → "user-login-with-oauth2"
+ */
+export function slugify(idea: string): string {
+  return idea
+    .toLowerCase()
+    .replace(/[\u4e00-\u9fa5]+/g, (m) => pinyinFallback(m)) // CJK → strip or placeholder
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "feature";
+}
+
+/** Best-effort: just strip CJK and use surrounding ascii context. */
+function pinyinFallback(cjk: string): string {
+  // We don't have a pinyin lib — use empty string so the surrounding ascii words still form a slug
+  void cjk;
+  return "-";
+}
+
+// ─── Version Detection ───────────────────────────────────────────────────────
+
+export interface SpecVersion {
+  filePath: string;
+  version: number;
+  content: string;
+}
+
+/**
+ * Scan `specsDir` for files matching `feature-<slug>-v<N>.md` and return the latest.
+ */
+export async function findLatestVersion(
+  specsDir: string,
+  slug: string
+): Promise<SpecVersion | null> {
+  if (!(await fs.pathExists(specsDir))) return null;
+
+  const files = await fs.readdir(specsDir);
+  const pattern = new RegExp(`^feature-${escapeRegex(slug)}-v(\\d+)\\.md$`);
+  let latest: SpecVersion | null = null;
+
+  for (const file of files) {
+    const m = file.match(pattern);
+    if (!m) continue;
+    const version = parseInt(m[1], 10);
+    if (!latest || version > latest.version) {
+      const filePath = path.join(specsDir, file);
+      const content = await fs.readFile(filePath, "utf-8");
+      latest = { filePath, version, content };
+    }
+  }
+
+  return latest;
+}
+
+/**
+ * Return the path and version number for the NEXT spec file.
+ * If `feature-<slug>-v1.md` exists, returns `feature-<slug>-v2.md`, etc.
+ */
+export async function nextVersionPath(
+  specsDir: string,
+  slug: string
+): Promise<{ filePath: string; version: number }> {
+  const latest = await findLatestVersion(specsDir, slug);
+  const version = latest ? latest.version + 1 : 1;
+  const filePath = path.join(specsDir, `feature-${slug}-v${version}.md`);
+  return { filePath, version };
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ─── Diff Engine ─────────────────────────────────────────────────────────────
+
+export interface DiffLine {
+  type: "added" | "removed" | "unchanged";
+  content: string;
+  lineNo: number;
+}
+
+export interface DiffResult {
+  added: number;
+  removed: number;
+  unchanged: number;
+  lines: DiffLine[];
+}
+
+/**
+ * Line-level diff between two text strings.
+ * Uses a simple LCS-based greedy diff (no external deps required).
+ */
+export function computeDiff(oldText: string, newText: string): DiffResult {
+  const oldLines = oldText.split("\n");
+  const newLines = newText.split("\n");
+
+  // Build LCS table
+  const m = oldLines.length;
+  const n = newLines.length;
+
+  // For large files, limit to avoid quadratic cost
+  const MAX = 800;
+  if (m > MAX || n > MAX) {
+    return computeSimpleDiff(oldLines, newLines);
+  }
+
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      if (oldLines[i] === newLines[j]) {
+        dp[i][j] = dp[i + 1][j + 1] + 1;
+      } else {
+        dp[i][j] = Math.max(dp[i + 1][j], dp[i][j + 1]);
+      }
+    }
+  }
+
+  const lines: DiffLine[] = [];
+  let i = 0, j = 0, lineNo = 1;
+
+  while (i < m || j < n) {
+    if (i < m && j < n && oldLines[i] === newLines[j]) {
+      lines.push({ type: "unchanged", content: oldLines[i], lineNo: lineNo++ });
+      i++; j++;
+    } else if (j < n && (i >= m || dp[i + 1][j] <= dp[i][j + 1])) {
+      lines.push({ type: "added", content: newLines[j], lineNo: lineNo++ });
+      j++;
+    } else {
+      lines.push({ type: "removed", content: oldLines[i], lineNo: lineNo });
+      i++;
+    }
+  }
+
+  const added = lines.filter((l) => l.type === "added").length;
+  const removed = lines.filter((l) => l.type === "removed").length;
+  const unchanged = lines.filter((l) => l.type === "unchanged").length;
+
+  return { added, removed, unchanged, lines };
+}
+
+/** Fast O(n) diff for large files — just mark all old as removed, all new as added. */
+function computeSimpleDiff(oldLines: string[], newLines: string[]): DiffResult {
+  const lines: DiffLine[] = [
+    ...oldLines.map((c, i) => ({ type: "removed" as const, content: c, lineNo: i + 1 })),
+    ...newLines.map((c, i) => ({ type: "added" as const, content: c, lineNo: i + 1 })),
+  ];
+  return { added: newLines.length, removed: oldLines.length, unchanged: 0, lines };
+}
+
+// ─── Diff Printer ─────────────────────────────────────────────────────────────
+
+const CONTEXT_LINES = 3; // unchanged lines to show around each hunk
+
+/**
+ * Print a compact, colored unified-style diff to the console.
+ * Only shows changed hunks with `CONTEXT_LINES` lines of context.
+ */
+export function printDiff(diff: DiffResult): void {
+  if (diff.added === 0 && diff.removed === 0) {
+    console.log(chalk.gray("  (no changes)"));
+    return;
+  }
+
+  const { lines } = diff;
+  const changedIdxs = new Set(
+    lines
+      .map((l, i) => (l.type !== "unchanged" ? i : -1))
+      .filter((i) => i !== -1)
+  );
+
+  // Build set of indices to display (changed ± context)
+  const toShow = new Set<number>();
+  for (const idx of changedIdxs) {
+    for (let k = Math.max(0, idx - CONTEXT_LINES); k <= Math.min(lines.length - 1, idx + CONTEXT_LINES); k++) {
+      toShow.add(k);
+    }
+  }
+
+  const sorted = [...toShow].sort((a, b) => a - b);
+  let prevIdx = -2;
+
+  for (const idx of sorted) {
+    if (idx > prevIdx + 1 && prevIdx !== -2) {
+      console.log(chalk.cyan("  @@"));
+    }
+    const l = lines[idx];
+    if (l.type === "added") {
+      console.log(chalk.green(`  + ${l.content}`));
+    } else if (l.type === "removed") {
+      console.log(chalk.red(`  - ${l.content}`));
+    } else {
+      console.log(chalk.gray(`    ${l.content}`));
+    }
+    prevIdx = idx;
+  }
+}
+
+/**
+ * Print a one-line diff summary banner.
+ */
+export function printDiffSummary(diff: DiffResult, label: string): void {
+  const parts: string[] = [];
+  if (diff.added > 0) parts.push(chalk.green(`+${diff.added}`));
+  if (diff.removed > 0) parts.push(chalk.red(`-${diff.removed}`));
+  if (parts.length === 0) parts.push(chalk.gray("no change"));
+  console.log(chalk.bold(`  ${label}: `) + parts.join("  ") + chalk.gray(` lines`));
+}

package/core/task-generator.ts

@@ -0,0 +1,174 @@
+import chalk from "chalk";
+import * as fs from "fs-extra";
+import * as path from "path";
+import { AIProvider } from "./spec-generator";
+import { ProjectContext } from "./context-loader";
+import { tasksSystemPrompt } from "../prompts/tasks.prompt";
+
+// ─── Verified File Inventory ──────────────────────────────────────────────────
+// Builds a structured, cross-referenced file list so the AI can pick
+// real paths for filesToTouch without hallucinating.
+
+function buildVerifiedInventory(context: ProjectContext): string {
+  const lines: string[] = ["=== Verified File Inventory (filesToTouch MUST use paths from here) ===\n"];
+
+  // 1. Shared config files first — highest priority, most likely to be hallucinated
+  if (context.sharedConfigFiles && context.sharedConfigFiles.length > 0) {
+    lines.push("-- Shared Config Files (APPEND-ONLY — never create a parallel file) --");
+    for (const f of context.sharedConfigFiles) {
+      lines.push(`  [${f.category}] ${f.path}`);
+    }
+    lines.push("");
+  }
+
+  // 2. API / route / controller files (often need new siblings)
+  if (context.apiStructure.length > 0) {
+    lines.push("-- API / Route / Controller Files --");
+    for (const f of context.apiStructure.slice(0, 20)) {
+      lines.push(`  ${f}`);
+    }
+    lines.push("");
+  }
+
+  // 3. Full file tree (for deriving sibling naming patterns)
+  if (context.fileStructure.length > 0) {
+    lines.push("-- Project File Tree (first 60 entries) --");
+    for (const f of context.fileStructure.slice(0, 60)) {
+      lines.push(`  ${f}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "REMINDER: If a needed file does not appear above and is NOT a new file, verify its path.\n" +
+    "For i18n/locale files, constants, enums, or route indexes — use EXACTLY the path shown above.\n"
+  );
+
+  return lines.join("\n");
+}
+
+export function buildTaskPrompt(spec: string, context?: ProjectContext): string {
+  if (!context) return spec;
+
+  const parts: string[] = [spec];
+
+  if (context.constitution) {
+    parts.push(`\n=== Project Constitution (rules to follow) ===\n${context.constitution}`);
+  }
+
+  if (context.techStack.length > 0) {
+    parts.push(`\n=== Tech Stack ===\n${context.techStack.join(", ")}`);
+  }
+
+  parts.push("\n" + buildVerifiedInventory(context));
+
+  return parts.join("\n");
+}
+
+export type TaskLayer = "data" | "infra" | "service" | "api" | "test";
+export type TaskPriority = "high" | "medium" | "low";
+export type TaskStatus = "pending" | "done" | "failed";
+
+export interface SpecTask {
+  id: string;
+  title: string;
+  description: string;
+  layer: TaskLayer;
+  filesToTouch: string[];
+  acceptanceCriteria: string[];
+  dependencies: string[];
+  priority: TaskPriority;
+  /** Runtime checkpoint — set by code generator, persisted to tasks file */
+  status?: TaskStatus;
+}
+
+const LAYER_ORDER: Record<TaskLayer, number> = {
+  data: 0,
+  infra: 1,
+  service: 2,
+  api: 3,
+  test: 4,
+};
+
+export class TaskGenerator {
+  constructor(private provider: AIProvider) {}
+
+  async generateTasks(spec: string, context?: ProjectContext): Promise<SpecTask[]> {
+    const prompt = buildTaskPrompt(spec, context);
+    const raw = await this.provider.generate(prompt, tasksSystemPrompt);
+    return parseTasks(raw);
+  }
+
+  async saveTasks(tasks: SpecTask[], specFilePath: string): Promise<string> {
+    const dir = path.dirname(specFilePath);
+    const base = path.basename(specFilePath, ".md");
+    const tasksFile = path.join(dir, `${base}-tasks.json`);
+    await fs.writeJson(tasksFile, tasks, { spaces: 2 });
+    return tasksFile;
+  }
+
+  sortByLayer(tasks: SpecTask[]): SpecTask[] {
+    return [...tasks].sort((a, b) => {
+      const layerDiff = (LAYER_ORDER[a.layer] ?? 99) - (LAYER_ORDER[b.layer] ?? 99);
+      if (layerDiff !== 0) return layerDiff;
+      return a.id.localeCompare(b.id);
+    });
+  }
+}
+
+function parseTasks(raw: string): SpecTask[] {
+  // Try JSON code fence first
+  const fenced = raw.match(/```(?:json)?\n(\[[\s\S]*?\])\n```/);
+  const jsonStr = fenced ? fenced[1] : (raw.match(/\[[\s\S]*\]/)?.[0] ?? "");
+  try {
+    const parsed = JSON.parse(jsonStr);
+    if (Array.isArray(parsed)) return parsed as SpecTask[];
+  } catch {
+    // fall through
+  }
+  return [];
+}
+
+export function printTasks(tasks: SpecTask[]): void {
+  const layerColors: Record<TaskLayer, chalk.Chalk> = {
+    data: chalk.magenta,
+    infra: chalk.gray,
+    service: chalk.blue,
+    api: chalk.cyan,
+    test: chalk.green,
+  };
+
+  console.log(chalk.bold(`\n  Tasks (${tasks.length}):`));
+  for (const task of tasks) {
+    const color = layerColors[task.layer] ?? chalk.white;
+    const badge = color(`[${task.layer}]`);
+    const prio = task.priority === "high" ? chalk.red("●") : task.priority === "medium" ? chalk.yellow("●") : chalk.gray("●");
+    console.log(`  ${prio} ${chalk.bold(task.id)} ${badge} ${task.title}`);
+  }
+}
+
+export async function loadTasksForSpec(specFilePath: string): Promise<SpecTask[] | null> {
+  const base = path.basename(specFilePath, ".md");
+  const dir = path.dirname(specFilePath);
+  const tasksFile = path.join(dir, `${base}-tasks.json`);
+  if (await fs.pathExists(tasksFile)) {
+    return fs.readJson(tasksFile);
+  }
+  return null;
+}
+
+/** Persist a single task's status to the tasks JSON file (checkpoint). */
+export async function updateTaskStatus(
+  specFilePath: string,
+  taskId: string,
+  status: TaskStatus
+): Promise<void> {
+  const tasks = await loadTasksForSpec(specFilePath);
+  if (!tasks) return;
+  const task = tasks.find((t) => t.id === taskId);
+  if (!task) return;
+  task.status = status;
+  const base = path.basename(specFilePath, ".md");
+  const dir = path.dirname(specFilePath);
+  await fs.writeJson(path.join(dir, `${base}-tasks.json`), tasks, { spaces: 2 });
+}