@nathapp/nax 0.50.2 → 0.51.0

package/src/analyze/classifier.ts

@@ -1,282 +0,0 @@
-/**
- * LLM-Enhanced Classifier
- *
- * Uses a single cheap LLM call (haiku) to classify all stories in one shot.
- * Falls back to keyword matching if LLM call fails.
- */
-
-import type { AgentAdapter } from "../agents";
-import { ClaudeCodeAdapter } from "../agents/claude";
-import type { NaxConfig } from "../config";
-import { resolveModel } from "../config/schema";
-import { getLogger } from "../logger";
-import type { UserStory } from "../prd";
-import { classifyComplexity } from "../routing";
-import { errorMessage } from "../utils/errors";
-import type { ClassificationResult, CodebaseScan, StoryClassification } from "./types";
-
-/**
- * Injectable dependencies for classifier — allows tests to mock adapter.complete()
- * without needing the claude binary.
- *
- * @internal
- */
-export const _classifyDeps = {
-  adapter: new ClaudeCodeAdapter() as AgentAdapter,
-};
-
-/**
- * Raw LLM classification item (before validation)
- */
-interface LLMClassificationItem {
-  storyId: unknown;
-  complexity: unknown;
-  relevantFiles: unknown;
-  reasoning: unknown;
-  estimatedLOC: unknown;
-  risks: unknown;
-}
-
-/**
- * Classify stories using LLM-enhanced analysis with fallback to keyword matching.
- *
- * Makes a single Anthropic API call (haiku tier) to classify all stories.
- * If the LLM call fails or returns invalid JSON, falls back to keyword matching.
- *
- * @param stories - User stories to classify
- * @param scan - Codebase scan result
- * @param config - Ngent configuration
- * @returns Classification result with method used
- *
- * @example
- * ```ts
- * const result = await classifyStories(stories, scan, config);
- * if (result.method === "keyword-fallback") {
- *   console.warn("LLM classification failed:", result.fallbackReason);
- * }
- * console.log(result.classifications);
- * ```
- */
-export async function classifyStories(
-  stories: UserStory[],
-  scan: CodebaseScan,
-  config: NaxConfig,
-): Promise<ClassificationResult> {
-  // Check if LLM-enhanced analysis is enabled
-  if (!config.analyze?.llmEnhanced) {
-    return {
-      classifications: stories.map((story) => fallbackClassification(story)),
-      method: "keyword-fallback",
-      fallbackReason: "LLM-enhanced analysis disabled in config",
-    };
-  }
-
-  // Try LLM classification
-  try {
-    const classifications = await classifyWithLLM(stories, scan, config);
-    return {
-      classifications,
-      method: "llm",
-    };
-  } catch (error) {
-    // Fall back to keyword matching
-    const reason = errorMessage(error);
-    const logger = getLogger();
-    logger.warn("analyze", "LLM classification failed, falling back to keyword matching", { error: reason });
-
-    return {
-      classifications: stories.map((story) => fallbackClassification(story)),
-      method: "keyword-fallback",
-      fallbackReason: reason,
-    };
-  }
-}
-
-/**
- * Classify stories using LLM with structured JSON output.
- *
- * @param stories - User stories to classify
- * @param scan - Codebase scan result
- * @param config - Ngent configuration
- * @returns Array of story classifications
- */
-async function classifyWithLLM(
-  stories: UserStory[],
-  scan: CodebaseScan,
-  config: NaxConfig,
-): Promise<StoryClassification[]> {
-  // Build prompt
-  const prompt = buildClassificationPrompt(stories, scan);
-
-  // Resolve model from config.models.fast
-  const fastModelEntry = config.models.fast;
-  if (!fastModelEntry) {
-    throw new Error("config.models.fast not configured");
-  }
-  const modelDef = resolveModel(fastModelEntry);
-
-  // Make API call via adapter (uses config.models.fast tier)
-  const jsonText = await _classifyDeps.adapter.complete(prompt, {
-    jsonMode: true,
-    maxTokens: 4096,
-    model: modelDef.model,
-    config,
-  });
-
-  // Parse JSON response
-  const parsed: unknown = JSON.parse(jsonText);
-
-  // Validate structure
-  if (!Array.isArray(parsed)) {
-    throw new Error("LLM response is not an array");
-  }
-
-  // Map to StoryClassification[]
-  const classifications: StoryClassification[] = parsed.map((item: unknown) => {
-    const rawItem = item as LLMClassificationItem;
-    return {
-      storyId: String(rawItem.storyId),
-      complexity: validateComplexity(rawItem.complexity),
-      contextFiles: Array.isArray(rawItem.relevantFiles) ? rawItem.relevantFiles.map(String) : [],
-      reasoning: String(rawItem.reasoning || "No reasoning provided"),
-      estimatedLOC: Number(rawItem.estimatedLOC) || 0,
-      risks: Array.isArray(rawItem.risks) ? rawItem.risks.map(String) : [],
-    };
-  });
-
-  // Ensure all stories are classified
-  const classifiedIds = new Set(classifications.map((c) => c.storyId));
-  for (const story of stories) {
-    if (!classifiedIds.has(story.id)) {
-      throw new Error(`Story ${story.id} not classified by LLM`);
-    }
-  }
-
-  return classifications;
-}
-
-/**
- * Build classification prompt for LLM.
- *
- * @param stories - User stories to classify
- * @param scan - Codebase scan result
- * @returns Formatted prompt string
- */
-function buildClassificationPrompt(stories: UserStory[], scan: CodebaseScan): string {
-  // Format codebase summary
-  const codebaseSummary = `
-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();
-
-  // Format stories as JSON for LLM
-  const storiesJson = JSON.stringify(
-    stories.map((s) => ({
-      id: s.id,
-      title: s.title,
-      description: s.description,
-      acceptanceCriteria: s.acceptanceCriteria,
-      tags: s.tags,
-    })),
-    null,
-    2,
-  );
-
-  return `You are a code complexity classifier. Given a codebase summary and user stories,
-classify each story's implementation complexity.
-
-CODEBASE:
-${codebaseSummary}
-
-STORIES:
-${storiesJson}
-
-For each story, respond with a JSON array (and ONLY the JSON array, no markdown code fences):
-[{
-  "storyId": "US-001",
-  "complexity": "simple|medium|complex|expert",
-  "relevantFiles": ["src/path/to/file.ts"],
-  "reasoning": "Why this complexity level",
-  "estimatedLOC": 50,
-  "risks": ["No existing cache layer"]
-}]
-
-Classification rules:
-- simple: 1-3 files, <100 LOC, straightforward implementation, existing patterns
-- medium: 3-6 files, 100-300 LOC, moderate logic, some new patterns
-- complex: 6+ files, 300-800 LOC, architectural changes, cross-cutting concerns
-- expert: Security/crypto/real-time/distributed systems, >800 LOC, new infrastructure
-
-Consider:
-1. Does infrastructure exist? (e.g., "add caching" when no cache layer exists = complex)
-2. How many files will be touched?
-3. Are there cross-cutting concerns (auth, validation, error handling)?
-4. Does it require new dependencies or architectural decisions?
-
-Respond with ONLY the JSON array.`;
-}
-
-/**
- * Validate complexity value from LLM response.
- *
- * @param value - Complexity value from LLM
- * @returns Valid Complexity type
- */
-function validateComplexity(value: unknown): "simple" | "medium" | "complex" | "expert" {
-  if (value === "simple" || value === "medium" || value === "complex" || value === "expert") {
-    return value;
-  }
-  // Default to medium if invalid
-  return "medium";
-}
-
-/**
- * Fallback classification using keyword matching.
- *
- * @param story - User story to classify
- * @returns Story classification using keyword-based complexity
- */
-function fallbackClassification(story: UserStory): StoryClassification {
-  const complexity = classifyComplexity(story.title, story.description, story.acceptanceCriteria, story.tags);
-
-  return {
-    storyId: story.id,
-    complexity,
-    contextFiles: [],
-    reasoning: `Keyword-based classification: ${complexity}`,
-    estimatedLOC: estimateLOCFromComplexity(complexity),
-    risks: [],
-  };
-}
-
-/**
- * Estimate LOC from complexity level (rough heuristic).
- *
- * @param complexity - Complexity level
- * @returns Estimated lines of code
- */
-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;
-  }
-}

package/src/analyze/index.ts

@@ -1,16 +0,0 @@
-/**
- * Analyze Module
- *
- * LLM-enhanced story classification with codebase scanning.
- */
-
-export type {
-  CodebaseScan,
-  StoryClassification,
-  ClassifierResponse,
-  ClassificationMethod,
-  ClassificationResult,
-} from "./types";
-
-export { scanCodebase } from "./scanner";
-export { classifyStories } from "./classifier";

package/src/analyze/scanner.ts

@@ -1,171 +0,0 @@
-/**
- * Codebase Scanner
- *
- * Scans the project directory to generate a summary for LLM classification.
- */
-
-import { existsSync, readdirSync } 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 {
-    // readdirSync with withFileTypes avoids a separate stat() call per entry —
-    // directory info comes from the single readdir syscall (much faster on large trees).
-    const dirEntries = readdirSync(dir, { withFileTypes: true });
-
-    // Sort: directories first, then files
-    dirEntries.sort((a, b) => {
-      if (a.isDirectory() && !b.isDirectory()) return -1;
-      if (!a.isDirectory() && b.isDirectory()) return 1;
-      return a.name.localeCompare(b.name);
-    });
-
-    for (let i = 0; i < dirEntries.length; i++) {
-      const dirent = dirEntries[i];
-      const isLast = i === dirEntries.length - 1;
-      const connector = isLast ? "└── " : "├── ";
-      const childPrefix = isLast ? "    " : "│   ";
-      const isDir = dirent.isDirectory();
-
-      entries.push(`${prefix}${connector}${dirent.name}${isDir ? "/" : ""}`);
-
-      // Recurse into directories
-      if (isDir) {
-        const subtree = await generateFileTree(
-          join(dir, dirent.name),
-          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

@@ -1,51 +0,0 @@
-/**
- * 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

@@ -1,108 +0,0 @@
-/**
- * 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")}`,
-  });
-}