@nathapp/nax 0.50.3 → 0.51.0

package/src/context/auto-detect.ts

@@ -1,228 +0,0 @@
-/**
- * Auto-detection for contextFiles when PRD omits them (BUG-006)
- *
- * Extracts keywords from story title, runs git grep to find matching source files,
- * excludes test/index/generated files, caps at maxFiles.
- */
-
-import { getLogger } from "../logger";
-import { errorMessage } from "../utils/errors";
-
-export interface AutoDetectOptions {
-  /** Working directory for git grep */
-  workdir: string;
-  /** Story title to extract keywords from */
-  storyTitle: string;
-  /** Maximum files to return (default: 5) */
-  maxFiles?: number;
-  /** Enable import tracing (default: false, reserved for future use) */
-  traceImports?: boolean;
-}
-
-/**
- * Extract keywords from story title for git grep search.
- *
- * Heuristics:
- * - Remove common words (the, a, an, and, or, to, from, for, with, etc.)
- * - Split on spaces/punctuation
- * - Keep words >= 3 chars
- * - Lowercase for case-insensitive matching
- *
- * @example
- * extractKeywords("BUG-006: Context auto-detection (contextFiles)")
- * // => ["bug", "006", "context", "auto", "detection", "contextfiles"]
- */
-export function extractKeywords(title: string): string[] {
-  const stopWords = new Set([
-    "the",
-    "a",
-    "an",
-    "and",
-    "or",
-    "to",
-    "from",
-    "for",
-    "with",
-    "in",
-    "on",
-    "at",
-    "by",
-    "is",
-    "are",
-    "was",
-    "were",
-    "be",
-    "been",
-    "being",
-    "have",
-    "has",
-    "had",
-    "do",
-    "does",
-    "did",
-    "will",
-    "would",
-    "should",
-    "could",
-    "may",
-    "might",
-    "can",
-    "must",
-    "of",
-    "as",
-    "if",
-    "when",
-    "bug",
-    "fix",
-    "add",
-    "update",
-    "remove",
-    "implement",
-  ]);
-
-  // Split on non-alphanumeric, filter, lowercase
-  const words = title
-    .toLowerCase()
-    .split(/[^a-z0-9]+/)
-    .filter((w) => w.length >= 3 && !stopWords.has(w));
-
-  // Deduplicate
-  return Array.from(new Set(words));
-}
-
-/**
- * Auto-detect context files via git grep when PRD omits contextFiles.
- *
- * Algorithm:
- * 1. Extract keywords from story title
- * 2. Run git grep for each keyword in src/ directories
- * 3. Deduplicate files
- * 4. Exclude test/index/generated files
- * 5. Cap at maxFiles (default: 5)
- *
- * Returns empty array if:
- * - Not a git repository
- * - No keywords extracted
- * - git grep fails
- * - No matching files found
- *
- * @param options - Auto-detect configuration
- * @returns Array of relative file paths (sorted by relevance score)
- */
-export async function autoDetectContextFiles(options: AutoDetectOptions): Promise<string[]> {
-  const { workdir, storyTitle, maxFiles = 5 } = options;
-  const logger = getLogger();
-
-  // Extract keywords
-  const keywords = extractKeywords(storyTitle);
-  if (keywords.length === 0) {
-    logger.debug("auto-detect", "No keywords extracted from story title", { storyTitle });
-    return [];
-  }
-
-  logger.debug("auto-detect", "Extracted keywords", { keywords, storyTitle });
-
-  // Build git grep command
-  // Use -i for case-insensitive, -l for filename-only, -I to skip binary files
-  // Search in src/ directories only (exclude test, node_modules, etc.)
-  const grepPattern = keywords.join("|"); // OR pattern
-  const grepCommand = [
-    "git",
-    "grep",
-    "-i", // case-insensitive
-    "-l", // files-with-matches
-    "-I", // skip binary files
-    "-E", // extended regex
-    "-e",
-    grepPattern,
-    "--", // separator
-    "src/", // limit to src directory
-  ];
-
-  try {
-    const proc = Bun.spawn(grepCommand, {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const stdout = await new Response(proc.stdout).text();
-    const exitCode = await proc.exited;
-
-    // git grep returns 1 when no matches found (not an error)
-    if (exitCode !== 0 && exitCode !== 1) {
-      const stderr = await new Response(proc.stderr).text();
-      logger.warn("auto-detect", "git grep failed", { exitCode, stderr: stderr.trim() });
-      return [];
-    }
-
-    if (!stdout.trim()) {
-      logger.debug("auto-detect", "No files matched keywords", { keywords });
-      return [];
-    }
-
-    // Parse file list
-    const allFiles = stdout
-      .trim()
-      .split("\n")
-      .map((line) => line.trim())
-      .filter((line) => line.length > 0);
-
-    // Filter out test files, index files, generated files
-    const filtered = allFiles.filter((filePath) => {
-      const lower = filePath.toLowerCase();
-      // Exclude test files
-      if (lower.includes(".test.") || lower.includes(".spec.") || lower.includes("/test/")) {
-        return false;
-      }
-      // Exclude index files (barrel exports, low signal)
-      if (lower.endsWith("/index.ts") || lower.endsWith("/index.js")) {
-        return false;
-      }
-      // Exclude generated files
-      if (lower.includes(".generated.") || lower.includes("/__generated__/")) {
-        return false;
-      }
-      return true;
-    });
-
-    // Score and sort by relevance
-    // Simple heuristic: count keyword matches in file path
-    interface ScoredFile {
-      path: string;
-      score: number;
-    }
-
-    const scored: ScoredFile[] = filtered.map((filePath) => {
-      const lowerPath = filePath.toLowerCase();
-      const score = keywords.filter((kw) => lowerPath.includes(kw)).length;
-      return { path: filePath, score };
-    });
-
-    // Sort by score descending, then alphabetically
-    scored.sort((a, b) => {
-      if (a.score !== b.score) {
-        return b.score - a.score; // Higher score first
-      }
-      return a.path.localeCompare(b.path); // Alphabetical tiebreaker
-    });
-
-    // Cap at maxFiles
-    const selected = scored.slice(0, maxFiles).map((s) => s.path);
-
-    logger.info("auto-detect", "Auto-detected context files", {
-      keywords,
-      totalMatches: allFiles.length,
-      afterFilter: filtered.length,
-      selected: selected.length,
-      files: selected,
-    });
-
-    return selected;
-  } catch (error) {
-    logger.warn("auto-detect", "Auto-detection failed", {
-      error: errorMessage(error),
-    });
-    return [];
-  }
-}

package/src/context/builder.ts

@@ -1,299 +0,0 @@
-/**
- * Context builder for story-scoped prompt optimization
- *
- * Extracts current story + dependency stories from PRD and builds context within token budget.
- */
-
-import path from "node:path";
-import type { NaxConfig } from "../config";
-import { getLogger } from "../logger";
-import { estimateTokens } from "../optimizer/types";
-import type { UserStory } from "../prd";
-import { countStories, getContextFiles } from "../prd";
-import { errorMessage } from "../utils/errors";
-import { autoDetectContextFiles } from "./auto-detect";
-import {
-  createDependencyContext,
-  createErrorContext,
-  createFileContext,
-  createPriorFailuresContext,
-  createProgressContext,
-  createStoryContext,
-  createTestCoverageContext,
-} from "./elements";
-import { getParentOutputFiles } from "./parent-context";
-import { generateTestCoverageSummary } from "./test-scanner";
-import type { BuiltContext, ContextBudget, ContextElement, StoryContext } from "./types";
-
-// Dependency injection for testability
-export const _deps = {
-  autoDetectContextFiles,
-};
-
-// Re-export for backward compatibility
-export {
-  createStoryContext,
-  createDependencyContext,
-  createErrorContext,
-  createProgressContext,
-  createFileContext,
-  createTestCoverageContext,
-  createPriorFailuresContext,
-} from "./elements";
-export { formatContextAsMarkdown } from "./formatter";
-
-/** Sort context elements by priority (descending) and token count (ascending for same priority) */
-export function sortContextElements(elements: ContextElement[]): ContextElement[] {
-  return [...elements].sort((a, b) => {
-    if (a.priority !== b.priority) return b.priority - a.priority;
-    return a.tokens - b.tokens;
-  });
-}
-
-/** Generate progress summary */
-function generateProgressSummary(prd: StoryContext["prd"]): string {
-  const counts = countStories(prd);
-  const total = counts.total;
-  const complete = counts.passed + counts.failed;
-  if (counts.failed > 0) {
-    return `Progress: ${complete}/${total} stories complete (${counts.passed} passed, ${counts.failed} failed)`;
-  }
-  return `Progress: ${complete}/${total} stories complete (${counts.passed} passed)`;
-}
-
-/** Generate human-readable summary of built context */
-function generateSummary(elements: ContextElement[], totalTokens: number, truncated: boolean): string {
-  const counts: Record<string, number> = {
-    story: 0,
-    dependency: 0,
-    error: 0,
-    progress: 0,
-    file: 0,
-    "test-coverage": 0,
-  };
-  for (const element of elements) {
-    counts[element.type]++;
-  }
-  const parts: string[] = [];
-  if (counts.progress > 0) parts.push(`${counts.progress} progress`);
-  if (counts.story > 0) parts.push(`${counts.story} story`);
-  if (counts.dependency > 0) parts.push(`${counts.dependency} dependencies`);
-  if (counts.error > 0) parts.push(`${counts.error} errors`);
-  if (counts.file > 0) parts.push(`${counts.file} files`);
-  if (counts["test-coverage"] > 0) parts.push("test coverage");
-
-  const summary = `Context: ${parts.join(", ")} (${totalTokens} tokens)`;
-  return truncated ? `${summary} [TRUNCATED]` : summary;
-}
-
-/** Build context from PRD + current story within token budget. */
-export async function buildContext(storyContext: StoryContext, budget: ContextBudget): Promise<BuiltContext> {
-  const { prd, currentStoryId } = storyContext;
-  const elements: ContextElement[] = [];
-
-  const currentStory = prd.userStories.find((s) => s.id === currentStoryId);
-  if (!currentStory) throw new Error(`Story ${currentStoryId} not found in PRD`);
-
-  // Add progress summary (highest priority)
-  elements.push(createProgressContext(generateProgressSummary(prd), 100));
-
-  // Add prior failures (highest priority after progress, priority 95)
-  if (
-    currentStory.priorFailures &&
-    Array.isArray(currentStory.priorFailures) &&
-    currentStory.priorFailures.length > 0
-  ) {
-    elements.push(createPriorFailuresContext(currentStory.priorFailures, 95));
-  }
-
-  // Add prior errors (high priority)
-  if (currentStory.priorErrors && Array.isArray(currentStory.priorErrors) && currentStory.priorErrors.length > 0) {
-    for (const error of currentStory.priorErrors) {
-      elements.push(createErrorContext(error, 90));
-    }
-  }
-
-  // Add current story (high priority)
-  elements.push(createStoryContext(currentStory, 80));
-
-  // ENH-006: Inject planning analysis from prd.analysis (priority 88 — above story, below errors)
-  if (prd.analysis) {
-    const analysisContent = `The following analysis was performed during the planning phase. Use it to understand the codebase context before implementing:\n\n${prd.analysis}`;
-    elements.push({
-      type: "planning-analysis",
-      label: "Planning Analysis",
-      content: analysisContent,
-      priority: 88,
-      tokens: estimateTokens(analysisContent),
-    });
-  }
-
-  // Add dependency stories (medium priority)
-  addDependencyElements(elements, currentStory, prd);
-
-  // Add test coverage summary (priority 85)
-  await addTestCoverageElement(elements, storyContext, currentStory);
-
-  // Add relevant source files (priority 60)
-  await addFileElements(elements, storyContext, currentStory);
-
-  // Select elements within budget
-  const sorted = sortContextElements(elements);
-  const selected: ContextElement[] = [];
-  let totalTokens = 0;
-  let truncated = false;
-
-  for (const element of sorted) {
-    if (totalTokens + element.tokens <= budget.availableForContext) {
-      selected.push(element);
-      totalTokens += element.tokens;
-    } else {
-      truncated = true;
-    }
-  }
-
-  return { elements: selected, totalTokens, truncated, summary: generateSummary(selected, totalTokens, truncated) };
-}
-
-/** Add dependency story elements to the context. */
-function addDependencyElements(elements: ContextElement[], story: UserStory, prd: StoryContext["prd"]): void {
-  if (!story.dependencies || story.dependencies.length === 0) return;
-  for (const depId of story.dependencies) {
-    const depStory = prd.userStories.find((s) => s.id === depId);
-    if (depStory) {
-      elements.push(createDependencyContext(depStory, 50));
-    } else {
-      const logger = getLogger();
-      logger.warn("context", "Dependency story not found in PRD", { dependencyId: depId, referencedBy: story.id });
-    }
-  }
-}
-
-/** Add test coverage summary element. */
-async function addTestCoverageElement(
-  elements: ContextElement[],
-  storyContext: StoryContext,
-  story: UserStory,
-): Promise<void> {
-  if (storyContext.config?.context?.testCoverage?.enabled === false || !storyContext.workdir) return;
-  try {
-    const tcConfig = storyContext.config?.context?.testCoverage;
-    const contextFiles = getContextFiles(story);
-    const scanResult = await generateTestCoverageSummary({
-      workdir: storyContext.workdir,
-      testDir: tcConfig?.testDir,
-      testPattern: tcConfig?.testPattern,
-      maxTokens: tcConfig?.maxTokens ?? 500,
-      detail: tcConfig?.detail ?? "names-and-counts",
-      contextFiles: contextFiles.length > 0 ? contextFiles : undefined,
-      scopeToStory: tcConfig?.scopeToStory ?? true,
-    });
-    if (scanResult.summary) {
-      elements.push(createTestCoverageContext(scanResult.summary, scanResult.tokens, 85));
-    }
-  } catch (error) {
-    const logger = getLogger();
-    logger.warn("context", "Test coverage scan failed", { error: (error as Error).message });
-  }
-}
-
-/** Add relevant source file elements (auto-detected or from story config). */
-async function addFileElements(
-  elements: ContextElement[],
-  storyContext: StoryContext,
-  story: UserStory,
-): Promise<void> {
-  const MAX_FILE_SIZE_BYTES = 10 * 1024;
-  const MAX_FILES = 5;
-
-  // Skip all file injection when fileInjection is 'disabled' or undefined (treat missing as disabled)
-  const fileInjection = storyContext.config?.context?.fileInjection;
-  if (fileInjection !== "keyword") return;
-
-  let contextFiles = getContextFiles(story);
-
-  // ENH-005: Inject parent output files for context chaining
-  const parentFiles = getParentOutputFiles(story, storyContext.prd?.userStories ?? []);
-  if (parentFiles.length > 0) {
-    const logger = getLogger();
-    logger.info("context", "Injecting parent output files for context chaining", {
-      storyId: story.id,
-      parentFiles,
-    });
-    // Merge with existing contextFiles (don't replace — parent files are supplementary)
-    contextFiles = [...new Set([...contextFiles, ...parentFiles])];
-  }
-
-  // Auto-detect contextFiles if empty and enabled (BUG-006)
-  if (
-    contextFiles.length === 0 &&
-    storyContext.config?.context?.autoDetect?.enabled !== false &&
-    storyContext.workdir
-  ) {
-    const autoDetectConfig = storyContext.config?.context?.autoDetect;
-    try {
-      const detected = await _deps.autoDetectContextFiles({
-        workdir: storyContext.workdir,
-        storyTitle: story.title,
-        maxFiles: autoDetectConfig?.maxFiles ?? 5,
-        traceImports: autoDetectConfig?.traceImports ?? false,
-      });
-      if (detected.length > 0) {
-        contextFiles = detected;
-        const logger = getLogger();
-        logger.info("context", "Auto-detected context files", { storyId: story.id, files: detected });
-      }
-    } catch (error) {
-      const logger = getLogger();
-      logger.warn("context", "Context auto-detection failed", {
-        storyId: story.id,
-        error: errorMessage(error),
-      });
-    }
-  }
-
-  if (contextFiles.length === 0) return;
-  const filesToLoad = contextFiles.slice(0, MAX_FILES);
-  const workdir = storyContext.workdir || process.cwd();
-
-  for (const relativeFilePath of filesToLoad) {
-    try {
-      const absolutePath = path.resolve(workdir, relativeFilePath);
-      const file = Bun.file(absolutePath);
-      if (!(await file.exists())) {
-        const logger = getLogger();
-        logger.warn("context", "Relevant file not found", { filePath: relativeFilePath, storyId: story.id });
-        continue;
-      }
-      if (file.size > MAX_FILE_SIZE_BYTES) {
-        // FEAT-011: File too large to inline — pass path-only so agent can read it if needed
-        const logger = getLogger();
-        logger.warn("context", "File too large for inline — using path-only", {
-          filePath: relativeFilePath,
-          sizeKB: Math.round(file.size / 1024),
-          maxKB: 10,
-          storyId: story.id,
-        });
-        elements.push(
-          createFileContext(
-            relativeFilePath,
-            `_File too large to inline (${Math.round(file.size / 1024)}KB). Path: \`${relativeFilePath}\` — read it directly if needed._`,
-            5,
-          ),
-        );
-        continue;
-      }
-      const content = await file.text();
-      const ext = path.extname(relativeFilePath).slice(1) || "txt";
-      elements.push(
-        createFileContext(relativeFilePath, `\`\`\`${ext}\n// File: ${relativeFilePath}\n${content}\n\`\`\``, 60),
-      );
-    } catch (error) {
-      const logger = getLogger();
-      logger.warn("context", "Error loading file", {
-        filePath: relativeFilePath,
-        error: errorMessage(error),
-      });
-    }
-  }
-}

package/src/context/elements.ts

@@ -1,122 +0,0 @@
-/**
- * Context Element Factories
- *
- * Extracted from builder.ts: token estimation and context element creation.
- */
-
-import { getLogger } from "../logger";
-import { estimateTokens } from "../optimizer/types";
-import type { StructuredFailure, UserStory } from "../prd";
-import type { ContextElement } from "./types";
-
-/** Create context element from current story */
-export function createStoryContext(story: UserStory, priority: number): ContextElement {
-  const content = formatStoryAsText(story);
-  return { type: "story", storyId: story.id, content, priority, tokens: estimateTokens(content) };
-}
-
-/** Create context element from dependency story */
-export function createDependencyContext(story: UserStory, priority: number): ContextElement {
-  const content = formatStoryAsText(story);
-  return { type: "dependency", storyId: story.id, content, priority, tokens: estimateTokens(content) };
-}
-
-/** Create context element from error */
-export function createErrorContext(errorMessage: string, priority: number): ContextElement {
-  return { type: "error", content: errorMessage, priority, tokens: estimateTokens(errorMessage) };
-}
-
-/** Create context element from progress summary */
-export function createProgressContext(progressText: string, priority: number): ContextElement {
-  return { type: "progress", content: progressText, priority, tokens: estimateTokens(progressText) };
-}
-
-/** Create context element from file content */
-export function createFileContext(filePath: string, content: string, priority: number): ContextElement {
-  return { type: "file", filePath, content, priority, tokens: estimateTokens(content) };
-}
-
-/** Create context element from test coverage summary */
-export function createTestCoverageContext(content: string, tokens: number, priority: number): ContextElement {
-  return { type: "test-coverage", content, priority, tokens };
-}
-
-/** Create context element from prior failures */
-export function createPriorFailuresContext(failures: StructuredFailure[], priority: number): ContextElement {
-  const content = formatPriorFailures(failures);
-  return { type: "prior-failures", content, priority, tokens: estimateTokens(content) };
-}
-
-/** Format prior failures as markdown for agent context */
-export function formatPriorFailures(failures: StructuredFailure[]): string {
-  if (!failures || failures.length === 0) {
-    return "";
-  }
-
-  const parts: string[] = [];
-  parts.push("## Prior Failures (Structured Context)\n");
-
-  for (const failure of failures) {
-    parts.push(`### Attempt ${failure.attempt} — ${failure.modelTier}`);
-    parts.push(`**Stage:** ${failure.stage}`);
-    parts.push(`**Summary:** ${failure.summary}`);
-
-    if (failure.testFailures && failure.testFailures.length > 0) {
-      parts.push("\n**Test Failures:**");
-      for (const testFailure of failure.testFailures) {
-        parts.push(`\n- **File:** \`${testFailure.file}\``);
-        parts.push(`  **Test:** ${testFailure.testName}`);
-        parts.push(`  **Error:** ${testFailure.error}`);
-        if (testFailure.stackTrace && testFailure.stackTrace.length > 0) {
-          parts.push(`  **Stack:** ${testFailure.stackTrace[0]}`);
-        }
-      }
-    }
-
-    if (failure.reviewFindings && failure.reviewFindings.length > 0) {
-      parts.push("\n**Review Findings (fix these issues):**");
-      for (const finding of failure.reviewFindings) {
-        const source = finding.source ? ` (${finding.source})` : "";
-        parts.push(`\n- **[${finding.severity}]** \`${finding.file}:${finding.line}\`${source}`);
-        parts.push(`  **Rule:** ${finding.ruleId}`);
-        parts.push(`  **Issue:** ${finding.message}`);
-        if (finding.url) {
-          parts.push(`  **Docs:** ${finding.url}`);
-        }
-      }
-    }
-    parts.push("");
-  }
-
-  return parts.join("\n");
-}
-
-/** Format story as text for context (defensive checks for malformed PRD data) */
-export function formatStoryAsText(story: UserStory): string {
-  const parts: string[] = [];
-  parts.push(`## ${story.id}: ${story.title}`);
-  parts.push("");
-  parts.push(`**Description:** ${story.description}`);
-  parts.push("");
-  parts.push("**Acceptance Criteria:**");
-
-  if (story.acceptanceCriteria && Array.isArray(story.acceptanceCriteria)) {
-    for (const ac of story.acceptanceCriteria) {
-      parts.push(`- ${ac}`);
-    }
-  } else {
-    const logger = getLogger();
-    logger.warn("context", "Story has invalid acceptanceCriteria", {
-      storyId: story.id,
-      type: typeof story.acceptanceCriteria,
-    });
-    parts.push("- (No acceptance criteria defined)");
-  }
-
-  if (story.tags && story.tags.length > 0) {
-    parts.push("");
-    parts.push(`**Tags:** ${story.tags.join(", ")}`);
-  }
-
-  return parts.join("\n");
-}