gitnexus 1.4.0 → 1.4.1

package/dist/core/wiki/diagrams.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Deterministic Visual Artifacts for Wiki Generation
+ *
+ * Pure functions converting graph data to Mermaid diagrams.
+ * All node IDs use `n_` prefix to avoid reserved keyword collisions (per commit dfd3d17).
+ */
+import type { CallEdge, ProcessInfo } from './graph-queries.js';
+/**
+ * Build a Mermaid flowchart of internal call edges within a module.
+ * Groups nodes into subgraphs by file. Returns null if no edges.
+ */
+export declare function buildCallGraphMermaid(moduleName: string, edges: CallEdge[], maxNodes?: number): string | null;
+/**
+ * Build a Mermaid sequence diagram from an execution flow.
+ * Participants are unique files; messages are function calls between steps.
+ * Returns null if fewer than 2 steps.
+ */
+export declare function buildSequenceDiagram(process: ProcessInfo, maxSteps?: number): string | null;
+/**
+ * Build a Mermaid graph showing relationships between documentation modules.
+ * Prunes to top N modules by total edge weight. Returns null if no edges.
+ */
+export declare function buildInterModuleDiagram(edges: Array<{
+    from: string;
+    to: string;
+    count: number;
+}>, maxNodes?: number): string | null;

package/dist/core/wiki/diagrams.js

@@ -0,0 +1,163 @@
+/**
+ * Deterministic Visual Artifacts for Wiki Generation
+ *
+ * Pure functions converting graph data to Mermaid diagrams.
+ * All node IDs use `n_` prefix to avoid reserved keyword collisions (per commit dfd3d17).
+ */
+import { shortPath } from './prompts.js';
+// ─── Helpers ──────────────────────────────────────────────────────────
+/**
+ * Sanitize a string for use as a Mermaid node ID.
+ * Prefixes with `n_` and strips non-alphanumeric characters.
+ */
+function sanitizeMermaidId(name) {
+    return 'n_' + name.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+/**
+ * Sanitize a string for use as a Mermaid label (inside quotes).
+ * Escapes quotes and strips control characters.
+ */
+function sanitizeMermaidLabel(label) {
+    return label.replace(/"/g, "'").replace(/[\r\n]/g, ' ');
+}
+// ─── Internal Call Graph (Leaf Pages) ─────────────────────────────────
+/**
+ * Build a Mermaid flowchart of internal call edges within a module.
+ * Groups nodes into subgraphs by file. Returns null if no edges.
+ */
+export function buildCallGraphMermaid(moduleName, edges, maxNodes = 12) {
+    if (edges.length === 0)
+        return null;
+    // Collect unique nodes and group by file
+    const nodeSet = new Map();
+    for (const e of edges) {
+        const fromKey = `${e.fromFile}::${e.fromName}`;
+        const toKey = `${e.toFile}::${e.toName}`;
+        if (!nodeSet.has(fromKey))
+            nodeSet.set(fromKey, { name: e.fromName, file: e.fromFile });
+        if (!nodeSet.has(toKey))
+            nodeSet.set(toKey, { name: e.toName, file: e.toFile });
+    }
+    // Prune if too many nodes — keep nodes with most edges
+    if (nodeSet.size > maxNodes) {
+        const edgeCounts = new Map();
+        for (const e of edges) {
+            const fromKey = `${e.fromFile}::${e.fromName}`;
+            const toKey = `${e.toFile}::${e.toName}`;
+            edgeCounts.set(fromKey, (edgeCounts.get(fromKey) || 0) + 1);
+            edgeCounts.set(toKey, (edgeCounts.get(toKey) || 0) + 1);
+        }
+        const sorted = Array.from(edgeCounts.entries()).sort((a, b) => b[1] - a[1]);
+        const topKeys = new Set(sorted.slice(0, maxNodes).map(([k]) => k));
+        for (const key of nodeSet.keys()) {
+            if (!topKeys.has(key))
+                nodeSet.delete(key);
+        }
+    }
+    // Group nodes by file
+    const fileGroups = new Map();
+    for (const [key, node] of nodeSet) {
+        let group = fileGroups.get(node.file);
+        if (!group) {
+            group = [];
+            fileGroups.set(node.file, group);
+        }
+        group.push({ key, name: node.name });
+    }
+    // Build Mermaid output
+    const lines = ['graph TD'];
+    const validNodeKeys = new Set(nodeSet.keys());
+    for (const [file, nodes] of fileGroups) {
+        const subId = sanitizeMermaidId(file);
+        lines.push(`  subgraph ${subId}["${sanitizeMermaidLabel(shortPath(file))}"]`);
+        for (const n of nodes) {
+            const nodeId = sanitizeMermaidId(n.key);
+            lines.push(`    ${nodeId}["${sanitizeMermaidLabel(n.name)}"]`);
+        }
+        lines.push('  end');
+    }
+    // Add edges (only between valid nodes)
+    for (const e of edges) {
+        const fromKey = `${e.fromFile}::${e.fromName}`;
+        const toKey = `${e.toFile}::${e.toName}`;
+        if (validNodeKeys.has(fromKey) && validNodeKeys.has(toKey)) {
+            lines.push(`  ${sanitizeMermaidId(fromKey)} --> ${sanitizeMermaidId(toKey)}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ─── Sequence Diagram (Execution Flows) ───────────────────────────────
+/**
+ * Build a Mermaid sequence diagram from an execution flow.
+ * Participants are unique files; messages are function calls between steps.
+ * Returns null if fewer than 2 steps.
+ */
+export function buildSequenceDiagram(process, maxSteps = 10) {
+    if (process.steps.length < 2)
+        return null;
+    const steps = process.steps.slice(0, maxSteps);
+    // Collect unique participants (files)
+    const participantOrder = [];
+    const participantSet = new Set();
+    for (const s of steps) {
+        if (!participantSet.has(s.filePath)) {
+            participantSet.add(s.filePath);
+            participantOrder.push(s.filePath);
+        }
+    }
+    const lines = ['sequenceDiagram'];
+    for (const fp of participantOrder) {
+        const alias = sanitizeMermaidId(fp);
+        lines.push(`  participant ${alias} as ${sanitizeMermaidLabel(shortPath(fp))}`);
+    }
+    // Generate messages between consecutive steps
+    for (let i = 0; i < steps.length - 1; i++) {
+        const from = sanitizeMermaidId(steps[i].filePath);
+        const to = sanitizeMermaidId(steps[i + 1].filePath);
+        const label = sanitizeMermaidLabel(steps[i + 1].name);
+        if (from === to) {
+            lines.push(`  ${from} ->> ${from}: ${label}`);
+        }
+        else {
+            lines.push(`  ${from} ->> ${to}: ${label}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ─── Inter-Module Architecture Diagram (Overview Page) ────────────────
+/**
+ * Build a Mermaid graph showing relationships between documentation modules.
+ * Prunes to top N modules by total edge weight. Returns null if no edges.
+ */
+export function buildInterModuleDiagram(edges, maxNodes = 10) {
+    if (edges.length === 0)
+        return null;
+    // Compute total weight per module
+    const moduleWeight = new Map();
+    for (const e of edges) {
+        moduleWeight.set(e.from, (moduleWeight.get(e.from) || 0) + e.count);
+        moduleWeight.set(e.to, (moduleWeight.get(e.to) || 0) + e.count);
+    }
+    // Keep top N modules
+    const topModules = new Set(Array.from(moduleWeight.entries())
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, maxNodes)
+        .map(([mod]) => mod));
+    // Filter edges to only include top modules
+    const filteredEdges = edges.filter(e => topModules.has(e.from) && topModules.has(e.to));
+    if (filteredEdges.length === 0)
+        return null;
+    const lines = ['graph LR'];
+    // Declare nodes
+    for (const mod of topModules) {
+        const nodeId = sanitizeMermaidId(mod);
+        lines.push(`  ${nodeId}["${sanitizeMermaidLabel(mod)}"]`);
+    }
+    // Add edges with labels
+    for (const e of filteredEdges) {
+        const fromId = sanitizeMermaidId(e.from);
+        const toId = sanitizeMermaidId(e.to);
+        lines.push(`  ${fromId} -->|${e.count} calls| ${toId}`);
+    }
+    return lines.join('\n');
+}

package/dist/core/wiki/generator.d.ts

@@ -17,6 +17,8 @@ export interface WikiOptions {
     apiKey?: string;
     maxTokensPerModule?: number;
     concurrency?: number;
+    /** Human-readable repo name (e.g. "owner/repo") for the overview title. Falls back to directory basename. */
+    repoName?: string;
 }
 export interface WikiMeta {
     fromCommit: string;
@@ -43,6 +45,7 @@ export declare class WikiGenerator {
     private options;
     private onProgress;
     private failedModules;
+    private moduleRegistry;
     constructor(repoPath: string, storagePath: string, kuzuPath: string, llmConfig: LLMConfig, options?: WikiOptions, onProgress?: ProgressCallback);
     private lastPercent;
     /**
@@ -66,13 +69,33 @@ export declare class WikiGenerator {
      */
     private parseGroupingResponse;
     /**
-     * Fallback grouping by top-level directory when LLM parsing fails.
+     * Fallback grouping. Uses community file mapping when available,
+     * otherwise groups by top-level directory.
      */
     private fallbackGrouping;
     /**
      * Split a large module into sub-modules by subdirectory.
      */
     private splitBySubdirectory;
+    /**
+     * Split a large module into sub-modules using community data.
+     * Falls back to subdirectory splitting if community data doesn't help.
+     */
+    private splitByCommunity;
+    /**
+     * Build a registry mapping module slugs to their names and exported symbols.
+     */
+    private buildModuleRegistry;
+    /**
+     * Validate and fix cross-reference links in generated markdown.
+     * Rewrites invalid slug references using fuzzy matching.
+     */
+    private validateAndFixCrossReferences;
+    /**
+     * Extract the overview summary from a generated page.
+     * Uses structured markers when available, falls back to heuristics.
+     */
+    private extractSummary;
     /**
      * Generate a leaf module page from source code + graph data.
      */
@@ -83,8 +106,31 @@ export declare class WikiGenerator {
     private generateParentPage;
     private generateOverview;
     private incrementalUpdate;
+    /**
+     * Purge deleted files from module metadata and tree.
+     * Removes orphaned modules that lost all files.
+     */
+    private purgeDeletedFiles;
+    /**
+     * Assign new files to existing modules using call-graph neighbor analysis.
+     * Falls back to "Other" if no neighbors found.
+     */
+    private assignNewFilesToModules;
+    /**
+     * Sync new file assignments into both moduleFiles and moduleTree.
+     */
+    private syncNewFilesToTree;
     private getCurrentCommit;
-    private getChangedFiles;
+    /**
+     * Parse git diff --name-status output into structured entries.
+     */
+    private parseNameStatusOutput;
+    /**
+     * Get changed files with their status (Added, Modified, Deleted).
+     * Handles renames as Delete + Add.
+     * Detects shallow clones and attempts to unshallow if needed.
+     */
+    private getChangedFilesWithStatus;
     private readSourceFiles;
     private truncateSource;
     private estimateModuleTokens;
@@ -102,6 +148,8 @@ export declare class WikiGenerator {
      */
     private runParallel;
     private findNodeBySlug;
+    /** Set of all slugs assigned so far — used to prevent collisions. */
+    private assignedSlugs;
     private slugify;
     private fileExists;
     private loadWikiMeta;