@nathapp/nax 0.18.1

package/src/context/auto-detect.ts

@@ -0,0 +1,227 @@
+/**
+ * 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";
+
+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: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+}

package/src/context/builder.ts

@@ -0,0 +1,246 @@
+/**
+ * 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 type { UserStory } from "../prd";
+import { countStories, getContextFiles } from "../prd";
+import { autoDetectContextFiles } from "./auto-detect";
+import {
+  createDependencyContext,
+  createErrorContext,
+  createFileContext,
+  createProgressContext,
+  createStoryContext,
+  createTestCoverageContext,
+  estimateTokens,
+} from "./elements";
+import { generateTestCoverageSummary } from "./test-scanner";
+import type { BuiltContext, ContextBudget, ContextElement, StoryContext } from "./types";
+
+// Re-export for backward compatibility
+export {
+  estimateTokens,
+  createStoryContext,
+  createDependencyContext,
+  createErrorContext,
+  createProgressContext,
+  createFileContext,
+  createTestCoverageContext,
+} 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 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));
+
+  // 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;
+
+  let contextFiles = getContextFiles(story);
+
+  // 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 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: error instanceof Error ? error.message : String(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) {
+        const logger = getLogger();
+        logger.warn("context", "File too large", {
+          filePath: relativeFilePath,
+          sizeKB: Math.round(file.size / 1024),
+          maxKB: 10,
+          storyId: story.id,
+        });
+        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: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}

package/src/context/elements.ts

@@ -0,0 +1,83 @@
+/**
+ * Context Element Factories
+ *
+ * Extracted from builder.ts: token estimation and context element creation.
+ */
+
+import { getLogger } from "../logger";
+import type { UserStory } from "../prd";
+import type { ContextElement } from "./types";
+
+/**
+ * Approximate character-to-token ratio for token estimation.
+ * Value of 3 is a middle ground optimized for mixed content (prose + code + markdown).
+ * Slightly overestimates tokens, preventing budget overflow.
+ */
+const CHARS_PER_TOKEN = 3;
+
+/** Estimate token count for text using character-to-token ratio. */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+/** 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 };
+}
+
+/** 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");
+}

package/src/context/formatter.ts

@@ -0,0 +1,107 @@
+/**
+ * Context Markdown Formatter
+ *
+ * Extracted from builder.ts: formats built context as markdown for agent consumption.
+ */
+
+import type { BuiltContext, ContextElement } from "./types";
+
+/**
+ * Format built context as markdown for agent consumption.
+ *
+ * Generates markdown with sections for progress, prior errors,
+ * test coverage, current story, dependency stories, and relevant files.
+ */
+export function formatContextAsMarkdown(built: BuiltContext): string {
+  const sections: string[] = [];
+
+  sections.push("# Story Context\n");
+  sections.push(`${built.summary}\n`);
+
+  // Group by type
+  const byType = new Map<string, ContextElement[]>();
+  for (const element of built.elements) {
+    const existing = byType.get(element.type) || [];
+    existing.push(element);
+    byType.set(element.type, existing);
+  }
+
+  renderSection(sections, byType, "progress", "## Progress\n", renderSimple);
+  renderErrorSection(sections, byType);
+  renderSection(sections, byType, "test-coverage", "", renderSimple);
+  renderSection(sections, byType, "story", "## Current Story\n", renderSimple);
+  renderSection(sections, byType, "dependency", "## Dependency Stories\n", renderSimple);
+  renderSection(sections, byType, "file", "## Relevant Source Files\n", renderSimple);
+
+  return sections.join("\n");
+}
+
+/** Render a simple section with elements as-is. */
+function renderSimple(sections: string[], elements: ContextElement[]): void {
+  for (const element of elements) {
+    sections.push(element.content);
+    sections.push("\n");
+  }
+}
+
+/** Render a typed section if elements exist. */
+function renderSection(
+  sections: string[],
+  byType: Map<string, ContextElement[]>,
+  type: string,
+  header: string,
+  renderer: (sections: string[], elements: ContextElement[]) => void,
+): void {
+  const elements = byType.get(type);
+  if (!elements || elements.length === 0) return;
+  if (header) sections.push(header);
+  renderer(sections, elements);
+}
+
+/** Render error section with special handling for ASSET_CHECK errors. */
+function renderErrorSection(sections: string[], byType: Map<string, ContextElement[]>): void {
+  const errorElements = byType.get("error");
+  if (!errorElements || errorElements.length === 0) return;
+
+  const assetCheckErrors: ContextElement[] = [];
+  const otherErrors: ContextElement[] = [];
+
+  for (const element of errorElements) {
+    if (element.content.startsWith("ASSET_CHECK_FAILED:")) {
+      assetCheckErrors.push(element);
+    } else {
+      otherErrors.push(element);
+    }
+  }
+
+  if (assetCheckErrors.length > 0) {
+    sections.push("## ⚠️ MANDATORY: Missing Files from Previous Attempts\n");
+    sections.push("**CRITICAL:** Previous attempts failed because these files were not created.\n");
+    sections.push("You MUST create these exact files. Do NOT use alternative filenames.\n\n");
+
+    for (const element of assetCheckErrors) {
+      const match = element.content.match(/Missing files: \[([^\]]+)\]/);
+      if (match) {
+        const fileList = match[1].split(",").map((f) => f.trim());
+        sections.push("**Required files:**\n");
+        for (const file of fileList) {
+          sections.push(`- \`${file}\``);
+        }
+        sections.push("\n");
+      } else {
+        sections.push("```");
+        sections.push(element.content);
+        sections.push("```\n");
+      }
+    }
+  }
+
+  if (otherErrors.length > 0) {
+    sections.push("## Prior Errors\n");
+    for (const element of otherErrors) {
+      sections.push("```");
+      sections.push(element.content);
+      sections.push("```\n");
+    }
+  }
+}