@nathapp/nax 0.18.1

package/src/verification/parser.ts

@@ -0,0 +1,230 @@
+/**
+ * Test Output Parsing
+ *
+ * Unified test output parsing logic for Bun test framework.
+ * Extracted from execution/test-output-parser.ts and execution/verification.ts.
+ */
+
+import type { TestFailure, TestOutputAnalysis, TestSummary } from "./types";
+
+/**
+ * Parse Bun test output into structured failure objects.
+ *
+ * Example output format:
+ * ```
+ * bun test v1.0.0
+ *
+ * test/example.test.ts:
+ * ✓ passing test [0.5ms]
+ * ✗ failing test [1.2ms]
+ *
+ * (fail) describe block > nested block > test name [1.2ms]
+ * Error: Expected 1 to equal 2
+ *   at /path/to/file.ts:10:15
+ *   at Object.test (/path/to/file.ts:8:3)
+ * ```
+ */
+export function parseBunTestOutput(output: string): TestSummary {
+  const lines = output.split("\n");
+  const failures: TestFailure[] = [];
+  let passed = 0;
+  let failed = 0;
+  let currentFile = "";
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Extract file path from headers like "test/example.test.ts:"
+    if (line.trim().endsWith(".test.ts:") || line.trim().endsWith(".test.js:")) {
+      currentFile = line.trim().replace(/:$/, "");
+      i++;
+      continue;
+    }
+
+    // Count passed tests (✓ or ✔)
+    if (line.includes("✓") || line.includes("✔")) {
+      passed++;
+      i++;
+      continue;
+    }
+
+    // Count failed tests (✗ or ✘)
+    if (line.includes("✗") || line.includes("✘")) {
+      failed++;
+      i++;
+      continue;
+    }
+
+    // Parse failure line: "(fail) TestName > nested > name [duration]"
+    const failMatch = line.match(/^\(fail\)\s+(.+?)\s+\[[\d.]+m?s\]/);
+    if (failMatch) {
+      const testName = failMatch[1].trim();
+      i++;
+
+      // Extract error message and stack trace
+      let error = "";
+      const stackTrace: string[] = [];
+      let stackLineCount = 0;
+
+      // Read lines until we hit a blank line or another test result
+      while (i < lines.length && stackLineCount < 5) {
+        const nextLine = lines[i];
+
+        // Stop at blank line or next test result
+        if (!nextLine.trim() || nextLine.includes("(fail)") || nextLine.includes("✓") || nextLine.includes("✗")) {
+          break;
+        }
+
+        // First non-blank line is typically the error message
+        if (!error && nextLine.trim()) {
+          error = nextLine.trim();
+          i++;
+          continue;
+        }
+
+        // Subsequent lines starting with "at" are stack trace
+        if (nextLine.trim().startsWith("at ")) {
+          stackTrace.push(nextLine.trim());
+          stackLineCount++;
+        }
+        i++;
+      }
+
+      failures.push({
+        file: currentFile || "unknown",
+        testName,
+        error: error || "Unknown error",
+        stackTrace,
+      });
+      continue;
+    }
+
+    i++;
+  }
+
+  return { passed, failed, failures };
+}
+
+/**
+ * Format failure summary for agent feedback.
+ *
+ * Format:
+ * ```
+ * 1. file.test.ts > TestName > nested
+ *    Error: message
+ *    at file.ts:10:15
+ *
+ * 2. another.test.ts > OtherTest
+ *    Error: another error
+ *    at other.ts:20:10
+ * ```
+ */
+export function formatFailureSummary(failures: TestFailure[], maxChars = 2000): string {
+  if (failures.length === 0) {
+    return "No test failures";
+  }
+
+  const lines: string[] = [];
+  let totalChars = 0;
+
+  for (let i = 0; i < failures.length; i++) {
+    const failure = failures[i];
+    const num = i + 1;
+
+    // Format: "1. file.test.ts > TestName"
+    const header = `${num}. ${failure.file} > ${failure.testName}`;
+    const errorLine = `   Error: ${failure.error}`;
+
+    // Add first stack trace line if available
+    const stackLine = failure.stackTrace.length > 0 ? `   ${failure.stackTrace[0]}` : "";
+
+    const blockLines = [header, errorLine];
+    if (stackLine) {
+      blockLines.push(stackLine);
+    }
+    blockLines.push(""); // blank line separator
+
+    const block = blockLines.join("\n");
+    const blockLength = block.length;
+
+    // Check if adding this block would exceed maxChars
+    if (totalChars + blockLength > maxChars && lines.length > 0) {
+      const remaining = failures.length - i;
+      lines.push(`\n... and ${remaining} more failure(s) (truncated)`);
+      break;
+    }
+
+    lines.push(...blockLines);
+    totalChars += blockLength;
+  }
+
+  return lines.join("\n").trim();
+}
+
+/**
+ * Parse test output to detect environmental failures.
+ *
+ * When exit code != 0 but all tests pass, classifies as ENVIRONMENTAL_FAILURE
+ * instead of TEST_FAILURE.
+ */
+export function parseTestOutput(output: string, exitCode: number): TestOutputAnalysis {
+  // Regex patterns for different test frameworks
+  const patterns = [
+    /(\d+)\s+pass(?:ed)?(?:,\s+|\s+)(\d+)\s+fail/i, // "5 pass, 0 fail" or "5 passed 0 fail"
+    /Tests:\s+(\d+)\s+passed,\s+(\d+)\s+failed/i, // Jest format
+    /(\d+)\s+pass/i, // Bun format (just pass count)
+  ];
+
+  let passCount = 0;
+  let failCount = 0;
+
+  for (const pattern of patterns) {
+    // Match ALL occurrences — use the LAST one (final summary line)
+    const matches = Array.from(output.matchAll(new RegExp(pattern, "gi")));
+    if (matches.length > 0) {
+      const lastMatch = matches[matches.length - 1];
+      passCount = Number.parseInt(lastMatch[1], 10);
+      // Some formats only show pass count
+      failCount = lastMatch[2] ? Number.parseInt(lastMatch[2], 10) : 0;
+      break;
+    }
+  }
+
+  // Check for explicit fail count if not found
+  if (failCount === 0) {
+    const failMatches = Array.from(output.matchAll(/(\d+)\s+fail/gi));
+    if (failMatches.length > 0) {
+      failCount = Number.parseInt(failMatches[failMatches.length - 1][1], 10);
+    }
+  }
+
+  const allTestsPassed = passCount > 0 && failCount === 0;
+  const isEnvironmentalFailure = allTestsPassed && exitCode !== 0;
+
+  const result: TestOutputAnalysis = {
+    allTestsPassed,
+    passCount,
+    failCount,
+    isEnvironmentalFailure,
+  };
+
+  if (isEnvironmentalFailure) {
+    result.error = `ENVIRONMENTAL_FAILURE: All ${passCount} tests passed but exit code was ${exitCode}. Check linter/typecheck/missing files.`;
+  }
+
+  return result;
+}
+
+/**
+ * Calculate early escalation threshold for environmental failures.
+ *
+ * Environmental failures should escalate faster: after ceil(tier.attempts / 2)
+ * instead of the full tier budget.
+ */
+export function getEnvironmentalEscalationThreshold(tierAttempts: number, divisor = 2): number {
+  return Math.ceil(tierAttempts / divisor);
+}
+
+// Re-export types for consumers that import from this module
+export type { TestFailure, TestSummary } from "./types";

package/src/verification/rectification.ts

@@ -0,0 +1,108 @@
+/**
+ * Rectification Logic
+ *
+ * Retry logic with backoff, max attempt tracking, and failure categorization.
+ * Extracted from execution/rectification.ts to eliminate duplication.
+ */
+
+import type { RectificationConfig } from "../config";
+import type { UserStory } from "../prd";
+import { formatFailureSummary } from "./parser";
+import type { RectificationState, TestFailure } from "./types";
+
+/**
+ * Determine if rectification should retry based on state and config.
+ *
+ * Returns true if:
+ * - Current attempt < maxRetries
+ * - AND currentFailures > 0 (still have failures to fix)
+ * - AND NOT regressing (if abortOnIncreasingFailures is true)
+ *
+ * Returns false if:
+ * - Max retries reached
+ * - OR all tests passing (currentFailures = 0)
+ * - OR failures increased (regression spiral) AND abortOnIncreasingFailures = true
+ */
+export function shouldRetryRectification(state: RectificationState, config: RectificationConfig): boolean {
+  // Stop if max retries reached
+  if (state.attempt >= config.maxRetries) {
+    return false;
+  }
+
+  // Stop if all tests passing
+  if (state.currentFailures === 0) {
+    return false;
+  }
+
+  // Abort if failures increased (regression spiral check)
+  if (config.abortOnIncreasingFailures && state.currentFailures > state.initialFailures) {
+    return false;
+  }
+
+  // Continue retrying
+  return true;
+}
+
+/**
+ * Create a rectification prompt with failure context.
+ *
+ * Includes:
+ * - Clear instructions about test regressions
+ * - Formatted failure summary
+ * - Specific test commands for failing files
+ */
+export function createRectificationPrompt(
+  failures: TestFailure[],
+  story: UserStory,
+  config?: RectificationConfig,
+): string {
+  const maxChars = config?.maxFailureSummaryChars ?? 2000;
+  const failureSummary = formatFailureSummary(failures, maxChars);
+
+  // Extract unique failing test files
+  const failingFiles = Array.from(new Set(failures.map((f) => f.file)));
+  const testCommands = failingFiles.map((file) => `  bun test ${file}`).join("\n");
+
+  return `# Rectification Required
+
+Your changes caused test regressions. Fix these without breaking existing logic.
+
+## Story Context
+
+**Title:** ${story.title}
+
+**Description:**
+${story.description}
+
+**Acceptance Criteria:**
+${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}
+
+---
+
+## Test Failures
+
+${failureSummary}
+
+---
+
+## Instructions
+
+1. Review the failures above carefully.
+2. Identify the root cause of each failure.
+3. Fix the implementation WITHOUT loosening test assertions.
+4. Run the failing tests to verify your fixes:
+
+${testCommands}
+
+5. Ensure ALL tests pass before completing.
+
+**IMPORTANT:**
+- Do NOT modify test files unless there is a legitimate bug in the test itself.
+- Do NOT loosen assertions to mask implementation bugs.
+- Focus on fixing the source code to meet the test requirements.
+- When running tests, run ONLY the failing test files shown above — NEVER run \`bun test\` without a file filter.
+`;
+}
+
+// Re-export types for consumers that import from this module
+export type { RectificationState } from "./types";

package/src/verification/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Unified Verification Types
+ *
+ * Shared type definitions for test execution, parsing, and verification.
+ */
+
+/** Verification scope: what tests to run */
+export type VerificationScope = "scoped" | "full" | "regression";
+
+/** Verification status outcomes */
+export type VerificationStatus =
+  | "SUCCESS"
+  | "TEST_FAILURE"
+  | "ENVIRONMENTAL_FAILURE"
+  | "ASSET_CHECK_FAILED"
+  | "TIMEOUT";
+
+/** Test execution result (raw) */
+export interface TestExecutionResult {
+  success: boolean;
+  timeout: boolean;
+  exitCode?: number;
+  output?: string;
+  error?: string;
+  killed?: boolean;
+  childProcessesKilled?: boolean;
+  countsTowardEscalation: boolean;
+}
+
+/** Test output analysis (parsed) */
+export interface TestOutputAnalysis {
+  allTestsPassed: boolean;
+  passCount: number;
+  failCount: number;
+  isEnvironmentalFailure: boolean;
+  error?: string;
+}
+
+/** Asset verification result */
+export interface AssetVerificationResult {
+  success: boolean;
+  missingFiles: string[];
+  error?: string;
+}
+
+/** Structured test failure information */
+export interface TestFailure {
+  /** File path where the test failed */
+  file: string;
+  /** Full test name (including nested describe blocks) */
+  testName: string;
+  /** Error message */
+  error: string;
+  /** Stack trace lines (truncated to first 5 lines) */
+  stackTrace: string[];
+}
+
+/** Test run summary */
+export interface TestSummary {
+  /** Number of tests that passed */
+  passed: number;
+  /** Number of tests that failed */
+  failed: number;
+  /** Structured failure details */
+  failures: TestFailure[];
+}
+
+/** Complete verification result */
+export interface VerificationResult {
+  status: VerificationStatus;
+  success: boolean;
+  countsTowardEscalation: boolean;
+  output?: string;
+  error?: string;
+  missingFiles?: string[];
+  passCount?: number;
+  failCount?: number;
+}
+
+/** Rectification state tracking per story execution */
+export interface RectificationState {
+  /** Current attempt number (0 = initial run, 1+ = retries) */
+  attempt: number;
+  /** Number of test failures on initial run */
+  initialFailures: number;
+  /** Number of test failures on current run */
+  currentFailures: number;
+}
+
+/** Verification gate options */
+export interface VerificationGateOptions {
+  /** Working directory */
+  workdir: string;
+  /** Test command to execute */
+  command: string;
+  /** Timeout in seconds */
+  timeoutSeconds: number;
+  /** Expected files (for asset verification) */
+  expectedFiles?: string[];
+  /** Quality config for open handle / force exit behavior */
+  forceExit?: boolean;
+  detectOpenHandles?: boolean;
+  detectOpenHandlesRetries?: number;
+  /** How many times this story has timed out (tracks across retries) */
+  timeoutRetryCount?: number;
+  /** Process management config */
+  gracePeriodMs?: number;
+  drainTimeoutMs?: number;
+  shell?: string;
+  stripEnvVars?: string[];
+  /** Scoped test paths (for scoped verification) */
+  scopedTestPaths?: string[];
+}

package/src/worktree/dispatcher.ts

@@ -0,0 +1,65 @@
+import type { UserStory } from "../prd/types";
+import type { WorktreeManager } from "./manager";
+
+export interface DispatchResult {
+  storyId: string;
+  success: boolean;
+  worktreePath: string;
+  error?: string;
+}
+
+export class ParallelDispatcher {
+  constructor(
+    private worktreeManager: WorktreeManager,
+    private runPipeline: (args: { workdir: string; story: UserStory }) => Promise<boolean>,
+  ) {}
+
+  async dispatch(projectRoot: string, stories: UserStory[], maxConcurrency: number): Promise<DispatchResult[]> {
+    const results: DispatchResult[] = [];
+    const independentBatches = this.getBatches(stories);
+
+    for (const batch of independentBatches) {
+      const batchPromises = batch.map(async (story) => {
+        const worktreePath = `${projectRoot}/.nax-wt/${story.id}`;
+        try {
+          await this.worktreeManager.create(projectRoot, story.id);
+          const success = await this.runPipeline({ workdir: worktreePath, story });
+          return { storyId: story.id, success, worktreePath };
+        } catch (err) {
+          return {
+            storyId: story.id,
+            success: false,
+            worktreePath,
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+      });
+
+      const batchResults = await pLimit(maxConcurrency, batchPromises);
+      results.push(...batchResults);
+    }
+
+    return results;
+  }
+
+  private getBatches(stories: UserStory[]): UserStory[][] {
+    // TODO: Implement dependency-aware batching
+    return [stories];
+  }
+}
+
+// Helper for concurrency limiting (Simplified p-limit)
+async function pLimit<T>(concurrency: number, promises: Promise<T>[]): Promise<T[]> {
+  const results: T[] = [];
+  const executing: Promise<void>[] = [];
+  for (const p of promises) {
+    const e = p.then((r) => {
+      results.push(r);
+      executing.splice(executing.indexOf(e), 1);
+    });
+    executing.push(e);
+    if (executing.length >= concurrency) await Promise.race(executing);
+  }
+  await Promise.all(executing);
+  return results;
+}

package/src/worktree/index.ts

@@ -0,0 +1,2 @@
+export { WorktreeManager } from "./manager";
+export type { WorktreeInfo } from "./types";

package/src/worktree/manager.ts

@@ -0,0 +1,187 @@
+import { existsSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { getSafeLogger } from "../logger";
+import type { WorktreeInfo } from "./types";
+
+export class WorktreeManager {
+  /**
+   * Creates a git worktree at .nax-wt/<storyId>/ with branch nax/<storyId>
+   * and symlinks node_modules and .env from project root
+   */
+  async create(projectRoot: string, storyId: string): Promise<void> {
+    const worktreePath = join(projectRoot, ".nax-wt", storyId);
+    const branchName = `nax/${storyId}`;
+
+    try {
+      // Create worktree with new branch
+      const proc = Bun.spawn(["git", "worktree", "add", worktreePath, "-b", branchName], {
+        cwd: projectRoot,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await proc.exited;
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        throw new Error(`Failed to create worktree: ${stderr || "unknown error"}`);
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        // Enhance error messages for common scenarios
+        if (error.message.includes("not a git repository")) {
+          throw new Error(`Not a git repository: ${projectRoot}`);
+        }
+        if (error.message.includes("already exists")) {
+          throw new Error(`Worktree for story ${storyId} already exists at ${worktreePath}`);
+        }
+        throw error;
+      }
+      throw new Error(`Failed to create worktree: ${String(error)}`);
+    }
+
+    // Symlink node_modules if it exists
+    const nodeModulesSource = join(projectRoot, "node_modules");
+    if (existsSync(nodeModulesSource)) {
+      const nodeModulesTarget = join(worktreePath, "node_modules");
+      try {
+        symlinkSync(nodeModulesSource, nodeModulesTarget, "dir");
+      } catch (error) {
+        // Clean up worktree if symlinking fails
+        await this.remove(projectRoot, storyId);
+        throw new Error(`Failed to symlink node_modules: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    // Symlink .env if it exists
+    const envSource = join(projectRoot, ".env");
+    if (existsSync(envSource)) {
+      const envTarget = join(worktreePath, ".env");
+      try {
+        symlinkSync(envSource, envTarget, "file");
+      } catch (error) {
+        // Clean up worktree if symlinking fails
+        await this.remove(projectRoot, storyId);
+        throw new Error(`Failed to symlink .env: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
+  /**
+   * Removes worktree and deletes branch
+   */
+  async remove(projectRoot: string, storyId: string): Promise<void> {
+    const worktreePath = join(projectRoot, ".nax-wt", storyId);
+    const branchName = `nax/${storyId}`;
+
+    // Remove worktree
+    try {
+      const proc = Bun.spawn(["git", "worktree", "remove", worktreePath, "--force"], {
+        cwd: projectRoot,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await proc.exited;
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        if (
+          stderr.includes("not found") ||
+          stderr.includes("does not exist") ||
+          stderr.includes("no such worktree") ||
+          stderr.includes("is not a working tree")
+        ) {
+          throw new Error(`Worktree not found: ${worktreePath}`);
+        }
+        throw new Error(`Failed to remove worktree: ${stderr || "unknown error"}`);
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(`Failed to remove worktree: ${String(error)}`);
+    }
+
+    // Delete branch
+    try {
+      const proc = Bun.spawn(["git", "branch", "-D", branchName], {
+        cwd: projectRoot,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await proc.exited;
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        // Don't fail if branch doesn't exist
+        if (!stderr.includes("not found")) {
+          const logger = getSafeLogger();
+          logger?.warn("worktree", `Failed to delete branch ${branchName}`, { stderr });
+        }
+      }
+    } catch (error) {
+      // Log warning but don't fail - worktree is already removed
+      const logger = getSafeLogger();
+      logger?.warn("worktree", `Failed to delete branch ${branchName}`, {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Returns active worktrees
+   */
+  async list(projectRoot: string): Promise<WorktreeInfo[]> {
+    try {
+      const proc = Bun.spawn(["git", "worktree", "list", "--porcelain"], {
+        cwd: projectRoot,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await proc.exited;
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        throw new Error(`Failed to list worktrees: ${stderr || "unknown error"}`);
+      }
+
+      const stdout = await new Response(proc.stdout).text();
+      return this.parseWorktreeList(stdout);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(`Failed to list worktrees: ${String(error)}`);
+    }
+  }
+
+  /**
+   * Parses git worktree list --porcelain output
+   */
+  private parseWorktreeList(output: string): WorktreeInfo[] {
+    const worktrees: WorktreeInfo[] = [];
+    const lines = output.trim().split("\n");
+
+    let currentWorktree: Partial<WorktreeInfo> = {};
+
+    for (const line of lines) {
+      if (line.startsWith("worktree ")) {
+        currentWorktree.path = line.substring("worktree ".length);
+      } else if (line.startsWith("branch ")) {
+        currentWorktree.branch = line.substring("branch ".length).replace("refs/heads/", "");
+      } else if (line === "") {
+        // Empty line indicates end of worktree entry
+        if (currentWorktree.path && currentWorktree.branch) {
+          worktrees.push(currentWorktree as WorktreeInfo);
+        }
+        currentWorktree = {};
+      }
+    }
+
+    // Handle last entry if no trailing newline
+    if (currentWorktree.path && currentWorktree.branch) {
+      worktrees.push(currentWorktree as WorktreeInfo);
+    }
+
+    return worktrees;
+  }
+}