cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/core/ingestion/pipeline-phases/rpc-edges.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Phase: rpcEdges
+ *
+ * Detects method-level cross-service RPC calls from custom annotations
+ * (e.g. @Center / @RCenter) defined in workspace config.
+ *
+ * Reads source file headers from disk to detect annotations on Interface
+ * nodes (the `content` property is not available during pipeline execution),
+ * then matches methods by serviceId + methodName across services.
+ *
+ * Single-side nodes (consumer without a provider, or provider without a
+ * consumer in the repo) are connected to synthetic ExternalService nodes
+ * so that impact analysis can trace external RPC dependencies.
+ *
+ * @deps    parse
+ * @reads   graph (Interface nodes, HAS_METHOD edges), filesystem
+ * @writes  graph (RCALLS edges, ExternalService nodes)
+ * @output  edges (RpcEdge[])
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rpcEdgesPhase = void 0;
+const workspace_config_js_1 = require("../workspace-config.js");
+const utils_js_1 = require("../../../lib/utils.js");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function buildAnnotationRegex(annotation) {
+    const escaped = annotation.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(escaped + '\\s*\\(\\s*(?:(?:value|)\\s*=\\s*)?["\']([^"\']+)["\']');
+}
+function extractServiceDir(filePath, services) {
+    const normalized = filePath.replace(/\\/g, '/');
+    for (const svc of services) {
+        const prefix = svc.replace(/\/+$/, '') + '/';
+        if (normalized.startsWith(prefix))
+            return svc.replace(/\/+$/, '');
+    }
+    return normalized.split('/')[0];
+}
+/** Read the first N lines of a source file to detect class-level annotations. */
+function readFileHeader(filePath, repoPath, maxLines = 50) {
+    try {
+        const full = (0, node_fs_1.readFileSync)((0, node_path_1.join)(repoPath, filePath), 'utf-8');
+        const lines = full.split('\n');
+        return lines.slice(0, maxLines).join('\n');
+    }
+    catch {
+        return '';
+    }
+}
+/** Ensure an ExternalService node exists for the given serviceId. Returns the node ID. */
+function ensureExternalServiceNode(graph, serviceId) {
+    const nodeId = (0, utils_js_1.generateId)('ExternalService', serviceId);
+    if (!graph.getNode(nodeId)) {
+        graph.addNode({
+            id: nodeId,
+            label: 'ExternalService',
+            properties: {
+                name: serviceId,
+                filePath: '',
+                description: `External RPC service: ${serviceId}`,
+            },
+        });
+    }
+    return nodeId;
+}
+exports.rpcEdgesPhase = {
+    name: 'rpcEdges',
+    deps: ['parse'],
+    async execute(ctx, _deps) {
+        const config = (0, workspace_config_js_1.loadWorkspaceConfig)(ctx.repoPath);
+        if (!config) {
+            return { edges: [], externalServiceNodes: 0, orphanConsumerEdges: 0, orphanProviderEdges: 0 };
+        }
+        const { provider, consumer } = config.annotations.rpc;
+        const providerRegex = buildAnnotationRegex(provider);
+        const consumerRegex = buildAnnotationRegex(consumer);
+        // Phase 1: Collect annotated Interface nodes
+        const providerInterfaces = [];
+        const consumerInterfaces = [];
+        ctx.graph.forEachNode((node) => {
+            if (node.label !== 'Interface')
+                return;
+            const filePath = node.properties?.filePath;
+            if (!filePath)
+                return;
+            const header = readFileHeader(filePath, ctx.repoPath);
+            if (!header)
+                return;
+            const providerMatch = header.match(providerRegex);
+            if (providerMatch) {
+                providerInterfaces.push({
+                    nodeId: node.id,
+                    serviceId: providerMatch[1],
+                    role: 'provider',
+                    serviceDir: extractServiceDir(filePath, config.services),
+                    interfaceName: node.properties?.name ?? '',
+                    methodIds: [],
+                });
+                return;
+            }
+            const consumerMatch = header.match(consumerRegex);
+            if (consumerMatch) {
+                consumerInterfaces.push({
+                    nodeId: node.id,
+                    serviceId: consumerMatch[1],
+                    role: 'consumer',
+                    serviceDir: extractServiceDir(filePath, config.services),
+                    interfaceName: node.properties?.name ?? '',
+                    methodIds: [],
+                });
+            }
+        });
+        // Phase 2: Build parent -> child methods map from HAS_METHOD edges
+        const methodsByParent = new Map();
+        ctx.graph.forEachRelationship((rel) => {
+            if (rel.type === 'HAS_METHOD') {
+                let list = methodsByParent.get(rel.sourceId);
+                if (!list) {
+                    list = [];
+                    methodsByParent.set(rel.sourceId, list);
+                }
+                const targetNode = ctx.graph.getNode(rel.targetId);
+                if (targetNode) {
+                    list.push({ id: targetNode.id, name: targetNode.properties?.name });
+                }
+            }
+        });
+        const methodNamesById = new Map();
+        for (const [, methods] of methodsByParent) {
+            for (const m of methods) {
+                methodNamesById.set(m.id, m.name);
+            }
+        }
+        for (const info of [...providerInterfaces, ...consumerInterfaces]) {
+            info.methodIds = (methodsByParent.get(info.nodeId) ?? []).map((m) => m.id);
+        }
+        // Phase 3: Index provider methods by (serviceId, methodName)
+        // Use array to avoid silent overwrites when multiple providers share
+        // the same (serviceId, methodName) pair.
+        const providerMethodsByService = new Map();
+        for (const info of providerInterfaces) {
+            let serviceMap = providerMethodsByService.get(info.serviceId);
+            if (!serviceMap) {
+                serviceMap = new Map();
+                providerMethodsByService.set(info.serviceId, serviceMap);
+            }
+            for (const methodId of info.methodIds) {
+                const methodName = methodNamesById.get(methodId);
+                if (methodName) {
+                    let arr = serviceMap.get(methodName);
+                    if (!arr) {
+                        arr = [];
+                        serviceMap.set(methodName, arr);
+                    }
+                    arr.push({ methodId, serviceDir: info.serviceDir });
+                }
+            }
+        }
+        // Phase 4: Match consumer methods → provider methods, create RCALLS edges
+        const edges = [];
+        const matchedConsumerMethods = new Set();
+        const matchedProviderMethods = new Set();
+        for (const info of consumerInterfaces) {
+            const serviceMap = providerMethodsByService.get(info.serviceId);
+            if (!serviceMap)
+                continue;
+            for (const consumerMethodId of info.methodIds) {
+                const methodName = methodNamesById.get(consumerMethodId);
+                if (!methodName)
+                    continue;
+                const providerEntries = serviceMap.get(methodName);
+                if (!providerEntries || providerEntries.length === 0)
+                    continue;
+                // Disambiguate: prefer cross-service, then interface name, else skip.
+                let providerEntry;
+                if (providerEntries.length === 1) {
+                    providerEntry = providerEntries[0];
+                }
+                else {
+                    // Step 1: prefer cross-service (consumer dir !== provider dir)
+                    const crossService = providerEntries.filter((p) => p.serviceDir !== info.serviceDir);
+                    if (crossService.length === 1) {
+                        providerEntry = crossService[0];
+                    }
+                    else if (crossService.length > 1) {
+                        // Step 2: exact interface name match (reverse-lookup by methodId —
+                        // a serviceDir may host multiple provider interfaces, so finding
+                        // by serviceDir alone returns the wrong interface).
+                        const nameMatch = crossService.filter((p) => {
+                            const providerIface = providerInterfaces.find((pi) => pi.methodIds.includes(p.methodId));
+                            return providerIface?.interfaceName === info.interfaceName;
+                        });
+                        if (nameMatch.length === 1) {
+                            providerEntry = nameMatch[0];
+                        }
+                        // Step 3: else skip — no edge created
+                    }
+                    // Same-service only: try interface name match
+                    if (!providerEntry && crossService.length === 0) {
+                        const nameMatch = providerEntries.filter((p) => {
+                            const providerIface = providerInterfaces.find((pi) => pi.methodIds.includes(p.methodId));
+                            return providerIface?.interfaceName === info.interfaceName;
+                        });
+                        if (nameMatch.length === 1) {
+                            providerEntry = nameMatch[0];
+                        }
+                    }
+                }
+                if (!providerEntry)
+                    continue;
+                edges.push({
+                    consumerMethodId,
+                    providerMethodId: providerEntry.methodId,
+                    serviceId: info.serviceId,
+                    consumerService: info.serviceDir,
+                    providerService: providerEntry.serviceDir,
+                });
+                ctx.graph.addRelationship({
+                    id: (0, utils_js_1.generateId)('RCALLS', `${consumerMethodId}->${providerEntry.methodId}`),
+                    sourceId: consumerMethodId,
+                    targetId: providerEntry.methodId,
+                    type: 'RCALLS',
+                    confidence: 1.0,
+                    reason: `rpc:${info.serviceId}:${methodName}`,
+                });
+                matchedConsumerMethods.add(consumerMethodId);
+                matchedProviderMethods.add(providerEntry.methodId);
+            }
+        }
+        // Phase 5: Create ExternalService virtual nodes + RCALLS edges for single-side methods
+        const externalServiceIds = new Set();
+        let orphanConsumerEdges = 0;
+        let orphanProviderEdges = 0;
+        // Phase 5a: Consumer methods with no matching provider → ExternalService
+        for (const info of consumerInterfaces) {
+            // Skip if all methods were matched
+            const unmatchedMethods = info.methodIds.filter((id) => !matchedConsumerMethods.has(id));
+            if (unmatchedMethods.length === 0)
+                continue;
+            // Check if there are any providers at all for this serviceId
+            const hasProvider = providerMethodsByService.has(info.serviceId);
+            for (const methodId of unmatchedMethods) {
+                const methodName = methodNamesById.get(methodId);
+                if (!methodName)
+                    continue;
+                // If providers exist but method didn't match by name, it's a partial
+                // mismatch — still create an edge to the ExternalService node only
+                // when there is NO provider interface for this serviceId at all.
+                // When providers exist but no method name match, the method is not
+                // an orphan — it just wasn't called via RPC.
+                if (hasProvider)
+                    continue;
+                const extNodeId = ensureExternalServiceNode(ctx.graph, info.serviceId);
+                externalServiceIds.add(info.serviceId);
+                ctx.graph.addRelationship({
+                    id: (0, utils_js_1.generateId)('RCALLS', `${methodId}->${extNodeId}`),
+                    sourceId: methodId,
+                    targetId: extNodeId,
+                    type: 'RCALLS',
+                    confidence: 1.0,
+                    reason: `rpc:orphan-consumer:${info.serviceId}:${methodName}`,
+                });
+                orphanConsumerEdges++;
+            }
+        }
+        // Phase 5b: Provider methods with no matching consumer → ExternalService
+        for (const info of providerInterfaces) {
+            const unmatchedMethods = info.methodIds.filter((id) => !matchedProviderMethods.has(id));
+            if (unmatchedMethods.length === 0)
+                continue;
+            // Only create virtual edges if there is NO consumer interface for this serviceId.
+            // If consumers exist but method name didn't match, skip — not an orphan provider.
+            const hasConsumer = consumerInterfaces.some((ci) => ci.serviceId === info.serviceId);
+            if (hasConsumer)
+                continue;
+            for (const methodId of unmatchedMethods) {
+                const methodName = methodNamesById.get(methodId);
+                if (!methodName)
+                    continue;
+                const extNodeId = ensureExternalServiceNode(ctx.graph, info.serviceId);
+                externalServiceIds.add(info.serviceId);
+                ctx.graph.addRelationship({
+                    id: (0, utils_js_1.generateId)('RCALLS', `${extNodeId}->${methodId}`),
+                    sourceId: extNodeId,
+                    targetId: methodId,
+                    type: 'RCALLS',
+                    confidence: 1.0,
+                    reason: `rpc:orphan-provider:${info.serviceId}:${methodName}`,
+                });
+                orphanProviderEdges++;
+            }
+        }
+        return {
+            edges,
+            externalServiceNodes: externalServiceIds.size,
+            orphanConsumerEdges,
+            orphanProviderEdges,
+        };
+    },
+};

package/dist/core/code/engine/core/ingestion/pipeline-phases/runner.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * Pipeline Phase Runner
+ *
+ * Executes pipeline phases in dependency order using Kahn's topological sort.
+ * Each phase receives typed outputs from its upstream dependencies.
+ *
+ * The runner is intentionally simple:
+ * - No dynamic phase loading
+ * - No plugin system
+ * - Static phase graph, compile-time type safety
+ * - Sequential execution (parallel support is architecturally possible
+ *   but most phases have linear dependencies)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPipeline = runPipeline;
+const env_js_1 = require("../utils/env.js");
+const logger_js_1 = require("../../logger.js");
+/**
+ * Validate that the phases form a valid dependency graph (no cycles, all deps present).
+ * Returns phases in topological execution order.
+ */
+function topologicalSort(phases) {
+    const phaseMap = new Map();
+    for (const phase of phases) {
+        if (phaseMap.has(phase.name)) {
+            throw new Error(`Duplicate phase name: '${phase.name}'`);
+        }
+        phaseMap.set(phase.name, phase);
+    }
+    // Validate all deps exist
+    for (const phase of phases) {
+        for (const dep of phase.deps) {
+            if (!phaseMap.has(dep)) {
+                throw new Error(`Phase '${phase.name}' depends on '${dep}', which is not registered`);
+            }
+        }
+    }
+    // Kahn's algorithm
+    const inDegree = new Map();
+    const reverseDeps = new Map();
+    for (const phase of phases) {
+        inDegree.set(phase.name, phase.deps.length);
+        for (const dep of phase.deps) {
+            let rev = reverseDeps.get(dep);
+            if (!rev) {
+                rev = [];
+                reverseDeps.set(dep, rev);
+            }
+            rev.push(phase.name);
+        }
+    }
+    const sorted = [];
+    const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([name]) => name);
+    while (queue.length > 0) {
+        const name = queue.shift();
+        sorted.push(phaseMap.get(name));
+        for (const dependent of reverseDeps.get(name) ?? []) {
+            const newDeg = (inDegree.get(dependent) ?? 1) - 1;
+            inDegree.set(dependent, newDeg);
+            if (newDeg === 0)
+                queue.push(dependent);
+        }
+    }
+    if (sorted.length !== phases.length) {
+        const remaining = new Set([...inDegree.entries()].filter(([, d]) => d > 0).map(([name]) => name));
+        const cyclePath = findCyclePath(remaining, phaseMap);
+        const dependentsBlocked = remaining.size - new Set(cyclePath).size;
+        let message = `Cycle detected in pipeline phases: ${cyclePath.join(' -> ')}`;
+        if (dependentsBlocked > 0) {
+            message += ` (and ${dependentsBlocked} transitive dependent${dependentsBlocked === 1 ? '' : 's'} blocked)`;
+        }
+        throw new Error(message);
+    }
+    return sorted;
+}
+/**
+ * Find a concrete cycle path among the phases that Kahn's algorithm could not drain.
+ *
+ * Kahn's leftovers include both true cycle members AND phases transitively dependent
+ * on them. To produce an actionable error message, we DFS over the leftovers (using
+ * each leftover's `deps` as edges) until we hit a back-edge — that closes the cycle.
+ * The returned list is the cycle in order with the entry node repeated at the end:
+ * `[A, B, C, A]` for `A -> B -> C -> A`.
+ *
+ * Falls back to the raw remaining set (sorted) if no back-edge is found, which
+ * should be unreachable but keeps the error informative.
+ */
+function findCyclePath(remaining, phaseMap) {
+    for (const start of remaining) {
+        const stack = [];
+        const onStack = new Set();
+        const visited = new Set();
+        const dfs = (name) => {
+            stack.push(name);
+            onStack.add(name);
+            visited.add(name);
+            const phase = phaseMap.get(name);
+            if (phase) {
+                for (const dep of phase.deps) {
+                    if (!remaining.has(dep))
+                        continue; // dep already drained — not part of cycle
+                    if (onStack.has(dep)) {
+                        // Back-edge — slice from the first occurrence of `dep` and close the loop.
+                        const cycleStart = stack.indexOf(dep);
+                        return [...stack.slice(cycleStart), dep];
+                    }
+                    if (!visited.has(dep)) {
+                        const found = dfs(dep);
+                        if (found)
+                            return found;
+                    }
+                }
+            }
+            stack.pop();
+            onStack.delete(name);
+            return null;
+        };
+        const cycle = dfs(start);
+        if (cycle)
+            return cycle;
+    }
+    // Unreachable in practice (Kahn proved a cycle exists), but stay defensive.
+    return [...remaining].sort();
+}
+/**
+ * Execute a set of pipeline phases in dependency order.
+ *
+ * @param phases  All phases to execute (order doesn't matter — sorted internally)
+ * @param ctx     Shared pipeline context
+ * @returns       Map of phase name → PhaseResult (all completed phases)
+ */
+async function runPipeline(phases, ctx) {
+    let sorted;
+    try {
+        sorted = topologicalSort(phases);
+    }
+    catch (err) {
+        // Emit a terminal 'error' progress event for graph-validation failures
+        // (cycle detected, duplicate phase, missing dep) so CLI/MCP consumers see
+        // the failure before the rejection propagates. Symmetric with the
+        // per-phase error path below. Best-effort: a throwing handler must not
+        // mask the underlying validation error.
+        const message = err instanceof Error ? err.message : String(err);
+        try {
+            ctx.onProgress({
+                phase: 'error',
+                percent: 100,
+                message: 'Pipeline graph validation failed',
+                detail: message,
+            });
+        }
+        catch {
+            // Swallow handler errors — preserving the original cause is more important.
+        }
+        throw err;
+    }
+    const results = new Map();
+    for (const phase of sorted) {
+        const start = Date.now();
+        if (env_js_1.isDev) {
+            logger_js_1.logger.info(`▶ Phase: ${phase.name}`);
+        }
+        // Only expose declared dependencies — prevents hidden coupling to undeclared phases.
+        const declaredDeps = new Map();
+        for (const depName of phase.deps) {
+            const depResult = results.get(depName);
+            if (depResult)
+                declaredDeps.set(depName, depResult);
+        }
+        let output;
+        try {
+            output = await phase.execute(ctx, declaredDeps);
+        }
+        catch (err) {
+            const originalMessage = err instanceof Error ? err.message : String(err);
+            const wrapped = new Error(`Phase '${phase.name}' failed: ${originalMessage}`, {
+                cause: err,
+            });
+            // Emit a terminal 'error' progress event so CLI/MCP consumers see the failure
+            // before the rejection propagates. Best-effort: a throwing handler must not
+            // mask the underlying phase error.
+            try {
+                ctx.onProgress({
+                    phase: 'error',
+                    percent: 100,
+                    message: `Phase '${phase.name}' failed`,
+                    detail: originalMessage,
+                });
+            }
+            catch {
+                // Swallow handler errors — preserving the original cause is more important.
+            }
+            throw wrapped;
+        }
+        const durationMs = Date.now() - start;
+        results.set(phase.name, {
+            phaseName: phase.name,
+            output,
+            durationMs,
+        });
+        if (env_js_1.isDev) {
+            logger_js_1.logger.info(`✓ Phase: ${phase.name} (${durationMs}ms)`);
+        }
+    }
+    return results;
+}

package/dist/core/code/engine/core/ingestion/pipeline-phases/scan.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Phase: scan
+ *
+ * Walks the repository filesystem and collects file paths + sizes.
+ * Does NOT read file contents — that happens in downstream phases.
+ *
+ * @deps    (none — this is the pipeline root)
+ * @reads   repoPath (filesystem)
+ * @writes  graph (nothing yet — just returns scanned paths)
+ * @output  ScannedFile[], allPaths[], totalFiles
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanPhase = void 0;
+const filesystem_walker_js_1 = require("../filesystem-walker.js");
+exports.scanPhase = {
+    name: 'scan',
+    deps: [],
+    async execute(ctx) {
+        ctx.onProgress({
+            phase: 'extracting',
+            percent: 0,
+            message: 'Scanning repository...',
+        });
+        const scannedFiles = await (0, filesystem_walker_js_1.walkRepositoryPaths)(ctx.repoPath, (current, total, filePath) => {
+            const scanProgress = Math.round((current / total) * 15);
+            ctx.onProgress({
+                phase: 'extracting',
+                percent: scanProgress,
+                message: 'Scanning repository...',
+                detail: filePath,
+                stats: {
+                    filesProcessed: current,
+                    totalFiles: total,
+                    nodesCreated: ctx.graph.nodeCount,
+                },
+            });
+        });
+        const totalFiles = scannedFiles.length;
+        const allPaths = scannedFiles.map((f) => f.path);
+        ctx.onProgress({
+            phase: 'extracting',
+            percent: 15,
+            message: 'Repository scanned successfully',
+            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        return { scannedFiles, allPaths, totalFiles };
+    },
+};