gitnexus 1.3.11 → 1.4.1

package/dist/core/wiki/generator.js

@@ -12,10 +12,11 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { execSync, execFileSync } from 'child_process';
-import { initWikiDb, closeWikiDb, getFilesWithExports, getAllFiles, getIntraModuleCallEdges, getInterModuleCallEdges, getProcessesForFiles, getAllProcesses, getInterModuleEdgesForOverview, } from './graph-queries.js';
+import { initWikiDb, closeWikiDb, getFilesWithExports, getAllFiles, getIntraModuleCallEdges, getInterModuleCallEdges, getProcessesForFiles, getAllProcesses, getInterModuleEdgesForOverview, getCallGraphNeighborFiles, getCommunityFileMapping, getInterCommunityCallEdges, getCrossCommunityProcesses, } from './graph-queries.js';
 import { generateHTMLViewer } from './html-viewer.js';
 import { callLLM, estimateTokens, } from './llm-client.js';
-import { GROUPING_SYSTEM_PROMPT, GROUPING_USER_PROMPT, MODULE_SYSTEM_PROMPT, MODULE_USER_PROMPT, PARENT_SYSTEM_PROMPT, PARENT_USER_PROMPT, OVERVIEW_SYSTEM_PROMPT, OVERVIEW_USER_PROMPT, fillTemplate, formatFileListForGrouping, formatDirectoryTree, formatCallEdges, formatProcesses, } from './prompts.js';
+import { GROUPING_SYSTEM_PROMPT, GROUPING_USER_PROMPT, GROUPING_SYSTEM_PROMPT_LEGACY, GROUPING_USER_PROMPT_LEGACY, MODULE_SYSTEM_PROMPT, MODULE_USER_PROMPT, PARENT_SYSTEM_PROMPT, PARENT_USER_PROMPT, OVERVIEW_SYSTEM_PROMPT, OVERVIEW_USER_PROMPT, fillTemplate, formatFileListForGrouping, formatDirectoryTree, formatCallEdges, formatProcesses, formatCommunityGroups, formatInterCommunityEdges, formatCrossCommunityProcesses, formatModuleRegistry, } from './prompts.js';
+import { buildCallGraphMermaid, buildSequenceDiagram, buildInterModuleDiagram, } from './diagrams.js';
 import { shouldIgnorePath } from '../../config/ignore-service.js';
 // ─── Constants ────────────────────────────────────────────────────────
 const DEFAULT_MAX_TOKENS_PER_MODULE = 30_000;
@@ -32,6 +33,7 @@ export class WikiGenerator {
     options;
     onProgress;
     failedModules = [];
+    moduleRegistry = new Map();
     constructor(repoPath, storagePath, kuzuPath, llmConfig, options = {}, onProgress) {
         this.repoPath = repoPath;
         this.storagePath = storagePath;
@@ -76,12 +78,20 @@ export class WikiGenerator {
             await this.ensureHTMLViewer();
             return { pagesGenerated: 0, mode: 'up-to-date', failedModules: [] };
         }
-        // Force mode: delete snapshot to force full re-grouping
+        // Force mode: clean all state and delete pages
         if (forceMode) {
             try {
                 await fs.unlink(path.join(this.wikiDir, 'first_module_tree.json'));
             }
             catch { }
+            try {
+                await fs.unlink(path.join(this.wikiDir, 'meta.json'));
+            }
+            catch { }
+            try {
+                await fs.unlink(path.join(this.wikiDir, 'module_tree.json'));
+            }
+            catch { }
             // Delete existing module pages so they get regenerated
             const existingFiles = await fs.readdir(this.wikiDir).catch(() => []);
             for (const f of existingFiles) {
@@ -106,10 +116,14 @@ export class WikiGenerator {
             }
         }
         finally {
+            console.log('[wiki] Closing KuzuDB...');
             await closeWikiDb();
+            console.log('[wiki] KuzuDB closed');
         }
         // Always generate the HTML viewer after wiki content changes
+        console.log('[wiki] Building HTML viewer...');
         await this.ensureHTMLViewer();
+        console.log('[wiki] HTML viewer done');
         return result;
     }
     // ─── HTML Viewer ─────────────────────────────────────────────────────
@@ -144,6 +158,8 @@ export class WikiGenerator {
         // Phase 1: Build module tree
         const moduleTree = await this.buildModuleTree(enrichedFiles);
         pagesGenerated = 0;
+        // Build module registry for cross-references
+        this.moduleRegistry = this.buildModuleRegistry(moduleTree, enrichedFiles);
         // Phase 2: Generate module pages (parallel with concurrency limit)
         const totalModules = this.countModules(moduleTree);
         let modulesProcessed = 0;
@@ -195,9 +211,18 @@ export class WikiGenerator {
         }
         // Phase 3: Generate overview
         this.onProgress('overview', 88, 'Generating overview page...');
-        await this.generateOverview(moduleTree);
-        pagesGenerated++;
+        try {
+            await this.generateOverview(moduleTree);
+            pagesGenerated++;
+            console.log('[wiki] Overview generated successfully');
+        }
+        catch (err) {
+            console.error('[wiki] Overview generation failed:', err.message);
+            this.failedModules.push('_overview');
+            this.onProgress('overview', 90, `Overview generation failed: ${err.message?.slice(0, 120) || 'unknown error'}`);
+        }
         // Save metadata
+        console.log('[wiki] Saving metadata...');
         this.onProgress('finalize', 95, 'Saving metadata...');
         const moduleFiles = this.extractModuleFiles(moduleTree);
         await this.saveModuleTree(moduleTree);
@@ -226,15 +251,41 @@ export class WikiGenerator {
         catch {
             // No snapshot, generate new
         }
-        this.onProgress('grouping', 15, 'Grouping files into modules (LLM)...');
+        this.onProgress('grouping', 12, 'Querying graph communities...');
+        // Try to get community data for graph-driven decomposition
+        const communityGroups = await getCommunityFileMapping();
+        const useCommunities = communityGroups.length > 0;
+        let systemPrompt;
+        let prompt;
         const fileList = formatFileListForGrouping(files);
         const dirTree = formatDirectoryTree(files.map(f => f.filePath));
-        const prompt = fillTemplate(GROUPING_USER_PROMPT, {
-            FILE_LIST: fileList,
-            DIRECTORY_TREE: dirTree,
-        });
-        const response = await callLLM(prompt, this.llmConfig, GROUPING_SYSTEM_PROMPT, this.streamOpts('Grouping files', 15));
-        const grouping = this.parseGroupingResponse(response.content, files);
+        if (useCommunities) {
+            // Graph-aware grouping: use communities as primary signal
+            this.onProgress('grouping', 15, 'Grouping files into modules (graph-driven LLM)...');
+            const [interEdges, crossProcs] = await Promise.all([
+                getInterCommunityCallEdges(),
+                getCrossCommunityProcesses(),
+            ]);
+            systemPrompt = GROUPING_SYSTEM_PROMPT;
+            prompt = fillTemplate(GROUPING_USER_PROMPT, {
+                COMMUNITY_GROUPS: formatCommunityGroups(communityGroups),
+                INTER_COMMUNITY_EDGES: formatInterCommunityEdges(interEdges),
+                CROSS_COMMUNITY_PROCESSES: formatCrossCommunityProcesses(crossProcs),
+                FILE_LIST: fileList,
+                DIRECTORY_TREE: dirTree,
+            });
+        }
+        else {
+            // Legacy grouping: file-only approach
+            this.onProgress('grouping', 15, 'Grouping files into modules (LLM)...');
+            systemPrompt = GROUPING_SYSTEM_PROMPT_LEGACY;
+            prompt = fillTemplate(GROUPING_USER_PROMPT_LEGACY, {
+                FILE_LIST: fileList,
+                DIRECTORY_TREE: dirTree,
+            });
+        }
+        const response = await callLLM(prompt, this.llmConfig, systemPrompt, this.streamOpts('Grouping files', 15));
+        const grouping = this.parseGroupingResponse(response.content, files, communityGroups);
         // Convert to tree nodes
         const tree = [];
         for (const [moduleName, modulePaths] of Object.entries(grouping)) {
@@ -243,7 +294,9 @@ export class WikiGenerator {
             // Token budget check — split if too large
             const totalTokens = await this.estimateModuleTokens(modulePaths);
             if (totalTokens > this.maxTokensPerModule && modulePaths.length > 3) {
-                node.children = this.splitBySubdirectory(moduleName, modulePaths);
+                node.children = useCommunities
+                    ? this.splitByCommunity(moduleName, modulePaths, communityGroups)
+                    : this.splitBySubdirectory(moduleName, modulePaths);
                 node.files = []; // Parent doesn't own files directly when split
             }
             tree.push(node);
@@ -256,7 +309,7 @@ export class WikiGenerator {
     /**
      * Parse LLM grouping response. Validates all files are assigned.
      */
-    parseGroupingResponse(content, files) {
+    parseGroupingResponse(content, files, communityGroups) {
         // Extract JSON from response (handle markdown fences)
         let jsonStr = content.trim();
         const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
@@ -268,11 +321,11 @@ export class WikiGenerator {
             parsed = JSON.parse(jsonStr);
         }
         catch {
-            // Fallback: group by top-level directory
-            return this.fallbackGrouping(files);
+            // Fallback: group by community or top-level directory
+            return this.fallbackGrouping(files, communityGroups);
         }
         if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-            return this.fallbackGrouping(files);
+            return this.fallbackGrouping(files, communityGroups);
         }
         // Validate — ensure all files are assigned
         const allFilePaths = new Set(files.map(f => f.filePath));
@@ -301,12 +354,33 @@ export class WikiGenerator {
         }
         return Object.keys(validGrouping).length > 0
             ? validGrouping
-            : this.fallbackGrouping(files);
+            : this.fallbackGrouping(files, communityGroups);
     }
     /**
-     * Fallback grouping by top-level directory when LLM parsing fails.
+     * Fallback grouping. Uses community file mapping when available,
+     * otherwise groups by top-level directory.
      */
-    fallbackGrouping(files) {
+    fallbackGrouping(files, communityGroups) {
+        // Use community data if available
+        if (communityGroups && communityGroups.length > 0) {
+            const result = {};
+            const assignedFiles = new Set();
+            for (const group of communityGroups) {
+                if (group.files.length > 0) {
+                    result[group.label] = [...group.files];
+                    for (const f of group.files)
+                        assignedFiles.add(f);
+                }
+            }
+            // Assign unassigned files
+            const unassigned = files.map(f => f.filePath).filter(fp => !assignedFiles.has(fp));
+            if (unassigned.length > 0) {
+                result['Other'] = unassigned;
+            }
+            if (Object.keys(result).length > 0)
+                return result;
+        }
+        // Directory-based fallback
         const groups = new Map();
         for (const f of files) {
             const parts = f.filePath.replace(/\\/g, '/').split('/');
@@ -342,6 +416,159 @@ export class WikiGenerator {
             files: subFiles,
         }));
     }
+    /**
+     * Split a large module into sub-modules using community data.
+     * Falls back to subdirectory splitting if community data doesn't help.
+     */
+    splitByCommunity(moduleName, files, communityGroups) {
+        const subGroups = new Map();
+        const unassigned = [];
+        // Group files by their community membership
+        for (const fp of files) {
+            let bestCommunity = '';
+            let bestCount = 0;
+            for (const group of communityGroups) {
+                const count = group.files.filter(f => f === fp).length +
+                    group.secondaryFiles.filter(f => f === fp).length;
+                if (count > bestCount) {
+                    bestCount = count;
+                    bestCommunity = group.label;
+                }
+            }
+            if (bestCommunity) {
+                let group = subGroups.get(bestCommunity);
+                if (!group) {
+                    group = [];
+                    subGroups.set(bestCommunity, group);
+                }
+                group.push(fp);
+            }
+            else {
+                unassigned.push(fp);
+            }
+        }
+        // If community split didn't produce meaningful groups, fall back to subdirectory
+        if (subGroups.size <= 1) {
+            return this.splitBySubdirectory(moduleName, files);
+        }
+        // Add unassigned to largest group
+        if (unassigned.length > 0) {
+            let largestKey = '';
+            let largestSize = 0;
+            for (const [key, group] of subGroups) {
+                if (group.length > largestSize) {
+                    largestSize = group.length;
+                    largestKey = key;
+                }
+            }
+            if (largestKey) {
+                subGroups.get(largestKey).push(...unassigned);
+            }
+        }
+        return Array.from(subGroups.entries()).map(([label, subFiles]) => ({
+            name: `${moduleName} — ${label}`,
+            slug: this.slugify(`${moduleName}-${label}`),
+            files: subFiles,
+        }));
+    }
+    // ─── Module Registry (Cross-References) ─────────────────────────────
+    /**
+     * Build a registry mapping module slugs to their names and exported symbols.
+     */
+    buildModuleRegistry(tree, filesWithExports) {
+        const exportMap = new Map(filesWithExports.map(f => [f.filePath, f]));
+        const registry = new Map();
+        const addNode = (node) => {
+            const symbols = [];
+            const nodeFiles = node.children
+                ? node.children.flatMap(c => c.files)
+                : node.files;
+            for (const fp of nodeFiles) {
+                const fileEntry = exportMap.get(fp);
+                if (fileEntry) {
+                    for (const sym of fileEntry.symbols) {
+                        if (symbols.length < 10)
+                            symbols.push(sym.name);
+                    }
+                }
+            }
+            registry.set(node.slug, { name: node.name, slug: node.slug, symbols });
+            if (node.children) {
+                for (const child of node.children) {
+                    addNode(child);
+                }
+            }
+        };
+        for (const node of tree) {
+            addNode(node);
+        }
+        return registry;
+    }
+    // ─── Cross-Reference Validation ─────────────────────────────────────
+    /**
+     * Validate and fix cross-reference links in generated markdown.
+     * Rewrites invalid slug references using fuzzy matching.
+     */
+    validateAndFixCrossReferences(markdown, registry) {
+        const validSlugs = new Set(Array.from(registry.values()).map(e => e.slug));
+        const slugByName = new Map();
+        for (const entry of registry.values()) {
+            slugByName.set(entry.name.toLowerCase(), entry.slug);
+        }
+        return markdown.replace(/\[([^\]]+)\]\(([a-z0-9-]+)\.md\)/g, (match, text, slug) => {
+            if (validSlugs.has(slug))
+                return match;
+            // Try fuzzy match by link text
+            const fuzzySlug = slugByName.get(text.toLowerCase());
+            if (fuzzySlug)
+                return `[${text}](${fuzzySlug}.md)`;
+            // Try matching slug as partial
+            for (const validSlug of validSlugs) {
+                if (validSlug.includes(slug) || slug.includes(validSlug)) {
+                    return `[${text}](${validSlug}.md)`;
+                }
+            }
+            // Strip broken link
+            return text;
+        });
+    }
+    // ─── Summary Extraction ─────────────────────────────────────────────
+    /**
+     * Extract the overview summary from a generated page.
+     * Uses structured markers when available, falls back to heuristics.
+     */
+    extractSummary(content, maxLength = 800) {
+        // Priority 1: <!-- summary-end --> marker
+        const markerIdx = content.indexOf('<!-- summary-end -->');
+        if (markerIdx > 0) {
+            return content.slice(0, markerIdx).trim();
+        }
+        // Priority 2: Content up to first ## heading (skip # title)
+        const lines = content.split('\n');
+        let pastTitle = false;
+        let result = '';
+        for (const line of lines) {
+            if (!pastTitle && line.startsWith('# ')) {
+                pastTitle = true;
+                result += line + '\n';
+                continue;
+            }
+            if (pastTitle && /^##\s/.test(line)) {
+                break;
+            }
+            result += line + '\n';
+        }
+        if (result.trim().length > 20) {
+            return result.trim().slice(0, maxLength);
+        }
+        // Priority 3: Truncate at sentence boundary near maxLength
+        const truncated = content.slice(0, maxLength);
+        const lastSentence = truncated.lastIndexOf('. ');
+        if (lastSentence > maxLength * 0.5) {
+            return truncated.slice(0, lastSentence + 1).trim();
+        }
+        return truncated.trim();
+    }
     // ─── Phase 2: Generate Module Pages ─────────────────────────────────
     /**
      * Generate a leaf module page from source code + graph data.
@@ -369,10 +596,25 @@ export class WikiGenerator {
             OUTGOING_CALLS: formatCallEdges(interCalls.outgoing),
             INCOMING_CALLS: formatCallEdges(interCalls.incoming),
             PROCESSES: formatProcesses(processes),
+            MODULE_REGISTRY: formatModuleRegistry(this.moduleRegistry, node.slug),
         });
         const response = await callLLM(prompt, this.llmConfig, MODULE_SYSTEM_PROMPT, this.streamOpts(node.name));
-        // Write page with front matter
-        const pageContent = `# ${node.name}\n\n${response.content}`;
+        // Build deterministic diagrams
+        let diagramSection = '';
+        const callGraph = buildCallGraphMermaid(node.name, intraCalls);
+        if (callGraph) {
+            diagramSection += `\n\n## Internal Call Graph\n\n\`\`\`mermaid\n${callGraph}\n\`\`\``;
+        }
+        const topProcesses = processes.slice(0, 3);
+        for (const proc of topProcesses) {
+            const seqDiagram = buildSequenceDiagram(proc);
+            if (seqDiagram) {
+                diagramSection += `\n\n## Workflow: ${proc.label}\n\n\`\`\`mermaid\n${seqDiagram}\n\`\`\``;
+            }
+        }
+        // Assemble page, validate cross-references, and write
+        let pageContent = `# ${node.name}\n\n${response.content}${diagramSection}`;
+        pageContent = this.validateAndFixCrossReferences(pageContent, this.moduleRegistry);
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
     /**
@@ -387,9 +629,7 @@ export class WikiGenerator {
             const childPage = path.join(this.wikiDir, `${child.slug}.md`);
             try {
                 const content = await fs.readFile(childPage, 'utf-8');
-                // Extract overview section (first ~500 chars or up to "### Architecture")
-                const overviewEnd = content.indexOf('### Architecture');
-                const overview = overviewEnd > 0 ? content.slice(0, overviewEnd).trim() : content.slice(0, 800).trim();
+                const overview = this.extractSummary(content);
                 childDocs.push(`#### ${child.name}\n${overview}`);
             }
             catch {
@@ -398,16 +638,26 @@ export class WikiGenerator {
         }
         // Get cross-child call edges
         const allChildFiles = node.children.flatMap(c => c.files);
-        const crossCalls = await getIntraModuleCallEdges(allChildFiles);
-        const processes = await getProcessesForFiles(allChildFiles, 3);
+        const [crossCalls, processes] = await Promise.all([
+            getIntraModuleCallEdges(allChildFiles),
+            getProcessesForFiles(allChildFiles, 3),
+        ]);
         const prompt = fillTemplate(PARENT_USER_PROMPT, {
             MODULE_NAME: node.name,
             CHILDREN_DOCS: childDocs.join('\n\n'),
             CROSS_MODULE_CALLS: formatCallEdges(crossCalls),
             CROSS_PROCESSES: formatProcesses(processes),
+            MODULE_REGISTRY: formatModuleRegistry(this.moduleRegistry, node.slug),
         });
         const response = await callLLM(prompt, this.llmConfig, PARENT_SYSTEM_PROMPT, this.streamOpts(node.name));
-        const pageContent = `# ${node.name}\n\n${response.content}`;
+        // Append cross-child call graph diagram
+        let diagramSection = '';
+        const callGraph = buildCallGraphMermaid(node.name, crossCalls);
+        if (callGraph) {
+            diagramSection += `\n\n## Cross-Module Call Graph\n\n\`\`\`mermaid\n${callGraph}\n\`\`\``;
+        }
+        let pageContent = `# ${node.name}\n\n${response.content}${diagramSection}`;
+        pageContent = this.validateAndFixCrossReferences(pageContent, this.moduleRegistry);
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
     // ─── Phase 3: Generate Overview ─────────────────────────────────────
@@ -418,8 +668,7 @@ export class WikiGenerator {
             const pagePath = path.join(this.wikiDir, `${node.slug}.md`);
             try {
                 const content = await fs.readFile(pagePath, 'utf-8');
-                const overviewEnd = content.indexOf('### Architecture');
-                const overview = overviewEnd > 0 ? content.slice(0, overviewEnd).trim() : content.slice(0, 600).trim();
+                const overview = this.extractSummary(content, 600);
                 moduleSummaries.push(`#### ${node.name}\n${overview}`);
             }
             catch {
@@ -436,22 +685,49 @@ export class WikiGenerator {
         const edgesText = moduleEdges.length > 0
             ? moduleEdges.map(e => `${e.from} → ${e.to} (${e.count} calls)`).join('\n')
             : 'No inter-module call edges detected';
+        // Cap module summaries to avoid blowing up the prompt
+        let summariesText = moduleSummaries.join('\n\n');
+        const MAX_SUMMARIES_CHARS = 30_000; // ~7.5k tokens
+        if (summariesText.length > MAX_SUMMARIES_CHARS) {
+            summariesText = summariesText.slice(0, MAX_SUMMARIES_CHARS) + '\n\n(... remaining modules truncated for brevity)';
+        }
         const prompt = fillTemplate(OVERVIEW_USER_PROMPT, {
             PROJECT_INFO: projectInfo,
-            MODULE_SUMMARIES: moduleSummaries.join('\n\n'),
+            MODULE_SUMMARIES: summariesText,
             MODULE_EDGES: edgesText,
             TOP_PROCESSES: formatProcesses(topProcesses),
+            MODULE_REGISTRY: formatModuleRegistry(this.moduleRegistry),
         });
+        const promptTokens = estimateTokens(prompt + OVERVIEW_SYSTEM_PROMPT);
+        this.onProgress('overview', 88, `Generating overview (~${promptTokens} input tokens)...`);
         const response = await callLLM(prompt, this.llmConfig, OVERVIEW_SYSTEM_PROMPT, this.streamOpts('Generating overview', 88));
-        const pageContent = `# ${path.basename(this.repoPath)} — Wiki\n\n${response.content}`;
+        // Append architecture diagram
+        let diagramSection = '';
+        const archDiagram = buildInterModuleDiagram(moduleEdges);
+        if (archDiagram) {
+            diagramSection += `\n\n## Architecture Diagram\n\n\`\`\`mermaid\n${archDiagram}\n\`\`\``;
+        }
+        const displayName = this.options.repoName || path.basename(this.repoPath);
+        let pageContent = `# ${displayName} — Wiki\n\n${response.content}${diagramSection}`;
+        pageContent = this.validateAndFixCrossReferences(pageContent, this.moduleRegistry);
         await fs.writeFile(path.join(this.wikiDir, 'overview.md'), pageContent, 'utf-8');
     }
     // ─── Incremental Updates ────────────────────────────────────────────
     async incrementalUpdate(existingMeta, currentCommit) {
         this.onProgress('incremental', 5, 'Detecting changes...');
-        // Get changed files since last generation
-        const changedFiles = this.getChangedFiles(existingMeta.fromCommit, currentCommit);
-        if (changedFiles.length === 0) {
+        // Get changed files with status since last generation
+        const changedEntries = this.getChangedFilesWithStatus(existingMeta.fromCommit, currentCommit);
+        // Shallow clone fallback — commit history too shallow for incremental diff
+        if (changedEntries.some(e => e.filePath === '__SHALLOW_CLONE_FALLBACK__')) {
+            this.onProgress('incremental', 10, 'Commit history too shallow — running full generation...');
+            try {
+                await fs.unlink(path.join(this.wikiDir, 'first_module_tree.json'));
+            }
+            catch { }
+            const fullResult = await this.fullGeneration(currentCommit);
+            return { ...fullResult, mode: 'incremental' };
+        }
+        if (changedEntries.length === 0) {
             // No file changes but commit differs (e.g. merge commit)
             await this.saveWikiMeta({
                 ...existingMeta,
@@ -460,11 +736,27 @@ export class WikiGenerator {
             });
             return { pagesGenerated: 0, mode: 'incremental', failedModules: [] };
         }
-        this.onProgress('incremental', 10, `${changedFiles.length} files changed`);
-        // Determine affected modules
+        // Categorize changes
+        const deletedFiles = [];
+        const addedFiles = [];
+        const modifiedFiles = [];
+        for (const entry of changedEntries) {
+            if (entry.status === 'D')
+                deletedFiles.push(entry.filePath);
+            else if (entry.status === 'A')
+                addedFiles.push(entry.filePath);
+            else
+                modifiedFiles.push(entry.filePath);
+        }
+        this.onProgress('incremental', 10, `${changedEntries.length} files changed (${addedFiles.length}A/${modifiedFiles.length}M/${deletedFiles.length}D)`);
+        // Purge deleted files from metadata and tree
+        if (deletedFiles.length > 0) {
+            this.purgeDeletedFiles(existingMeta, deletedFiles);
+        }
+        // Determine affected modules from modified files
         const affectedModules = new Set();
         const newFiles = [];
-        for (const fp of changedFiles) {
+        for (const fp of [...modifiedFiles, ...addedFiles]) {
             let found = false;
             for (const [mod, files] of Object.entries(existingMeta.moduleFiles)) {
                 if (files.includes(fp)) {
@@ -477,6 +769,15 @@ export class WikiGenerator {
                 newFiles.push(fp);
             }
         }
+        // Also mark modules that lost files as affected
+        for (const fp of deletedFiles) {
+            for (const [mod, files] of Object.entries(existingMeta.moduleFiles)) {
+                if (files.includes(fp)) {
+                    affectedModules.add(mod);
+                    break;
+                }
+            }
+        }
         // If significant new files exist, re-run full grouping
         if (newFiles.length > 5) {
             this.onProgress('incremental', 15, 'Significant new files detected, running full generation...');
@@ -488,14 +789,17 @@ export class WikiGenerator {
             const fullResult = await this.fullGeneration(currentCommit);
             return { ...fullResult, mode: 'incremental' };
         }
-        // Add new files to nearest module or "Other"
+        // Assign new files to nearest module using call-graph neighbors
         if (newFiles.length > 0) {
-            if (!existingMeta.moduleFiles['Other']) {
-                existingMeta.moduleFiles['Other'] = [];
+            const assignments = await this.assignNewFilesToModules(newFiles, existingMeta);
+            this.syncNewFilesToTree(existingMeta, assignments);
+            for (const mod of new Set(Object.values(assignments))) {
+                affectedModules.add(mod);
             }
-            existingMeta.moduleFiles['Other'].push(...newFiles);
-            affectedModules.add('Other');
         }
+        // Build registry for cross-references
+        const enrichedFiles = await getFilesWithExports();
+        this.moduleRegistry = this.buildModuleRegistry(existingMeta.moduleTree, enrichedFiles);
         // Regenerate affected module pages (parallel)
         let pagesGenerated = 0;
         const moduleTree = existingMeta.moduleTree;
@@ -539,8 +843,9 @@ export class WikiGenerator {
             await this.generateOverview(moduleTree);
             pagesGenerated++;
         }
-        // Save updated metadata
+        // Save updated metadata and module tree
         this.onProgress('incremental', 95, 'Saving metadata...');
+        await this.saveModuleTree(moduleTree);
         await this.saveWikiMeta({
             ...existingMeta,
             fromCommit: currentCommit,
@@ -550,6 +855,119 @@ export class WikiGenerator {
         this.onProgress('done', 100, 'Incremental update complete');
         return { pagesGenerated, mode: 'incremental', failedModules: [...this.failedModules] };
     }
+    // ─── Incremental Helpers ───────────────────────────────────────────
+    /**
+     * Purge deleted files from module metadata and tree.
+     * Removes orphaned modules that lost all files.
+     */
+    purgeDeletedFiles(meta, deletedFiles) {
+        const deletedSet = new Set(deletedFiles);
+        // Remove from moduleFiles
+        for (const [mod, files] of Object.entries(meta.moduleFiles)) {
+            meta.moduleFiles[mod] = files.filter(f => !deletedSet.has(f));
+        }
+        // Prune empty modules from moduleFiles
+        for (const mod of Object.keys(meta.moduleFiles)) {
+            if (meta.moduleFiles[mod].length === 0) {
+                delete meta.moduleFiles[mod];
+                // Delete orphaned markdown page
+                const slug = this.slugify(mod);
+                fs.unlink(path.join(this.wikiDir, `${slug}.md`)).catch(() => { });
+            }
+        }
+        // Walk moduleTree recursively, filter files, prune empty nodes
+        const pruneTree = (nodes) => {
+            return nodes.filter(node => {
+                node.files = node.files.filter(f => !deletedSet.has(f));
+                if (node.children) {
+                    node.children = pruneTree(node.children);
+                    // If parent lost all children and has no files, prune it
+                    if (node.children.length === 0 && node.files.length === 0) {
+                        fs.unlink(path.join(this.wikiDir, `${node.slug}.md`)).catch(() => { });
+                        return false;
+                    }
+                }
+                else if (node.files.length === 0) {
+                    fs.unlink(path.join(this.wikiDir, `${node.slug}.md`)).catch(() => { });
+                    return false;
+                }
+                return true;
+            });
+        };
+        meta.moduleTree = pruneTree(meta.moduleTree);
+    }
+    /**
+     * Assign new files to existing modules using call-graph neighbor analysis.
+     * Falls back to "Other" if no neighbors found.
+     */
+    async assignNewFilesToModules(newFiles, meta) {
+        const assignments = {};
+        // Build file-to-module lookup from existing metadata
+        const fileToModule = new Map();
+        for (const [mod, files] of Object.entries(meta.moduleFiles)) {
+            for (const f of files)
+                fileToModule.set(f, mod);
+        }
+        // Query per-file (newFiles.length <= 5 since >5 triggers full regen)
+        for (const fp of newFiles) {
+            const neighbors = await getCallGraphNeighborFiles([fp]);
+            const knownNeighbors = neighbors.filter(n => fileToModule.has(n));
+            if (knownNeighbors.length > 0) {
+                // Count hits per module
+                const moduleCounts = new Map();
+                for (const n of knownNeighbors) {
+                    const mod = fileToModule.get(n);
+                    moduleCounts.set(mod, (moduleCounts.get(mod) || 0) + 1);
+                }
+                // Assign to module with most neighbor hits
+                let bestMod = 'Other';
+                let bestCount = 0;
+                for (const [mod, count] of moduleCounts) {
+                    if (count > bestCount) {
+                        bestCount = count;
+                        bestMod = mod;
+                    }
+                }
+                assignments[fp] = bestMod;
+            }
+            else {
+                assignments[fp] = 'Other';
+            }
+        }
+        return assignments;
+    }
+    /**
+     * Sync new file assignments into both moduleFiles and moduleTree.
+     */
+    syncNewFilesToTree(meta, assignments) {
+        for (const [fp, mod] of Object.entries(assignments)) {
+            // Update moduleFiles
+            if (!meta.moduleFiles[mod]) {
+                meta.moduleFiles[mod] = [];
+            }
+            meta.moduleFiles[mod].push(fp);
+            // Update moduleTree
+            const modSlug = this.slugify(mod);
+            const node = this.findNodeBySlug(meta.moduleTree, modSlug);
+            if (node) {
+                if (node.children && node.children.length > 0) {
+                    // Add to first child as default
+                    node.children[0].files.push(fp);
+                }
+                else {
+                    node.files.push(fp);
+                }
+            }
+            else {
+                // Create new "Other" node if needed
+                meta.moduleTree.push({
+                    name: mod,
+                    slug: modSlug,
+                    files: [fp],
+                });
+            }
+        }
+    }
     // ─── Helpers ────────────────────────────────────────────────────────
     getCurrentCommit() {
         try {
@@ -559,13 +977,84 @@ export class WikiGenerator {
             return '';
         }
     }
-    getChangedFiles(fromCommit, toCommit) {
+    /**
+     * Parse git diff --name-status output into structured entries.
+     */
+    parseNameStatusOutput(output) {
+        if (!output)
+            return [];
+        const results = [];
+        for (const line of output.split('\n').filter(Boolean)) {
+            const parts = line.split('\t');
+            if (parts.length < 2)
+                continue;
+            const rawStatus = parts[0].charAt(0);
+            if (rawStatus === 'R' && parts.length >= 3) {
+                // Rename: treat as delete old + add new
+                results.push({ status: 'D', filePath: parts[1] });
+                results.push({ status: 'A', filePath: parts[2] });
+            }
+            else if (rawStatus === 'A' || rawStatus === 'M' || rawStatus === 'D') {
+                results.push({ status: rawStatus, filePath: parts[1] });
+            }
+            else {
+                // Default to modified for unknown statuses (C for copy, etc.)
+                results.push({ status: 'M', filePath: parts[parts.length - 1] });
+            }
+        }
+        return results;
+    }
+    /**
+     * Get changed files with their status (Added, Modified, Deleted).
+     * Handles renames as Delete + Add.
+     * Detects shallow clones and attempts to unshallow if needed.
+     */
+    getChangedFilesWithStatus(fromCommit, toCommit) {
         try {
-            const output = execFileSync('git', ['diff', `${fromCommit}..${toCommit}`, '--name-only'], { cwd: this.repoPath }).toString().trim();
-            return output ? output.split('\n').filter(Boolean) : [];
+            const output = execFileSync('git', ['diff', `${fromCommit}..${toCommit}`, '--name-status'], { cwd: this.repoPath }).toString().trim();
+            if (output)
+                return this.parseNameStatusOutput(output);
+            // Empty output — verify fromCommit is reachable (not a shallow clone issue)
+            try {
+                execFileSync('git', ['cat-file', '-t', fromCommit], { cwd: this.repoPath });
+                // Commit is reachable, genuinely no changes
+                return [];
+            }
+            catch {
+                // fromCommit not reachable — fall through to unshallow logic
+            }
         }
         catch {
-            return [];
+            // git diff threw — most common shallow clone symptom ("fatal: bad revision")
+            // Verify it's actually a reachability issue before attempting unshallow
+            try {
+                execFileSync('git', ['cat-file', '-t', fromCommit], { cwd: this.repoPath });
+                // Commit exists but diff still failed — genuine error, not shallow
+                return [];
+            }
+            catch {
+                // fromCommit not reachable — fall through to unshallow logic
+            }
+        }
+        // fromCommit not reachable — likely a shallow clone
+        console.log(`[wiki] fromCommit ${fromCommit.slice(0, 8)} not reachable, attempting to unshallow...`);
+        try {
+            execFileSync('git', ['fetch', '--unshallow'], {
+                cwd: this.repoPath,
+                timeout: 120_000,
+            });
+        }
+        catch (fetchErr) {
+            console.warn(`[wiki] git fetch --unshallow failed:`, fetchErr);
+            return [{ status: 'A', filePath: '__SHALLOW_CLONE_FALLBACK__' }];
+        }
+        // Retry the diff after unshallowing
+        try {
+            const retryOutput = execFileSync('git', ['diff', `${fromCommit}..${toCommit}`, '--name-status'], { cwd: this.repoPath }).toString().trim();
+            return this.parseNameStatusOutput(retryOutput);
+        }
+        catch {
+            return [{ status: 'A', filePath: '__SHALLOW_CLONE_FALLBACK__' }];
         }
     }
     async readSourceFiles(filePaths) {
@@ -752,12 +1241,22 @@ export class WikiGenerator {
         }
         return null;
     }
+    /** Set of all slugs assigned so far — used to prevent collisions. */
+    assignedSlugs = new Set();
     slugify(name) {
-        return name
+        let base = name
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, '-')
             .replace(/^-+|-+$/g, '')
             .slice(0, 60);
+        // Deduplicate: append -2, -3, etc. if slug already taken
+        let slug = base;
+        let counter = 2;
+        while (this.assignedSlugs.has(slug)) {
+            slug = `${base}-${counter++}`;
+        }
+        this.assignedSlugs.add(slug);
+        return slug;
     }
     async fileExists(fp) {
         try {