@codragraph/cli 1.6.2

package/dist/core/ingestion/class-extractors/generic.js

@@ -0,0 +1,135 @@
+const DEFAULT_SCOPE_NAME_NODE_TYPES = new Set([
+    'nested_namespace_specifier',
+    'scoped_identifier',
+    'scoped_type_identifier',
+    'qualified_name',
+    'namespace_name',
+    'namespace_identifier',
+    'package_identifier',
+    'type_identifier',
+    'identifier',
+    'name',
+    'constant',
+]);
+const DEFAULT_TYPE_NAME_NODE_TYPES = new Set([
+    'type_identifier',
+    'identifier',
+    'simple_identifier',
+    'namespace_identifier',
+    'constant',
+    'name',
+]);
+const DEFAULT_LABEL_BY_NODE_TYPE = {
+    class_declaration: 'Class',
+    abstract_class_declaration: 'Class',
+    interface_declaration: 'Interface',
+    struct_declaration: 'Struct',
+    record_declaration: 'Record',
+    enum_declaration: 'Enum',
+    class_definition: 'Class',
+    struct_specifier: 'Struct',
+    class_specifier: 'Class',
+    enum_specifier: 'Enum',
+    struct_item: 'Struct',
+    enum_item: 'Enum',
+    class: 'Class',
+    object_declaration: 'Class',
+    companion_object: 'Class',
+    protocol_declaration: 'Interface',
+    extension_declaration: 'Class',
+};
+const CLASS_LIKE_LABELS = new Set([
+    'Class',
+    'Struct',
+    'Interface',
+    'Enum',
+    'Record',
+]);
+const normalizeQualifiedName = (value) => value
+    .replace(/\s+/g, '')
+    .replace(/^::/, '')
+    .replace(/::/g, '.')
+    .replace(/\\/g, '.')
+    .replace(/\.+/g, '.')
+    .replace(/^\.+|\.+$/g, '');
+const splitQualifiedName = (value) => {
+    const normalized = normalizeQualifiedName(value);
+    return normalized ? normalized.split('.').filter(Boolean) : [];
+};
+const extractScopeSegmentsFromNode = (scopeNode, scopeNameNodeTypes) => {
+    const nameNode = scopeNode.childForFieldName?.('name') ??
+        scopeNode.namedChildren?.find((child) => scopeNameNodeTypes.has(child.type));
+    return nameNode ? splitQualifiedName(nameNode.text) : [];
+};
+const extractTypeNameFromNode = (node) => {
+    const nameField = node.childForFieldName?.('name');
+    if (nameField)
+        return nameField.text;
+    const nameChild = node.namedChildren?.find((child) => DEFAULT_TYPE_NAME_NODE_TYPES.has(child.type));
+    return nameChild?.text;
+};
+const isClassLikeLabel = (label) => label !== undefined && label !== null && CLASS_LIKE_LABELS.has(label);
+export function createClassExtractor(config) {
+    const typeDeclarationSet = new Set(config.typeDeclarationNodes);
+    const fileScopeSet = new Set(config.fileScopeNodeTypes ?? []);
+    const ancestorScopeSet = new Set(config.ancestorScopeNodeTypes ?? []);
+    const scopeNameNodeTypes = new Set([
+        ...DEFAULT_SCOPE_NAME_NODE_TYPES,
+        ...(config.scopeNameNodeTypes ?? []),
+    ]);
+    const buildQualifiedName = (node, simpleName) => {
+        let root = node;
+        while (root.parent)
+            root = root.parent;
+        const readScopeSegments = (scopeNode) => config.extractScopeSegments?.(scopeNode) ??
+            extractScopeSegmentsFromNode(scopeNode, scopeNameNodeTypes);
+        const fileScopeSegments = [];
+        for (const child of root.namedChildren ?? []) {
+            if (fileScopeSet.has(child.type)) {
+                fileScopeSegments.push(...readScopeSegments(child));
+            }
+        }
+        const ancestorScopes = [];
+        let current = node.parent;
+        while (current) {
+            if (ancestorScopeSet.has(current.type)) {
+                const segments = readScopeSegments(current);
+                if (segments.length > 0)
+                    ancestorScopes.push(segments);
+            }
+            current = current.parent;
+        }
+        return [
+            ...fileScopeSegments,
+            ...ancestorScopes.reverse().flat(),
+            ...splitQualifiedName(simpleName),
+        ]
+            .filter(Boolean)
+            .join('.');
+    };
+    const extract = (node, fallback) => {
+        if (!typeDeclarationSet.has(node.type))
+            return null;
+        const name = config.extractName?.(node) ?? extractTypeNameFromNode(node) ?? fallback?.name;
+        const type = config.extractType?.(node) ??
+            DEFAULT_LABEL_BY_NODE_TYPE[node.type] ??
+            (isClassLikeLabel(fallback?.type) ? fallback.type : undefined);
+        if (!name || !type)
+            return null;
+        return {
+            name,
+            type,
+            qualifiedName: buildQualifiedName(node, name) || name,
+        };
+    };
+    return {
+        language: config.language,
+        isTypeDeclaration(node) {
+            return typeDeclarationSet.has(node.type);
+        },
+        extract,
+        extractQualifiedName(node, simpleName) {
+            return extract(node, { name: simpleName })?.qualifiedName ?? null;
+        },
+    };
+}

package/dist/core/ingestion/class-types.d.ts

@@ -0,0 +1,34 @@
+import type { NodeLabel, SupportedLanguages } from '../../_shared/index.js';
+import type { SyntaxNode } from './utils/ast-helpers.js';
+export type ClassLikeNodeLabel = Extract<NodeLabel, 'Class' | 'Struct' | 'Interface' | 'Enum' | 'Record'>;
+export interface ExtractedClassSymbol {
+    name: string;
+    type: ClassLikeNodeLabel;
+    qualifiedName: string;
+}
+/**
+ * Cross-language qualified type names are normalized to dot-separated scope
+ * segments:
+ * - file/package scope contributes leading segments when the language has one
+ * - lexical namespace/module/type scope contributes enclosing segments
+ * - the simple type name is always the trailing segment
+ */
+export interface ClassExtractor {
+    language: SupportedLanguages;
+    isTypeDeclaration(node: SyntaxNode): boolean;
+    extract(node: SyntaxNode, fallback?: {
+        name?: string;
+        type?: NodeLabel | null;
+    }): ExtractedClassSymbol | null;
+    extractQualifiedName(node: SyntaxNode, simpleName: string): string | null;
+}
+export interface ClassExtractionConfig {
+    language: SupportedLanguages;
+    typeDeclarationNodes: string[];
+    fileScopeNodeTypes?: string[];
+    ancestorScopeNodeTypes?: string[];
+    scopeNameNodeTypes?: string[];
+    extractName?: (node: SyntaxNode) => string | undefined;
+    extractType?: (node: SyntaxNode) => ClassLikeNodeLabel | undefined;
+    extractScopeSegments?: (node: SyntaxNode) => string[] | null | undefined;
+}

package/dist/core/ingestion/class-types.js

@@ -0,0 +1 @@
+export {};

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,168 @@
+/**
+ * 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/cobol/cobol-copy-expander.d.ts

@@ -0,0 +1,57 @@
+/**
+ * COBOL COPY statement expansion engine.
+ *
+ * Expands COPY statements by inlining copybook content, applying REPLACING
+ * transformations (LEADING, TRAILING, EXACT), and handling nested copies
+ * with cycle detection.
+ *
+ * This is a preprocessing step that runs BEFORE extractCobolSymbolsWithRegex.
+ * The caller should run preprocessCobolSource first to clean patch markers.
+ *
+ * Supported syntax:
+ *   COPY CPSESP.
+ *   COPY "WORKGRID.CPY".
+ *   COPY CPSESP REPLACING LEADING "ESP-" BY "LK-ESP-"
+ *                         LEADING "KPSESPL" BY "LK-KPSESPL".
+ *   COPY ANAZI REPLACING "ANAZI-KEY" BY "LK-KEY".
+ */
+export interface CopyReplacing {
+    type: 'LEADING' | 'TRAILING' | 'EXACT';
+    from: string;
+    to: string;
+    isPseudotext?: boolean;
+}
+export interface CopyResolution {
+    copyTarget: string;
+    resolvedPath: string | null;
+    line: number;
+    replacing: CopyReplacing[];
+    library?: string;
+}
+export interface CopyExpansionResult {
+    expandedContent: string;
+    copyResolutions: CopyResolution[];
+}
+export declare const DEFAULT_MAX_DEPTH = 10;
+/**
+ * Parse REPLACING clause text into structured replacements.
+ *
+ * Input examples:
+ *   LEADING "ESP-" BY "LK-ESP-" LEADING "KPSESPL" BY "LK-KPSESPL"
+ *   "ANAZI-KEY" BY "LK-KEY"
+ *   TRAILING "-IN" BY "-OUT"
+ *   ==CUST-== BY ==WS-CUST-==
+ *   ==OLD-TEXT== BY ====
+ */
+export declare function parseReplacingClause(text: string): CopyReplacing[];
+/**
+ * Expand COBOL COPY statements by inlining copybook content.
+ *
+ * @param content     - Source COBOL content (after preprocessCobolSource)
+ * @param filePath    - Path of the source file (for diagnostics)
+ * @param resolveFile - Maps a COPY target name to a filesystem path, or null if not found
+ * @param readFile    - Reads file content by path, or null if unreadable
+ * @param maxDepth    - Maximum nesting depth for recursive expansion (default: 10)
+ * @returns Expanded content and resolution metadata
+ */
+export declare function expandCopies(content: string, filePath: string, resolveFile: (name: string) => string | null, readFile: (path: string) => string | null, maxDepth?: number): CopyExpansionResult;