@nathapp/nax 0.18.1

package/test/unit/prd-failure-category.test.ts

@@ -0,0 +1,176 @@
+/**
+ * PRD failureCategory Tests
+ *
+ * Tests for failureCategory field on UserStory and the markStoryFailed()
+ * function storing the category.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { FailureCategory } from "../../src/execution";
+import { markStoryFailed, markStoryPassed, markStoryPaused } from "../../src/prd";
+import type { PRD, UserStory } from "../../src/prd/types";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeStory(id: string): UserStory {
+  return {
+    id,
+    title: `Story ${id}`,
+    description: "Test story",
+    acceptanceCriteria: ["AC1"],
+    tags: [],
+    dependencies: [],
+    status: "pending",
+    passes: false,
+    escalations: [],
+    attempts: 0,
+  };
+}
+
+function makePrd(stories: UserStory[]): PRD {
+  return {
+    project: "test",
+    feature: "test-feature",
+    branchName: "feature/test",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    userStories: stories,
+  };
+}
+
+// ── UserStory interface ───────────────────────────────────────────────────────
+
+describe("UserStory.failureCategory field", () => {
+  test("is optional — not present by default", () => {
+    const story = makeStory("US-001");
+    expect(story.failureCategory).toBeUndefined();
+  });
+
+  test("can be assigned a FailureCategory value", () => {
+    const story = makeStory("US-001");
+    story.failureCategory = "session-failure";
+    expect(story.failureCategory).toBe("session-failure");
+  });
+
+  test("accepts all four FailureCategory values", () => {
+    const categories: FailureCategory[] = [
+      "isolation-violation",
+      "session-failure",
+      "tests-failing",
+      "verifier-rejected",
+    ];
+    const story = makeStory("US-001");
+    for (const cat of categories) {
+      story.failureCategory = cat;
+      expect(story.failureCategory).toBe(cat);
+    }
+  });
+});
+
+// ── markStoryFailed() ─────────────────────────────────────────────────────────
+
+describe("markStoryFailed()", () => {
+  test("marks story as failed (backward compat — no failureCategory)", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    markStoryFailed(prd, "US-001");
+    expect(prd.userStories[0].status).toBe("failed");
+    expect(prd.userStories[0].failureCategory).toBeUndefined();
+  });
+
+  test("increments attempts when no failureCategory given", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    markStoryFailed(prd, "US-001");
+    expect(prd.userStories[0].attempts).toBe(1);
+  });
+
+  test("stores failureCategory='session-failure'", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    markStoryFailed(prd, "US-001", "session-failure");
+    expect(prd.userStories[0].failureCategory).toBe("session-failure");
+    expect(prd.userStories[0].status).toBe("failed");
+  });
+
+  test("stores failureCategory='isolation-violation'", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    markStoryFailed(prd, "US-001", "isolation-violation");
+    expect(prd.userStories[0].failureCategory).toBe("isolation-violation");
+  });
+
+  test("stores failureCategory='tests-failing'", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    markStoryFailed(prd, "US-001", "tests-failing");
+    expect(prd.userStories[0].failureCategory).toBe("tests-failing");
+  });
+
+  test("stores failureCategory='verifier-rejected'", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    markStoryFailed(prd, "US-001", "verifier-rejected");
+    expect(prd.userStories[0].failureCategory).toBe("verifier-rejected");
+  });
+
+  test("increments attempts when failureCategory is given", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    prd.userStories[0].attempts = 2;
+    markStoryFailed(prd, "US-001", "tests-failing");
+    expect(prd.userStories[0].attempts).toBe(3);
+  });
+
+  test("does not overwrite failureCategory with undefined when not passed", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    // Simulate a prior failure that set a category
+    prd.userStories[0].failureCategory = "session-failure";
+    // Call without a category — should NOT clear the existing value
+    markStoryFailed(prd, "US-001");
+    expect(prd.userStories[0].failureCategory).toBe("session-failure");
+  });
+
+  test("does nothing when story not found", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    // Should not throw
+    markStoryFailed(prd, "US-999", "session-failure");
+    expect(prd.userStories[0].status).toBe("pending");
+  });
+
+  test("does not affect other stories", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001", "tests-failing");
+    expect(prd.userStories[1].status).toBe("pending");
+    expect(prd.userStories[1].failureCategory).toBeUndefined();
+  });
+});
+
+// ── FailureCategory type export from src/execution ───────────────────────────
+
+describe("FailureCategory export from src/execution", () => {
+  test("FailureCategory is exported from src/execution index", () => {
+    // This test verifies the re-export compiles and can be used as a type
+    const cat: FailureCategory = "session-failure";
+    expect(cat).toBe("session-failure");
+  });
+
+  test("all four categories are valid FailureCategory values", () => {
+    const isolation: FailureCategory = "isolation-violation";
+    const session: FailureCategory = "session-failure";
+    const failing: FailureCategory = "tests-failing";
+    const rejected: FailureCategory = "verifier-rejected";
+    expect([isolation, session, failing, rejected]).toHaveLength(4);
+  });
+});
+
+// ── markStoryPaused / markStoryPassed unaffected ─────────────────────────────
+
+describe("markStoryPaused and markStoryPassed — failureCategory not affected", () => {
+  test("markStoryPaused does not set failureCategory", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    markStoryPaused(prd, "US-001");
+    expect(prd.userStories[0].status).toBe("paused");
+    expect(prd.userStories[0].failureCategory).toBeUndefined();
+  });
+
+  test("markStoryPassed does not set failureCategory", () => {
+    const prd = makePrd([makeStory("US-001")]);
+    markStoryPassed(prd, "US-001");
+    expect(prd.userStories[0].status).toBe("passed");
+    expect(prd.userStories[0].failureCategory).toBeUndefined();
+  });
+});

package/test/unit/prd-get-next-story.test.ts

@@ -0,0 +1,186 @@
+/**
+ * getNextStory() Unit Tests (BUG-022)
+ *
+ * Tests for the story retry priority behavior:
+ * - Retries current failed story when attempts <= maxRetries
+ * - Moves to next pending story when retries exhausted
+ * - Preserves backward-compatible behavior when called without params
+ */
+
+import { describe, expect, test } from "bun:test";
+import { getNextStory, markStoryFailed } from "../../src/prd";
+import type { PRD, UserStory } from "../../src/prd/types";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeStory(id: string, overrides: Partial<UserStory> = {}): UserStory {
+  return {
+    id,
+    title: `Story ${id}`,
+    description: "Test story",
+    acceptanceCriteria: ["AC1"],
+    tags: [],
+    dependencies: [],
+    status: "pending",
+    passes: false,
+    escalations: [],
+    attempts: 0,
+    ...overrides,
+  };
+}
+
+function makePrd(stories: UserStory[]): PRD {
+  return {
+    project: "test",
+    feature: "test-feature",
+    branchName: "feature/test",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    userStories: stories,
+  };
+}
+
+// ── Backward-compatible behavior (no params) ─────────────────────────────────
+
+describe("getNextStory() — backward compat (no currentStoryId/maxRetries)", () => {
+  test("returns first pending story", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    expect(getNextStory(prd)?.id).toBe("US-001");
+  });
+
+  test("skips failed stories (existing behavior)", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001");
+
+    expect(getNextStory(prd)?.id).toBe("US-002");
+  });
+
+  test("returns null when all stories are failed or passed", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001");
+    prd.userStories[1].status = "passed";
+    prd.userStories[1].passes = true;
+
+    expect(getNextStory(prd)).toBeNull();
+  });
+});
+
+// ── Retry priority (BUG-022) ─────────────────────────────────────────────────
+
+describe("getNextStory() — retry priority (BUG-022)", () => {
+  test("returns failed current story when attempts <= maxRetries", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001"); // attempts = 1
+
+    // With maxRetries=2 and attempts=1, S1 should be retried
+    const next = getNextStory(prd, "US-001", 2);
+    expect(next?.id).toBe("US-001");
+  });
+
+  test("returns failed current story on last allowed retry (attempts == maxRetries)", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001"); // attempts = 1
+    markStoryFailed(prd, "US-001"); // attempts = 2
+
+    // With maxRetries=2 and attempts=2, still within limit
+    const next = getNextStory(prd, "US-001", 2);
+    expect(next?.id).toBe("US-001");
+  });
+
+  test("moves to next story when attempts exceed maxRetries", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001"); // attempts = 1
+    markStoryFailed(prd, "US-001"); // attempts = 2
+    markStoryFailed(prd, "US-001"); // attempts = 3
+
+    // With maxRetries=2 and attempts=3, move to US-002
+    const next = getNextStory(prd, "US-001", 2);
+    expect(next?.id).toBe("US-002");
+  });
+
+  test("moves to next story when current story is not failed", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    // US-001 is pending (not failed)
+
+    const next = getNextStory(prd, "US-001", 2);
+    expect(next?.id).toBe("US-001"); // Normal pending story picked up
+  });
+
+  test("skips retry when maxRetries=0", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001"); // attempts = 1
+
+    // maxRetries=0 disables retry — move to US-002
+    const next = getNextStory(prd, "US-001", 0);
+    expect(next?.id).toBe("US-002");
+  });
+
+  test("skips retry when currentStoryId is null", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001"); // attempts = 1
+
+    // null currentStoryId — no retry priority, picks next pending
+    const next = getNextStory(prd, null, 2);
+    expect(next?.id).toBe("US-002");
+  });
+
+  test("skips retry when currentStoryId not found in PRD", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    markStoryFailed(prd, "US-001");
+
+    // Unknown story ID — falls through to normal logic
+    const next = getNextStory(prd, "US-999", 2);
+    expect(next?.id).toBe("US-002");
+  });
+});
+
+// ── Run order (AC-2) ─────────────────────────────────────────────────────────
+
+describe("getNextStory() — run order S1-I1 -> S1-I2 (retry) -> S2-I1", () => {
+  test("enforces retry-before-next-story order across simulated iterations", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    let lastId: string | null = null;
+    const maxRetries = 1;
+    const order: string[] = [];
+
+    // Iteration 1: S1 first attempt
+    const pick1 = getNextStory(prd, lastId, maxRetries);
+    expect(pick1?.id).toBe("US-001");
+    order.push(pick1!.id);
+    lastId = pick1!.id;
+    markStoryFailed(prd, "US-001"); // S1 fails (attempts = 1)
+
+    // Iteration 2: S1 retry (attempts=1 <= maxRetries=1)
+    const pick2 = getNextStory(prd, lastId, maxRetries);
+    expect(pick2?.id).toBe("US-001");
+    order.push(pick2!.id);
+    lastId = pick2!.id;
+    markStoryFailed(prd, "US-001"); // S1 fails again (attempts = 2)
+
+    // Iteration 3: S1 exhausted (attempts=2 > maxRetries=1), move to S2
+    const pick3 = getNextStory(prd, lastId, maxRetries);
+    expect(pick3?.id).toBe("US-002");
+    order.push(pick3!.id);
+
+    expect(order).toEqual(["US-001", "US-001", "US-002"]);
+  });
+
+  test("moves to S2 after S1 passes (no retry needed)", () => {
+    const prd = makePrd([makeStory("US-001"), makeStory("US-002")]);
+    let lastId: string | null = null;
+    const maxRetries = 2;
+
+    // Iteration 1: S1 picked
+    const pick1 = getNextStory(prd, lastId, maxRetries);
+    expect(pick1?.id).toBe("US-001");
+    lastId = pick1!.id;
+
+    // S1 passes
+    prd.userStories[0].status = "passed";
+    prd.userStories[0].passes = true;
+
+    // Iteration 2: S2 picked (S1 done)
+    const pick2 = getNextStory(prd, lastId, maxRetries);
+    expect(pick2?.id).toBe("US-002");
+  });
+});