ai-spec-dev 0.17.0 → 0.24.0

package/core/code-generator.ts

@@ -34,37 +34,166 @@ function buildInstalledPackagesSection(context?: ProjectContext): string {
 }
 
 /**
- * Build a context section from files already written in this generation run.
- * Injected before generating files that may import from those paths (e.g., route files
- * importing from API files generated in an earlier task).
- */
-/**
- * Extract all export declaration lines from a file's content.
- * This gives precise signal about every exported name without including
- * implementation details, and works regardless of file length.
- * Falls back to first 3000 chars for CommonJS or files with no explicit exports.
+ * 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.
  */
-function extractExportSignatures(content: string): string {
-  const exportLines = content
-    .split("\n")
-    .filter((line) => line.trimStart().startsWith("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 ──────
+    // Capture the full block so downstream tasks see the complete contract.
+    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 ───────────────
+    // Pinia stores wrap all actions inside defineStore(). Without the full block
+    // the consumer only sees "export const useTaskStore = defineStore(" and has
+    // to guess every action name — the primary source of fetchTasks→fetchTaskList
+    // hallucinations. Capture the complete defineStore(...) call so the return
+    // object (public API) is visible.
+    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 ─────────────────
+    // In Pinia composition-API stores and Vue composables the return object is
+    // the definitive list of exposed names. Capture it so consumers see the
+    // exact exported identifiers (e.g. "fetchTasks" not "fetchTaskList").
+    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 ───────────────────
+    // Needed for React components (export default function Foo()) and Vue
+    // composables (export default class Foo {}). Without full-block capture the
+    // consumer only sees the opening line and can't know the return shape.
+    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);
+    }
 
-  if (exportLines.length > 0) {
-    return exportLines.join("\n");
+    i++;
   }
 
-  // Fallback for CommonJS or files without top-level export keywords
-  return content.slice(0, 3000) + (content.length > 3000 ? "\n... (truncated)" : "");
+  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.
+ * Injected before generating files that may import from those paths (e.g., route files
+ * importing from API files generated in an earlier task).
+ */
 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) {
+    // View/page components: only show the path as a name sentinel.
+    // The router needs to know the exact filename (e.g. TaskManagement.vue, NOT index.vue).
+    const isViewFile = /src[\\/](views?|pages?)[\\/]/i.test(filePath);
+    if (isViewFile) {
+      lines.push(`\n// exists: ${filePath}`);
+      continue;
+    }
     lines.push(`\n--- ${filePath} ---`);
-    lines.push(extractExportSignatures(content));
+    // Store and composable files: pass full content — the entire file IS the contract
+    const isStoreOrComposable = /src[\\/](stores?|composables?)[\\/]/i.test(filePath);
+    lines.push(isStoreOrComposable ? content : extractBehavioralContract(content));
   }
   return lines.join("\n") + "\n";
 }
@@ -452,7 +581,10 @@ Output ONLY a valid JSON array:
     }
 
     // ── Group pending tasks by layer in dependency order ──────────────────────
-    const LAYER_ORDER = ["data", "infra", "service", "api", "test"];
+    // Frontend layer chain:
+    //   service (api call fns) → api (stores) → view (page components) → route (router files) → test
+    // "route" sits after "view" so router files see the exact filenames of view components in cache.
+    const LAYER_ORDER = ["data", "infra", "service", "api", "view", "route", "test"];
     const layerGroups: Array<{ layer: string; tasks: SpecTask[] }> = [];
 
     for (const layer of LAYER_ORDER) {
@@ -480,11 +612,9 @@ Output ONLY a valid JSON array:
         printTaskProgress(completedTasks, tasks.length, layerTasks[0], "run");
       }
 
-      // Snapshot the cache before this layer starts — all parallel tasks in the same
-      // layer see the same (pre-layer) cache, preventing partial-write races.
-      const generatedFilesSection = buildGeneratedFilesSection(generatedFileCache);
-
-      // ── Execute all tasks in this layer concurrently ──────────────────────
+      // ── Execute tasks in this layer in topological batch order ─────────────
+      // Tasks with intra-layer dependencies run in separate sequential batches;
+      // independent tasks within a batch run in parallel.
       interface TaskResult {
         task: SpecTask;
         files: string[];
@@ -494,9 +624,9 @@ Output ONLY a valid JSON array:
         impliesRegistration: boolean;
       }
 
-      const taskResultPromises: Promise<TaskResult>[] = layerTasks.map(async (task) => {
+      const executeTask = async (task: SpecTask, batchIsParallel: boolean): Promise<TaskResult> => {
         if (task.filesToTouch.length === 0) {
-          if (!isParallel) console.log(chalk.gray("    No files specified, skipping."));
+          if (!batchIsParallel) console.log(chalk.gray("    No files specified, skipping."));
           return { task, files: [], createdFiles: [], success: 0, total: 0, impliesRegistration: false };
         }
 
@@ -517,9 +647,15 @@ Output ONLY a valid JSON array:
         // Determine if this task creates registerable artifacts (for post-layer shared config update)
         const createsNewFiles = filePlan.some((f) => f.action === "create");
         const taskText = `${task.title} ${task.description}`.toLowerCase();
+        // Layer-based check: "route", "view", and "api" layers always imply
+        // registration (route index / store index update) when they create new files.
+        // Text-keyword check is a fallback for layers not explicitly listed.
         const impliesRegistration =
           createsNewFiles &&
-          (taskText.includes("route") ||
+          (task.layer === "route" ||
+            task.layer === "view" ||
+            task.layer === "api" ||
+            taskText.includes("route") ||
             taskText.includes("router") ||
             taskText.includes("page") ||
             taskText.includes("view") ||
@@ -537,14 +673,17 @@ Output ONLY a valid JSON array:
           return { task, files: [], createdFiles: [], success: 0, total: 0, impliesRegistration };
         }
 
+        // Re-snapshot the cache at task execution time so intra-layer earlier
+        // batches' output is visible to later batches.
+        const currentGeneratedFilesSection = buildGeneratedFilesSection(generatedFileCache);
         const taskContext = `Task: ${task.id} — ${task.title}\n${task.description}\nAcceptance: ${task.acceptanceCriteria.join("; ")}`;
         const { success, total, files } = await this.generateFiles(
           filePlan,
           `${spec}\n\n=== Current Task ===\n${taskContext}`,
           workingDir,
-          constitutionSection + frontendSection + sharedConfigSection + generatedFilesSection,
+          constitutionSection + frontendSection + sharedConfigSection + currentGeneratedFilesSection,
           systemPrompt,
-          isParallel ? task.id : undefined  // prefix output lines with task ID in parallel mode
+          batchIsParallel ? task.id : undefined  // prefix output lines with task ID in parallel mode
         );
 
         const createdFiles = filePlan
@@ -552,9 +691,41 @@ Output ONLY a valid JSON array:
           .map((fp) => fp.file);
 
         return { task, files, createdFiles, success, total, impliesRegistration };
-      });
-
-      const layerResults = await Promise.all(taskResultPromises);
+      };
+
+      // Helper: update generatedFileCache from a completed batch's results.
+      // Called after each batch so the next batch sees the prior batch's exports.
+      const updateCacheFromBatch = async (results: TaskResult[]) => {
+        for (const result of results) {
+          for (const writtenFile of result.files) {
+            const isCodeFile = /src[\\/](api[s]?|services?|stores?|composables?)[\\/]/i.test(writtenFile);
+            // View/page files: cache a sentinel so router layer knows the exact filename.
+            const isViewFile = /src[\\/](views?|pages?)[\\/]/i.test(writtenFile);
+            if (isCodeFile || isViewFile) {
+              try {
+                const content = isViewFile
+                  ? `// view component — use this exact path for router imports`
+                  : await fs.readFile(path.join(workingDir, writtenFile), "utf-8");
+                generatedFileCache.set(writtenFile, content);
+              } catch { /* ignore */ }
+            }
+          }
+        }
+      };
+
+      // Partition tasks into topological batches (respects dependencies field).
+      // Each batch runs in parallel; batches run sequentially.
+      const taskBatches = topoSortLayerTasks(layerTasks);
+      const layerResults: TaskResult[] = [];
+
+      for (const batch of taskBatches) {
+        const batchIsParallel = batch.length > 1;
+        const batchResultPromises = batch.map((task) => executeTask(task, batchIsParallel));
+        const batchResults = await Promise.all(batchResultPromises);
+        layerResults.push(...batchResults);
+        // Update cache after each batch so the next batch sees the exports.
+        await updateCacheFromBatch(batchResults);
+      }
 
       // ── Aggregate layer results ───────────────────────────────────────────
       if (isParallel) {
@@ -581,20 +752,6 @@ Output ONLY a valid JSON array:
 
       completedTasks += layerTasks.length;
 
-      // ── Update generatedFileCache with all files written in this layer ────
-      // Done after all parallel tasks complete — ensures the next layer sees
-      // the full set of exports from this layer, not a partial view.
-      for (const result of layerResults) {
-        for (const writtenFile of result.files) {
-          if (/src[\\/](api[s]?|services?|stores?|composables?)[\\/]/.test(writtenFile)) {
-            try {
-              const content = await fs.readFile(path.join(workingDir, writtenFile), "utf-8");
-              generatedFileCache.set(writtenFile, content);
-            } catch { /* ignore */ }
-          }
-        }
-      }
-
       // ── Post-layer: batch shared config update ────────────────────────────
       // If any task in this layer created registerable files, update shared config
       // files once using the complete list of new modules from the whole layer.
@@ -723,6 +880,67 @@ ${spec}`,
   }
 }
 
+// ─── 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.
+ */
+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 ───────────────────────────────────────────────────────
 
 const LAYER_ICONS: Record<string, string> = {
@@ -730,6 +948,8 @@ const LAYER_ICONS: Record<string, string> = {
   infra: "⚙️ ",
   service: "🔧",
   api: "🌐",
+  view: "🖥️ ",
+  route: "🗺️ ",
   test: "🧪",
 };
 

package/core/error-feedback.ts

@@ -164,8 +164,10 @@ function parseErrors(output: string, source: ErrorEntry["source"]): ErrorEntry[]
   const errors: ErrorEntry[] = [];
   if (!output.trim()) return errors;
 
-  // Take the last 80 lines — most relevant error output
-  const lines = output.split("\n").slice(-80);
+  // Scan the FULL output — actual errors with file:line refs appear early,
+  // not at the end. The old slice(-80) approach was discarding the first errors
+  // and only keeping the trailing summary, which caused the AI to fix the wrong things.
+  const lines = output.split("\n");
 
   for (const line of lines) {
     const trimmed = line.trim();
@@ -176,16 +178,22 @@ function parseErrors(output: string, source: ErrorEntry["source"]): ErrorEntry[]
     if (trimmed.startsWith("at ")) continue;
     if (trimmed.startsWith("Node.js ")) continue;
 
-    // Try to extract file path (supports TS/JS, Go, Python, Java, Rust, PHP)
+    // Only capture lines that reference a source file (file:line pattern).
+    // This filters out summary lines ("Found 12 errors.") and only keeps
+    // actionable entries the AI can actually fix.
     const fileMatch = trimmed.match(/^([^:]+\.(?:ts|js|tsx|jsx|go|py|java|rs|php)):\d+/);
+    if (!fileMatch) continue;
+
     errors.push({
       source,
-      message: trimmed.slice(0, 300),
-      file: fileMatch?.[1],
+      message: trimmed.slice(0, 400),
+      file: fileMatch[1],
     });
+
+    if (errors.length >= 20) break; // cap at 20 — first 20 are the most actionable
   }
 
-  return errors.slice(0, 20); // cap at 20 errors
+  return errors;
 }
 
 // ─── Auto-Fix ───────────────────────────────────────────────────────────────────

package/core/knowledge-memory.ts

@@ -146,6 +146,60 @@ export async function appendLessonsToConstitution(
   }
 }
 
+/**
+ * Directly append a freeform lesson to constitution §9.
+ * Zero-friction entry point — no AI call required.
+ */
+export async function appendDirectLesson(
+  projectRoot: string,
+  lessonText: string
+): Promise<{ appended: boolean; reason?: string }> {
+  const constitutionPath = path.join(projectRoot, CONSTITUTION_FILE);
+  let content = "";
+  try {
+    content = await fs.readFile(constitutionPath, "utf-8");
+  } catch {
+    return { appended: false, reason: "No constitution file found. Run `ai-spec init` first." };
+  }
+
+  // Dedup: check first 60 chars
+  const normalized = lessonText.toLowerCase().slice(0, 60);
+  if (content.toLowerCase().includes(normalized)) {
+    return { appended: false, reason: "Similar lesson already exists in the constitution." };
+  }
+
+  const date = new Date().toISOString().slice(0, 10);
+  const entry = `- 📝 **[${date}]** ${lessonText.trim()}`;
+  const hasMemorySection = content.includes(MEMORY_SECTION_MARKER);
+
+  let updatedContent: string;
+  if (hasMemorySection) {
+    const sectionStart = content.indexOf(MEMORY_SECTION_MARKER);
+    const afterHeader = sectionStart + MEMORY_SECTION_HEADER.length;
+    const nextSectionMatch = content.slice(afterHeader).match(/\n## \d/);
+    const insertPos = nextSectionMatch
+      ? afterHeader + nextSectionMatch.index!
+      : content.length;
+    updatedContent =
+      content.slice(0, insertPos) + entry + "\n" + content.slice(insertPos);
+  } else {
+    updatedContent = content + MEMORY_SECTION_HEADER + entry + "\n";
+  }
+
+  await fs.writeFile(constitutionPath, updatedContent, "utf-8");
+
+  const stats = parseConstitutionStats(updatedContent);
+  if (stats.lessonCount >= 8) {
+    console.log(
+      chalk.yellow(
+        `  ⚠ §9 now has ${stats.lessonCount} lessons. Run \`ai-spec init --consolidate\` to prune and rebase.`
+      )
+    );
+  }
+
+  return { appended: true };
+}
+
 /**
  * Full knowledge memory flow: extract issues from review → append to constitution.
  */