@zuvia-software-solutions/code-mapper 1.4.0

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

@@ -0,0 +1,40 @@
+/** @file call-routing.ts @description Per-language call routing dispatch, primarily for Ruby where imports, heritage, and property definitions are expressed as method calls */
+import { SupportedLanguages } from '../../config/supported-languages.js';
+export type CallRoutingResult = RubyCallRouting | null;
+export type CallRouter = (calledName: string, callNode: any) => CallRoutingResult;
+export declare const callRouters: Record<SupportedLanguages, CallRouter>;
+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;
+}
+/**
+ * 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 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,97 @@
+// code-mapper/src/core/ingestion/call-routing.ts
+/** @file call-routing.ts @description Per-language call routing dispatch, primarily for Ruby where imports, heritage, and property definitions are expressed as method calls */
+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 = passthrough to 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;
+/**
+ * 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 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') {
+        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,
+                });
+            }
+        }
+        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,30 @@
+/** @file cluster-enricher.ts @description LLM-based enrichment for community clusters, generating semantic names, keywords, and descriptions */
+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 token-efficient) */
+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,151 @@
+// code-mapper/src/core/ingestion/cluster-enricher.ts
+/** @file cluster-enricher.ts @description LLM-based enrichment for community clusters, generating semantic names, keywords, and descriptions */
+const buildEnrichmentPrompt = (members, heuristicLabel) => {
+    // Limit to 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"}`;
+};
+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 to heuristic label if parsing fails
+        return {
+            name: fallbackLabel,
+            keywords: [],
+            description: '',
+        };
+    }
+};
+/**
+ * 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, fall back to 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 (~4 chars per token)
+            tokensUsed += prompt.length / 4 + response.length / 4;
+            const enrichment = parseEnrichmentResponse(response, community.heuristicLabel);
+            enrichments.set(community.id, enrichment);
+        }
+        catch (error) {
+            // On error, fall back to heuristic
+            console.warn(`Failed to enrich cluster ${community.id}:`, error);
+            enrichments.set(community.id, {
+                name: community.heuristicLabel,
+                keywords: [],
+                description: '',
+            });
+        }
+    }
+    return { enrichments, tokensUsed };
+};
+/** Enrich multiple clusters in a single LLM call (batch mode, more token-efficient) */
+export const enrichClustersBatch = async (communities, memberMap, llmClient, batchSize = 5, onProgress) => {
+    const enrichments = new Map();
+    let tokensUsed = 0;
+    // Process communities in batches
+    for (let i = 0; i < communities.length; i += batchSize) {
+        // Report batch 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 JSON 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);
+            // Fall back to heuristics for this batch
+            for (const community of batch) {
+                enrichments.set(community.id, {
+                    name: community.heuristicLabel,
+                    keywords: [],
+                    description: '',
+                });
+            }
+        }
+    }
+    // Fill in missing communities with heuristic labels
+    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,26 @@
+/** @file community-processor.ts @description Detects code communities using the Leiden algorithm on CALLS/EXTENDS/IMPLEMENTS edges, grouping symbols by functional area */
+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 the Leiden algorithm on CALLS/EXTENDS/IMPLEMENTS edges */
+export declare const processCommunities: (knowledgeGraph: KnowledgeGraph, onProgress?: (message: string, progress: number) => void) => Promise<CommunityDetectionResult>;

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

@@ -0,0 +1,272 @@
+// code-mapper/src/core/ingestion/community-processor.ts
+/** @file community-processor.ts @description Detects code communities using the Leiden algorithm on CALLS/EXTENDS/IMPLEMENTS edges, grouping symbols by functional area */
+// Leiden algorithm is vendored from graphology (never published to npm);
+// loaded via createRequire for ESM compatibility
+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];
+};
+/** Detect communities in the knowledge graph using the Leiden algorithm on CALLS/EXTENDS/IMPLEMENTS edges */
+export const processCommunities = async (knowledgeGraph, onProgress) => {
+    onProgress?.('Building graph for community detection...', 0);
+    // Pre-check symbol count to determine large-graph mode
+    let symbolCount = 0;
+    knowledgeGraph.forEachNode(node => {
+        if (node.label === 'Function' || node.label === 'Class' || node.label === 'Method' || node.label === 'Interface') {
+            symbolCount++;
+        }
+    });
+    const isLarge = symbolCount > 10_000;
+    const graph = buildGraphologyGraph(knowledgeGraph, isLarge);
+    if (graph.order === 0) {
+        return {
+            communities: [],
+            memberships: [],
+            stats: { totalCommunities: 0, modularity: 0, nodesProcessed: 0 }
+        };
+    }
+    const nodeCount = graph.order;
+    const edgeCount = graph.size;
+    onProgress?.(`Running Leiden on ${nodeCount} nodes, ${edgeCount} edges${isLarge ? ` (filtered from ${symbolCount} symbols)` : ''}...`, 30);
+    // Large graphs: higher resolution + capped iterations (~95%+ modularity in 2-3 iterations)
+    // Timeout: abort after 60s for pathological graph structures
+    const LEIDEN_TIMEOUT_MS = 60_000;
+    let details;
+    try {
+        details = await Promise.race([
+            Promise.resolve(leiden.detailed(graph, {
+                resolution: isLarge ? 2.0 : 1.0,
+                maxIterations: isLarge ? 3 : 0,
+            })),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Leiden timeout')), LEIDEN_TIMEOUT_MS)),
+        ]);
+    }
+    catch (e) {
+        if (e.message === 'Leiden timeout') {
+            onProgress?.('Community detection timed out, using fallback...', 60);
+            // Fallback: assign all nodes to a single community
+            const communities = {};
+            graph.forEachNode((node) => { communities[node] = 0; });
+            details = { communities, count: 1, modularity: 0 };
+        }
+        else {
+            throw e;
+        }
+    }
+    onProgress?.(`Found ${details.count} communities...`, 60);
+    // Create community nodes with heuristic labels
+    const communityNodes = createCommunityNodes(details.communities, details.count, graph, knowledgeGraph);
+    onProgress?.('Creating membership edges...', 80);
+    // 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,
+        }
+    };
+};
+/**
+ * Build a graphology graph with only symbol nodes and clustering edges
+ *
+ * For large graphs (>10K symbols), filters low-confidence edges and degree-1 nodes
+ * to reduce noise and Leiden runtime
+ */
+const MIN_CONFIDENCE_LARGE = 0.5;
+const buildGraphologyGraph = (knowledgeGraph, isLarge) => {
+    const graph = new Graph({ type: 'undirected', allowSelfLoops: false });
+    const symbolTypes = new Set(['Function', 'Class', 'Method', 'Interface']);
+    const clusteringRelTypes = new Set(['CALLS', 'EXTENDS', 'IMPLEMENTS']);
+    const connectedNodes = new Set();
+    const nodeDegree = new Map();
+    knowledgeGraph.forEachRelationship(rel => {
+        if (!clusteringRelTypes.has(rel.type) || rel.sourceId === rel.targetId)
+            return;
+        if (isLarge && rel.confidence < MIN_CONFIDENCE_LARGE)
+            return;
+        connectedNodes.add(rel.sourceId);
+        connectedNodes.add(rel.targetId);
+        nodeDegree.set(rel.sourceId, (nodeDegree.get(rel.sourceId) || 0) + 1);
+        nodeDegree.set(rel.targetId, (nodeDegree.get(rel.targetId) || 0) + 1);
+    });
+    knowledgeGraph.forEachNode(node => {
+        if (!symbolTypes.has(node.label) || !connectedNodes.has(node.id))
+            return;
+        // For large graphs, skip degree-1 nodes (singletons that cost iteration time)
+        if (isLarge && (nodeDegree.get(node.id) || 0) < 2)
+            return;
+        graph.addNode(node.id, {
+            name: node.properties.name,
+            filePath: node.properties.filePath,
+            type: node.label,
+        });
+    });
+    knowledgeGraph.forEachRelationship(rel => {
+        if (!clusteringRelTypes.has(rel.type))
+            return;
+        if (isLarge && rel.confidence < MIN_CONFIDENCE_LARGE)
+            return;
+        if (graph.hasNode(rel.sourceId) && graph.hasNode(rel.targetId) && rel.sourceId !== rel.targetId) {
+            if (!graph.hasEdge(rel.sourceId, rel.targetId)) {
+                graph.addEdge(rel.sourceId, rel.targetId);
+            }
+        }
+    });
+    return graph;
+};
+/** Create Community nodes with auto-generated labels based on member file paths */
+const createCommunityNodes = (communities, communityCount, graph, knowledgeGraph) => {
+    // Group node IDs by community number
+    const communityMembers = new Map();
+    Object.entries(communities).forEach(([nodeId, commNum]) => {
+        if (!communityMembers.has(commNum)) {
+            communityMembers.set(commNum, []);
+        }
+        communityMembers.get(commNum).push(nodeId);
+    });
+    // Build node -> file path lookup
+    const nodePathMap = new Map();
+    for (const node of knowledgeGraph.iterNodes()) {
+        if (node.properties.filePath) {
+            nodePathMap.set(node.id, node.properties.filePath);
+        }
+    }
+    // Create community nodes, skip singletons
+    const communityNodes = [];
+    communityMembers.forEach((memberIds, commNum) => {
+        // Skip singleton communities
+        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 member count descending
+    communityNodes.sort((a, b) => b.symbolCount - a.symbolCount);
+    return communityNodes;
+};
+/** Generate a human-readable label from the most common folder name in the community */
+const generateHeuristicLabel = (memberIds, nodePathMap, graph, commNum) => {
+    // Count folder occurrences from member file paths
+    const folderCounts = new Map();
+    memberIds.forEach(nodeId => {
+        const filePath = nodePathMap.get(nodeId) || '';
+        const parts = filePath.split('/').filter(Boolean);
+        // Use parent directory as the most specific folder
+        if (parts.length >= 2) {
+            const folder = parts[parts.length - 2];
+            // Skip generic folders
+            if (!['src', 'lib', 'core', 'utils', 'common', 'shared', 'helpers'].includes(folder.toLowerCase())) {
+                folderCounts.set(folder, (folderCounts.get(folder) || 0) + 1);
+            }
+        }
+    });
+    // Pick the most common folder
+    let maxCount = 0;
+    let bestFolder = '';
+    folderCounts.forEach((count, folder) => {
+        if (count > maxCount) {
+            maxCount = count;
+            bestFolder = folder;
+        }
+    });
+    if (bestFolder) {
+        // Capitalize and return
+        return bestFolder.charAt(0).toUpperCase() + bestFolder.slice(1);
+    }
+    // Fallback: detect common prefix in function names
+    const names = [];
+    memberIds.forEach(nodeId => {
+        const name = graph.getNodeAttribute(nodeId, 'name');
+        if (name)
+            names.push(name);
+    });
+    // Use common prefix if long enough
+    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
+    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);
+};
+/** Estimate cohesion score (0-1) based on internal edge density, sampling for large communities */
+const calculateCohesion = (memberIds, graph) => {
+    if (memberIds.length <= 1)
+        return 1.0;
+    const memberSet = new Set(memberIds);
+    // Sample up to 50 members to avoid O(N^2) cost
+    const SAMPLE_SIZE = 50;
+    const sample = memberIds.length <= SAMPLE_SIZE
+        ? memberIds
+        : memberIds.slice(0, SAMPLE_SIZE);
+    let internalEdges = 0;
+    let totalEdges = 0;
+    for (const nodeId of sample) {
+        if (!graph.hasNode(nodeId))
+            continue;
+        graph.forEachNeighbor(nodeId, (neighbor) => {
+            totalEdges++;
+            if (memberSet.has(neighbor)) {
+                internalEdges++;
+            }
+        });
+    }
+    // Cohesion = fraction of edges that are internal
+    if (totalEdges === 0)
+        return 1.0;
+    return Math.min(1.0, internalEdges / totalEdges);
+};

package/dist/core/ingestion/constants.d.ts

@@ -0,0 +1,5 @@
+/** @file constants.ts @description Tree-sitter parsing buffer size constants and adaptive sizing */
+export declare const TREE_SITTER_BUFFER_SIZE: number;
+export declare const TREE_SITTER_MAX_BUFFER: number;
+/** Compute adaptive buffer size: 2x file size, clamped between 512 KB and 32 MB */
+export declare const getTreeSitterBufferSize: (contentLength: number) => number;

package/dist/core/ingestion/constants.js

@@ -0,0 +1,8 @@
+// code-mapper/src/core/ingestion/constants.ts
+/** @file constants.ts @description Tree-sitter parsing buffer size constants and adaptive sizing */
+// Default minimum buffer size for tree-sitter parsing (512 KB)
+export const TREE_SITTER_BUFFER_SIZE = 512 * 1024;
+// Maximum buffer size cap (32 MB), also the file-size skip threshold
+export const TREE_SITTER_MAX_BUFFER = 32 * 1024 * 1024;
+/** Compute adaptive buffer size: 2x file size, clamped between 512 KB and 32 MB */
+export const getTreeSitterBufferSize = (contentLength) => Math.min(Math.max(contentLength * 2, TREE_SITTER_BUFFER_SIZE), TREE_SITTER_MAX_BUFFER);

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

@@ -0,0 +1,23 @@
+/** @file entry-point-scoring.ts @description Scores functions as entry point candidates using call ratio, export status, name patterns, and framework detection */
+import { SupportedLanguages } from '../../config/supported-languages.js';
+export interface EntryPointScoreResult {
+    score: number;
+    reasons: string[];
+}
+/**
+ * Calculate an entry point score for a function/method
+ *
+ * Score = baseScore * exportMultiplier * nameMultiplier * frameworkMultiplier
+ *
+ * @param name - Function/method name
+ * @param language - Programming language
+ * @param isExported - Whether the function is exported/public
+ * @param callerCount - Number of callers
+ * @param calleeCount - Number of callees
+ * @returns Score and reasons explaining the score
+ */
+export declare function calculateEntryPointScore(name: string, language: SupportedLanguages, isExported: boolean, callerCount: number, calleeCount: number, filePath?: string): EntryPointScoreResult;
+/** Check if a file path is a test file (excluded from entry points) */
+export declare function isTestFile(filePath: string): boolean;
+/** Check if a file path is a utility/helper file (lower entry point priority) */
+export declare function isUtilityFile(filePath: string): boolean;