ai-spec-dev 0.25.0 → 0.28.1

package/core/reviewer.ts

@@ -7,6 +7,7 @@ import {
   reviewSystemPrompt,
   reviewArchitectureSystemPrompt,
   reviewImplementationSystemPrompt,
+  reviewImpactComplexitySystemPrompt,
 } from "../prompts/codegen.prompt";
 
 // ─── Review History ────────────────────────────────────────────────────────────
@@ -16,6 +17,8 @@ interface ReviewHistoryEntry {
   specFile: string;
   score: number;
   topIssues: string[];
+  impactLevel?: "低" | "中" | "高";
+  complexityLevel?: "低" | "中" | "高";
 }
 
 const REVIEW_HISTORY_FILE = ".ai-spec-reviews.json";
@@ -53,6 +56,18 @@ function extractScore(reviewText: string): number {
   return match ? parseFloat(match[1]) : 0;
 }
 
+/** Extract impact level from Pass 3 review ("影响等级：低/中/高") */
+function extractImpactLevel(reviewText: string): "低" | "中" | "高" | undefined {
+  const match = reviewText.match(/影响等级[：:]\s*(低|中|高)/);
+  return match ? (match[1] as "低" | "中" | "高") : undefined;
+}
+
+/** Extract complexity level from Pass 3 review ("复杂度等级：低/中/高") */
+function extractComplexityLevel(reviewText: string): "低" | "中" | "高" | undefined {
+  const match = reviewText.match(/复杂度等级[：:]\s*(低|中|高)/);
+  return match ? (match[1] as "低" | "中" | "高") : undefined;
+}
+
 /** Extract top issue lines from a review result (lines starting with - or · under ⚠️ section) */
 function extractTopIssues(reviewText: string): string[] {
   const issuesSection = reviewText.match(/##.*?问题.*?\n([\s\S]*?)(?=##|$)/i)?.[1] ?? "";
@@ -112,19 +127,18 @@ export class CodeReviewer {
   }
 
   /**
-   * Two-pass review:
+   * Three-pass review:
    *   Pass 1 — architecture (spec compliance, layer separation, auth)
    *   Pass 2 — implementation details (validation, error handling, edge cases)
    *             + historical issue recurrence check
-   *
-   * Falls back to single-pass if the two-pass flag is not set.
+   *   Pass 3 — impact assessment + code complexity
    */
-  private async runTwoPassReview(
+  private async runThreePassReview(
     specContent: string,
     codeContext: string,
     specFile?: string
   ): Promise<string> {
-    console.log(chalk.gray("  Pass 1/2: Architecture review..."));
+    console.log(chalk.gray("  Pass 1/3: Architecture review..."));
 
     // ── Pass 1: Architecture ──────────────────────────────────────────────────
     const archPrompt = `Review the architecture of this change.
@@ -136,7 +150,7 @@ ${specContent || "(No spec — review for general code quality)"}
 ${codeContext}`;
 
     const archReview = await this.provider.generate(archPrompt, reviewArchitectureSystemPrompt);
-    console.log(chalk.gray("  Pass 2/2: Implementation review..."));
+    console.log(chalk.gray("  Pass 2/3: Implementation review..."));
 
     // ── Pass 2: Implementation + History ─────────────────────────────────────
     const history = await loadReviewHistory(this.projectRoot);
@@ -155,19 +169,42 @@ ${archReview}
 ${historyContext}`;
 
     const implReview = await this.provider.generate(implPrompt, reviewImplementationSystemPrompt);
+    console.log(chalk.gray("  Pass 3/3: Impact & complexity assessment..."));
+
+    // ── Pass 3: Impact & Complexity ───────────────────────────────────────────
+    const impactPrompt = `Assess the impact and complexity of this change.
+
+=== Feature Spec ===
+${specContent || "(No spec — review for general code quality)"}
+
+=== Code ===
+${codeContext}
+
+=== Architecture Review (Pass 1 — do NOT repeat) ===
+${archReview}
+
+=== Implementation Review (Pass 2 — do NOT repeat) ===
+${implReview}`;
+
+    const impactReview = await this.provider.generate(impactPrompt, reviewImpactComplexitySystemPrompt);
 
     // ── Combine ───────────────────────────────────────────────────────────────
-    const combined = `${archReview}\n\n${"─".repeat(52)}\n\n${implReview}`;
+    const sep = "─".repeat(52);
+    const combined = `${archReview}\n\n${sep}\n\n${implReview}\n\n${sep}\n\n${impactReview}`;
 
     // ── Persist history ───────────────────────────────────────────────────────
     const score = extractScore(implReview) || extractScore(archReview);
     const topIssues = extractTopIssues(implReview);
+    const impactLevel = extractImpactLevel(impactReview);
+    const complexityLevel = extractComplexityLevel(impactReview);
     if (score > 0 && specFile) {
       await appendReviewHistory(this.projectRoot, {
         date: new Date().toISOString().slice(0, 10),
         specFile: path.relative(this.projectRoot, specFile),
         score,
         topIssues,
+        ...(impactLevel ? { impactLevel } : {}),
+        ...(complexityLevel ? { complexityLevel } : {}),
       });
     }
 
@@ -195,7 +232,7 @@ ${historyContext}`;
     );
 
     const codeContext = diff.slice(0, 10000);
-    const reviewResult = await this.runTwoPassReview(specContent, codeContext, specFile);
+    const reviewResult = await this.runThreePassReview(specContent, codeContext, specFile);
 
     console.log(chalk.cyan("\n─── Review Result ───────────────────────────────"));
     console.log(reviewResult);
@@ -231,7 +268,7 @@ ${historyContext}`;
       }
     }
 
-    const reviewResult = await this.runTwoPassReview(specContent, filesSection, specFile);
+    const reviewResult = await this.runThreePassReview(specContent, filesSection, specFile);
 
     console.log(chalk.cyan("\n─── Review Result ───────────────────────────────"));
     console.log(reviewResult);

package/core/run-logger.ts

@@ -0,0 +1,136 @@
+import * as fs from "fs-extra";
+import * as path from "path";
+import chalk from "chalk";
+
+const LOG_DIR = ".ai-spec-logs";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface LogEntry {
+  ts: string;
+  event: string;
+  durationMs?: number;
+  data?: Record<string, unknown>;
+}
+
+export interface RunLog {
+  runId: string;
+  startedAt: string;
+  workingDir: string;
+  provider?: string;
+  model?: string;
+  specPath?: string;
+  entries: LogEntry[];
+  filesWritten: string[];
+  errors: string[];
+  endedAt?: string;
+  totalDurationMs?: number;
+}
+
+// ─── RunLogger ────────────────────────────────────────────────────────────────
+
+export class RunLogger {
+  private log: RunLog;
+  private readonly startMs: number;
+  private readonly logPath: string;
+  private readonly stageStartMs = new Map<string, number>();
+
+  constructor(
+    private readonly workingDir: string,
+    readonly runId: string,
+    meta?: { provider?: string; model?: string; specPath?: string }
+  ) {
+    this.startMs = Date.now();
+    this.logPath = path.join(workingDir, LOG_DIR, `${runId}.json`);
+    this.log = {
+      runId,
+      startedAt: new Date().toISOString(),
+      workingDir,
+      ...meta,
+      entries: [],
+      filesWritten: [],
+      errors: [],
+    };
+    this.flush();
+  }
+
+  stageStart(event: string, data?: Record<string, unknown>): void {
+    this.stageStartMs.set(event, Date.now());
+    this.push(event, data);
+  }
+
+  stageEnd(event: string, data?: Record<string, unknown>): void {
+    const start = this.stageStartMs.get(event);
+    const durationMs = start !== undefined ? Date.now() - start : undefined;
+    this.push(`${event}:done`, { ...data, durationMs });
+  }
+
+  stageFail(event: string, error: string, data?: Record<string, unknown>): void {
+    const start = this.stageStartMs.get(event);
+    const durationMs = start !== undefined ? Date.now() - start : undefined;
+    this.push(`${event}:failed`, { ...data, error, durationMs });
+    this.log.errors.push(`[${event}] ${error}`);
+    this.flush();
+  }
+
+  fileWritten(filePath: string): void {
+    if (!this.log.filesWritten.includes(filePath)) {
+      this.log.filesWritten.push(filePath);
+      this.flush();
+    }
+  }
+
+  finish(): void {
+    this.log.endedAt = new Date().toISOString();
+    this.log.totalDurationMs = Date.now() - this.startMs;
+    this.flush();
+  }
+
+  printSummary(): void {
+    const dur = this.log.totalDurationMs
+      ? ` in ${(this.log.totalDurationMs / 1000).toFixed(1)}s`
+      : "";
+    const errPart = this.log.errors.length > 0
+      ? chalk.yellow(` · ${this.log.errors.length} error(s)`)
+      : "";
+    console.log(
+      chalk.gray(`\n  Run ID: ${chalk.white(this.runId)}${dur}`) +
+      chalk.gray(` · ${this.log.filesWritten.length} file(s) written`) +
+      errPart
+    );
+    console.log(chalk.gray(`  Log   : ${path.relative(this.workingDir, this.logPath)}`));
+  }
+
+  private push(event: string, data?: Record<string, unknown>): void {
+    this.log.entries.push({ ts: new Date().toISOString(), event, ...( data ? { data } : {}) });
+    this.flush();
+  }
+
+  private flush(): void {
+    fs.ensureDir(path.dirname(this.logPath))
+      .then(() => fs.writeJson(this.logPath, this.log, { spaces: 2 }))
+      .catch(() => {}); // logging must never crash the main pipeline
+  }
+}
+
+// ─── RunId ────────────────────────────────────────────────────────────────────
+
+export function generateRunId(): string {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const time = now.toTimeString().slice(0, 8).replace(/:/g, "");
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `${date}-${time}-${rand}`;
+}
+
+// ─── Module-level singleton ────────────────────────────────────────────────────
+
+let _activeLogger: RunLogger | null = null;
+
+export function setActiveLogger(logger: RunLogger): void {
+  _activeLogger = logger;
+}
+
+export function getActiveLogger(): RunLogger | null {
+  return _activeLogger;
+}

package/core/run-snapshot.ts

@@ -0,0 +1,84 @@
+import * as fs from "fs-extra";
+import * as path from "path";
+
+const BACKUP_DIR = ".ai-spec-backup";
+
+// ─── RunSnapshot ──────────────────────────────────────────────────────────────
+/**
+ * Before a file is overwritten, copy its original content to
+ * `.ai-spec-backup/<runId>/<relative-path>`.
+ *
+ * Call `restore()` to roll back all changes made in this run.
+ */
+export class RunSnapshot {
+  private readonly backupRoot: string;
+  private readonly snapshotted = new Set<string>();
+
+  constructor(
+    private readonly workingDir: string,
+    readonly runId: string
+  ) {
+    this.backupRoot = path.join(workingDir, BACKUP_DIR, runId);
+  }
+
+  /**
+   * Snapshot a file before it gets overwritten.
+   * No-op if the file does not exist yet (new file — nothing to restore).
+   * No-op if this file was already snapshotted in this run.
+   */
+  async snapshotFile(filePath: string): Promise<void> {
+    const fullPath = path.isAbsolute(filePath)
+      ? filePath
+      : path.join(this.workingDir, filePath);
+
+    if (!(await fs.pathExists(fullPath))) return;
+    if (this.snapshotted.has(fullPath)) return;
+
+    const relative = path.relative(this.workingDir, fullPath);
+    const dest = path.join(this.backupRoot, relative);
+    await fs.ensureDir(path.dirname(dest));
+    await fs.copy(fullPath, dest);
+    this.snapshotted.add(fullPath);
+  }
+
+  /** Restore all snapshotted files. Returns list of restored relative paths. */
+  async restore(): Promise<string[]> {
+    if (!(await fs.pathExists(this.backupRoot))) return [];
+
+    const restored: string[] = [];
+    const walk = async (dir: string) => {
+      for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await walk(full);
+        } else {
+          const relative = path.relative(this.backupRoot, full);
+          const dest = path.join(this.workingDir, relative);
+          await fs.ensureDir(path.dirname(dest));
+          await fs.copy(full, dest, { overwrite: true });
+          restored.push(relative);
+        }
+      }
+    };
+    await walk(this.backupRoot);
+    return restored;
+  }
+
+  get fileCount(): number {
+    return this.snapshotted.size;
+  }
+}
+
+// ─── Module-level singleton ────────────────────────────────────────────────────
+// Allows code-generator and error-feedback to access the active snapshot
+// without prop-drilling through every function signature.
+
+let _activeSnapshot: RunSnapshot | null = null;
+
+export function setActiveSnapshot(snapshot: RunSnapshot): void {
+  _activeSnapshot = snapshot;
+}
+
+export function getActiveSnapshot(): RunSnapshot | null {
+  return _activeSnapshot;
+}

package/core/spec-generator.ts

@@ -5,6 +5,7 @@ import axios from "axios";
 import { ProxyAgent } from "undici";
 import { specPrompt } from "../prompts/spec.prompt";
 import { ProjectContext } from "./context-loader";
+import { withReliability } from "./provider-utils";
 
 // ─── Proxy Helper ─────────────────────────────────────────────────────────────
 // 仅用于 Gemini：其他 SDK（Anthropic / OpenAI）会自动读取 HTTPS_PROXY。
@@ -207,12 +208,17 @@ export class GeminiProvider implements AIProvider {
   }
 
   async generate(prompt: string, systemInstruction?: string): Promise<string> {
-    const model = this.genAI.getGenerativeModel(
-      { model: this.modelName, ...(systemInstruction ? { systemInstruction } : {}) },
-      geminiRequestOptions()
+    return withReliability(
+      async () => {
+        const model = this.genAI.getGenerativeModel(
+          { model: this.modelName, ...(systemInstruction ? { systemInstruction } : {}) },
+          geminiRequestOptions()
+        );
+        const result = await model.generateContent(prompt);
+        return result.response.text();
+      },
+      { label: `${this.providerName}/${this.modelName}` }
     );
-    const result = await model.generateContent(prompt);
-    return result.response.text();
   }
 }
 
@@ -229,15 +235,20 @@ export class ClaudeProvider implements AIProvider {
   }
 
   async generate(prompt: string, systemInstruction?: string): Promise<string> {
-    const message = await this.client.messages.create({
-      model: this.modelName,
-      max_tokens: 8192,
-      ...(systemInstruction ? { system: systemInstruction } : {}),
-      messages: [{ role: "user", content: prompt }],
-    });
-    const block = message.content[0];
-    if (block.type === "text") return block.text;
-    throw new Error("Unexpected response type from Claude API");
+    return withReliability(
+      async () => {
+        const message = await this.client.messages.create({
+          model: this.modelName,
+          max_tokens: 8192,
+          ...(systemInstruction ? { system: systemInstruction } : {}),
+          messages: [{ role: "user", content: prompt }],
+        });
+        const block = message.content[0];
+        if (block.type === "text") return block.text;
+        throw new Error("Unexpected response type from Claude API");
+      },
+      { label: `${this.providerName}/${this.modelName}` }
+    );
   }
 }
 
@@ -270,25 +281,25 @@ export class OpenAICompatibleProvider implements AIProvider {
   }
 
   async generate(prompt: string, systemInstruction?: string): Promise<string> {
-    const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [];
-
-    if (systemInstruction) {
-      // o1/o3 require "developer" role; gpt-4o/gpt-4-turbo use "system"
-      // Auto-detect: if model starts with "o1" or "o3", use developer role
-      const isOSeries = /^o[13]/.test(this.modelName);
-      const role = isOSeries ? "developer" : this.systemRole;
-      messages.push({ role, content: systemInstruction } as OpenAI.Chat.ChatCompletionMessageParam);
-    }
-    messages.push({ role: "user", content: prompt });
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const completion = await (this.client.chat.completions.create as any)({
-      model: this.modelName,
-      messages,
-      ...(this.extraBody ? { extra_body: this.extraBody } : {}),
-    });
-
-    return (completion.choices[0].message.content as string) ?? "";
+    return withReliability(
+      async () => {
+        const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [];
+        if (systemInstruction) {
+          const isOSeries = /^o[13]/.test(this.modelName);
+          const role = isOSeries ? "developer" : this.systemRole;
+          messages.push({ role, content: systemInstruction } as OpenAI.Chat.ChatCompletionMessageParam);
+        }
+        messages.push({ role: "user", content: prompt });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const completion = await (this.client.chat.completions.create as any)({
+          model: this.modelName,
+          messages,
+          ...(this.extraBody ? { extra_body: this.extraBody } : {}),
+        });
+        return (completion.choices[0].message.content as string) ?? "";
+      },
+      { label: `${this.providerName}/${this.modelName}` }
+    );
   }
 }
 
@@ -310,41 +321,46 @@ export class MiMoProvider implements AIProvider {
   }
 
   async generate(prompt: string, systemInstruction?: string): Promise<string> {
-    const body: Record<string, unknown> = {
-      model: this.modelName,
-      max_tokens: 16384,
-      messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
-      top_p: 0.95,
-      stream: false,
-      temperature: 1.0,
-      stop_sequences: null,
-    };
-
-    if (systemInstruction) {
-      body.system = systemInstruction;
-    }
-
-    const response = await axios.post(this.baseUrl, body, {
-      headers: {
-        "api-key": this.apiKey,
-        "Content-Type": "application/json",
+    return withReliability(
+      async () => {
+        const body: Record<string, unknown> = {
+          model: this.modelName,
+          max_tokens: 16384,
+          messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
+          top_p: 0.95,
+          stream: false,
+          temperature: 1.0,
+          stop_sequences: null,
+        };
+
+        if (systemInstruction) {
+          body.system = systemInstruction;
+        }
+
+        const response = await axios.post(this.baseUrl, body, {
+          headers: {
+            "api-key": this.apiKey,
+            "Content-Type": "application/json",
+          },
+        });
+
+        // Response follows Anthropic format: { content: [{ type: "text"|"thinking", ... }] }
+        // MiMo may return a "thinking" block before the actual "text" block — skip it.
+        const data = response.data as { stop_reason?: string; content?: Array<{ type: string; text?: string; thinking?: string }> };
+        const blocks = data?.content ?? [];
+
+        const textBlock = blocks.find((b) => b.type === "text");
+        if (textBlock?.text) return textBlock.text;
+
+        // If stop_reason is max_tokens, the model was cut off mid-generation (thinking block only)
+        if (data?.stop_reason === "max_tokens") {
+          throw new Error(`MiMo response truncated (max_tokens reached). The prompt may be too long. Try a shorter spec or switch to a model with larger context.`);
+        }
+
+        throw new Error(`Unexpected MiMo response: ${JSON.stringify(response.data).slice(0, 200)}`);
       },
-    });
-
-    // Response follows Anthropic format: { content: [{ type: "text"|"thinking", ... }] }
-    // MiMo may return a "thinking" block before the actual "text" block — skip it.
-    const data = response.data as { stop_reason?: string; content?: Array<{ type: string; text?: string; thinking?: string }> };
-    const blocks = data?.content ?? [];
-
-    const textBlock = blocks.find((b) => b.type === "text");
-    if (textBlock?.text) return textBlock.text;
-
-    // If stop_reason is max_tokens, the model was cut off mid-generation (thinking block only)
-    if (data?.stop_reason === "max_tokens") {
-      throw new Error(`MiMo response truncated (max_tokens reached). The prompt may be too long. Try a shorter spec or switch to a model with larger context.`);
-    }
-
-    throw new Error(`Unexpected MiMo response: ${JSON.stringify(response.data).slice(0, 200)}`);
+      { label: `${this.providerName}/${this.modelName}` }
+    );
   }
 }
 

package/core/task-generator.ts

@@ -155,10 +155,18 @@ export async function loadTasksForSpec(specFilePath: string): Promise<SpecTask[]
   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);
+  if (!(await fs.pathExists(tasksFile))) return null;
+  try {
+    return await fs.readJson(tasksFile);
+  } catch {
+    // Corrupt or partially-written tasks file — warn and fall back to re-generation
+    // rather than crashing the entire CLI with a raw JSON parse error.
+    console.warn(
+      chalk.yellow(`  ⚠ Tasks file is corrupt or unreadable (${path.basename(tasksFile)}).`) +
+      chalk.gray(` Re-run \`ai-spec tasks <spec>\` to regenerate.`)
+    );
+    return null;
   }
-  return null;
 }
 
 /** Persist a single task's status to the tasks JSON file (checkpoint). */