cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/core/ingestion/class-extractors/configs/csharp.js

@@ -0,0 +1,24 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/csharp.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.csharpClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+exports.csharpClassConfig = {
+    language: index_js_1.SupportedLanguages.CSharp,
+    typeDeclarationNodes: [
+        'class_declaration',
+        'interface_declaration',
+        'struct_declaration',
+        'enum_declaration',
+        'record_declaration',
+    ],
+    fileScopeNodeTypes: ['file_scoped_namespace_declaration'],
+    ancestorScopeNodeTypes: [
+        'namespace_declaration',
+        'class_declaration',
+        'interface_declaration',
+        'struct_declaration',
+        'enum_declaration',
+        'record_declaration',
+    ],
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/dart.js

@@ -0,0 +1,10 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/dart.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dartClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+exports.dartClassConfig = {
+    language: index_js_1.SupportedLanguages.Dart,
+    typeDeclarationNodes: ['class_definition', 'extension_declaration', 'enum_declaration'],
+    ancestorScopeNodeTypes: ['class_definition', 'extension_declaration', 'enum_declaration'],
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/go.js

@@ -0,0 +1,28 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/go.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.goClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+exports.goClassConfig = {
+    language: index_js_1.SupportedLanguages.Go,
+    // `type_spec`, not the enclosing `type_declaration` (#2837): one node per
+    // DECLARED TYPE, so a grouped `type ( A struct{…}; B struct{…} )` yields one
+    // each instead of one for the whole block. Every Go capture that reaches this
+    // extractor is anchored the same way, so the wrapper is never handed over —
+    // and accepting it would be worse than rejecting it, because picking one spec
+    // out of several with no reference point silently returns the FIRST type's
+    // name. A `null` here is loud; the wrong name is not.
+    typeDeclarationNodes: ['type_spec'],
+    fileScopeNodeTypes: ['package_clause'],
+    extractName(node) {
+        return node.childForFieldName('name')?.text;
+    },
+    extractType(node) {
+        const typeNode = node.childForFieldName('type');
+        if (typeNode?.type === 'struct_type')
+            return 'Struct';
+        if (typeNode?.type === 'interface_type')
+            return 'Interface';
+        return undefined;
+    },
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/jvm.js

@@ -0,0 +1,67 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/jvm.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kotlinClassConfig = exports.javaClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+const ast_helpers_js_1 = require("../../utils/ast-helpers.js");
+// ---------------------------------------------------------------------------
+// Java
+// ---------------------------------------------------------------------------
+exports.javaClassConfig = {
+    language: index_js_1.SupportedLanguages.Java,
+    typeDeclarationNodes: [
+        'class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+        'record_declaration',
+        // Anonymous class bodies (`new Runnable() { ... }`) — the matching
+        // JAVA_QUERIES pattern only captures `object_creation_expression`
+        // WITH a `class_body`, and `extractName` below returns undefined for
+        // any other shape, so plain `new Foo()` constructor calls never
+        // produce a Class node (#2550).
+        'object_creation_expression',
+        // Enum constant bodies (`enum E { A { ... } }`) — javac's other
+        // anonymous shape, named E$N by the same authority (#2555).
+        'enum_constant',
+    ],
+    fileScopeNodeTypes: ['package_declaration'],
+    ancestorScopeNodeTypes: [
+        'class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+        'record_declaration',
+    ],
+    extractName(node) {
+        return (0, ast_helpers_js_1.synthesizeJavaTypeIdentity)(node)?.name;
+    },
+    extractType(node) {
+        return (0, ast_helpers_js_1.synthesizeJavaTypeIdentity)(node)?.label;
+    },
+    // An anonymous body whose name CANNOT be synthesized must not become a
+    // Class node at all. Without this skip, `extract()`'s
+    // `extractTypeNameFromNode` fallback fabricates a name — the CONSTRUCTED
+    // type for `new Runnable() { ... }` (phantom `Class:...:Runnable`,
+    // empirically caught in review) or the constant's own identifier for an
+    // `enum_constant` (`Class:...:A`).
+    shouldSkipClassCapture({ definitionNode }) {
+        return (definitionNode !== null &&
+            definitionNode !== undefined &&
+            (definitionNode.type === 'object_creation_expression' ||
+                definitionNode.type === 'enum_constant') &&
+            (0, ast_helpers_js_1.synthesizeJavaTypeIdentity)(definitionNode) === undefined);
+    },
+};
+// ---------------------------------------------------------------------------
+// Kotlin
+// ---------------------------------------------------------------------------
+exports.kotlinClassConfig = {
+    language: index_js_1.SupportedLanguages.Kotlin,
+    typeDeclarationNodes: ['class_declaration', 'object_declaration', 'companion_object'],
+    fileScopeNodeTypes: ['package_header'],
+    ancestorScopeNodeTypes: ['class_declaration', 'object_declaration', 'companion_object'],
+    extractType(node) {
+        if (node.type !== 'class_declaration')
+            return undefined;
+        return node.children.some((child) => child?.text === 'interface') ? 'Interface' : 'Class';
+    },
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/php.js

@@ -0,0 +1,10 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/php.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.phpClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+exports.phpClassConfig = {
+    language: index_js_1.SupportedLanguages.PHP,
+    typeDeclarationNodes: ['class_declaration', 'interface_declaration', 'enum_declaration'],
+    ancestorScopeNodeTypes: ['namespace_definition'],
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/python.js

@@ -0,0 +1,10 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/python.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pythonClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+exports.pythonClassConfig = {
+    language: index_js_1.SupportedLanguages.Python,
+    typeDeclarationNodes: ['class_definition'],
+    ancestorScopeNodeTypes: ['class_definition'],
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/ruby.js

@@ -0,0 +1,13 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/ruby.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rubyClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+exports.rubyClassConfig = {
+    language: index_js_1.SupportedLanguages.Ruby,
+    typeDeclarationNodes: ['class'],
+    ancestorScopeNodeTypes: ['module', 'class'],
+    // #1978: key nested-type nodes by their fully-qualified path (Outer.Inner) so
+    // same-tail classes nested under different modules stay distinct.
+    qualifiedNodeId: true,
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/rust.js

@@ -0,0 +1,10 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/rust.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rustClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+exports.rustClassConfig = {
+    language: index_js_1.SupportedLanguages.Rust,
+    typeDeclarationNodes: ['struct_item', 'enum_item'],
+    ancestorScopeNodeTypes: ['mod_item', 'struct_item', 'enum_item'],
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/swift.js

@@ -0,0 +1,21 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/swift.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.swiftClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+exports.swiftClassConfig = {
+    language: index_js_1.SupportedLanguages.Swift,
+    typeDeclarationNodes: ['class_declaration', 'protocol_declaration'],
+    ancestorScopeNodeTypes: ['class_declaration', 'protocol_declaration'],
+    extractType(node) {
+        if (node.type === 'protocol_declaration')
+            return 'Interface';
+        if (node.type !== 'class_declaration')
+            return undefined;
+        if (node.children.some((child) => child?.text === 'struct'))
+            return 'Struct';
+        if (node.children.some((child) => child?.text === 'enum'))
+            return 'Enum';
+        return 'Class';
+    },
+};

package/dist/core/code/engine/core/ingestion/class-extractors/configs/typescript-javascript.js

@@ -0,0 +1,31 @@
+"use strict";
+// cgraph/src/core/ingestion/class-extractors/configs/typescript-javascript.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vueClassConfig = exports.javascriptClassConfig = exports.typescriptClassConfig = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+const shared = {
+    typeDeclarationNodes: [
+        'class_declaration',
+        'abstract_class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+    ],
+    ancestorScopeNodeTypes: [
+        'class_declaration',
+        'abstract_class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+    ],
+};
+exports.typescriptClassConfig = {
+    ...shared,
+    language: index_js_1.SupportedLanguages.TypeScript,
+};
+exports.javascriptClassConfig = {
+    ...shared,
+    language: index_js_1.SupportedLanguages.JavaScript,
+};
+exports.vueClassConfig = {
+    ...shared,
+    language: index_js_1.SupportedLanguages.Vue,
+};

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

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClassExtractor = createClassExtractor;
+const qualified_name_js_1 = require("../utils/qualified-name.js");
+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 extractScopeSegmentsFromNode = (scopeNode, scopeNameNodeTypes) => {
+    const nameNode = scopeNode.childForFieldName?.('name') ??
+        scopeNode.namedChildren?.find((child) => scopeNameNodeTypes.has(child.type));
+    return nameNode ? (0, qualified_name_js_1.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);
+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(),
+            ...(0, qualified_name_js_1.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;
+        const templateArguments = config.extractTemplateArguments?.(node);
+        return {
+            name,
+            type,
+            qualifiedName: buildQualifiedName(node, name) || name,
+            ...(templateArguments !== undefined ? { templateArguments } : {}),
+        };
+    };
+    return {
+        language: config.language,
+        qualifiedNodeId: config.qualifiedNodeId ?? false,
+        isTypeDeclaration(node) {
+            return typeDeclarationSet.has(node.type);
+        },
+        extract,
+        extractQualifiedName(node, simpleName) {
+            return extract(node, { name: simpleName })?.qualifiedName ?? null;
+        },
+        // #1991: qualify a non-typeDeclaration scope node (e.g. a Ruby `module` → Trait)
+        // by the same ancestor-scope walk the node-id path uses, so two same-tail nested
+        // mixin modules stay distinct. extract()/extractQualifiedName cannot be reused —
+        // they bail on non-typeDeclarations (a module is not in typeDeclarationNodes).
+        qualifyScopeName(node, simpleName) {
+            return buildQualifiedName(node, simpleName);
+        },
+        shouldSkipClassCapture(context) {
+            return config.shouldSkipClassCapture?.(context) ?? false;
+        },
+        extractTemplateArgumentsFromCapture(context) {
+            return config.extractTemplateArgumentsFromCapture?.(context);
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * Cluster Enricher
+ *
+ * LLM-based enrichment for community clusters.
+ * Generates semantic names, keywords, and descriptions using an LLM.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichClustersBatch = exports.enrichClusters = void 0;
+const logger_js_1 = require("../logger.js");
+// ============================================================================
+// 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
+ */
+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
+            logger_js_1.logger.warn({ error }, `Failed to enrich cluster ${community.id}:`);
+            enrichments.set(community.id, {
+                name: community.heuristicLabel,
+                keywords: [],
+                description: '',
+            });
+        }
+    }
+    return { enrichments, tokensUsed };
+};
+exports.enrichClusters = enrichClusters;
+// ============================================================================
+// BATCH ENRICHMENT (more efficient)
+// ============================================================================
+/**
+ * Enrich multiple clusters in a single LLM call (batch mode)
+ * More efficient for token usage but requires larger context window
+ */
+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) {
+            logger_js_1.logger.warn({ error }, 'Batch enrichment failed, falling back to heuristics:');
+            // 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 };
+};
+exports.enrichClustersBatch = enrichClustersBatch;