@nathapp/nax 0.18.1

package/src/analyze/scanner.ts

@@ -0,0 +1,175 @@
+/**
+ * Codebase Scanner
+ *
+ * Scans the project directory to generate a summary for LLM classification.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { CodebaseScan } from "./types";
+
+/**
+ * Scan codebase to generate summary for LLM classification.
+ *
+ * Generates:
+ * - File tree (src/ directory, max depth 3)
+ * - Package.json dependencies
+ * - Test pattern detection
+ *
+ * @param workdir - Project root directory
+ * @returns Codebase scan result
+ *
+ * @example
+ * ```ts
+ * const scan = await scanCodebase("/path/to/project");
+ * console.log(scan.fileTree);
+ * console.log(scan.dependencies);
+ * ```
+ */
+export async function scanCodebase(workdir: string): Promise<CodebaseScan> {
+  const srcPath = join(workdir, "src");
+  const packageJsonPath = join(workdir, "package.json");
+
+  // Generate file tree (src/ only, max depth 3)
+  const fileTree = existsSync(srcPath) ? await generateFileTree(srcPath, 3) : "No src/ directory";
+
+  // Extract dependencies from package.json
+  let dependencies: Record<string, string> = {};
+  let devDependencies: Record<string, string> = {};
+
+  if (existsSync(packageJsonPath)) {
+    try {
+      const pkg = await Bun.file(packageJsonPath).json();
+      dependencies = pkg.dependencies || {};
+      devDependencies = pkg.devDependencies || {};
+    } catch {
+      // Invalid package.json, use empty deps
+    }
+  }
+
+  // Detect test patterns
+  const testPatterns = detectTestPatterns(workdir, dependencies, devDependencies);
+
+  return {
+    fileTree,
+    dependencies,
+    devDependencies,
+    testPatterns,
+  };
+}
+
+/**
+ * Generate file tree for a directory with depth limit.
+ *
+ * @param dir - Directory path
+ * @param maxDepth - Maximum depth to traverse
+ * @param currentDepth - Current depth (internal)
+ * @param prefix - Line prefix for formatting (internal)
+ * @returns Formatted file tree string
+ */
+async function generateFileTree(dir: string, maxDepth: number, currentDepth = 0, prefix = ""): Promise<string> {
+  if (currentDepth >= maxDepth) {
+    return "";
+  }
+
+  const entries: string[] = [];
+
+  try {
+    const dirEntries = Array.from(
+      new Bun.Glob("*").scanSync({
+        cwd: dir,
+        onlyFiles: false,
+      }),
+    );
+
+    // Sort: directories first, then files
+    dirEntries.sort((a, b) => {
+      const aIsDir = !a.includes(".");
+      const bIsDir = !b.includes(".");
+      if (aIsDir && !bIsDir) return -1;
+      if (!aIsDir && bIsDir) return 1;
+      return a.localeCompare(b);
+    });
+
+    for (let i = 0; i < dirEntries.length; i++) {
+      const entry = dirEntries[i];
+      const fullPath = join(dir, entry);
+      const isLast = i === dirEntries.length - 1;
+      const connector = isLast ? "└── " : "├── ";
+      const childPrefix = isLast ? "    " : "│   ";
+
+      // Check if directory
+      const stat = await Bun.file(fullPath).stat();
+      const isDir = stat.isDirectory();
+
+      entries.push(`${prefix}${connector}${entry}${isDir ? "/" : ""}`);
+
+      // Recurse into directories
+      if (isDir) {
+        const subtree = await generateFileTree(fullPath, maxDepth, currentDepth + 1, prefix + childPrefix);
+        if (subtree) {
+          entries.push(subtree);
+        }
+      }
+    }
+  } catch {
+    // Directory not accessible, skip
+  }
+
+  return entries.join("\n");
+}
+
+/**
+ * Detect test patterns from directory structure and dependencies.
+ *
+ * Checks for:
+ * - Test framework (vitest, jest, bun:test, mocha, etc.)
+ * - Test directory structure (test/, __tests__/)
+ * - Test file patterns (*.test.ts, *.spec.ts)
+ *
+ * @param workdir - Project root directory
+ * @param dependencies - Production dependencies
+ * @param devDependencies - Dev dependencies
+ * @returns Array of detected patterns
+ */
+function detectTestPatterns(
+  workdir: string,
+  dependencies: Record<string, string>,
+  devDependencies: Record<string, string>,
+): string[] {
+  const patterns: string[] = [];
+  const allDeps = { ...dependencies, ...devDependencies };
+
+  // Detect test framework
+  if (allDeps.vitest) {
+    patterns.push("Test framework: vitest");
+  } else if (allDeps.jest || allDeps["@jest/globals"]) {
+    patterns.push("Test framework: jest");
+  } else if (allDeps.mocha) {
+    patterns.push("Test framework: mocha");
+  } else if (allDeps.ava) {
+    patterns.push("Test framework: ava");
+  } else {
+    // Check for bun:test (no package.json entry)
+    patterns.push("Test framework: likely bun:test (no framework dependency)");
+  }
+
+  // Detect test directory
+  if (existsSync(join(workdir, "test"))) {
+    patterns.push("Test directory: test/");
+  }
+  if (existsSync(join(workdir, "__tests__"))) {
+    patterns.push("Test directory: __tests__/");
+  }
+  if (existsSync(join(workdir, "tests"))) {
+    patterns.push("Test directory: tests/");
+  }
+
+  // Detect test file patterns
+  const hasTestFiles = existsSync(join(workdir, "test")) || existsSync(join(workdir, "src"));
+  if (hasTestFiles) {
+    patterns.push("Test files: *.test.ts, *.spec.ts");
+  }
+
+  return patterns;
+}

package/src/analyze/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Analyze Module Types
+ *
+ * Types for codebase scanning and LLM-enhanced classification.
+ */
+
+import type { Complexity } from "../config";
+
+/** Codebase scan result */
+export interface CodebaseScan {
+  /** File tree (src/ directory, max depth 3) */
+  fileTree: string;
+  /** Package dependencies */
+  dependencies: Record<string, string>;
+  /** Dev dependencies */
+  devDependencies: Record<string, string>;
+  /** Detected test patterns */
+  testPatterns: string[];
+}
+
+/** LLM classification result for a single story */
+export interface StoryClassification {
+  /** Story ID (e.g., "US-001") */
+  storyId: string;
+  /** Classified complexity */
+  complexity: Complexity;
+  /** Context files to inject into agent prompt before execution */
+  contextFiles: string[];
+  /** Reasoning for the classification */
+  reasoning: string;
+  /** Estimated lines of code to change */
+  estimatedLOC: number;
+  /** Potential implementation risks */
+  risks: string[];
+}
+
+/** LLM classifier response (array of classifications) */
+export type ClassifierResponse = StoryClassification[];
+
+/** Classification method used */
+export type ClassificationMethod = "llm" | "keyword-fallback";
+
+/** Classification result with metadata */
+export interface ClassificationResult {
+  /** Classification data */
+  classifications: StoryClassification[];
+  /** Method used (llm or keyword-fallback) */
+  method: ClassificationMethod;
+  /** Error message if LLM failed and fallback was used */
+  fallbackReason?: string;
+}

package/src/cli/accept.ts

@@ -0,0 +1,108 @@
+/**
+ * Accept Command
+ *
+ * Allows manual override of failed acceptance criteria.
+ * Stores override in prd.json with reason.
+ *
+ * Usage:
+ *   nax accept --override AC-2 "intentional: using lazy expiry instead of exact timing"
+ */
+
+import path from "node:path";
+import { findProjectDir, validateDirectory } from "../config";
+import { NaxError } from "../errors";
+import { getLogger } from "../logger";
+import { loadPRD, savePRD } from "../prd";
+
+/**
+ * Accept command options.
+ */
+export interface AcceptOptions {
+  /** Feature name */
+  feature: string;
+  /** AC ID to override (e.g., "AC-2") */
+  override: string;
+  /** Reason for accepting despite test failure */
+  reason: string;
+}
+
+/**
+ * Execute the accept command.
+ *
+ * Loads the PRD, adds the AC override with reason, and saves.
+ *
+ * @param options - Command options
+ *
+ * @example
+ * ```bash
+ * nax accept --feature auth-system --override AC-2 "intentional: lazy expiry"
+ * ```
+ */
+export async function acceptCommand(options: AcceptOptions): Promise<void> {
+  const logger = getLogger();
+  const { feature, override, reason } = options;
+
+  // Validate AC ID format
+  if (!override.match(/^AC-\d+$/i)) {
+    logger.error("cli", "Invalid AC ID format", { override, expected: "AC-1, AC-2, etc." });
+    throw new NaxError("Invalid AC ID format", "INVALID_AC_ID", { override, expected: "AC-1, AC-2, etc." });
+  }
+
+  // Normalize AC ID to uppercase
+  const acId = override.toUpperCase();
+
+  // Find project directory
+  const projectDirResult = findProjectDir(process.cwd());
+  if (!projectDirResult) {
+    logger.error("cli", "Not in a nax project directory", { hint: "Run 'nax init' first" });
+    throw new NaxError("Not in a nax project directory", "PROJECT_NOT_FOUND", { hint: "Run 'nax init' first" });
+  }
+  const projectDir = projectDirResult;
+
+  // Validate directory
+  try {
+    validateDirectory(projectDir);
+  } catch (err) {
+    logger.error("cli", "Invalid project directory", { error: (err as Error).message });
+    throw new NaxError("Invalid project directory", "INVALID_DIRECTORY", { error: (err as Error).message });
+  }
+
+  // Build path to feature PRD
+  const featureDir = path.join(projectDir, "nax", "features", feature);
+  const prdPath = path.join(featureDir, "prd.json");
+
+  // Check if feature exists
+  const prdFile = Bun.file(prdPath);
+  if (!(await prdFile.exists())) {
+    logger.error("cli", "Feature not found", { feature, prdPath });
+    throw new NaxError("Feature not found", "FEATURE_NOT_FOUND", { feature, prdPath });
+  }
+
+  // Load PRD
+  const prd = await loadPRD(prdPath);
+
+  // Add override
+  if (!prd.acceptanceOverrides) {
+    prd.acceptanceOverrides = {};
+  }
+
+  if (prd.acceptanceOverrides[acId]) {
+    logger.warn("cli", "Override already exists", {
+      acId,
+      previous: prd.acceptanceOverrides[acId],
+      new: reason,
+    });
+  }
+
+  prd.acceptanceOverrides[acId] = reason;
+
+  // Save PRD
+  await savePRD(prd, prdPath);
+
+  logger.info("cli", "✓ Override added", {
+    acId,
+    reason,
+    prdPath,
+    hint: `Re-run acceptance tests: bun test ${path.join(featureDir, "acceptance.test.ts")}`,
+  });
+}

package/src/cli/analyze-parser.ts

@@ -0,0 +1,284 @@
+/**
+ * Analyze Parser & Classification
+ *
+ * Extracted from analyze.ts: spec parsing, keyword classification,
+ * codebase context building, and reclassification logic.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAgent } from "../agents/registry";
+import { scanCodebase } from "../analyze/scanner";
+import type { CodebaseScan } from "../analyze/types";
+import type { NaxConfig } from "../config";
+import { resolveModel } from "../config/schema";
+import { getLogger } from "../logger";
+import type { PRD, UserStory } from "../prd";
+import { loadPRD } from "../prd";
+import { classifyComplexity, routeTask } from "../routing";
+
+/** Parse user stories from spec.md markdown */
+export function parseUserStoriesFromSpec(markdown: string): UserStory[] {
+  const stories: UserStory[] = [];
+  const lines = markdown.split("\n");
+
+  let currentStory: Partial<UserStory> | null = null;
+  let currentSection: "title" | "description" | "criteria" | null = null;
+  let descriptionLines: string[] = [];
+  let criteriaLines: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    const storyMatch = line.match(/^##\s+(US-\d+|Story)(?::\s*(.+))?/);
+    if (storyMatch) {
+      if (currentStory) {
+        stories.push(finalizeStory(currentStory, descriptionLines, criteriaLines));
+      }
+
+      const id = storyMatch[1] === "Story" ? `US-${String(stories.length + 1).padStart(3, "0")}` : storyMatch[1];
+      currentStory = {
+        id,
+        title: storyMatch[2]?.trim() || "[Untitled]",
+        description: "",
+        acceptanceCriteria: [],
+        tags: [],
+        dependencies: [],
+        status: "pending",
+        passes: false,
+        escalations: [],
+        attempts: 0,
+      };
+      descriptionLines = [];
+      criteriaLines = [];
+      currentSection = "title";
+      continue;
+    }
+
+    if (!currentStory) continue;
+
+    if (line.match(/^###\s+Description/i)) {
+      currentSection = "description";
+      continue;
+    }
+    if (line.match(/^###\s+Acceptance\s+Criteria/i)) {
+      currentSection = "criteria";
+      continue;
+    }
+
+    if (currentSection === "description" && line.trim()) {
+      descriptionLines.push(line.trim());
+    }
+    if (currentSection === "criteria" && line.trim()) {
+      const criterionMatch = line.match(/^-\s+\[.\]\s+(.+)/);
+      if (criterionMatch) criteriaLines.push(criterionMatch[1].trim());
+    }
+
+    const tagsMatch = line.match(/^Tags:\s*(.+)/i);
+    if (tagsMatch && currentStory) {
+      currentStory.tags = tagsMatch[1]
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean);
+    }
+
+    const depsMatch = line.match(/^Dependencies:\s*(.+)/i);
+    if (depsMatch && currentStory) {
+      currentStory.dependencies = depsMatch[1]
+        .split(",")
+        .map((d) => d.trim())
+        .filter(Boolean);
+    }
+  }
+
+  if (currentStory) {
+    stories.push(finalizeStory(currentStory, descriptionLines, criteriaLines));
+  }
+
+  return stories;
+}
+
+/** Finalize a story by combining collected data */
+function finalizeStory(story: Partial<UserStory>, descriptionLines: string[], criteriaLines: string[]): UserStory {
+  return {
+    id: story.id || "US-000",
+    title: story.title || "[Untitled]",
+    description: descriptionLines.join(" ").trim() || story.title || "",
+    acceptanceCriteria: criteriaLines.length > 0 ? criteriaLines : ["Implementation complete"],
+    tags: story.tags || [],
+    dependencies: story.dependencies || [],
+    status: "pending",
+    passes: false,
+    escalations: [],
+    attempts: 0,
+  };
+}
+
+/** Build codebase context string from scan result. */
+export function buildCodebaseContext(scan: CodebaseScan): string {
+  return `FILE TREE:
+${scan.fileTree}
+
+DEPENDENCIES:
+${Object.entries(scan.dependencies)
+  .map(([name, version]) => `- ${name}: ${version}`)
+  .join("\n")}
+
+DEV DEPENDENCIES:
+${Object.entries(scan.devDependencies)
+  .map(([name, version]) => `- ${name}: ${version}`)
+  .join("\n")}
+
+TEST PATTERNS:
+${scan.testPatterns.map((p) => `- ${p}`).join("\n")}`.trim();
+}
+
+/** Apply keyword-based classification to user stories. */
+export function applyKeywordClassification(stories: UserStory[], config?: NaxConfig): UserStory[] {
+  return stories.map((story) => {
+    const complexity = classifyComplexity(story.title, story.description, story.acceptanceCriteria, story.tags);
+    const routing = config
+      ? routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, config)
+      : { complexity, testStrategy: "test-after" as const, reasoning: "No config provided" };
+
+    return {
+      ...story,
+      routing: {
+        complexity,
+        testStrategy: routing.testStrategy,
+        reasoning: `Keyword-based classification: ${complexity}`,
+        estimatedLOC: estimateLOCFromComplexity(complexity),
+        risks: [],
+        strategy: "keyword" as const,
+      },
+    };
+  });
+}
+
+/** Estimate LOC from complexity level (rough heuristic). */
+export function estimateLOCFromComplexity(complexity: "simple" | "medium" | "complex" | "expert"): number {
+  switch (complexity) {
+    case "simple":
+      return 50;
+    case "medium":
+      return 150;
+    case "complex":
+      return 400;
+    case "expert":
+      return 800;
+  }
+}
+
+/** Re-classify existing prd.json without decomposing. */
+export async function reclassifyExistingPRD(
+  featureDir: string,
+  featureName: string,
+  branchName: string,
+  workdir: string,
+  config?: NaxConfig,
+): Promise<PRD> {
+  const prdPath = join(featureDir, "prd.json");
+  if (!existsSync(prdPath)) {
+    throw new Error(`prd.json not found at ${prdPath}. Run analyze without --reclassify first.`);
+  }
+
+  const prd = await loadPRD(prdPath);
+  const logger = getLogger();
+  logger.info("cli", "Re-classifying existing stories");
+
+  const scan = await scanCodebase(workdir);
+  const codebaseContext = buildCodebaseContext(scan);
+  const updatedStories: UserStory[] = [];
+
+  for (const story of prd.userStories) {
+    const storySpec = `## ${story.id}: ${story.title}\n\n${story.description}\n\n### Acceptance Criteria\n${story.acceptanceCriteria.map((c) => `- ${c}`).join("\n")}`;
+
+    try {
+      if (config?.analyze.llmEnhanced) {
+        const classified = await reclassifyWithLLM(story, storySpec, workdir, codebaseContext, config);
+        updatedStories.push(classified);
+        logger.info("cli", `[OK] ${story.id} reclassified`, {
+          storyId: story.id,
+          complexity: classified.routing?.complexity,
+        });
+      } else {
+        const classified = reclassifyWithKeywords(story, config);
+        updatedStories.push(classified);
+        logger.info("cli", `[OK] ${story.id} reclassified`, {
+          storyId: story.id,
+          complexity: classified.routing?.complexity,
+        });
+      }
+    } catch (error) {
+      logger.warn("cli", `[WARN] ${story.id} kept original`, { storyId: story.id, error: (error as Error).message });
+      updatedStories.push(story);
+    }
+  }
+
+  return { ...prd, updatedAt: new Date().toISOString(), userStories: updatedStories };
+}
+
+/** Reclassify a single story via LLM agent. */
+async function reclassifyWithLLM(
+  story: UserStory,
+  storySpec: string,
+  workdir: string,
+  codebaseContext: string,
+  config: NaxConfig,
+): Promise<UserStory> {
+  const agentName = config.autoMode.defaultAgent;
+  const adapter = getAgent(agentName);
+  if (!adapter) throw new Error(`Agent "${agentName}" not found`);
+
+  const modelTier = config.analyze.model;
+  const modelDef = resolveModel(config.models[modelTier]);
+
+  const result = await adapter.decompose({ specContent: storySpec, workdir, codebaseContext, modelTier, modelDef });
+
+  if (result.stories.length === 0) return story;
+  const ds = result.stories[0];
+
+  let testStrategy: import("../config").TestStrategy;
+  let routingStrategy: "llm" | "keyword";
+  if (ds.testStrategy) {
+    testStrategy = ds.testStrategy;
+    routingStrategy = "llm";
+  } else {
+    const routing = routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, config);
+    testStrategy = routing.testStrategy;
+    routingStrategy = "keyword";
+  }
+
+  return {
+    ...story,
+    routing: {
+      complexity: ds.complexity,
+      testStrategy,
+      reasoning: ds.reasoning,
+      estimatedLOC: ds.estimatedLOC,
+      risks: ds.risks,
+      strategy: routingStrategy,
+      llmModel: routingStrategy === "llm" ? modelDef.model : undefined,
+    },
+    contextFiles: ds.contextFiles,
+  };
+}
+
+/** Reclassify a single story via keyword heuristics. */
+function reclassifyWithKeywords(story: UserStory, config?: NaxConfig): UserStory {
+  const complexity = classifyComplexity(story.title, story.description, story.acceptanceCriteria, story.tags);
+  const routing = config
+    ? routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, config)
+    : { complexity, testStrategy: "test-after" as const, reasoning: "No config provided" };
+
+  return {
+    ...story,
+    routing: {
+      complexity,
+      testStrategy: routing.testStrategy,
+      reasoning: `Keyword-based classification: ${complexity}`,
+      estimatedLOC: estimateLOCFromComplexity(complexity),
+      risks: [],
+    },
+  };
+}