ai-spec-dev 0.31.0 → 0.35.0

package/core/reviewer.ts

@@ -4,10 +4,37 @@ import * as path from "path";
 import * as fs from "fs-extra";
 import { AIProvider } from "./spec-generator";
 import {
+  specComplianceSystemPrompt,
   reviewArchitectureSystemPrompt,
   reviewImplementationSystemPrompt,
   reviewImpactComplexitySystemPrompt,
 } from "../prompts/codegen.prompt";
+import { CONSTITUTION_FILE } from "./constitution-generator";
+
+// ─── Constitution Lessons Helper ──────────────────────────────────────────────
+
+/**
+ * Extract the §9 accumulated lessons section from a constitution file.
+ * Returns null if the section is absent or the file cannot be read.
+ */
+async function loadAccumulatedLessons(projectRoot: string): Promise<string | null> {
+  const constitutionPath = path.join(projectRoot, CONSTITUTION_FILE);
+  let content: string;
+  try {
+    content = await fs.readFile(constitutionPath, "utf-8");
+  } catch {
+    return null;
+  }
+  const marker = "## 9. 积累教训";
+  const idx = content.indexOf(marker);
+  if (idx === -1) return null;
+  // Extract from §9 header to end of file (or next top-level section)
+  const section = content.slice(idx);
+  const nextSection = section.slice(marker.length).match(/\n## \d/);
+  return nextSection
+    ? section.slice(0, marker.length + nextSection.index!)
+    : section;
+}
 
 // ─── Review History ────────────────────────────────────────────────────────────
 
@@ -15,6 +42,7 @@ interface ReviewHistoryEntry {
   date: string;
   specFile: string;
   score: number;
+  complianceScore?: number;
   topIssues: string[];
   impactLevel?: "低" | "中" | "高";
   complexityLevel?: "低" | "中" | "高";
@@ -55,6 +83,18 @@ function extractScore(reviewText: string): number {
   return match ? parseFloat(match[1]) : 0;
 }
 
+/** Extract compliance score from Pass 0 output (looks for "ComplianceScore: X/10") */
+export function extractComplianceScore(complianceText: string): number {
+  const match = complianceText.match(/ComplianceScore:\s*(\d+(?:\.\d+)?)\s*\/\s*10/i);
+  return match ? parseFloat(match[1]) : 0;
+}
+
+/** Count missing requirements from Pass 0 output */
+export function extractMissingCount(complianceText: string): number {
+  const summaryMatch = complianceText.match(/Missing:\s*(\d+)/i);
+  return summaryMatch ? parseInt(summaryMatch[1], 10) : 0;
+}
+
 /** Extract impact level from Pass 3 review ("影响等级：低/中/高") */
 function extractImpactLevel(reviewText: string): "低" | "中" | "高" | undefined {
   const match = reviewText.match(/影响等级[：:]\s*(低|中|高)/);
@@ -126,8 +166,9 @@ export class CodeReviewer {
   }
 
   /**
-   * Three-pass review:
-   *   Pass 1 — architecture (spec compliance, layer separation, auth)
+   * Four-pass review:
+   *   Pass 0 — spec compliance (exhaustive requirement coverage audit)
+   *   Pass 1 — architecture (layer separation, contract design, auth posture)
    *   Pass 2 — implementation details (validation, error handling, edge cases)
    *             + historical issue recurrence check
    *   Pass 3 — impact assessment + code complexity
@@ -137,11 +178,43 @@ export class CodeReviewer {
     codeContext: string,
     specFile?: string
   ): Promise<string> {
-    console.log(chalk.gray("  Pass 1/3: Architecture review..."));
+    // ── Pass 0: Spec Compliance (skip if no spec provided) ───────────────────
+    let complianceReview = "";
+    if (specContent && specContent.trim() && specContent !== "(No spec — review for general code quality)") {
+      console.log(chalk.gray("  Pass 0/3: Spec compliance check..."));
+      const compliancePrompt = `Check whether the implementation covers every requirement in the spec.
 
-    // ── Pass 1: Architecture ──────────────────────────────────────────────────
-    const archPrompt = `Review the architecture of this change.
+=== Feature Spec ===
+${specContent}
+
+=== Code ===
+${codeContext}`;
+      complianceReview = await this.provider.generate(compliancePrompt, specComplianceSystemPrompt);
+
+      // Surface compliance score immediately
+      const complianceScore = extractComplianceScore(complianceReview);
+      const missingCount = extractMissingCount(complianceReview);
+      if (complianceScore > 0) {
+        const scoreColor = complianceScore >= 8 ? chalk.green : complianceScore >= 6 ? chalk.yellow : chalk.red;
+        console.log(
+          chalk.gray("  Pass 0 result: ") +
+          scoreColor(`ComplianceScore ${complianceScore}/10`) +
+          (missingCount > 0 ? chalk.red(` · ${missingCount} missing requirement(s)`) : chalk.green(" · all requirements covered"))
+        );
+      }
+    }
 
+    console.log(chalk.gray(`  Pass 1/3: Architecture review...`));
+
+    // ── Pass 1: Architecture (+ §9 lessons cross-check) ──────────────────────
+    const accumulatedLessons = await loadAccumulatedLessons(this.projectRoot);
+    const archPrompt = `Review the architecture of this change.
+${complianceReview
+  ? `\n=== Spec Compliance Report (Pass 0 — already audited, do NOT re-audit missing requirements) ===\n${complianceReview}\n`
+  : ""}
+${accumulatedLessons
+  ? `\n=== §9 历史积累教训 (Accumulated Lessons — check if any are repeated in this code) ===\n${accumulatedLessons}\n`
+  : ""}
 === Feature Spec ===
 ${specContent || "(No spec — review for general code quality)"}
 
@@ -189,10 +262,14 @@ ${implReview}`;
 
     // ── Combine ───────────────────────────────────────────────────────────────
     const sep = "─".repeat(52);
-    const combined = `${archReview}\n\n${sep}\n\n${implReview}\n\n${sep}\n\n${impactReview}`;
+    const parts = complianceReview
+      ? [complianceReview, archReview, implReview, impactReview]
+      : [archReview, implReview, impactReview];
+    const combined = parts.join(`\n\n${sep}\n\n`);
 
     // ── Persist history ───────────────────────────────────────────────────────
     const score = extractScore(implReview) || extractScore(archReview);
+    const complianceScore = extractComplianceScore(complianceReview);
     const topIssues = extractTopIssues(implReview);
     const impactLevel = extractImpactLevel(impactReview);
     const complexityLevel = extractComplexityLevel(impactReview);
@@ -201,6 +278,7 @@ ${implReview}`;
         date: new Date().toISOString().slice(0, 10),
         specFile: path.relative(this.projectRoot, specFile),
         score,
+        ...(complianceScore > 0 ? { complianceScore } : {}),
         topIssues,
         ...(impactLevel ? { impactLevel } : {}),
         ...(complexityLevel ? { complexityLevel } : {}),

package/core/run-logger.ts

@@ -4,6 +4,86 @@ import chalk from "chalk";
 
 const LOG_DIR = ".ai-spec-logs";
 
+// ─── JSONL helpers ────────────────────────────────────────────────────────────
+// Each event is synchronously appended as one JSON line to a `.jsonl` shadow
+// file alongside the full `.json`. If the process crashes mid-run the `.json`
+// may be empty or stale, but every line written to the `.jsonl` is durable.
+// `loadRunLogs` (run-trend.ts) can reconstruct a RunLog from orphan `.jsonl`
+// files for crash recovery.
+
+function appendJsonlLine(filePath: string, record: Record<string, unknown>): void {
+  try {
+    fs.appendFileSync(filePath, JSON.stringify(record) + "\n");
+  } catch {
+    // JSONL write must never crash the pipeline
+  }
+}
+
+/** Reconstruct a RunLog from a `.jsonl` file (crash recovery path). */
+export function reconstructRunLogFromJsonl(jsonlPath: string): RunLog | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(jsonlPath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const log: Partial<RunLog> & { entries: LogEntry[]; filesWritten: string[]; errors: string[] } = {
+    entries: [],
+    filesWritten: [],
+    errors: [],
+    runId: "",
+    startedAt: "",
+    workingDir: "",
+  };
+
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const rec = JSON.parse(trimmed) as Record<string, unknown>;
+      switch (rec["type"]) {
+        case "header":
+          log.runId      = rec["runId"]      as string;
+          log.startedAt  = rec["startedAt"]  as string;
+          log.workingDir = rec["workingDir"] as string;
+          if (rec["provider"]) log.provider = rec["provider"] as string;
+          if (rec["model"])    log.model    = rec["model"]    as string;
+          if (rec["specPath"]) log.specPath  = rec["specPath"] as string;
+          break;
+        case "meta":
+          if (rec["key"] === "promptHash")  log.promptHash  = rec["value"] as string;
+          if (rec["key"] === "harnessScore") log.harnessScore = rec["value"] as number;
+          break;
+        case "entry":
+          log.entries.push({
+            ts: rec["ts"] as string,
+            event: rec["event"] as string,
+            ...(rec["durationMs"] !== undefined ? { durationMs: rec["durationMs"] as number } : {}),
+            ...(rec["data"] ? { data: rec["data"] as Record<string, unknown> } : {}),
+          });
+          break;
+        case "file":
+          if (rec["path"]) log.filesWritten.push(rec["path"] as string);
+          break;
+        case "error":
+          if (rec["message"]) log.errors.push(rec["message"] as string);
+          break;
+        case "footer":
+          if (rec["endedAt"])        log.endedAt        = rec["endedAt"]        as string;
+          if (rec["totalDurationMs"]) log.totalDurationMs = rec["totalDurationMs"] as number;
+          if (rec["harnessScore"])   log.harnessScore   = rec["harnessScore"]   as number;
+          break;
+      }
+    } catch {
+      // corrupt line — skip
+    }
+  }
+
+  if (!log.runId || !log.startedAt) return null;
+  return log as RunLog;
+}
+
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export interface LogEntry {
@@ -42,6 +122,7 @@ export class RunLogger {
   private log: RunLog;
   private readonly startMs: number;
   private readonly logPath: string;
+  private readonly jsonlPath: string;
   private readonly stageStartMs = new Map<string, number>();
 
   constructor(
@@ -50,7 +131,8 @@ export class RunLogger {
     meta?: { provider?: string; model?: string; specPath?: string }
   ) {
     this.startMs = Date.now();
-    this.logPath = path.join(workingDir, LOG_DIR, `${runId}.json`);
+    this.logPath  = path.join(workingDir, LOG_DIR, `${runId}.json`);
+    this.jsonlPath = path.join(workingDir, LOG_DIR, `${runId}.jsonl`);
     this.log = {
       runId,
       startedAt: new Date().toISOString(),
@@ -60,6 +142,16 @@ export class RunLogger {
       filesWritten: [],
       errors: [],
     };
+    // Write JSONL header immediately — ensures the file exists even on early crash
+    fs.ensureDir(path.dirname(this.jsonlPath)).then(() => {
+      appendJsonlLine(this.jsonlPath, {
+        type: "header",
+        runId,
+        startedAt: this.log.startedAt,
+        workingDir,
+        ...meta,
+      });
+    }).catch(() => {});
     this.flush();
   }
 
@@ -78,25 +170,30 @@ export class RunLogger {
     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}`);
+    const errorMsg = `[${event}] ${error}`;
+    this.log.errors.push(errorMsg);
+    appendJsonlLine(this.jsonlPath, { type: "error", message: errorMsg });
     this.flush();
   }
 
   /** Record the prompt hash for this run (call once at run start). */
   setPromptHash(hash: string): void {
     this.log.promptHash = hash;
+    appendJsonlLine(this.jsonlPath, { type: "meta", key: "promptHash", value: hash });
     this.flush();
   }
 
   /** Record the harness self-eval score (call once at run end). */
   setHarnessScore(score: number): void {
     this.log.harnessScore = score;
+    appendJsonlLine(this.jsonlPath, { type: "meta", key: "harnessScore", value: score });
     this.flush();
   }
 
   fileWritten(filePath: string): void {
     if (!this.log.filesWritten.includes(filePath)) {
       this.log.filesWritten.push(filePath);
+      appendJsonlLine(this.jsonlPath, { type: "file", path: filePath });
       this.flush();
     }
   }
@@ -104,6 +201,12 @@ export class RunLogger {
   finish(): void {
     this.log.endedAt = new Date().toISOString();
     this.log.totalDurationMs = Date.now() - this.startMs;
+    appendJsonlLine(this.jsonlPath, {
+      type: "footer",
+      endedAt: this.log.endedAt,
+      totalDurationMs: this.log.totalDurationMs,
+      harnessScore: this.log.harnessScore,
+    });
     this.flush();
   }
 
@@ -123,7 +226,10 @@ export class RunLogger {
   }
 
   private push(event: string, data?: Record<string, unknown>): void {
-    this.log.entries.push({ ts: new Date().toISOString(), event, ...( data ? { data } : {}) });
+    const entry: LogEntry = { ts: new Date().toISOString(), event, ...(data ? { data } : {}) };
+    this.log.entries.push(entry);
+    // Append to JSONL synchronously — durable even on crash
+    appendJsonlLine(this.jsonlPath, { type: "entry", ...entry });
     this.flush();
   }
 

package/core/run-trend.ts

@@ -0,0 +1,261 @@
+import * as fs from "fs-extra";
+import * as path from "path";
+import chalk from "chalk";
+import { RunLog, reconstructRunLogFromJsonl } from "./run-logger";
+
+const LOG_DIR = ".ai-spec-logs";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface TrendEntry {
+  runId: string;
+  startedAt: string;
+  promptHash: string | null;
+  harnessScore: number | null;
+  specPath: string | null;
+  provider: string | null;
+  model: string | null;
+  filesWritten: number;
+  totalDurationMs: number | null;
+  errors: number;
+}
+
+export interface PromptGroupSummary {
+  promptHash: string;
+  runs: number;
+  avg: number;
+  best: number;
+  worst: number;
+  firstSeen: string;
+  lastSeen: string;
+  /** true if this is the most recently used prompt hash */
+  isCurrent: boolean;
+}
+
+export interface TrendReport {
+  entries: TrendEntry[];
+  promptGroups: PromptGroupSummary[];
+  totalRuns: number;
+}
+
+// ─── Loader ──────────────────────────────────────────────────────────────────
+
+/**
+ * Read all RunLog JSON files from `.ai-spec-logs/`, sorted newest-first.
+ * Silently skips unreadable / corrupt files.
+ */
+export async function loadRunLogs(workingDir: string): Promise<RunLog[]> {
+  const logDir = path.join(workingDir, LOG_DIR);
+  if (!(await fs.pathExists(logDir))) return [];
+
+  const files = await fs.readdir(logDir);
+  const jsonFiles  = new Set(files.filter((f) => f.endsWith(".json")));
+  const jsonlFiles = files.filter((f) => f.endsWith(".jsonl")).sort().reverse();
+
+  const logs: RunLog[] = [];
+  const seenRunIds = new Set<string>();
+
+  // Primary path: read complete .json files (newest-first)
+  for (const file of [...jsonFiles].sort().reverse()) {
+    try {
+      const log: RunLog = await fs.readJson(path.join(logDir, file));
+      if (log.runId && log.startedAt) {
+        logs.push(log);
+        seenRunIds.add(log.runId);
+      }
+    } catch {
+      // corrupt file — skip silently
+    }
+  }
+
+  // Crash-recovery path: reconstruct from orphan .jsonl files (no matching .json)
+  for (const file of jsonlFiles) {
+    const runId = file.replace(/\.jsonl$/, "");
+    if (seenRunIds.has(runId)) continue; // already loaded via .json
+    const correspondingJson = `${runId}.json`;
+    if (jsonFiles.has(correspondingJson)) continue; // .json exists, prefer it
+    const log = reconstructRunLogFromJsonl(path.join(logDir, file));
+    if (log) {
+      logs.push(log);
+      seenRunIds.add(log.runId);
+    }
+  }
+
+  // Sort newest-first by startedAt
+  logs.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+  return logs;
+}
+
+// ─── Aggregation ─────────────────────────────────────────────────────────────
+
+export function buildTrendReport(
+  logs: RunLog[],
+  opts: { last?: number; promptFilter?: string } = {}
+): TrendReport {
+  let entries: TrendEntry[] = logs.map((log) => ({
+    runId: log.runId,
+    startedAt: log.startedAt,
+    promptHash: log.promptHash ?? null,
+    harnessScore: log.harnessScore ?? null,
+    specPath: log.specPath ?? null,
+    provider: log.provider ?? null,
+    model: log.model ?? null,
+    filesWritten: log.filesWritten?.length ?? 0,
+    totalDurationMs: log.totalDurationMs ?? null,
+    errors: log.errors?.length ?? 0,
+  }));
+
+  // filter: only runs with a harnessScore (create runs)
+  entries = entries.filter((e) => e.harnessScore !== null);
+
+  // filter by prompt hash if requested
+  if (opts.promptFilter) {
+    entries = entries.filter((e) =>
+      e.promptHash?.startsWith(opts.promptFilter!)
+    );
+  }
+
+  // limit to last N
+  if (opts.last && opts.last > 0) {
+    entries = entries.slice(0, opts.last);
+  }
+
+  // build prompt group summaries (only from filtered entries)
+  const groupMap = new Map<string, TrendEntry[]>();
+  for (const e of entries) {
+    const key = e.promptHash ?? "(none)";
+    if (!groupMap.has(key)) groupMap.set(key, []);
+    groupMap.get(key)!.push(e);
+  }
+
+  // determine "current" = the prompt hash of the most recent run
+  const currentHash = entries[0]?.promptHash ?? null;
+
+  const promptGroups: PromptGroupSummary[] = [];
+  for (const [hash, group] of groupMap.entries()) {
+    const scores = group.map((e) => e.harnessScore as number);
+    promptGroups.push({
+      promptHash: hash,
+      runs: group.length,
+      avg: Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 10) / 10,
+      best: Math.max(...scores),
+      worst: Math.min(...scores),
+      firstSeen: group[group.length - 1].startedAt,
+      lastSeen: group[0].startedAt,
+      isCurrent: hash === currentHash,
+    });
+  }
+
+  // sort groups: most recently used first
+  promptGroups.sort((a, b) => b.lastSeen.localeCompare(a.lastSeen));
+
+  return { entries, promptGroups, totalRuns: entries.length };
+}
+
+// ─── Display ─────────────────────────────────────────────────────────────────
+
+function scoreBar(score: number): string {
+  const filled = Math.round(score);
+  return "█".repeat(filled) + "░".repeat(10 - filled);
+}
+
+function scoreColor(score: number, text: string): string {
+  if (score >= 8) return chalk.green(text);
+  if (score >= 6) return chalk.yellow(text);
+  return chalk.red(text);
+}
+
+function formatDate(iso: string): string {
+  return iso.slice(0, 10); // YYYY-MM-DD
+}
+
+function formatDuration(ms: number | null): string {
+  if (ms === null) return "  —  ";
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  return `${Math.floor(s / 60)}m${s % 60}s`;
+}
+
+function shortSpec(specPath: string | null): string {
+  if (!specPath) return chalk.gray("—");
+  return path.basename(specPath);
+}
+
+export function printTrendReport(report: TrendReport, workingDir: string): void {
+  const { entries, promptGroups } = report;
+
+  console.log(chalk.cyan("\n─── Harness Trend ───────────────────────────────────────────"));
+
+  if (entries.length === 0) {
+    console.log(chalk.gray("  No scored runs found. Run `ai-spec create` to start tracking."));
+    console.log(chalk.cyan("─".repeat(63)));
+    return;
+  }
+
+  // ── Prompt Version Summary ────────────────────────────────────────
+  if (promptGroups.length > 0) {
+    console.log(chalk.bold("\n  Prompt Versions:\n"));
+
+    const colWidths = {
+      hash:  10,
+      runs:   5,
+      avg:    5,
+      best:   5,
+      worst:  5,
+    };
+
+    // header
+    console.log(
+      chalk.gray(
+        "  " +
+        "Hash      ".padEnd(colWidths.hash) + " " +
+        "Runs ".padStart(colWidths.runs) + " " +
+        "  Avg" + " " +
+        " Best" + " " +
+        "Worst" + "  " +
+        "Last seen"
+      )
+    );
+    console.log(chalk.gray("  " + "─".repeat(55)));
+
+    for (const g of promptGroups) {
+      const currentMark = g.isCurrent ? chalk.cyan(" ◀ current") : "";
+      const avgStr = scoreColor(g.avg, g.avg.toFixed(1).padStart(5));
+      const bestStr = chalk.green(g.best.toFixed(1).padStart(5));
+      const worstStr = g.worst < 6 ? chalk.red(g.worst.toFixed(1).padStart(5)) : chalk.yellow(g.worst.toFixed(1).padStart(5));
+
+      console.log(
+        "  " +
+        chalk.white(g.promptHash.padEnd(colWidths.hash)) + " " +
+        chalk.gray(String(g.runs).padStart(colWidths.runs)) + " " +
+        avgStr + " " +
+        bestStr + " " +
+        worstStr + "  " +
+        chalk.gray(formatDate(g.lastSeen)) +
+        currentMark
+      );
+    }
+  }
+
+  // ── Run History ───────────────────────────────────────────────────
+  console.log(chalk.bold("\n  Run History:\n"));
+
+  for (const e of entries) {
+    const score = e.harnessScore as number;
+    const bar   = scoreColor(score, `[${scoreBar(score)}]`);
+    const scoreStr = scoreColor(score, score.toFixed(1).padStart(4));
+    const hash  = e.promptHash ? chalk.gray(e.promptHash) : chalk.gray("(no hash)");
+    const dur   = chalk.gray(formatDuration(e.totalDurationMs));
+    const errMark = e.errors > 0 ? chalk.yellow(` ⚠${e.errors}err`) : "";
+    const spec  = chalk.gray(shortSpec(e.specPath));
+
+    console.log(
+      `  ${chalk.gray(formatDate(e.startedAt))}  ${bar}${scoreStr}  ${hash}  ${dur}${errMark}  ${spec}`
+    );
+  }
+
+  // ── Footer ────────────────────────────────────────────────────────
+  const logRelDir = path.relative(workingDir, path.join(workingDir, LOG_DIR));
+  console.log(chalk.gray(`\n  ${entries.length} run(s) shown  ·  logs: ${logRelDir}/`));
+  console.log(chalk.cyan("─".repeat(63)));
+}