codebrief 1.1.9 → 1.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebrief",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "description": "Generate AI context files for your project in seconds",
   "main": "src/index.js",
   "bin": {

package/src/ai.js

@@ -11,31 +11,57 @@ const IMPORTANT_PATTERNS = [
   "package.json",
   "tsconfig.json",
   "next.config.*",
+  "nuxt.config.*",
   "vite.config.*",
+  "webpack.config.*",
   "tailwind.config.*",
+  "postcss.config.*",
   "prisma/schema.prisma",
   "drizzle.config.*",
-  "README.md",
+  ".env.example",
+  "docker-compose.*",
+  "Dockerfile",
   "src/index.*",
   "src/main.*",
   "src/app.*",
   "src/server.*",
+  "src/config.*",
+  "src/routes.*",
+  "src/middleware.*",
   "lib/db.*",
   "lib/auth.*",
+  "lib/utils.*",
   "app/layout.*",
   "app/page.*",
+  "app/api/**/route.*",
+  "pages/_app.*",
+  "pages/index.*",
+  "server/index.*",
+  "server/api/**",
+  "controllers/*",
+  "models/*",
+  "services/*",
 ];
 
-function sampleSourceFiles(rootDir, fileTree, charBudget = 18000) {
+function sampleSourceFiles(rootDir, fileTree, charBudget = 32000) {
   const samples = [];
   let budget = charBudget;
 
-  // First pass: prioritised files
+  // Smart read: for large files, take head + tail to capture imports AND exports/env vars
+  function smartRead(filePath, maxChars) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    if (raw.length <= maxChars) return raw;
+    const head = Math.floor(maxChars * 0.6);
+    const tail = maxChars - head - 20; // 20 for separator
+    return raw.slice(0, head) + "\n// ... (truncated) ...\n" + raw.slice(-tail);
+  }
+
+  // First pass: prioritised files (generous budget — these are the most important)
   for (const pattern of IMPORTANT_PATTERNS) {
     const full = path.join(rootDir, pattern);
     if (fs.existsSync(full)) {
       try {
-        const content = fs.readFileSync(full, "utf-8").slice(0, 3000);
+        const content = smartRead(full, 6000);
         samples.push({ file: pattern, content });
         budget -= content.length;
         if (budget <= 0) break;
@@ -68,18 +94,17 @@ function sampleSourceFiles(rootDir, fileTree, charBudget = 18000) {
     const ext = path.extname(entry.name).toLowerCase();
     if (!sourceExts.has(ext)) continue;
 
-    const full = path.join(rootDir, entry.relativePath || entry.name);
+    const full = path.join(rootDir, entry.path || entry.name);
     // Skip already-read files
     if (samples.some((s) => full.endsWith(s.file))) continue;
 
     try {
-      const raw = fs.readFileSync(full, "utf-8");
-      const snippet = raw.slice(0, 1500);
+      const content = smartRead(full, 4000);
       samples.push({
-        file: entry.relativePath || entry.name,
-        content: snippet,
+        file: entry.path || entry.name,
+        content,
       });
-      budget -= snippet.length;
+      budget -= content.length;
     } catch {
       /* skip */
     }
@@ -88,14 +113,80 @@ function sampleSourceFiles(rootDir, fileTree, charBudget = 18000) {
   return samples;
 }
 
+// ── Env var extractor ────────────────────────────────────────
+// Scans all source files for process.env.XXX references
+function extractEnvVars(rootDir, fileTree) {
+  const envVars = new Map(); // name → [files]
+  const sourceExts = new Set([".js", ".ts", ".jsx", ".tsx", ".vue", ".svelte", ".py", ".go", ".rs", ".rb", ".php"]);
+  const envRegex = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+  const dotenvRegex = /^([A-Z_][A-Z0-9_]*)=/gm;
+
+  for (const entry of fileTree) {
+    if (entry.type !== "file") continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    const name = entry.name.toLowerCase();
+    if (!sourceExts.has(ext) && !name.startsWith(".env")) continue;
+
+    const full = path.join(rootDir, entry.path || entry.name);
+    try {
+      const raw = fs.readFileSync(full, "utf-8");
+      const regex = name.startsWith(".env") ? dotenvRegex : envRegex;
+      let match;
+      while ((match = regex.exec(raw)) !== null) {
+        const varName = match[1];
+        // Skip generic placeholder names
+        if (varName === "XXX" || varName.length < 3) continue;
+        if (!envVars.has(varName)) envVars.set(varName, []);
+        const file = entry.path || entry.name;
+        if (!envVars.get(varName).includes(file)) envVars.get(varName).push(file);
+      }
+    } catch { /* skip */ }
+  }
+
+  return envVars;
+}
+
+// ── Export extractor ─────────────────────────────────────────
+// Scans all source files for key function/class exports
+function extractExports(rootDir, fileTree) {
+  const exports = [];
+  const sourceExts = new Set([".js", ".ts", ".jsx", ".tsx"]);
+  const patterns = [
+    /(?:module\.exports\s*=\s*\{([^}]+)\})/g,
+    /(?:exports\.(\w+)\s*=)/g,
+    /(?:export\s+(?:default\s+)?(?:function|class|const|let|var)\s+(\w+))/g,
+  ];
+
+  for (const entry of fileTree) {
+    if (entry.type !== "file") continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!sourceExts.has(ext)) continue;
+
+    const full = path.join(rootDir, entry.path || entry.name);
+    try {
+      const raw = fs.readFileSync(full, "utf-8");
+      const file = entry.path || entry.name;
+      for (const regex of patterns) {
+        let match;
+        regex.lastIndex = 0;
+        while ((match = regex.exec(raw)) !== null) {
+          exports.push({ file, exports: match[1] || match[0] });
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  return exports;
+}
+
 // ── Prompt builder ───────────────────────────────────────────
-function buildPrompt(analysis, fileTree, fileSamples) {
+function buildPrompt(analysis, fileTree, fileSamples, envVars, fileExports) {
   const fileList = fileTree
-    .slice(0, 80)
+    .slice(0, 120)
     .map((e) =>
       e.type === "dir"
-        ? `  ${e.relativePath || e.name}/`
-        : `  ${e.relativePath || e.name}`,
+        ? `  ${e.path || e.name}/`
+        : `  ${e.path || e.name}`,
     )
     .join("\n");
 
@@ -108,41 +199,71 @@ function buildPrompt(analysis, fileTree, fileSamples) {
       .map(([k, v]) => `  ${k}: ${v}`)
       .join("\n") || "  (none)";
 
-  return `You are a senior software architect performing a deep code review. A developer ran \`codebrief\` on their project. Your job is to write a CONTEXT.md that gives an AI coding assistant (Cursor, Copilot, etc.) enough knowledge to contribute code as if it had written the project itself.
+  const envVarsText = envVars.size > 0
+    ? Array.from(envVars.entries())
+        .map(([name, files]) => `- \`${name}\` — used in ${files.map((f) => "`" + f + "`").join(", ")}`)
+        .join("\n")
+    : "(none found)";
+
+  const exportsText = fileExports.length > 0
+    ? fileExports.slice(0, 30).map((e) => `- \`${e.file}\`: ${e.exports}`).join("\n")
+    : "(none found)";
+
+  const systemMessage = `You are a world-class software architect. You read source code and produce extremely precise, file-grounded documentation. You NEVER write generic advice. Every sentence you write must cite a real file path, function name, or pattern visible in the code you are given. If you cannot ground a claim in the actual source, you omit it entirely.`;
 
-CRITICAL RULES:
-- Every claim must be grounded in the actual files and code samples provided. No generic filler.
-- Reference specific file paths (e.g. \`src/lib/auth.ts\`, \`app/api/users/route.ts\`) wherever possible.
-- If you cannot infer something from the provided code, omit that bullet entirely — do NOT guess or write placeholders.
-- Architecture Notes must name real functions, classes, modules, or patterns you actually observed, not vague descriptions.
-- Rules for AI must reflect patterns actually present in the source — not generic best practices.
+  const userMessage = `I ran \`codebrief\` and need you to write a CONTEXT.md that lets an AI code assistant (Cursor, Copilot) understand this project so well it can write production code immediately.
 
+---
+## HARD RULES (violating these = failure)
+
+1. **File-path grounding**: Every bullet in Architecture Notes, Rules for AI, and Never Do MUST reference at least one real file path or function/export name from the code samples. No exceptions.
+2. **No negatives**: NEVER write "X is not used", "the project does not have Y", "no database detected". If something doesn't exist, simply don't mention it.
+3. **No generic advice**: NEVER write vague statements like "follow best practices", "maintain code quality", "adhere to coding standards", "ensure security". These are worthless.
+4. **Omit, don't guess**: If you can't infer something from the actual code samples, omit that section/bullet entirely. Empty sections should be removed.
+5. **Specific > exhaustive**: 5 deeply specific bullets beat 15 vague ones.
+
+## BAD (never write like this)
+- "Authentication and session logic are not explicitly handled within the project"
+- "Adhere to the project's coding standards and best practices"
+- "Regular security audits are essential"
+- "Error handling mechanisms are crucial for a robust application"
+- "The project follows a modular structure, enhancing maintainability"
+
+## GOOD (write like this)
+- "CLI entry point is \`src/index.js:main()\` — parses flags via \`hasFlag()\`/\`getFlagValue()\`, calls \`scanDirectory()\` → \`analyzeProject()\` → \`generateContextFile()\` in sequence"
+- "AI enhancement in \`src/ai.js:enhanceWithAI()\` samples up to 32k chars of source via \`sampleSourceFiles()\`, builds a structured prompt, dispatches to the selected provider (Groq/OpenAI/Anthropic/Gemini/Grok/Ollama)"
+- "Never add npm dependencies — this project uses zero deps (native \`https\`, \`fs\`, \`path\` only). See \`package.json\` dependencies field is empty."
+- "All color output uses the \`c\` object from \`src/index.js\` (ANSI escape codes) — never use chalk or other color libraries"
+
+---
 ## Project metadata
 - Name: ${analysis.name}
 - Framework / Type: ${analysis.type}
 - Language: ${analysis.language}
 - Package manager: ${analysis.packageManager}
 - Stack: ${analysis.stack.join(", ") || "unknown"}
-- CSS framework: ${analysis.cssFramework || "none detected"}
-- UI library: ${analysis.uiLibrary || "none detected"}
-- State management: ${analysis.stateManagement || "none detected"}
-- Database / ORM: ${analysis.database || "none detected"}
-- Test framework: ${analysis.testFramework || "none detected"}
-- Deployment target: ${analysis.deployment || "unknown"}
+- CSS: ${analysis.cssFramework || "none"} · UI: ${analysis.uiLibrary || "none"} · State: ${analysis.stateManagement || "none"}
+- DB: ${analysis.database || "none"} · Tests: ${analysis.testFramework || "none"} · Deploy: ${analysis.deployment || "unknown"}
 - Monorepo: ${analysis.isMonorepo}
 
 ## Scripts
 ${scripts}
 
-## File tree (up to 80 entries)
+## File tree
 ${fileList}
 
-## Source file samples
+## Source code samples (READ CAREFULLY — this is your evidence)
 ${samplesText}
 
+## Environment variables found in code
+${envVarsText}
+
+## Module exports detected
+${exportsText}
+
 ---
 
-Produce the CONTEXT.md in exactly this structure:
+Now produce the CONTEXT.md in EXACTLY this structure. Remove any section where you have nothing concrete to say. Keep the emoji in every section header EXACTLY as shown.
 
 # Project Context: ${analysis.name}
 > AI-enhanced by **codebrief** · ${new Date().toISOString().split("T")[0]}
@@ -150,44 +271,40 @@ Produce the CONTEXT.md in exactly this structure:
 ---
 
 ## 🧱 Tech Stack
-- List each technology and its specific role in this project (e.g. "Prisma — ORM used in \`src/db/\` for all database queries").
+Bullet list. Each bullet: technology name + its specific role citing where it's used.
+Example: "Node.js — runtime; entry point at \`src/index.js\`, all code is CommonJS with \`require()\`"
 
 ## 🚀 Key Files
-- List the 5–8 most important files a new developer should read first, with one sentence explaining what each does. Use exact paths from the file tree.
+The 5–8 most important files to read first. Exact paths. One sentence each explaining what the file does and its key exports/functions.
 
 ## 📁 Folder Structure
-- Explain what each top-level folder is responsible for, inferred from the actual file tree.
+One bullet per top-level directory, explaining its responsibility based on the actual files inside.
 
 ## 🔧 Scripts
-- Explain what each script actually does in the context of this project.
-
-## 🗂️ Project Tree
-\`\`\`
-${fileList}
-\`\`\`
+One bullet per script. Say what it actually does, not just its command.
 
 ## 🏗️ Architecture Notes
-Write 8–15 bullet points. Each bullet must:
-- Name the specific file(s) or function(s) involved (e.g. "Auth flow starts in \`middleware.ts\`, validates JWT via \`src/lib/auth.ts:verifyToken()\`")
-- Describe a concrete data flow, pattern, or constraint — not a vague summary
-- Cover: request lifecycle, data access layer, auth/session, key abstractions, inter-module dependencies, anything surprising
+8–15 bullets. Each MUST:
+- Name specific file(s), function(s), or export(s)
+- Describe a concrete data flow, dependency, or design decision
+- Be something useful for an AI about to write code in this project
 
 ## 🤖 Rules for AI
-Write 8–12 rules based on patterns you actually observed in the code. Example format:
-- "Always use the \`db\` instance from \`src/lib/db.ts\` — never import Prisma directly"
-- "API routes live in \`app/api/\` and must use the response helper from \`src/lib/response.ts\`"
+8–12 rules extracted from the actual code patterns. Format:
+- "Always/Never [specific action] — [file or pattern reference]"
 
 ## 🚫 Never Do
-Write 6–10 prohibitions inferred from the stack and code style. Be specific, not generic.
+6–10 prohibitions grounded in the codebase. Each must cite WHY (a file, pattern, or convention).
 
-## 🔐 Environment & Security
-- List environment variables referenced in the code (exact names if found).
-- Note any auth patterns, token handling, or secrets management observed.
+## 🔐 Environment & Secrets
+List actual env var names found in the code (e.g. \`GROQ_API_KEY\`, \`OPENAI_API_KEY\`). Describe how they're loaded and used. If none found, omit this section.
 
 ---
 *Re-run \`codebrief --ai\` after major refactors to keep this file current.*
 
-Respond with ONLY the Markdown. No preamble, no code fences wrapping the entire output.`;
+Respond with ONLY the Markdown. No preamble, no wrapping code fences.`;
+
+  return { systemMessage, userMessage };
 }
 
 // ── HTTP helper (native, no deps) ────────────────────────────
@@ -233,6 +350,10 @@ async function callGroq(prompt, model) {
         "  Get a free key in ~30s at https://console.groq.com",
     );
 
+  const messages = typeof prompt === "string"
+    ? [{ role: "user", content: prompt }]
+    : [{ role: "system", content: prompt.systemMessage }, { role: "user", content: prompt.userMessage }];
+
   const res = await httpsPost(
     "api.groq.com",
     "/openai/v1/chat/completions",
@@ -242,9 +363,9 @@ async function callGroq(prompt, model) {
     },
     {
       model,
-      messages: [{ role: "user", content: prompt }],
-      temperature: 0.3,
-      max_tokens: 4096,
+      messages,
+      temperature: 0.2,
+      max_tokens: 8192,
     },
   );
   return res.choices?.[0]?.message?.content || "";
@@ -256,6 +377,10 @@ async function callOpenAI(prompt, model) {
   if (!apiKey)
     throw new Error("OPENAI_API_KEY environment variable is not set.");
 
+  const messages = typeof prompt === "string"
+    ? [{ role: "user", content: prompt }]
+    : [{ role: "system", content: prompt.systemMessage }, { role: "user", content: prompt.userMessage }];
+
   const res = await httpsPost(
     "api.openai.com",
     "/v1/chat/completions",
@@ -265,9 +390,9 @@ async function callOpenAI(prompt, model) {
     },
     {
       model,
-      messages: [{ role: "user", content: prompt }],
-      temperature: 0.3,
-      max_tokens: 4096,
+      messages,
+      temperature: 0.2,
+      max_tokens: 8192,
     },
   );
   return res.choices?.[0]?.message?.content || "";
@@ -279,6 +404,19 @@ async function callAnthropic(prompt, model) {
   if (!apiKey)
     throw new Error("ANTHROPIC_API_KEY environment variable is not set.");
 
+  const messages = typeof prompt === "string"
+    ? [{ role: "user", content: prompt }]
+    : [{ role: "user", content: prompt.userMessage }];
+
+  const system = typeof prompt === "string" ? undefined : prompt.systemMessage;
+
+  const body = {
+    model,
+    max_tokens: 8192,
+    messages,
+  };
+  if (system) body.system = system;
+
   const res = await httpsPost(
     "api.anthropic.com",
     "/v1/messages",
@@ -287,11 +425,7 @@ async function callAnthropic(prompt, model) {
       "x-api-key": apiKey,
       "anthropic-version": "2023-06-01",
     },
-    {
-      model,
-      max_tokens: 4096,
-      messages: [{ role: "user", content: prompt }],
-    },
+    body,
   );
   return res.content?.[0]?.text || "";
 }
@@ -305,13 +439,17 @@ async function callGemini(prompt, model) {
         "  Get a free key at https://aistudio.google.com/app/apikey",
     );
 
+  const fullText = typeof prompt === "string"
+    ? prompt
+    : `${prompt.systemMessage}\n\n${prompt.userMessage}`;
+
   const res = await httpsPost(
     "generativelanguage.googleapis.com",
     `/v1beta/models/${model}:generateContent?key=${apiKey}`,
     { "Content-Type": "application/json" },
     {
-      contents: [{ parts: [{ text: prompt }] }],
-      generationConfig: { temperature: 0.3, maxOutputTokens: 4096 },
+      contents: [{ parts: [{ text: fullText }] }],
+      generationConfig: { temperature: 0.2, maxOutputTokens: 8192 },
     },
   );
   return res.candidates?.[0]?.content?.parts?.[0]?.text || "";
@@ -326,6 +464,10 @@ async function callGrok(prompt, model) {
         "  Get a key at https://console.x.ai",
     );
 
+  const messages = typeof prompt === "string"
+    ? [{ role: "user", content: prompt }]
+    : [{ role: "system", content: prompt.systemMessage }, { role: "user", content: prompt.userMessage }];
+
   const res = await httpsPost(
     "api.x.ai",
     "/v1/chat/completions",
@@ -335,9 +477,9 @@ async function callGrok(prompt, model) {
     },
     {
       model,
-      messages: [{ role: "user", content: prompt }],
-      temperature: 0.3,
-      max_tokens: 4096,
+      messages,
+      temperature: 0.2,
+      max_tokens: 8192,
     },
   );
   return res.choices?.[0]?.message?.content || "";
@@ -347,7 +489,10 @@ async function callOllama(prompt, model) {
   model = model || getDefaultModel("ollama");
   // Ollama runs locally on port 11434 — use http
   const http = require("http");
-  const body = JSON.stringify({ model, prompt, stream: false });
+  const fullText = typeof prompt === "string"
+    ? prompt
+    : `${prompt.systemMessage}\n\n${prompt.userMessage}`;
+  const body = JSON.stringify({ model, prompt: fullText, stream: false });
 
   return new Promise((resolve, reject) => {
     const req = http.request(
@@ -396,7 +541,9 @@ async function enhanceWithAI(analysis, fileTree, rootDir, options = {}) {
   const { provider = "openai", model } = options;
 
   const fileSamples = sampleSourceFiles(rootDir, fileTree);
-  const prompt = buildPrompt(analysis, fileTree, fileSamples);
+  const envVars = extractEnvVars(rootDir, fileTree);
+  const fileExports = extractExports(rootDir, fileTree);
+  const prompt = buildPrompt(analysis, fileTree, fileSamples, envVars, fileExports);
 
   switch (provider.toLowerCase()) {
     case "groq":