@duytransipher/gitnexus 1.4.6-sipher.0

package/dist/core/ingestion/call-routing.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared Ruby call routing logic.
+ *
+ * Ruby expresses imports, heritage (mixins), and property definitions as
+ * method calls rather than syntax-level constructs. This module provides a
+ * routing function used by the CLI call-processor, CLI parse-worker, and
+ * the web call-processor so that the classification logic lives in one place.
+ *
+ * NOTE: This file is intentionally duplicated in gitnexus-web/ because the
+ * two packages have separate build targets (Node native vs WASM/browser).
+ * Keep both copies in sync until a shared package is introduced.
+ */
+/** null = this call was not routed; fall through to default call handling */
+export type CallRoutingResult = RubyCallRouting | null;
+export type CallRouter = (calledName: string, callNode: any) => CallRoutingResult;
+/** Per-language call routing. noRouting = no special routing (normal call processing) */
+export declare const callRouters: {
+    javascript: CallRouter;
+    typescript: CallRouter;
+    python: CallRouter;
+    java: CallRouter;
+    kotlin: CallRouter;
+    go: CallRouter;
+    rust: CallRouter;
+    csharp: CallRouter;
+    php: CallRouter;
+    swift: CallRouter;
+    cpp: CallRouter;
+    c: CallRouter;
+    ruby: typeof routeRubyCall;
+};
+export type RubyCallRouting = {
+    kind: 'import';
+    importPath: string;
+    isRelative: boolean;
+} | {
+    kind: 'heritage';
+    items: RubyHeritageItem[];
+} | {
+    kind: 'properties';
+    items: RubyPropertyItem[];
+} | {
+    kind: 'call';
+} | {
+    kind: 'skip';
+};
+export interface RubyHeritageItem {
+    enclosingClass: string;
+    mixinName: string;
+    heritageKind: 'include' | 'extend' | 'prepend';
+}
+export type RubyAccessorType = 'attr_accessor' | 'attr_reader' | 'attr_writer';
+export interface RubyPropertyItem {
+    propName: string;
+    accessorType: RubyAccessorType;
+    startLine: number;
+    endLine: number;
+    /** YARD @return [Type] annotation preceding the attr_accessor call */
+    declaredType?: string;
+}
+/**
+ * Classify a Ruby call node and extract its semantic payload.
+ *
+ * @param calledName - The method name (e.g. 'require', 'include', 'attr_accessor')
+ * @param callNode   - The tree-sitter `call` AST node
+ * @returns A discriminated union describing the call's semantic role
+ */
+export declare function routeRubyCall(calledName: string, callNode: any): RubyCallRouting;

package/dist/core/ingestion/call-routing.js

@@ -0,0 +1,129 @@
+/**
+ * Shared Ruby call routing logic.
+ *
+ * Ruby expresses imports, heritage (mixins), and property definitions as
+ * method calls rather than syntax-level constructs. This module provides a
+ * routing function used by the CLI call-processor, CLI parse-worker, and
+ * the web call-processor so that the classification logic lives in one place.
+ *
+ * NOTE: This file is intentionally duplicated in gitnexus-web/ because the
+ * two packages have separate build targets (Node native vs WASM/browser).
+ * Keep both copies in sync until a shared package is introduced.
+ */
+import { SupportedLanguages } from '../../config/supported-languages.js';
+/** No-op router: returns null for every call (passthrough to normal processing) */
+const noRouting = () => null;
+/** Per-language call routing. noRouting = no special routing (normal call processing) */
+export const callRouters = {
+    [SupportedLanguages.JavaScript]: noRouting,
+    [SupportedLanguages.TypeScript]: noRouting,
+    [SupportedLanguages.Python]: noRouting,
+    [SupportedLanguages.Java]: noRouting,
+    [SupportedLanguages.Kotlin]: noRouting,
+    [SupportedLanguages.Go]: noRouting,
+    [SupportedLanguages.Rust]: noRouting,
+    [SupportedLanguages.CSharp]: noRouting,
+    [SupportedLanguages.PHP]: noRouting,
+    [SupportedLanguages.Swift]: noRouting,
+    [SupportedLanguages.CPlusPlus]: noRouting,
+    [SupportedLanguages.C]: noRouting,
+    [SupportedLanguages.Ruby]: routeRubyCall,
+};
+// ── Pre-allocated singletons for common return values ────────────────────────
+const CALL_RESULT = { kind: 'call' };
+const SKIP_RESULT = { kind: 'skip' };
+/** Max depth for parent-walking loops to prevent pathological AST traversals */
+const MAX_PARENT_DEPTH = 50;
+// ── Routing function ────────────────────────────────────────────────────────
+/**
+ * Classify a Ruby call node and extract its semantic payload.
+ *
+ * @param calledName - The method name (e.g. 'require', 'include', 'attr_accessor')
+ * @param callNode   - The tree-sitter `call` AST node
+ * @returns A discriminated union describing the call's semantic role
+ */
+export function routeRubyCall(calledName, callNode) {
+    // ── require / require_relative → import ─────────────────────────────────
+    if (calledName === 'require' || calledName === 'require_relative') {
+        const argList = callNode.childForFieldName?.('arguments');
+        const stringNode = argList?.children?.find((c) => c.type === 'string');
+        const contentNode = stringNode?.children?.find((c) => c.type === 'string_content');
+        if (!contentNode)
+            return SKIP_RESULT;
+        let importPath = contentNode.text;
+        // Validate: reject null bytes, control chars, excessively long paths
+        if (!importPath || importPath.length > 1024 || /[\x00-\x1f]/.test(importPath)) {
+            return SKIP_RESULT;
+        }
+        const isRelative = calledName === 'require_relative';
+        if (isRelative && !importPath.startsWith('.')) {
+            importPath = './' + importPath;
+        }
+        return { kind: 'import', importPath, isRelative };
+    }
+    // ── include / extend / prepend → heritage (mixin) ──────────────────────
+    if (calledName === 'include' || calledName === 'extend' || calledName === 'prepend') {
+        let enclosingClass = null;
+        let current = callNode.parent;
+        let depth = 0;
+        while (current && ++depth <= MAX_PARENT_DEPTH) {
+            if (current.type === 'class' || current.type === 'module') {
+                const nameNode = current.childForFieldName?.('name');
+                if (nameNode) {
+                    enclosingClass = nameNode.text;
+                    break;
+                }
+            }
+            current = current.parent;
+        }
+        if (!enclosingClass)
+            return SKIP_RESULT;
+        const items = [];
+        const argList = callNode.childForFieldName?.('arguments');
+        for (const arg of (argList?.children ?? [])) {
+            if (arg.type === 'constant' || arg.type === 'scope_resolution') {
+                items.push({ enclosingClass, mixinName: arg.text, heritageKind: calledName });
+            }
+        }
+        return items.length > 0 ? { kind: 'heritage', items } : SKIP_RESULT;
+    }
+    // ── attr_accessor / attr_reader / attr_writer → property definitions ───
+    if (calledName === 'attr_accessor' || calledName === 'attr_reader' || calledName === 'attr_writer') {
+        // Extract YARD @return [Type] from preceding comment (e.g. `# @return [Address]`)
+        let yardType;
+        let sibling = callNode.previousSibling;
+        while (sibling) {
+            if (sibling.type === 'comment') {
+                const match = /@return\s+\[([^\]]+)\]/.exec(sibling.text);
+                if (match) {
+                    const raw = match[1].trim();
+                    // Extract simple type name: "User", "Array<User>" → "User"
+                    const simple = raw.match(/^([A-Z]\w*)/);
+                    if (simple)
+                        yardType = simple[1];
+                    break;
+                }
+            }
+            else if (sibling.isNamed) {
+                break; // stop at non-comment named sibling
+            }
+            sibling = sibling.previousSibling;
+        }
+        const items = [];
+        const argList = callNode.childForFieldName?.('arguments');
+        for (const arg of (argList?.children ?? [])) {
+            if (arg.type === 'simple_symbol') {
+                items.push({
+                    propName: arg.text.startsWith(':') ? arg.text.slice(1) : arg.text,
+                    accessorType: calledName,
+                    startLine: arg.startPosition.row,
+                    endLine: arg.endPosition.row,
+                    ...(yardType ? { declaredType: yardType } : {}),
+                });
+            }
+        }
+        return items.length > 0 ? { kind: 'properties', items } : SKIP_RESULT;
+    }
+    // ── Everything else → regular call ─────────────────────────────────────
+    return CALL_RESULT;
+}

package/dist/core/ingestion/cluster-enricher.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cluster Enricher
+ *
+ * LLM-based enrichment for community clusters.
+ * Generates semantic names, keywords, and descriptions using an LLM.
+ */
+import { CommunityNode } from './community-processor.js';
+export interface ClusterEnrichment {
+    name: string;
+    keywords: string[];
+    description: string;
+}
+export interface EnrichmentResult {
+    enrichments: Map<string, ClusterEnrichment>;
+    tokensUsed: number;
+}
+export interface LLMClient {
+    generate: (prompt: string) => Promise<string>;
+}
+export interface ClusterMemberInfo {
+    name: string;
+    filePath: string;
+    type: string;
+}
+/**
+ * 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 declare const enrichClusters: (communities: CommunityNode[], memberMap: Map<string, ClusterMemberInfo[]>, llmClient: LLMClient, onProgress?: (current: number, total: number) => void) => Promise<EnrichmentResult>;
+/**
+ * Enrich multiple clusters in a single LLM call (batch mode)
+ * More efficient for token usage but requires larger context window
+ */
+export declare const enrichClustersBatch: (communities: CommunityNode[], memberMap: Map<string, ClusterMemberInfo[]>, llmClient: LLMClient, batchSize?: number, onProgress?: (current: number, total: number) => void) => Promise<EnrichmentResult>;

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>;