gitnexus 1.0.0

package/dist/core/ingestion/cluster-enricher.js

@@ -0,0 +1,170 @@
+/**
+ * Cluster Enricher
+ *
+ * LLM-based enrichment for community clusters.
+ * Generates semantic names, keywords, and descriptions using an LLM.
+ */
+// ============================================================================
+// PROMPT TEMPLATE
+// ============================================================================
+const buildEnrichmentPrompt = (members, heuristicLabel) => {
+    // Limit to first 20 members to control token usage
+    const limitedMembers = members.slice(0, 20);
+    const memberList = limitedMembers
+        .map(m => `${m.name} (${m.type})`)
+        .join(', ');
+    return `Analyze this code cluster and provide a semantic name and short description.
+
+Heuristic: "${heuristicLabel}"
+Members: ${memberList}${members.length > 20 ? ` (+${members.length - 20} more)` : ''}
+
+Reply with JSON only:
+{"name": "2-4 word semantic name", "description": "One sentence describing purpose"}`;
+};
+// ============================================================================
+// PARSE LLM RESPONSE
+// ============================================================================
+const parseEnrichmentResponse = (response, fallbackLabel) => {
+    try {
+        // Extract JSON from response (handles markdown code blocks)
+        const jsonMatch = response.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            throw new Error('No JSON found in response');
+        }
+        const parsed = JSON.parse(jsonMatch[0]);
+        return {
+            name: parsed.name || fallbackLabel,
+            keywords: Array.isArray(parsed.keywords) ? parsed.keywords : [],
+            description: parsed.description || '',
+        };
+    }
+    catch {
+        // Fallback if parsing fails
+        return {
+            name: fallbackLabel,
+            keywords: [],
+            description: '',
+        };
+    }
+};
+// ============================================================================
+// MAIN ENRICHMENT FUNCTION
+// ============================================================================
+/**
+ * Enrich clusters with LLM-generated names, keywords, and descriptions
+ *
+ * @param communities - Community nodes to enrich
+ * @param memberMap - Map of communityId -> member info
+ * @param llmClient - LLM client for generation
+ * @param onProgress - Progress callback
+ */
+export const enrichClusters = async (communities, memberMap, llmClient, onProgress) => {
+    const enrichments = new Map();
+    let tokensUsed = 0;
+    for (let i = 0; i < communities.length; i++) {
+        const community = communities[i];
+        const members = memberMap.get(community.id) || [];
+        onProgress?.(i + 1, communities.length);
+        if (members.length === 0) {
+            // No members, use heuristic
+            enrichments.set(community.id, {
+                name: community.heuristicLabel,
+                keywords: [],
+                description: '',
+            });
+            continue;
+        }
+        try {
+            const prompt = buildEnrichmentPrompt(members, community.heuristicLabel);
+            const response = await llmClient.generate(prompt);
+            // Rough token estimate
+            tokensUsed += prompt.length / 4 + response.length / 4;
+            const enrichment = parseEnrichmentResponse(response, community.heuristicLabel);
+            enrichments.set(community.id, enrichment);
+        }
+        catch (error) {
+            // On error, fallback to heuristic
+            console.warn(`Failed to enrich cluster ${community.id}:`, error);
+            enrichments.set(community.id, {
+                name: community.heuristicLabel,
+                keywords: [],
+                description: '',
+            });
+        }
+    }
+    return { enrichments, tokensUsed };
+};
+// ============================================================================
+// BATCH ENRICHMENT (more efficient)
+// ============================================================================
+/**
+ * Enrich multiple clusters in a single LLM call (batch mode)
+ * More efficient for token usage but requires larger context window
+ */
+export const enrichClustersBatch = async (communities, memberMap, llmClient, batchSize = 5, onProgress) => {
+    const enrichments = new Map();
+    let tokensUsed = 0;
+    // Process in batches
+    for (let i = 0; i < communities.length; i += batchSize) {
+        // Report progress
+        onProgress?.(Math.min(i + batchSize, communities.length), communities.length);
+        const batch = communities.slice(i, i + batchSize);
+        const batchPrompt = batch.map((community, idx) => {
+            const members = memberMap.get(community.id) || [];
+            const limitedMembers = members.slice(0, 15);
+            const memberList = limitedMembers
+                .map(m => `${m.name} (${m.type})`)
+                .join(', ');
+            return `Cluster ${idx + 1} (id: ${community.id}):
+Heuristic: "${community.heuristicLabel}"
+Members: ${memberList}`;
+        }).join('\n\n');
+        const prompt = `Analyze these code clusters and generate semantic names, keywords, and descriptions.
+
+${batchPrompt}
+
+Output JSON array:
+[
+  {"id": "comm_X", "name": "...", "keywords": [...], "description": "..."},
+  ...
+]`;
+        try {
+            const response = await llmClient.generate(prompt);
+            tokensUsed += prompt.length / 4 + response.length / 4;
+            // Parse batch response
+            const jsonMatch = response.match(/\[[\s\S]*\]/);
+            if (jsonMatch) {
+                const parsed = JSON.parse(jsonMatch[0]);
+                for (const item of parsed) {
+                    enrichments.set(item.id, {
+                        name: item.name,
+                        keywords: item.keywords || [],
+                        description: item.description || '',
+                    });
+                }
+            }
+        }
+        catch (error) {
+            console.warn('Batch enrichment failed, falling back to heuristics:', error);
+            // Fallback for this batch
+            for (const community of batch) {
+                enrichments.set(community.id, {
+                    name: community.heuristicLabel,
+                    keywords: [],
+                    description: '',
+                });
+            }
+        }
+    }
+    // Fill in any missing communities
+    for (const community of communities) {
+        if (!enrichments.has(community.id)) {
+            enrichments.set(community.id, {
+                name: community.heuristicLabel,
+                keywords: [],
+                description: '',
+            });
+        }
+    }
+    return { enrichments, tokensUsed };
+};

package/dist/core/ingestion/community-processor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Community Detection Processor
+ *
+ * Uses the Leiden algorithm (via graphology-communities-leiden) to detect
+ * communities/clusters in the code graph based on CALLS relationships.
+ *
+ * Communities represent groups of code that work together frequently,
+ * helping agents navigate the codebase by functional area rather than file structure.
+ */
+import { KnowledgeGraph } from '../graph/types.js';
+export interface CommunityNode {
+    id: string;
+    label: string;
+    heuristicLabel: string;
+    cohesion: number;
+    symbolCount: number;
+}
+export interface CommunityMembership {
+    nodeId: string;
+    communityId: string;
+}
+export interface CommunityDetectionResult {
+    communities: CommunityNode[];
+    memberships: CommunityMembership[];
+    stats: {
+        totalCommunities: number;
+        modularity: number;
+        nodesProcessed: number;
+    };
+}
+export declare const COMMUNITY_COLORS: string[];
+export declare const getCommunityColor: (communityIndex: number) => string;
+/**
+ * Detect communities in the knowledge graph using Leiden algorithm
+ *
+ * This runs AFTER all relationships (CALLS, IMPORTS, etc.) have been built.
+ * It uses primarily CALLS edges to cluster code that works together.
+ */
+export declare const processCommunities: (knowledgeGraph: KnowledgeGraph, onProgress?: (message: string, progress: number) => void) => Promise<CommunityDetectionResult>;

package/dist/core/ingestion/community-processor.js

@@ -0,0 +1,269 @@
+/**
+ * Community Detection Processor
+ *
+ * Uses the Leiden algorithm (via graphology-communities-leiden) to detect
+ * communities/clusters in the code graph based on CALLS relationships.
+ *
+ * Communities represent groups of code that work together frequently,
+ * helping agents navigate the codebase by functional area rather than file structure.
+ */
+// NOTE: The Leiden algorithm source is vendored from graphology's repo
+// (src/communities-leiden) because it was never published to npm.
+// We use createRequire to load the CommonJS vendored files in ESM context.
+import Graph from 'graphology';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Navigate to package root (works from both src/ and dist/)
+const leidenPath = resolve(__dirname, '..', '..', '..', 'vendor', 'leiden', 'index.cjs');
+const _require = createRequire(import.meta.url);
+const leiden = _require(leidenPath);
+// ============================================================================
+// COMMUNITY COLORS (for visualization)
+// ============================================================================
+export const COMMUNITY_COLORS = [
+    '#ef4444', // red
+    '#f97316', // orange
+    '#eab308', // yellow
+    '#22c55e', // green
+    '#06b6d4', // cyan
+    '#3b82f6', // blue
+    '#8b5cf6', // violet
+    '#d946ef', // fuchsia
+    '#ec4899', // pink
+    '#f43f5e', // rose
+    '#14b8a6', // teal
+    '#84cc16', // lime
+];
+export const getCommunityColor = (communityIndex) => {
+    return COMMUNITY_COLORS[communityIndex % COMMUNITY_COLORS.length];
+};
+// ============================================================================
+// MAIN PROCESSOR
+// ============================================================================
+/**
+ * Detect communities in the knowledge graph using Leiden algorithm
+ *
+ * This runs AFTER all relationships (CALLS, IMPORTS, etc.) have been built.
+ * It uses primarily CALLS edges to cluster code that works together.
+ */
+export const processCommunities = async (knowledgeGraph, onProgress) => {
+    onProgress?.('Building graph for community detection...', 0);
+    // Step 1: Build a graphology graph from the knowledge graph
+    // We only include symbol nodes (Function, Class, Method) and CALLS edges
+    const graph = buildGraphologyGraph(knowledgeGraph);
+    if (graph.order === 0) {
+        // No nodes to cluster
+        return {
+            communities: [],
+            memberships: [],
+            stats: { totalCommunities: 0, modularity: 0, nodesProcessed: 0 }
+        };
+    }
+    onProgress?.(`Running Leiden algorithm on ${graph.order} nodes...`, 30);
+    // Step 2: Run Leiden algorithm for community detection
+    const details = leiden.detailed(graph, {
+        resolution: 1.0, // Default resolution, can be tuned
+        randomWalk: true,
+    });
+    onProgress?.(`Found ${details.count} communities...`, 60);
+    // Step 3: Create community nodes with heuristic labels
+    const communityNodes = createCommunityNodes(details.communities, details.count, graph, knowledgeGraph);
+    onProgress?.('Creating membership edges...', 80);
+    // Step 4: Create membership mappings
+    const memberships = [];
+    Object.entries(details.communities).forEach(([nodeId, communityNum]) => {
+        memberships.push({
+            nodeId,
+            communityId: `comm_${communityNum}`,
+        });
+    });
+    onProgress?.('Community detection complete!', 100);
+    return {
+        communities: communityNodes,
+        memberships,
+        stats: {
+            totalCommunities: details.count,
+            modularity: details.modularity,
+            nodesProcessed: graph.order,
+        }
+    };
+};
+// ============================================================================
+// HELPER: Build graphology graph from knowledge graph
+// ============================================================================
+/**
+ * Build a graphology graph containing only symbol nodes and CALLS edges
+ * This is what the Leiden algorithm will cluster
+ */
+const buildGraphologyGraph = (knowledgeGraph) => {
+    // Use undirected graph for Leiden - it looks at edge density, not direction
+    const graph = new Graph({ type: 'undirected', allowSelfLoops: false });
+    // Symbol types that should be clustered
+    const symbolTypes = new Set(['Function', 'Class', 'Method', 'Interface']);
+    // Add symbol nodes
+    knowledgeGraph.nodes.forEach(node => {
+        if (symbolTypes.has(node.label)) {
+            graph.addNode(node.id, {
+                name: node.properties.name,
+                filePath: node.properties.filePath,
+                type: node.label,
+            });
+        }
+    });
+    // Add CALLS edges (primary clustering signal)
+    // We can also include EXTENDS/IMPLEMENTS for OOP clustering
+    const clusteringRelTypes = new Set(['CALLS', 'EXTENDS', 'IMPLEMENTS']);
+    knowledgeGraph.relationships.forEach(rel => {
+        if (clusteringRelTypes.has(rel.type)) {
+            // Only add edge if both nodes exist in our symbol graph
+            // Also skip self-loops (recursive calls) - not allowed in undirected graph
+            if (graph.hasNode(rel.sourceId) && graph.hasNode(rel.targetId) && rel.sourceId !== rel.targetId) {
+                // Avoid duplicate edges
+                if (!graph.hasEdge(rel.sourceId, rel.targetId)) {
+                    graph.addEdge(rel.sourceId, rel.targetId);
+                }
+            }
+        }
+    });
+    return graph;
+};
+// ============================================================================
+// HELPER: Create community nodes with heuristic labels
+// ============================================================================
+/**
+ * Create Community nodes with auto-generated labels based on member file paths
+ */
+const createCommunityNodes = (communities, communityCount, graph, knowledgeGraph) => {
+    // Group node IDs by community
+    const communityMembers = new Map();
+    Object.entries(communities).forEach(([nodeId, commNum]) => {
+        if (!communityMembers.has(commNum)) {
+            communityMembers.set(commNum, []);
+        }
+        communityMembers.get(commNum).push(nodeId);
+    });
+    // Build node lookup for file paths
+    const nodePathMap = new Map();
+    knowledgeGraph.nodes.forEach(node => {
+        if (node.properties.filePath) {
+            nodePathMap.set(node.id, node.properties.filePath);
+        }
+    });
+    // Create community nodes - SKIP SINGLETONS (isolated nodes)
+    const communityNodes = [];
+    communityMembers.forEach((memberIds, commNum) => {
+        // Skip singleton communities - they're just isolated nodes
+        if (memberIds.length < 2)
+            return;
+        const heuristicLabel = generateHeuristicLabel(memberIds, nodePathMap, graph, commNum);
+        communityNodes.push({
+            id: `comm_${commNum}`,
+            label: heuristicLabel,
+            heuristicLabel,
+            cohesion: calculateCohesion(memberIds, graph),
+            symbolCount: memberIds.length,
+        });
+    });
+    // Sort by size descending
+    communityNodes.sort((a, b) => b.symbolCount - a.symbolCount);
+    return communityNodes;
+};
+// ============================================================================
+// HELPER: Generate heuristic label from folder patterns
+// ============================================================================
+/**
+ * Generate a human-readable label from the most common folder name in the community
+ */
+const generateHeuristicLabel = (memberIds, nodePathMap, graph, commNum) => {
+    // Collect folder names from file paths
+    const folderCounts = new Map();
+    memberIds.forEach(nodeId => {
+        const filePath = nodePathMap.get(nodeId) || '';
+        const parts = filePath.split('/').filter(Boolean);
+        // Get the most specific folder (parent directory)
+        if (parts.length >= 2) {
+            const folder = parts[parts.length - 2];
+            // Skip generic folder names
+            if (!['src', 'lib', 'core', 'utils', 'common', 'shared', 'helpers'].includes(folder.toLowerCase())) {
+                folderCounts.set(folder, (folderCounts.get(folder) || 0) + 1);
+            }
+        }
+    });
+    // Find most common folder
+    let maxCount = 0;
+    let bestFolder = '';
+    folderCounts.forEach((count, folder) => {
+        if (count > maxCount) {
+            maxCount = count;
+            bestFolder = folder;
+        }
+    });
+    if (bestFolder) {
+        // Capitalize first letter
+        return bestFolder.charAt(0).toUpperCase() + bestFolder.slice(1);
+    }
+    // Fallback: use function names to detect patterns
+    const names = [];
+    memberIds.forEach(nodeId => {
+        const name = graph.getNodeAttribute(nodeId, 'name');
+        if (name)
+            names.push(name);
+    });
+    // Look for common prefixes
+    if (names.length > 2) {
+        const commonPrefix = findCommonPrefix(names);
+        if (commonPrefix.length > 2) {
+            return commonPrefix.charAt(0).toUpperCase() + commonPrefix.slice(1);
+        }
+    }
+    // Last resort: generic name with community ID for uniqueness
+    return `Cluster_${commNum}`;
+};
+/**
+ * Find common prefix among strings
+ */
+const findCommonPrefix = (strings) => {
+    if (strings.length === 0)
+        return '';
+    const sorted = strings.slice().sort();
+    const first = sorted[0];
+    const last = sorted[sorted.length - 1];
+    let i = 0;
+    while (i < first.length && first[i] === last[i]) {
+        i++;
+    }
+    return first.substring(0, i);
+};
+// ============================================================================
+// HELPER: Calculate community cohesion
+// ============================================================================
+/**
+ * Calculate cohesion score (0-1) based on internal edge density
+ * Higher cohesion = more internal connections relative to size
+ */
+const calculateCohesion = (memberIds, graph) => {
+    if (memberIds.length <= 1)
+        return 1.0;
+    const memberSet = new Set(memberIds);
+    let internalEdges = 0;
+    // Count edges within the community
+    memberIds.forEach(nodeId => {
+        if (graph.hasNode(nodeId)) {
+            graph.forEachNeighbor(nodeId, neighbor => {
+                if (memberSet.has(neighbor)) {
+                    internalEdges++;
+                }
+            });
+        }
+    });
+    // Each edge is counted twice (once from each end), so divide by 2
+    internalEdges = internalEdges / 2;
+    // Maximum possible internal edges for n nodes: n*(n-1)/2
+    const maxPossibleEdges = (memberIds.length * (memberIds.length - 1)) / 2;
+    if (maxPossibleEdges === 0)
+        return 1.0;
+    return Math.min(1.0, internalEdges / maxPossibleEdges);
+};

package/dist/core/ingestion/entry-point-scoring.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Entry Point Scoring
+ *
+ * Calculates entry point scores for process detection based on:
+ * 1. Call ratio (existing algorithm - callees / (callers + 1))
+ * 2. Export status (exported functions get higher priority)
+ * 3. Name patterns (functions matching entry point patterns like handle*, on*, *Controller)
+ * 4. Framework detection (path-based detection for Next.js, Express, Django, etc.)
+ *
+ * This module is language-agnostic - language-specific patterns are defined per language.
+ */
+export interface EntryPointScoreResult {
+    score: number;
+    reasons: string[];
+}
+/**
+ * Calculate an entry point score for a function/method
+ *
+ * Higher scores indicate better entry point candidates.
+ * Score = baseScore × exportMultiplier × nameMultiplier
+ *
+ * @param name - Function/method name
+ * @param language - Programming language
+ * @param isExported - Whether the function is exported/public
+ * @param callerCount - Number of functions that call this function
+ * @param calleeCount - Number of functions this function calls
+ * @returns Score and array of reasons explaining the score
+ */
+export declare function calculateEntryPointScore(name: string, language: string, isExported: boolean, callerCount: number, calleeCount: number, filePath?: string): EntryPointScoreResult;
+/**
+ * Check if a file path is a test file (should be excluded from entry points)
+ * Covers common test file patterns across all supported languages
+ */
+export declare function isTestFile(filePath: string): boolean;
+/**
+ * Check if a file path is likely a utility/helper file
+ * These might still have entry points but should be lower priority
+ */
+export declare function isUtilityFile(filePath: string): boolean;