@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/docs/llm-enricher.js

@@ -0,0 +1,401 @@
+/**
+ * LLM Documentation Enricher — V2 (DeepWiki Quality)
+ *
+ * Post-processes raw generated markdown docs by passing each section
+ * through the LLM for narrative enrichment. The raw data stays as-is
+ * but prose paragraphs, explanations, and cross-links are added.
+ *
+ * V2 improvements:
+ * - Chunked enrichment: large files split by ## headers, each enriched independently
+ * - Cross-validation: post-enrichment scan for hallucinated identifiers
+ * - Multi-pass: overview and architecture get 2 LLM passes (enrich + review)
+ * - Blueprint context: verified entity list injected into each LLM call
+ *
+ * Also generates PROJECT_KNOWLEDGE.md for context injection.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from '../utils/logger.js';
+/** Thinking strategy per page type (generic — no hardcoded filenames) */
+const THINKING_BY_TYPE = {
+    'changelog': 'minimal',
+    'tools': 'minimal',
+    'configuration': 'low',
+    'api-reference': 'low',
+    'getting-started': 'low',
+    'troubleshooting': 'medium',
+    'component': 'medium',
+    'subsystem': 'medium',
+    'key-concepts': 'medium',
+    'security': 'medium',
+    'overview': 'high',
+    'architecture': 'high',
+};
+/** Page types that get multi-pass enrichment (improvement D) */
+const MULTI_PASS_TYPES = new Set(['overview', 'architecture']);
+// ============================================================================
+// System Prompt
+// ============================================================================
+const ENRICHER_SYSTEM_PROMPT = `You are a senior technical writer documenting a complex open-source project in DeepWiki style.
+
+CRITICAL: Output the COMPLETE document — include ALL original tables, lists, and data. Your output REPLACES the file, so nothing can be lost.
+
+## Narration Style
+
+- NEVER start two consecutive paragraphs the same way
+- Explain the WHY before the HOW: "When the agent encounters X, it does Y because Z"
+- Use storytelling, not spec-sheet language
+- Vary sentence structure and vocabulary
+- Each section must feel like a chapter in a technical book
+
+Bad: "This section details the subsystems responsible for..."
+Good: "When Code Buddy needs to understand a large codebase, it doesn't read files line by line — it builds a semantic map. Here's how that map is constructed..."
+
+## What to ADD
+
+1. **Opening paragraph** under the title: 2-3 sentences explaining WHAT, WHY, and WHO should read this.
+
+2. **Transition paragraphs** between subsections: 1-2 sentences summarizing what the reader just learned and why the next section is the logical continuation.
+
+Example: "Now that we understand how the agent orchestrates tool calls, we need to examine the security layer that governs which tools can execute and under what conditions."
+
+3. **One Mermaid diagram** per document showing the key data flow or component relationship. Use graph TD or flowchart LR. Keep it under 10 nodes.
+
+4. **"Key Concepts" callout** for complex sections:
+> **Key concept:** The RAG tool selector reduces prompt size from 110+ tools to ~15, saving approximately 8,000 tokens per LLM call.
+
+5. **One developer tip** per section — a practical "watch out for" note:
+> **Developer tip:** When adding a new tool, always register it in both \`metadata.ts\` and \`tools.ts\` — missing either causes silent failures.
+
+6. **Method signatures** when discussing components: mention \`ClassName.methodName()\` in backticks. ONLY use names from the verified entities list.
+
+## Rules
+- Output the FULL enriched document (title through footer)
+- KEEP every table, list, and data point from the original
+- Write like MDN Web Docs: precise, technical, no marketing fluff
+- Each section gets 1-2 paragraphs of prose, not more
+- Total output should be 20-50% longer than input, not shorter
+- NEVER invent class or method names — only use names from the verified entities list`;
+const REVIEW_SYSTEM_PROMPT = `You are a technical documentation reviewer. Review the enriched document for accuracy:
+
+1. Check that ALL tables and data from the raw version are preserved
+2. Verify that method/class names in backticks are plausible (no obvious hallucinations)
+3. Fix any factual inconsistencies between the prose and the data tables
+4. Improve clarity of transition paragraphs
+5. Ensure Mermaid diagrams are syntactically valid
+
+Output the CORRECTED full document. If the document is already good, output it as-is.`;
+// ============================================================================
+// Enricher
+// ============================================================================
+export async function enrichDocs(options) {
+    const startTime = Date.now();
+    const cwd = options.cwd ?? process.cwd();
+    const errors = [];
+    let tokensUsed = 0;
+    let filesEnriched = 0;
+    let hallucinationsFixed = 0;
+    const knowledgeChunks = [];
+    // Find all .md files in the docs directory
+    const mdFiles = fs.readdirSync(options.docsDir)
+        .filter(f => f.endsWith('.md') && f !== 'index.md')
+        .sort();
+    for (let i = 0; i < mdFiles.length; i++) {
+        const file = mdFiles[i];
+        if (file === undefined)
+            continue;
+        options.onProgress?.(file, i + 1, mdFiles.length);
+        logger.info(`Enriching [${i + 1}/${mdFiles.length}] ${file}`);
+        const filePath = path.join(options.docsDir, file);
+        const rawContent = fs.readFileSync(filePath, 'utf-8');
+        // Skip very small files (changelog, etc.)
+        if (rawContent.length < 200)
+            continue;
+        try {
+            let enriched;
+            // Improvement B: Chunked enrichment for large files
+            if (rawContent.length > 8000) {
+                enriched = await enrichChunked(rawContent, file, options);
+            }
+            else {
+                enriched = await enrichSingle(rawContent, file, options);
+            }
+            tokensUsed += Math.ceil((rawContent.length + enriched.length) / 4);
+            // Improvement D: Multi-pass for critical sections
+            const fileSlug = file.replace(/^\d+[a-z]?-/, '').replace(/\.md$/, '');
+            if ([...MULTI_PASS_TYPES].some(t => fileSlug.includes(t))) {
+                logger.info(`  Review pass for ${file}`);
+                const reviewed = await reviewPass(enriched, rawContent, options);
+                if (reviewed.length >= enriched.length * 0.8) {
+                    enriched = reviewed;
+                    tokensUsed += Math.ceil((enriched.length + reviewed.length) / 4);
+                }
+            }
+            // Improvement C: Cross-validation — fix hallucinated identifiers
+            if (options.verifiedEntities && options.verifiedEntities.size > 0) {
+                const { fixed, fixCount } = crossValidateIdentifiers(enriched, options.verifiedEntities);
+                enriched = fixed;
+                hallucinationsFixed += fixCount;
+                if (fixCount > 0) {
+                    logger.info(`  Fixed ${fixCount} hallucinated identifiers in ${file}`);
+                }
+            }
+            // Validate: enriched should be at least 50% of raw (LLM may compress large tables)
+            if (enriched.length >= rawContent.length * 0.5 && enriched.length > 200) {
+                fs.writeFileSync(filePath, enriched);
+                filesEnriched++;
+                // Extract summary for knowledge file
+                const firstParagraphs = enriched.split('\n\n').slice(0, 3).join('\n\n');
+                knowledgeChunks.push(firstParagraphs.substring(0, 500));
+            }
+            else {
+                logger.debug(`Enriched ${file} was shorter than raw — keeping original`);
+                errors.push(`${file}: enriched output too short, kept original`);
+            }
+        }
+        catch (err) {
+            errors.push(`${file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Generate PROJECT_KNOWLEDGE.md from enriched content
+    const knowledgePath = path.join(cwd, '.codebuddy', 'PROJECT_KNOWLEDGE.md');
+    const knowledgeContent = [
+        '# Project Knowledge',
+        '',
+        `> Auto-generated project understanding from ${filesEnriched} documentation sections.`,
+        `> Last updated: ${new Date().toISOString()}`,
+        '',
+        ...knowledgeChunks,
+    ].join('\n');
+    fs.writeFileSync(knowledgePath, knowledgeContent.substring(0, 15000));
+    return {
+        filesEnriched,
+        tokensUsed,
+        durationMs: Date.now() - startTime,
+        knowledgePath,
+        errors,
+        hallucinationsFixed,
+    };
+}
+// ============================================================================
+// Single-file enrichment
+// ============================================================================
+async function enrichSingle(rawContent, file, options) {
+    const blueprintBlock = options.blueprintContext
+        ? `\n\n${options.blueprintContext}\n`
+        : '';
+    const prompt = [
+        `Transform this raw document into professional DeepWiki-style documentation.`,
+        `IMPORTANT: Output the COMPLETE document with ALL original content preserved plus your additions.`,
+        blueprintBlock,
+        `--- RAW DOCUMENT ---`,
+        rawContent.substring(0, 12000),
+        `--- END ---`,
+        ``,
+        `Output the full enriched markdown now. Remember: keep ALL tables/lists, add prose and one mermaid diagram.`,
+    ].join('\n');
+    // Determine thinking level from file name base (handle split subsystem files)
+    const thinkingLevel = options.thinkingLevel ?? getThinkingLevel(file);
+    const result = await options.llmCall(ENRICHER_SYSTEM_PROMPT, prompt, thinkingLevel);
+    return stripLLMNoise(result);
+}
+// ============================================================================
+// Improvement B: Chunked enrichment for large files
+// ============================================================================
+async function enrichChunked(rawContent, file, options) {
+    // Split by ## headers
+    const chunks = splitByHeaders(rawContent);
+    if (chunks.length <= 1) {
+        // Can't split — enrich as single (truncated)
+        return enrichSingle(rawContent, file, options);
+    }
+    logger.info(`  Chunked enrichment: ${chunks.length} sections`);
+    const enrichedChunks = [];
+    const thinkingLevel = options.thinkingLevel ?? getThinkingLevel(file);
+    const blueprintBlock = options.blueprintContext
+        ? `\n\n${options.blueprintContext}\n`
+        : '';
+    for (const chunk of chunks) {
+        // Skip tiny chunks (< 100 chars, probably just whitespace)
+        if (chunk.trim().length < 100) {
+            enrichedChunks.push(chunk);
+            continue;
+        }
+        const prompt = [
+            `Enrich this section of a larger document. Add prose, transitions, and key concepts.`,
+            `IMPORTANT: Output the COMPLETE section with ALL original content preserved.`,
+            blueprintBlock,
+            `--- SECTION ---`,
+            chunk.substring(0, 8000),
+            `--- END ---`,
+            ``,
+            `Output the enriched section. Keep ALL data, add prose only.`,
+        ].join('\n');
+        try {
+            const enriched = await options.llmCall(ENRICHER_SYSTEM_PROMPT, prompt, thinkingLevel);
+            // Validate chunk wasn't destroyed
+            if (enriched.length >= chunk.length * 0.4 && enriched.length > 50) {
+                enrichedChunks.push(enriched);
+            }
+            else {
+                enrichedChunks.push(chunk); // keep original
+            }
+        }
+        catch {
+            enrichedChunks.push(chunk); // keep original on error
+        }
+    }
+    return enrichedChunks.join('\n\n');
+}
+/** Split markdown content by ## headers */
+function splitByHeaders(content) {
+    const lines = content.split('\n');
+    const chunks = [];
+    let current = [];
+    for (const line of lines) {
+        if (line.startsWith('## ') && current.length > 0) {
+            chunks.push(current.join('\n'));
+            current = [line];
+        }
+        else {
+            current.push(line);
+        }
+    }
+    if (current.length > 0) {
+        chunks.push(current.join('\n'));
+    }
+    return chunks;
+}
+// ============================================================================
+// Improvement D: Review pass for critical sections
+// ============================================================================
+async function reviewPass(enriched, rawContent, options) {
+    const prompt = [
+        `Review this enriched document against the original raw data.`,
+        `Fix any hallucinated method/class names, factual errors, or missing data.`,
+        ``,
+        `--- ENRICHED DOCUMENT ---`,
+        enriched.substring(0, 12000),
+        `--- END ENRICHED ---`,
+        ``,
+        `--- ORIGINAL RAW DATA (for fact-checking) ---`,
+        rawContent.substring(0, 6000),
+        `--- END RAW ---`,
+        ``,
+        `Output ONLY the corrected full markdown document. No commentary, no code fences.`,
+    ].join('\n');
+    let result = await options.llmCall(REVIEW_SYSTEM_PROMPT, prompt, 'medium');
+    // Strip LLM commentary noise — some models add preamble before the actual document
+    result = stripLLMNoise(result);
+    return result;
+}
+/** Strip LLM meta-commentary and code fence wrappers from output */
+function stripLLMNoise(content) {
+    let result = content;
+    // Remove ```markdown wrapper if present
+    const mdFenceMatch = result.match(/```markdown\n([\s\S]*?)```\s*$/);
+    if (mdFenceMatch && mdFenceMatch[1] !== undefined) {
+        result = mdFenceMatch[1];
+    }
+    // Remove preamble before the first # heading
+    const firstHeading = result.indexOf('\n# ');
+    if (firstHeading > 0 && firstHeading < 500) {
+        result = result.substring(firstHeading + 1);
+    }
+    else if (result.startsWith('# ')) {
+        // Already clean
+    }
+    else {
+        // Check for heading without newline prefix
+        const headingIdx = result.indexOf('# ');
+        if (headingIdx > 0 && headingIdx < 500) {
+            result = result.substring(headingIdx);
+        }
+    }
+    return result.trim();
+}
+// ============================================================================
+// Improvement C: Cross-validation of identifiers
+// ============================================================================
+/**
+ * Scan enriched text for backtick-quoted identifiers that look like
+ * ClassName.methodName() and verify them against the verified entity set.
+ * Replace hallucinations with the closest match or strip the () suffix.
+ */
+function crossValidateIdentifiers(content, verifiedEntities) {
+    let fixCount = 0;
+    // Match `SomeIdentifier.someMethod()` or `SomeClass.method()` patterns
+    const result = content.replace(/`([A-Z][a-zA-Z0-9]*\.[a-zA-Z][a-zA-Z0-9]*)\(\)`/g, (match, identifier) => {
+        const [className, methodName] = identifier.split('.');
+        // The regex guarantees an identifier of the form `Class.method`, so both
+        // parts are always present; guard keeps TS happy and is a no-op at runtime.
+        if (className === undefined || methodName === undefined)
+            return match;
+        // Check if class exists
+        const classExists = verifiedEntities.has(className) ||
+            verifiedEntities.has(`cls:${className}`) ||
+            [...verifiedEntities].some(e => e.endsWith(`.${className}`) || e === className);
+        if (classExists) {
+            // Class exists — check if method name is plausible
+            const fullName = `${className}.${methodName}`;
+            if (verifiedEntities.has(fullName) || verifiedEntities.has(methodName)) {
+                return match; // verified, keep as-is
+            }
+            // Try to find closest method match
+            const closest = findClosestMethod(methodName, className, verifiedEntities);
+            if (closest) {
+                fixCount++;
+                return `\`${className}.${closest}()\``;
+            }
+            // Method not verifiable — keep class name but strip method call notation
+            // Leave as `ClassName.methodName()` since the class exists
+            return match;
+        }
+        // Class doesn't exist — might be hallucinated
+        fixCount++;
+        // Strip to just the name without ()
+        return `\`${identifier}\``;
+    });
+    return { fixed: result, fixCount };
+}
+/** Find the closest matching method name for a class */
+function findClosestMethod(methodName, className, entities) {
+    const lower = methodName.toLowerCase();
+    let bestMatch = '';
+    let bestScore = 0;
+    for (const entity of entities) {
+        const entityLower = entity.toLowerCase();
+        // Look for methods that belong to this class
+        if (entityLower.startsWith(className.toLowerCase() + '.')) {
+            const method = entity.split('.').slice(1).join('.');
+            const methodLower = method.toLowerCase();
+            // Score similarity
+            let common = 0;
+            for (let i = 0; i < Math.min(lower.length, methodLower.length); i++) {
+                if (lower[i] === methodLower[i])
+                    common++;
+                else
+                    break;
+            }
+            const score = common / Math.max(lower.length, methodLower.length);
+            if (score > bestScore && score > 0.6) {
+                bestScore = score;
+                bestMatch = method;
+            }
+        }
+    }
+    return bestMatch || null;
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/** Get thinking level for a file by matching its slug to page types */
+function getThinkingLevel(file) {
+    const slug = file.replace(/^\d+[a-z]?-/, '').replace(/\.md$/, '');
+    for (const [type, level] of Object.entries(THINKING_BY_TYPE)) {
+        if (slug.includes(type))
+            return level;
+    }
+    return 'medium';
+}
+//# sourceMappingURL=llm-enricher.js.map

package/dist/docs/llm-enricher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-enricher.js","sourceRoot":"","sources":["../../src/docs/llm-enricher.ts"],"names":[],"mappings":"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"}

package/dist/docs/planning/plan-generator.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Phase 2 — Documentation Plan Generator
+ *
+ * Generates an adaptive documentation plan from the ProjectProfile.
+ * The plan determines which pages to generate, their hierarchy,
+ * and cross-references. Uses LLM for intelligent planning,
+ * with a deterministic fallback for offline use.
+ */
+import type { ProjectProfile } from '../discovery/project-discovery.js';
+import type { LLMCall } from '../llm-enricher.js';
+export type PageType = 'overview' | 'getting-started' | 'key-concepts' | 'architecture' | 'component' | 'subsystem' | 'api-reference' | 'configuration' | 'security' | 'troubleshooting' | 'testing';
+export interface DocPage {
+    id: string;
+    slug: string;
+    title: string;
+    description: string;
+    sourceFiles: string[];
+    parentId?: string;
+    depth?: number;
+    relatedPages: string[];
+    pageType: PageType;
+}
+export interface ConceptEntry {
+    pageId: string;
+    file: string;
+    anchor: string;
+    description: string;
+}
+export interface DocPlan {
+    projectProfile: ProjectProfile;
+    pages: DocPage[];
+    conceptIndex: Record<string, ConceptEntry>;
+}
+/**
+ * Generate a documentation plan using LLM intelligence.
+ * Falls back to deterministic plan if LLM is unavailable.
+ */
+export declare function generateDocPlan(profile: ProjectProfile, llmCall?: LLMCall): Promise<DocPlan>;
+/**
+ * Generate a deterministic plan without LLM — works offline.
+ * Adapts structure to project size and detected features.
+ */
+export declare function generateDeterministicPlan(profile: ProjectProfile): DocPage[];