@nathapp/nax 0.18.1

package/test/unit/execution-logging-stderr.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Tests for exitCode and stderr in agent error scenarios
+ *
+ * Covers: AgentResult includes exitCode and stderr for debugging failures
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { AgentResult } from "../../src/agents/types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Test fixtures
+// ─────────────────────────────────────────────────────────────────────────────
+
+function createFailedResult(overrides: Partial<AgentResult> = {}): AgentResult {
+  return {
+    success: false,
+    exitCode: 1,
+    output: "",
+    stderr: "",
+    rateLimited: false,
+    durationMs: 1000,
+    estimatedCost: 0.01,
+    ...overrides,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests for AgentResult failure logging
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("AgentResult failure logging fields", () => {
+  it("includes exitCode for diagnosing failures", () => {
+    const result = createFailedResult({
+      exitCode: 1,
+      stderr: "Error message",
+    });
+
+    expect(result.exitCode).toBe(1);
+    expect(result.success).toBe(false);
+  });
+
+  it("captures stderr for root cause analysis", () => {
+    const result = createFailedResult({
+      exitCode: 401,
+      stderr: "401 Unauthorized: Invalid API key",
+    });
+
+    expect(result.exitCode).toBe(401);
+    expect(result.stderr).toContain("Unauthorized");
+  });
+
+  it("logs timeout with exit code 124", () => {
+    const result = createFailedResult({
+      exitCode: 124,
+      stderr: "SIGTERM: Process timeout",
+    });
+
+    expect(result.exitCode).toBe(124);
+    expect(result.stderr).toContain("timeout");
+  });
+
+  it("handles rate limit failures with exit code and stderr", () => {
+    const result = createFailedResult({
+      exitCode: 429,
+      stderr: "Rate limit exceeded",
+      rateLimited: true,
+    });
+
+    expect(result.exitCode).toBe(429);
+    expect(result.stderr).toContain("Rate limit");
+    expect(result.rateLimited).toBe(true);
+  });
+
+  it("logs server errors with 500 exit code", () => {
+    const result = createFailedResult({
+      exitCode: 500,
+      stderr: "Internal server error: database connection failed",
+    });
+
+    expect(result.exitCode).toBe(500);
+    expect(result.stderr).toContain("database");
+  });
+
+  it("supports backward compatibility when stderr is undefined", () => {
+    const result: AgentResult = {
+      success: false,
+      exitCode: 1,
+      output: "output",
+      // stderr intentionally undefined for backward compat
+      rateLimited: false,
+      durationMs: 1000,
+      estimatedCost: 0.01,
+    };
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toBeUndefined();
+  });
+
+  it("can serialize failure data to JSON for logging", () => {
+    const result = createFailedResult({
+      exitCode: 401,
+      stderr: "Authentication failed",
+    });
+
+    const logData = {
+      exitCode: result.exitCode,
+      stderr: result.stderr || "",
+      rateLimited: result.rateLimited,
+      storyId: "story-001",
+    };
+
+    const json = JSON.stringify(logData);
+    expect(json).toContain("401");
+    expect(json).toContain("Authentication");
+
+    const parsed = JSON.parse(json);
+    expect(parsed.exitCode).toBe(401);
+    expect(parsed.stderr).toBe("Authentication failed");
+  });
+
+  it("preserves special characters in stderr for JSONL format", () => {
+    const specialStderr = 'Error: "quoted" with\nnewline and \\backslash';
+    const result = createFailedResult({
+      stderr: specialStderr,
+    });
+
+    const logData = JSON.stringify({ stderr: result.stderr });
+    const parsed = JSON.parse(logData);
+    expect(parsed.stderr).toBe(specialStderr);
+  });
+
+  it("includes all critical fields for comprehensive failure logging", () => {
+    const result = createFailedResult({
+      success: false,
+      exitCode: 500,
+      output: "Last 5000 chars of stdout",
+      stderr: "Last 1000 chars of stderr",
+      rateLimited: false,
+      durationMs: 5000,
+      estimatedCost: 0.05,
+      pid: 12345,
+    });
+
+    // All fields should be available for logging
+    const logData = {
+      exitCode: result.exitCode,
+      stderr: result.stderr || "",
+      rateLimited: result.rateLimited,
+      storyId: "test",
+    };
+
+    expect(logData.exitCode).toBe(500);
+    expect(logData.stderr).toContain("stderr");
+    expect(logData.rateLimited).toBe(false);
+  });
+});

package/test/unit/execution-stage.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Tests for src/pipeline/stages/execution.ts
+ *
+ * Covers: routeTddFailure, execution stage critical paths
+ */
+
+import { describe, expect, it } from "bun:test";
+import { routeTddFailure } from "../../src/pipeline/stages/execution";
+import type { FailureCategory } from "../../src/tdd";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Test fixtures
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface MockContext {
+  retryAsLite?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// routeTddFailure
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("routeTddFailure", () => {
+  it("escalates on isolation-violation in strict mode", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure("isolation-violation", false, ctx);
+
+    expect(result.action).toBe("escalate");
+    expect(ctx.retryAsLite).toBe(true);
+  });
+
+  it("escalates on isolation-violation in lite mode without setting retryAsLite", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure("isolation-violation", true, ctx);
+
+    expect(result.action).toBe("escalate");
+    expect(ctx.retryAsLite).toBeUndefined();
+  });
+
+  it("escalates on session-failure", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure("session-failure", false, ctx);
+
+    expect(result.action).toBe("escalate");
+    expect(ctx.retryAsLite).toBeUndefined();
+  });
+
+  it("escalates on tests-failing", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure("tests-failing", false, ctx);
+
+    expect(result.action).toBe("escalate");
+    expect(ctx.retryAsLite).toBeUndefined();
+  });
+
+  it("escalates on verifier-rejected", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure("verifier-rejected", false, ctx);
+
+    expect(result.action).toBe("escalate");
+    expect(ctx.retryAsLite).toBeUndefined();
+  });
+
+  it("pauses on undefined failureCategory", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure(undefined, false, ctx, "Unknown failure");
+
+    expect(result.action).toBe("pause");
+    expect(result.reason).toBe("Unknown failure");
+    expect(ctx.retryAsLite).toBeUndefined();
+  });
+
+  it("pauses on unknown failureCategory", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure("unknown" as FailureCategory, false, ctx);
+
+    expect(result.action).toBe("pause");
+    expect(result.reason).toBe("Three-session TDD requires review");
+    expect(ctx.retryAsLite).toBeUndefined();
+  });
+
+  it("uses custom reviewReason when pausing", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure(undefined, false, ctx, "Custom reason for pause");
+
+    expect(result.action).toBe("pause");
+    expect(result.reason).toBe("Custom reason for pause");
+  });
+
+  it("defaults to generic pause message when no reviewReason provided", () => {
+    const ctx: MockContext = {};
+    const result = routeTddFailure(undefined, false, ctx);
+
+    expect(result.action).toBe("pause");
+    expect(result.reason).toBe("Three-session TDD requires review");
+  });
+
+  it("handles all known failure categories correctly", () => {
+    const categories: FailureCategory[] = [
+      "isolation-violation",
+      "session-failure",
+      "tests-failing",
+      "verifier-rejected",
+    ];
+
+    for (const category of categories) {
+      const ctx: MockContext = {};
+      const result = routeTddFailure(category, false, ctx);
+      expect(result.action).toBe("escalate");
+    }
+  });
+
+  it("only sets retryAsLite for isolation-violation in strict mode", () => {
+    const categories: FailureCategory[] = ["session-failure", "tests-failing", "verifier-rejected"];
+
+    for (const category of categories) {
+      const ctx: MockContext = {};
+      routeTddFailure(category, false, ctx);
+      expect(ctx.retryAsLite).toBeUndefined();
+    }
+  });
+});

package/test/unit/fix-generator.test.ts

@@ -0,0 +1,275 @@
+/**
+ * Fix Generator Tests
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  buildFixPrompt,
+  convertFixStoryToUserStory,
+  findRelatedStories,
+  parseACTextFromSpec,
+} from "../../src/acceptance/fix-generator";
+import type { PRD, UserStory } from "../../src/prd/types";
+
+describe("parseACTextFromSpec", () => {
+  test("extracts AC text from spec markdown", () => {
+    const spec = `# Feature
+
+## Acceptance Criteria
+- AC-1: handles empty input
+- AC-2: set(key, value, ttl) expires after ttl milliseconds
+- AC-3: validates format`;
+
+    const map = parseACTextFromSpec(spec);
+
+    expect(map).toEqual({
+      "AC-1": "handles empty input",
+      "AC-2": "set(key, value, ttl) expires after ttl milliseconds",
+      "AC-3": "validates format",
+    });
+  });
+
+  test("handles checkboxes and whitespace", () => {
+    const spec = `
+- [ ] AC-1: first criterion
+  - [x] AC-2: second criterion
+AC-3: third criterion
+    `;
+
+    const map = parseACTextFromSpec(spec);
+
+    expect(map).toEqual({
+      "AC-1": "first criterion",
+      "AC-2": "second criterion",
+      "AC-3": "third criterion",
+    });
+  });
+
+  test("normalizes AC IDs to uppercase", () => {
+    const spec = "- ac-1: lowercase\n- Ac-2: mixed case";
+
+    const map = parseACTextFromSpec(spec);
+
+    expect(map).toEqual({
+      "AC-1": "lowercase",
+      "AC-2": "mixed case",
+    });
+  });
+
+  test("returns empty map when no ACs found", () => {
+    const spec = "# Feature\n\nNo acceptance criteria here.";
+
+    const map = parseACTextFromSpec(spec);
+
+    expect(map).toEqual({});
+  });
+});
+
+describe("findRelatedStories", () => {
+  test("finds stories with matching AC in acceptanceCriteria", () => {
+    const prd: PRD = {
+      project: "test",
+      feature: "test",
+      branchName: "test",
+      createdAt: "2024-01-01",
+      updatedAt: "2024-01-01",
+      userStories: [
+        {
+          id: "US-001",
+          title: "First story",
+          description: "desc",
+          acceptanceCriteria: ["AC-1: handles empty input"],
+          tags: [],
+          dependencies: [],
+          status: "passed",
+          passes: true,
+          escalations: [],
+          attempts: 0,
+        },
+        {
+          id: "US-002",
+          title: "Second story",
+          description: "desc",
+          acceptanceCriteria: ["AC-2: TTL expiry", "AC-3: format validation"],
+          tags: [],
+          dependencies: [],
+          status: "passed",
+          passes: true,
+          escalations: [],
+          attempts: 0,
+        },
+        {
+          id: "US-003",
+          title: "Third story",
+          description: "desc",
+          acceptanceCriteria: ["AC-4: other criterion"],
+          tags: [],
+          dependencies: [],
+          status: "passed",
+          passes: true,
+          escalations: [],
+          attempts: 0,
+        },
+      ],
+    };
+
+    const related = findRelatedStories("AC-2", prd);
+
+    expect(related).toEqual(["US-002"]);
+  });
+
+  test("falls back to all passed stories when no AC match", () => {
+    const prd: PRD = {
+      project: "test",
+      feature: "test",
+      branchName: "test",
+      createdAt: "2024-01-01",
+      updatedAt: "2024-01-01",
+      userStories: [
+        {
+          id: "US-001",
+          title: "First",
+          description: "desc",
+          acceptanceCriteria: ["other AC"],
+          tags: [],
+          dependencies: [],
+          status: "passed",
+          passes: true,
+          escalations: [],
+          attempts: 0,
+        },
+        {
+          id: "US-002",
+          title: "Second",
+          description: "desc",
+          acceptanceCriteria: ["another AC"],
+          tags: [],
+          dependencies: [],
+          status: "pending",
+          passes: false,
+          escalations: [],
+          attempts: 0,
+        },
+        {
+          id: "US-003",
+          title: "Third",
+          description: "desc",
+          acceptanceCriteria: ["yet another AC"],
+          tags: [],
+          dependencies: [],
+          status: "passed",
+          passes: true,
+          escalations: [],
+          attempts: 0,
+        },
+      ],
+    };
+
+    const related = findRelatedStories("AC-99", prd);
+
+    // Should return passed stories (max 5)
+    expect(related).toContain("US-001");
+    expect(related).toContain("US-003");
+    expect(related).not.toContain("US-002"); // pending, not passed
+  });
+
+  test("limits fallback to 5 stories", () => {
+    const stories: UserStory[] = [];
+    for (let i = 1; i <= 10; i++) {
+      stories.push({
+        id: `US-${String(i).padStart(3, "0")}`,
+        title: `Story ${i}`,
+        description: "desc",
+        acceptanceCriteria: ["unrelated"],
+        tags: [],
+        dependencies: [],
+        status: "passed",
+        passes: true,
+        escalations: [],
+        attempts: 0,
+      });
+    }
+
+    const prd: PRD = {
+      project: "test",
+      feature: "test",
+      branchName: "test",
+      createdAt: "2024-01-01",
+      updatedAt: "2024-01-01",
+      userStories: stories,
+    };
+
+    const related = findRelatedStories("AC-99", prd);
+
+    expect(related.length).toBeLessThanOrEqual(5);
+  });
+});
+
+describe("buildFixPrompt", () => {
+  test("builds prompt with all required context", () => {
+    const prd: PRD = {
+      project: "test",
+      feature: "test",
+      branchName: "test",
+      createdAt: "2024-01-01",
+      updatedAt: "2024-01-01",
+      userStories: [
+        {
+          id: "US-002",
+          title: "Implement TTL",
+          description: "Add TTL support to key-value store",
+          acceptanceCriteria: ["AC-2: TTL expiry"],
+          tags: [],
+          dependencies: [],
+          status: "passed",
+          passes: true,
+          escalations: [],
+          attempts: 0,
+        },
+      ],
+    };
+
+    const prompt = buildFixPrompt(
+      "AC-2",
+      "set(key, value, ttl) expires after ttl milliseconds",
+      "Expected undefined, got 'value'",
+      ["US-002"],
+      prd,
+    );
+
+    expect(prompt).toContain("AC-2:");
+    expect(prompt).toContain("set(key, value, ttl)");
+    expect(prompt).toContain("Expected undefined, got 'value'");
+    expect(prompt).toContain("US-002");
+    expect(prompt).toContain("Implement TTL");
+    expect(prompt).toContain("Add TTL support");
+  });
+});
+
+describe("convertFixStoryToUserStory", () => {
+  test("converts FixStory to UserStory with correct fields", () => {
+    const fixStory = {
+      id: "US-FIX-001",
+      title: "Fix: AC-2 TTL expiry timing",
+      failedAC: "AC-2",
+      testOutput: "test output",
+      relatedStories: ["US-002", "US-005"],
+      description: "Update TTL implementation to properly expire entries after the specified duration.",
+    };
+
+    const userStory = convertFixStoryToUserStory(fixStory);
+
+    expect(userStory.id).toBe("US-FIX-001");
+    expect(userStory.title).toBe("Fix: AC-2 TTL expiry timing");
+    expect(userStory.description).toBe(
+      "Update TTL implementation to properly expire entries after the specified duration.",
+    );
+    expect(userStory.acceptanceCriteria).toEqual(["Fix AC-2"]);
+    expect(userStory.tags).toEqual(["fix", "acceptance-failure"]);
+    expect(userStory.dependencies).toEqual(["US-002", "US-005"]);
+    expect(userStory.status).toBe("pending");
+    expect(userStory.passes).toBe(false);
+    expect(userStory.escalations).toEqual([]);
+    expect(userStory.attempts).toBe(0);
+  });
+});