@nathapp/nax 0.50.2 → 0.51.0

package/src/acceptance/generator.ts

@@ -1,423 +0,0 @@
-/**
- * Acceptance Test Generator
- *
- * Parses spec.md acceptance criteria (AC-N lines) and generates acceptance.test.ts
- * via LLM call to the agent adapter.
- */
-
-import { join } from "node:path";
-import { ClaudeCodeAdapter } from "../agents/claude";
-import type { AgentAdapter } from "../agents/types";
-import { getLogger } from "../logger";
-import type { UserStory } from "../prd/types";
-import type {
-  AcceptanceCriterion,
-  AcceptanceTestResult,
-  GenerateAcceptanceTestsOptions,
-  GenerateFromPRDOptions,
-  RefinedCriterion,
-} from "./types";
-
-/**
- * Parse acceptance criteria from spec.md content.
- *
- * Extracts lines matching "AC-N: description" or "- AC-N: description" patterns.
- *
- * @param specContent - Full spec.md markdown content
- * @returns Array of extracted acceptance criteria
- *
- * @example
- * ```ts
- * const spec = `
- * ## Acceptance Criteria
- * - AC-1: System should handle empty input
- * - AC-2: set(key, value, ttl) expires after ttl milliseconds
- * `;
- * const criteria = parseAcceptanceCriteria(spec);
- * // Returns: [
- * //   { id: "AC-1", text: "System should handle empty input", lineNumber: 3 },
- * //   { id: "AC-2", text: "set(key, value, ttl) expires after ttl", lineNumber: 4 },
- * // ]
- * ```
- */
-/**
- * Injectable dependencies for generateFromPRD — allows tests to mock
- * adapter.complete() and file writes without real binaries or disk I/O.
- *
- * @internal
- */
-export const _generatorPRDDeps = {
-  adapter: new ClaudeCodeAdapter() as AgentAdapter,
-  writeFile: async (path: string, content: string): Promise<void> => {
-    await Bun.write(path, content);
-  },
-};
-
-/**
- * Generate acceptance tests from PRD UserStory[] and RefinedCriterion[].
- *
- * This is a stub — implementation is provided by the implementer session.
- *
- * @param stories - User stories from the PRD
- * @param refinedCriteria - Refined criteria produced by the refinement module
- * @param options - Generation options
- * @returns Generated test code and processed criteria
- */
-export async function generateFromPRD(
-  _stories: UserStory[],
-  refinedCriteria: RefinedCriterion[],
-  options: GenerateFromPRDOptions,
-): Promise<AcceptanceTestResult> {
-  const logger = getLogger();
-
-  const criteria: AcceptanceCriterion[] = refinedCriteria.map((c, i) => ({
-    id: `AC-${i + 1}`,
-    text: c.refined,
-    lineNumber: i + 1,
-  }));
-
-  if (refinedCriteria.length === 0) {
-    return { testCode: "", criteria: [] };
-  }
-
-  const criteriaList = refinedCriteria.map((c, i) => `AC-${i + 1}: ${c.refined}`).join("\n");
-
-  const strategyInstructions = buildStrategyInstructions(options.testStrategy, options.testFramework);
-
-  const prompt = `You are a test engineer. Generate acceptance tests for the "${options.featureName}" feature based on the refined acceptance criteria below.
-
-CODEBASE CONTEXT:
-${options.codebaseContext}
-
-ACCEPTANCE CRITERIA (refined):
-${criteriaList}
-
-${strategyInstructions}Generate a complete acceptance.test.ts file using bun:test framework. Each AC maps to exactly one test named "AC-N: <description>".
-
-Structure example (do NOT wrap in markdown fences — output raw TypeScript only):
-
-import { describe, test, expect } from "bun:test";
-
-describe("${options.featureName} - Acceptance Tests", () => {
-  test("AC-1: <description>", async () => {
-    // Test implementation
-  });
-});
-
-IMPORTANT: Output raw TypeScript code only. Do NOT use markdown code fences (\`\`\`typescript or \`\`\`). Start directly with the import statement.`;
-
-  logger.info("acceptance", "Generating tests from PRD refined criteria", { count: refinedCriteria.length });
-
-  const rawOutput = await _generatorPRDDeps.adapter.complete(prompt, {
-    model: options.modelDef.model,
-    config: options.config,
-  });
-  const testCode = extractTestCode(rawOutput);
-
-  if (!testCode) {
-    logger.warn("acceptance", "LLM returned non-code output for acceptance tests — falling back to skeleton", {
-      outputPreview: rawOutput.slice(0, 200),
-    });
-    const skeletonCriteria: AcceptanceCriterion[] = refinedCriteria.map((c, i) => ({
-      id: `AC-${i + 1}`,
-      text: c.refined,
-      lineNumber: i + 1,
-    }));
-    return { testCode: generateSkeletonTests(options.featureName, skeletonCriteria), criteria: skeletonCriteria };
-  }
-
-  const refinedJsonContent = JSON.stringify(
-    refinedCriteria.map((c, i) => ({
-      acId: `AC-${i + 1}`,
-      original: c.original,
-      refined: c.refined,
-      testable: c.testable,
-      storyId: c.storyId,
-    })),
-    null,
-    2,
-  );
-
-  await _generatorPRDDeps.writeFile(join(options.featureDir, "acceptance-refined.json"), refinedJsonContent);
-
-  return { testCode, criteria };
-}
-
-function buildStrategyInstructions(strategy?: string, framework?: string): string {
-  switch (strategy) {
-    case "component": {
-      const fw = framework ?? "ink-testing-library";
-      if (fw === "react") {
-        return "TEST STRATEGY: component (react)\nImport render and screen from @testing-library/react. Render the component and use screen.getByText to assert on output.\n\n";
-      }
-      return "TEST STRATEGY: component (ink-testing-library)\nImport render from ink-testing-library. Render the component and use lastFrame() to assert on output.\n\n";
-    }
-    case "cli":
-      return "TEST STRATEGY: cli\nUse Bun.spawn to run the binary. Read stdout and assert on the text output.\n\n";
-    case "e2e":
-      return "TEST STRATEGY: e2e\nUse fetch() against http://localhost to call the running service. Assert on response body using response.text() or response.json().\n\n";
-    case "snapshot":
-      return "TEST STRATEGY: snapshot\nRender the component and use toMatchSnapshot() to capture and compare snapshots.\n\n";
-    default:
-      return "";
-  }
-}
-
-export function parseAcceptanceCriteria(specContent: string): AcceptanceCriterion[] {
-  const criteria: AcceptanceCriterion[] = [];
-  const lines = specContent.split("\n");
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const lineNumber = i + 1;
-
-    // Match patterns:
-    // - AC-1: description
-    // - [ ] AC-1: description
-    // AC-1: description
-    const acMatch = line.match(/^\s*-?\s*(?:\[.\])?\s*(AC-\d+):\s*(.+)$/i);
-
-    if (acMatch) {
-      const id = acMatch[1].toUpperCase(); // Normalize to uppercase
-      const text = acMatch[2].trim();
-
-      criteria.push({
-        id,
-        text,
-        lineNumber,
-      });
-    }
-  }
-
-  return criteria;
-}
-
-/**
- * Build LLM prompt for generating acceptance tests.
- *
- * Combines acceptance criteria, codebase context, and test generation instructions.
- *
- * @param criteria - Extracted acceptance criteria
- * @param featureName - Feature name for context
- * @param codebaseContext - File tree, dependencies, test patterns
- * @returns Formatted prompt string
- *
- * @example
- * ```ts
- * const prompt = buildAcceptanceTestPrompt(
- *   [{ id: "AC-1", text: "handles empty input", lineNumber: 5 }],
- *   "url-shortener",
- *   "File tree:\nsrc/\n  index.ts\n"
- * );
- * ```
- */
-export function buildAcceptanceTestPrompt(
-  criteria: AcceptanceCriterion[],
-  featureName: string,
-  codebaseContext: string,
-): string {
-  const criteriaList = criteria.map((ac) => `${ac.id}: ${ac.text}`).join("\n");
-
-  return `You are a test engineer. Generate acceptance tests for the "${featureName}" feature based on the acceptance criteria below.
-
-CODEBASE CONTEXT:
-${codebaseContext}
-
-ACCEPTANCE CRITERIA:
-${criteriaList}
-
-Generate a complete acceptance.test.ts file using bun:test framework. Follow these rules:
-
-1. **One test per AC**: Each acceptance criterion maps to exactly one test
-2. **Test observable behavior only**: No implementation details, only user-facing behavior
-3. **Independent tests**: No shared state between tests
-4. **Real-implementation**: Tests should use real implementations without mocking (test observable behavior, not internal units)
-5. **Clear test names**: Use format "AC-N: <description>" for test names
-6. **Async where needed**: Use async/await for operations that may be asynchronous
-
-Use this structure:
-
-\`\`\`typescript
-import { describe, test, expect } from "bun:test";
-
-describe("${featureName} - Acceptance Tests", () => {
-  test("AC-1: <description>", async () => {
-    // Test implementation
-  });
-
-  test("AC-2: <description>", async () => {
-    // Test implementation
-  });
-});
-\`\`\`
-
-**Important**:
-- Import the feature code being tested
-- Set up any necessary test fixtures
-- Use expect() assertions to verify behavior
-- Clean up resources if needed (close connections, delete temp files)
-
-Respond with ONLY the TypeScript test code (no markdown code fences, no explanation).`;
-}
-
-/**
- * Generate acceptance tests from spec.md acceptance criteria.
- *
- * Parses AC lines from spec, builds LLM prompt, calls agent adapter,
- * and returns generated test code. Falls back to skeleton tests if LLM fails.
- *
- * @param adapter - Agent adapter to use for test generation
- * @param options - Generation options with spec content, context, and model
- * @returns Generated test code and processed criteria
- * @throws Error if AC parsing fails or agent call fails critically
- *
- * @example
- * ```ts
- * const adapter = new ClaudeCodeAdapter();
- * const result = await generateAcceptanceTests(adapter, {
- *   specContent: await Bun.file("spec.md").text(),
- *   featureName: "url-shortener",
- *   workdir: "/project",
- *   codebaseContext: "File tree:\nsrc/\n",
- *   modelTier: "balanced",
- *   modelDef: { provider: "anthropic", model: "claude-sonnet-4-5" },
- * });
- *
- * await Bun.write("acceptance.test.ts", result.testCode);
- * ```
- */
-export async function generateAcceptanceTests(
-  adapter: AgentAdapter,
-  options: GenerateAcceptanceTestsOptions,
-): Promise<AcceptanceTestResult> {
-  // Parse acceptance criteria from spec
-  const logger = getLogger();
-  const criteria = parseAcceptanceCriteria(options.specContent);
-
-  if (criteria.length === 0) {
-    // No AC found — generate empty skeleton
-    logger.warn("acceptance", "⚠ No acceptance criteria found in spec.md");
-    return {
-      testCode: generateSkeletonTests(options.featureName, []),
-      criteria: [],
-    };
-  }
-
-  logger.info("acceptance", "Found acceptance criteria", { count: criteria.length });
-
-  // Build prompt
-  const prompt = buildAcceptanceTestPrompt(criteria, options.featureName, options.codebaseContext);
-
-  try {
-    // Call adapter to generate tests
-    const output = await adapter.complete(prompt, {
-      model: options.modelDef.model,
-      config: options.config,
-    });
-
-    // Extract test code from output
-    const testCode = extractTestCode(output);
-
-    if (!testCode) {
-      logger.warn("acceptance", "LLM returned non-code output for acceptance tests — falling back to skeleton", {
-        outputPreview: output.slice(0, 200),
-      });
-      return {
-        testCode: generateSkeletonTests(options.featureName, criteria),
-        criteria,
-      };
-    }
-
-    return {
-      testCode,
-      criteria,
-    };
-  } catch (error) {
-    logger.warn("acceptance", "⚠ Agent test generation error", { error: (error as Error).message });
-    // Fall back to skeleton
-    return {
-      testCode: generateSkeletonTests(options.featureName, criteria),
-      criteria,
-    };
-  }
-}
-
-/**
- * Extract TypeScript test code from agent output.
- *
- * Handles markdown code fences and extracts clean test code.
- *
- * @param output - Agent stdout
- * @returns Extracted test code
- */
-function extractTestCode(output: string): string | null {
-  let code: string | undefined;
-
-  // Try to extract from markdown code fence
-  const fenceMatch = output.match(/```(?:typescript|ts)?\s*([\s\S]*?)\s*```/);
-  if (fenceMatch) {
-    code = fenceMatch[1].trim();
-  }
-
-  // If no fence, try to find import statement and take everything from there
-  if (!code) {
-    const importMatch = output.match(/import\s+{[\s\S]+/);
-    if (importMatch) {
-      code = importMatch[0].trim();
-    }
-  }
-
-  // If no fence and no import, try to find describe() block
-  if (!code) {
-    const describeMatch = output.match(/describe\s*\([\s\S]+/);
-    if (describeMatch) {
-      code = describeMatch[0].trim();
-    }
-  }
-
-  if (!code) return null;
-
-  // Validate: extracted code must contain at least one test-like keyword
-  const hasTestKeyword = /\b(?:describe|test|it|expect)\s*\(/.test(code);
-  if (!hasTestKeyword) {
-    return null;
-  }
-
-  return code;
-}
-
-/**
- * Generate skeleton acceptance tests with TODO placeholders.
- *
- * Used as fallback when LLM test generation fails.
- *
- * @param featureName - Feature name
- * @param criteria - Acceptance criteria to generate skeletons for
- * @returns TypeScript test code with TODO placeholders
- *
- * @example
- * ```ts
- * const skeleton = generateSkeletonTests("auth", [
- *   { id: "AC-1", text: "login succeeds", lineNumber: 5 },
- * ]);
- * // Generates test with TODO comment
- * ```
- */
-export function generateSkeletonTests(featureName: string, criteria: AcceptanceCriterion[]): string {
-  const tests = criteria
-    .map((ac) => {
-      return `  test("${ac.id}: ${ac.text}", async () => {
-    // TODO: Implement acceptance test for ${ac.id}
-    // ${ac.text}
-    expect(true).toBe(false); // Replace with actual test
-  });`;
-    })
-    .join("\n\n");
-
-  return `import { describe, test, expect } from "bun:test";
-
-describe("${featureName} - Acceptance Tests", () => {
-${tests || "  // No acceptance criteria found"}
-});
-`;
-}

package/src/acceptance/index.ts

@@ -1,42 +0,0 @@
-/**
- * Acceptance Test Generation Module
- *
- * Barrel exports for acceptance test generation functionality.
- */
-
-export type {
-  AcceptanceCriterion,
-  GenerateAcceptanceTestsOptions,
-  GenerateFromPRDOptions,
-  AcceptanceTestResult,
-  RefinedCriterion,
-  RefinementContext,
-} from "./types";
-
-export {
-  buildRefinementPrompt,
-  parseRefinementResponse,
-  refineAcceptanceCriteria,
-  _refineDeps,
-} from "./refinement";
-
-export {
-  parseAcceptanceCriteria,
-  buildAcceptanceTestPrompt,
-  generateAcceptanceTests,
-  generateFromPRD,
-  generateSkeletonTests,
-  _generatorPRDDeps,
-} from "./generator";
-
-export type {
-  FixStory,
-  GenerateFixStoriesOptions,
-} from "./fix-generator";
-
-export {
-  generateFixStories,
-  findRelatedStories,
-  parseACTextFromSpec,
-  convertFixStoryToUserStory,
-} from "./fix-generator";

package/src/acceptance/refinement.ts

@@ -1,224 +0,0 @@
-/**
- * AC Refinement Module
- *
- * Takes raw PRD acceptanceCriteria strings and refines them into concrete,
- * testable assertions using an LLM call via adapter.complete().
- */
-
-import type { AgentAdapter } from "../agents";
-import { ClaudeCodeAdapter } from "../agents/claude";
-import { resolveModel } from "../config/schema";
-import { getLogger } from "../logger";
-import { errorMessage } from "../utils/errors";
-import type { RefinedCriterion, RefinementContext } from "./types";
-
-/**
- * Injectable dependencies — allows tests to mock adapter.complete()
- * without needing the claude binary.
- *
- * @internal
- */
-export const _refineDeps = {
-  adapter: new ClaudeCodeAdapter() as AgentAdapter,
-};
-
-/**
- * Strategy-specific context for the refinement prompt.
- */
-export interface RefinementPromptOptions {
-  /** Test strategy — controls strategy-specific prompt instructions */
-  testStrategy?: "unit" | "component" | "cli" | "e2e" | "snapshot";
-  /** Test framework — informs LLM which testing library syntax to use */
-  testFramework?: string;
-}
-
-/**
- * Build the LLM prompt for refining acceptance criteria.
- *
- * @param criteria - Raw AC strings from PRD
- * @param codebaseContext - File tree / dependency context
- * @param options - Optional strategy/framework context
- * @returns Formatted prompt string
- */
-export function buildRefinementPrompt(
-  criteria: string[],
-  codebaseContext: string,
-  options?: RefinementPromptOptions,
-): string {
-  const criteriaList = criteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
-  const strategySection = buildStrategySection(options);
-  const refinedExample = buildRefinedExample(options?.testStrategy);
-
-  return `You are an acceptance criteria refinement assistant. Your task is to convert raw acceptance criteria into concrete, machine-verifiable assertions.
-
-CODEBASE CONTEXT:
-${codebaseContext}
-${strategySection}
-ACCEPTANCE CRITERIA TO REFINE:
-${criteriaList}
-
-For each criterion, produce a refined version that is concrete and automatically testable where possible.
-Respond with ONLY a JSON array (no markdown code fences):
-[{
-  "original": "<exact original criterion text>",
-  "refined": "<concrete, machine-verifiable description>",
-  "testable": true,
-  "storyId": ""
-}]
-
-Rules:
-- "original" must match the input criterion text exactly
-- "refined" must be a concrete assertion (e.g., ${refinedExample})
-- "testable" is false only if the criterion cannot be automatically verified (e.g., "UX feels responsive", "design looks good")
-- "storyId" leave as empty string — it will be assigned by the caller
-- Respond with ONLY the JSON array`;
-}
-
-/**
- * Build strategy-specific instructions section for the prompt.
- */
-function buildStrategySection(options?: RefinementPromptOptions): string {
-  if (!options?.testStrategy) {
-    return "";
-  }
-
-  const framework = options.testFramework ? ` Use ${options.testFramework} testing library syntax.` : "";
-
-  switch (options.testStrategy) {
-    case "component":
-      return `
-TEST STRATEGY: component
-Focus assertions on rendered output visible on screen — text content, visible elements, and screen state.
-Assert what the user sees rendered in the component, not what internal functions produce.${framework}
-`;
-    case "cli":
-      return `
-TEST STRATEGY: cli
-Focus assertions on stdout and stderr text output from the CLI command.
-Assert about terminal output content, exit codes, and standard output/standard error streams.${framework}
-`;
-    case "e2e":
-      return `
-TEST STRATEGY: e2e
-Focus assertions on HTTP response content — status codes, response bodies, and endpoint behavior.
-Assert about HTTP responses, status codes, and API endpoint output.${framework}
-`;
-    default:
-      return framework ? `\nTEST FRAMEWORK: ${options.testFramework}\n` : "";
-  }
-}
-
-/**
- * Build the "refined" example string based on the test strategy.
- */
-function buildRefinedExample(testStrategy?: RefinementPromptOptions["testStrategy"]): string {
-  switch (testStrategy) {
-    case "component":
-      return '"Text content visible on screen matches expected", "Rendered output contains expected element"';
-    case "cli":
-      return '"stdout contains expected text", "stderr is empty on success", "exit code is 0"';
-    case "e2e":
-      return '"HTTP status 200 returned", "Response body contains expected field", "Endpoint returns JSON"';
-    default:
-      return '"Array of length N returned", "HTTP status 200 returned"';
-  }
-}
-
-/**
- * Parse the LLM JSON response into RefinedCriterion[].
- *
- * Falls back gracefully: if JSON is malformed or a criterion is missing,
- * uses the original text with testable: true.
- *
- * @param response - Raw LLM response text
- * @param criteria - Original criteria strings (used as fallback)
- * @returns Array of refined criteria
- */
-export function parseRefinementResponse(response: string, criteria: string[]): RefinedCriterion[] {
-  if (!response || !response.trim()) {
-    return fallbackCriteria(criteria);
-  }
-
-  try {
-    const parsed: unknown = JSON.parse(response);
-
-    if (!Array.isArray(parsed)) {
-      return fallbackCriteria(criteria);
-    }
-
-    return (parsed as RefinedCriterion[]).map((item, i) => ({
-      original: typeof item.original === "string" && item.original.length > 0 ? item.original : (criteria[i] ?? ""),
-      refined: typeof item.refined === "string" && item.refined.length > 0 ? item.refined : (criteria[i] ?? ""),
-      testable: typeof item.testable === "boolean" ? item.testable : true,
-      storyId: typeof item.storyId === "string" ? item.storyId : "",
-    }));
-  } catch {
-    return fallbackCriteria(criteria);
-  }
-}
-
-/**
- * Refine raw acceptance criteria strings into concrete, testable assertions.
- *
- * @param criteria - Raw AC strings from PRD
- * @param context - Refinement context (storyId, codebase context, config)
- * @returns Promise resolving to array of refined criteria
- */
-export async function refineAcceptanceCriteria(
-  criteria: string[],
-  context: RefinementContext,
-): Promise<RefinedCriterion[]> {
-  if (criteria.length === 0) {
-    return [];
-  }
-
-  const { storyId, codebaseContext, config, testStrategy, testFramework } = context;
-  const logger = getLogger();
-
-  const modelTier = config.acceptance?.model ?? "fast";
-  const modelEntry = config.models[modelTier] ?? config.models.fast;
-
-  if (!modelEntry) {
-    throw new Error(`[refinement] config.models.${modelTier} not configured`);
-  }
-
-  const modelDef = resolveModel(modelEntry);
-  const prompt = buildRefinementPrompt(criteria, codebaseContext, { testStrategy, testFramework });
-
-  let response: string;
-
-  try {
-    response = await _refineDeps.adapter.complete(prompt, {
-      jsonMode: true,
-      maxTokens: 4096,
-      model: modelDef.model,
-      config,
-    });
-  } catch (error) {
-    const reason = errorMessage(error);
-    logger.warn("refinement", "adapter.complete() failed, falling back to original criteria", {
-      storyId,
-      error: reason,
-    });
-    return fallbackCriteria(criteria, storyId);
-  }
-
-  const parsed = parseRefinementResponse(response, criteria);
-
-  return parsed.map((item) => ({
-    ...item,
-    storyId: item.storyId || storyId,
-  }));
-}
-
-/**
- * Build fallback RefinedCriterion[] using original criterion text.
- */
-function fallbackCriteria(criteria: string[], storyId = ""): RefinedCriterion[] {
-  return criteria.map((c) => ({
-    original: c,
-    refined: c,
-    testable: true,
-    storyId,
-  }));
-}