code-graph-context 1.0.0 → 2.0.0

package/dist/mcp/tools/impact-analysis.tool.js

@@ -0,0 +1,319 @@
+/**
+ * Impact Analysis Tool
+ * Analyzes what would be affected if a node is modified
+ * Reuses cross-file edge pattern from incremental parsing
+ */
+import { z } from 'zod';
+import { Neo4jService, QUERIES } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, debugLog, resolveProjectIdOrError } from '../utils.js';
+// Default relationship weights for core AST relationships
+const DEFAULT_RELATIONSHIP_WEIGHTS = {
+    // Critical - inheritance/interface contracts
+    EXTENDS: 0.95,
+    IMPLEMENTS: 0.95,
+    // High - direct code dependencies
+    CALLS: 0.75,
+    HAS_MEMBER: 0.65,
+    TYPED_AS: 0.6,
+    // Medium - module dependencies
+    IMPORTS: 0.5,
+    EXPORTS: 0.5,
+    // Lower - structural
+    CONTAINS: 0.3,
+    HAS_PARAMETER: 0.3,
+    DECORATED_WITH: 0.4,
+};
+// Schema for framework-specific configuration
+const FrameworkConfigSchema = z.object({
+    relationshipWeights: z.record(z.string(), z.number().min(0).max(1)).optional(),
+    highRiskTypes: z.array(z.string()).optional(),
+    name: z.string().optional(),
+});
+export const createImpactAnalysisTool = (server) => {
+    server.registerTool(TOOL_NAMES.impactAnalysis, {
+        title: TOOL_METADATA[TOOL_NAMES.impactAnalysis].title,
+        description: TOOL_METADATA[TOOL_NAMES.impactAnalysis].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            nodeId: z
+                .string()
+                .optional()
+                .describe('The node ID to analyze impact for (from search_codebase or traverse_from_node results)'),
+            filePath: z
+                .string()
+                .optional()
+                .describe('Alternatively, provide a file path to analyze all exports from that file'),
+            maxDepth: z
+                .number()
+                .int()
+                .min(1)
+                .max(6)
+                .optional()
+                .describe('Maximum depth to traverse for transitive dependents (default: 4)')
+                .default(4),
+            frameworkConfig: FrameworkConfigSchema.optional().describe('Framework-specific configuration for risk scoring. Includes relationshipWeights (e.g., {"INJECTS": 0.9}), highRiskTypes (e.g., ["Controller", "Service"]), and optional name.'),
+        },
+    }, async ({ projectId, nodeId, filePath, maxDepth = 4, frameworkConfig }) => {
+        const neo4jService = new Neo4jService();
+        try {
+            // Resolve project ID from name, path, or ID
+            const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+            if (!projectResult.success)
+                return projectResult.error;
+            const resolvedProjectId = projectResult.projectId;
+            if (!nodeId && !filePath) {
+                return createErrorResponse('Either nodeId or filePath must be provided');
+            }
+            await debugLog('Impact analysis started', {
+                projectId: resolvedProjectId,
+                nodeId,
+                filePath,
+                maxDepth,
+                frameworkConfig,
+            });
+            // Merge default weights with framework-specific weights
+            const weights = { ...DEFAULT_RELATIONSHIP_WEIGHTS, ...frameworkConfig?.relationshipWeights };
+            const highRiskTypes = new Set(frameworkConfig?.highRiskTypes ?? []);
+            let targetInfo;
+            let directDependents;
+            if (nodeId) {
+                // Get target node info
+                const targetResult = await neo4jService.run(QUERIES.GET_NODE_BY_ID, { nodeId, projectId: resolvedProjectId });
+                if (targetResult.length === 0) {
+                    return createErrorResponse(`Node with ID "${nodeId}" not found in project "${resolvedProjectId}"`);
+                }
+                const target = targetResult[0];
+                targetInfo = {
+                    id: target.id,
+                    name: target.name ?? 'Unknown',
+                    type: target.semanticType ?? target.coreType ?? target.labels?.[0] ?? 'Unknown',
+                    filePath: target.filePath ?? '',
+                };
+                // Get direct dependents using cross-file edge pattern
+                const directResult = await neo4jService.run(QUERIES.GET_NODE_IMPACT, {
+                    nodeId,
+                    projectId: resolvedProjectId,
+                });
+                directDependents = normalizeDependents(directResult);
+            }
+            else {
+                // File-based analysis - find all Class/Function/Interface entities in the file
+                // and aggregate their impact analysis results
+                const entitiesQuery = `
+            MATCH (n)
+            WHERE n.projectId = $projectId
+              AND (n.filePath = $filePath OR n.filePath ENDS WITH '/' + $filePath)
+              AND (n:Class OR n:Function OR n:Interface)
+            RETURN n.id AS nodeId, n.name AS name, labels(n) AS labels,
+                   n.semanticType AS semanticType, n.coreType AS coreType
+          `;
+                const entities = await neo4jService.run(entitiesQuery, {
+                    filePath,
+                    projectId: resolvedProjectId,
+                });
+                if (entities.length === 0) {
+                    // No exportable entities found
+                    targetInfo = {
+                        id: filePath,
+                        name: filePath.split('/').pop() ?? filePath,
+                        type: 'SourceFile',
+                        filePath: filePath,
+                    };
+                    directDependents = [];
+                }
+                else {
+                    // Use first entity as the primary target for display
+                    const primaryEntity = entities[0];
+                    targetInfo = {
+                        id: primaryEntity.nodeId,
+                        name: primaryEntity.name ?? filePath.split('/').pop() ?? filePath,
+                        type: primaryEntity.semanticType ?? primaryEntity.coreType ?? 'Class',
+                        filePath: filePath,
+                    };
+                    // Aggregate impact from all entities in the file
+                    const allDependentsMap = new Map();
+                    for (const entity of entities) {
+                        const entityResult = await neo4jService.run(QUERIES.GET_NODE_IMPACT, {
+                            nodeId: entity.nodeId,
+                            projectId: resolvedProjectId,
+                        });
+                        for (const dep of normalizeDependents(entityResult)) {
+                            // Dedupe by nodeId, keeping highest weight
+                            const existing = allDependentsMap.get(dep.nodeId);
+                            if (!existing || dep.weight > existing.weight) {
+                                allDependentsMap.set(dep.nodeId, dep);
+                            }
+                        }
+                    }
+                    directDependents = Array.from(allDependentsMap.values());
+                    // Update nodeId for transitive analysis if we have dependents
+                    if (directDependents.length > 0 && entities.length > 0) {
+                        // Use first entity's nodeId for transitive analysis
+                        nodeId = primaryEntity.nodeId;
+                    }
+                }
+            }
+            // Get transitive dependents if nodeId provided
+            let transitiveDependents = [];
+            if (nodeId && maxDepth > 1) {
+                const transitiveResult = await neo4jService.run(QUERIES.GET_TRANSITIVE_DEPENDENTS(maxDepth), {
+                    nodeId,
+                    projectId: resolvedProjectId,
+                });
+                transitiveDependents = normalizeTransitiveDependents(transitiveResult);
+                // Filter out direct dependents from transitive
+                const directIds = new Set(directDependents.map((d) => d.nodeId));
+                transitiveDependents = transitiveDependents.filter((d) => !directIds.has(d.nodeId));
+            }
+            // Calculate risk score
+            const riskScore = calculateRiskScore(directDependents, transitiveDependents, weights, highRiskTypes);
+            const riskLevel = getRiskLevel(riskScore);
+            // Group dependents by type
+            const directByType = groupByType(directDependents);
+            const directByRelationship = groupByRelationship(directDependents);
+            const transitiveByType = groupByType(transitiveDependents);
+            // Get affected files
+            const affectedFiles = getAffectedFiles([...directDependents, ...transitiveDependents]);
+            // Find critical paths (high-weight relationships)
+            const criticalPaths = findCriticalPaths(directDependents, targetInfo, weights);
+            // Build summary
+            const summary = buildSummary(targetInfo, directDependents.length, transitiveDependents.length, affectedFiles.length, riskLevel);
+            const result = {
+                target: targetInfo,
+                riskLevel,
+                riskScore: Math.round(riskScore * 100) / 100,
+                summary,
+                directDependents: {
+                    count: directDependents.length,
+                    byType: directByType,
+                    byRelationship: directByRelationship,
+                },
+                transitiveDependents: {
+                    count: transitiveDependents.length,
+                    maxDepth: getMaxDepth(transitiveDependents),
+                    byType: transitiveByType,
+                },
+                affectedFiles,
+                criticalPaths,
+            };
+            await debugLog('Impact analysis complete', {
+                nodeId: nodeId ?? filePath,
+                riskLevel,
+                directCount: directDependents.length,
+                transitiveCount: transitiveDependents.length,
+            });
+            return createSuccessResponse(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            console.error('Impact analysis error:', error);
+            await debugLog('Impact analysis error', { nodeId, filePath, error });
+            return createErrorResponse(error);
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};
+// Helper functions
+const normalizeDependents = (results) => {
+    return results.map((r) => ({
+        nodeId: r.nodeId,
+        name: r.name ?? 'Unknown',
+        labels: r.labels ?? [],
+        semanticType: r.semanticType,
+        coreType: r.coreType,
+        filePath: r.filePath ?? '',
+        relationshipType: r.relationshipType ?? 'UNKNOWN',
+        weight: typeof r.weight === 'object'
+            ? r.weight.toNumber()
+            : (r.weight ?? 0.5),
+    }));
+};
+const normalizeTransitiveDependents = (results) => {
+    return results.map((r) => ({
+        nodeId: r.nodeId,
+        name: r.name ?? 'Unknown',
+        labels: r.labels ?? [],
+        semanticType: r.semanticType,
+        coreType: r.coreType,
+        filePath: r.filePath ?? '',
+        relationshipType: r.relationshipPath?.[0] ?? 'UNKNOWN',
+        weight: 0.5,
+        depth: typeof r.depth === 'object' ? r.depth.toNumber() : r.depth,
+        relationshipPath: r.relationshipPath,
+    }));
+};
+const calculateRiskScore = (directDependents, transitiveDependents, weights, highRiskTypes) => {
+    if (directDependents.length === 0)
+        return 0;
+    let score = 0;
+    // Factor 1: Number of direct dependents (logarithmic, max 0.3)
+    score += Math.min(Math.log10(directDependents.length + 1) / 2, 0.3);
+    // Factor 2: Average relationship weight of direct deps (max 0.3)
+    const avgWeight = directDependents.reduce((sum, d) => sum + (weights[d.relationshipType] ?? d.weight), 0) / directDependents.length;
+    score += avgWeight * 0.3;
+    // Factor 3: High-risk types affected (max 0.2)
+    const highRiskCount = directDependents.filter((d) => highRiskTypes.has(d.semanticType ?? '') || highRiskTypes.has(d.coreType ?? '')).length;
+    if (highRiskTypes.size > 0) {
+        score += Math.min(highRiskCount / Math.max(highRiskTypes.size, 3), 1) * 0.2;
+    }
+    // Factor 4: Transitive impact (max 0.2)
+    score += Math.min(Math.log10(transitiveDependents.length + 1) / 3, 0.2);
+    return Math.min(score, 1);
+};
+const getRiskLevel = (score) => {
+    if (score >= 0.75)
+        return 'CRITICAL';
+    if (score >= 0.5)
+        return 'HIGH';
+    if (score >= 0.25)
+        return 'MEDIUM';
+    return 'LOW';
+};
+const groupByType = (dependents) => {
+    const groups = {};
+    for (const dep of dependents) {
+        const type = dep.semanticType ?? dep.coreType ?? dep.labels?.[0] ?? 'Unknown';
+        groups[type] = (groups[type] ?? 0) + 1;
+    }
+    return groups;
+};
+const groupByRelationship = (dependents) => {
+    const groups = {};
+    for (const dep of dependents) {
+        groups[dep.relationshipType] = (groups[dep.relationshipType] ?? 0) + 1;
+    }
+    return groups;
+};
+const getAffectedFiles = (dependents) => {
+    const files = new Set();
+    for (const dep of dependents) {
+        if (dep.filePath)
+            files.add(dep.filePath);
+    }
+    return Array.from(files).sort();
+};
+const getMaxDepth = (dependents) => {
+    if (dependents.length === 0)
+        return 0;
+    return Math.max(...dependents.map((d) => d.depth ?? 1));
+};
+const findCriticalPaths = (directDependents, target, weights) => {
+    const paths = [];
+    for (const dep of directDependents) {
+        const relWeight = weights[dep.relationshipType] ?? 0.5;
+        // Only include high-weight relationships
+        if (relWeight >= 0.6) {
+            const depType = dep.semanticType ?? dep.coreType ?? '';
+            paths.push(`${dep.name} (${depType}) -[${dep.relationshipType}]-> ${target.name} (${target.type})`);
+        }
+    }
+    return paths.slice(0, 10);
+};
+const buildSummary = (target, directCount, transitiveCount, fileCount, riskLevel) => {
+    if (directCount === 0) {
+        return `${target.name} (${target.type}) has no external dependents - safe to modify`;
+    }
+    return `Modifying ${target.name} (${target.type}) affects ${directCount} direct and ${transitiveCount} transitive dependents across ${fileCount} files. Risk: ${riskLevel}`;
+};

package/dist/mcp/tools/index.js

@@ -2,10 +2,16 @@
  * MCP Tool Factory
  * Centralized tool creation and registration
  */
+import { createCheckParseStatusTool } from './check-parse-status.tool.js';
 import { createHelloTool } from './hello.tool.js';
+import { createImpactAnalysisTool } from './impact-analysis.tool.js';
+import { createListProjectsTool } from './list-projects.tool.js';
+import { createListWatchersTool } from './list-watchers.tool.js';
 import { createNaturalLanguageToCypherTool } from './natural-language-to-cypher.tool.js';
 import { createParseTypescriptProjectTool } from './parse-typescript-project.tool.js';
 import { createSearchCodebaseTool } from './search-codebase.tool.js';
+import { createStartWatchProjectTool } from './start-watch-project.tool.js';
+import { createStopWatchProjectTool } from './stop-watch-project.tool.js';
 import { createTestNeo4jConnectionTool } from './test-neo4j-connection.tool.js';
 import { createTraverseFromNodeTool } from './traverse-from-node.tool.js';
 /**
@@ -19,6 +25,14 @@ export const registerAllTools = (server) => {
     createSearchCodebaseTool(server);
     createTraverseFromNodeTool(server);
     createNaturalLanguageToCypherTool(server);
-    // Register project parsing tool
+    createImpactAnalysisTool(server);
+    // Register project parsing tools
     createParseTypescriptProjectTool(server);
+    createCheckParseStatusTool(server);
+    // Register project management tools
+    createListProjectsTool(server);
+    // Register file watch tools
+    createStartWatchProjectTool(server);
+    createStopWatchProjectTool(server);
+    createListWatchersTool(server);
 };

package/dist/mcp/tools/list-projects.tool.js

@@ -0,0 +1,62 @@
+/**
+ * List Projects Tool
+ * Lists all parsed projects in the database
+ */
+import { LIST_PROJECTS_QUERY } from '../../core/utils/project-id.js';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
+export const createListProjectsTool = (server) => {
+    server.registerTool(TOOL_NAMES.listProjects, {
+        title: TOOL_METADATA[TOOL_NAMES.listProjects].title,
+        description: TOOL_METADATA[TOOL_NAMES.listProjects].description,
+        inputSchema: {},
+    }, async () => {
+        const neo4jService = new Neo4jService();
+        try {
+            await debugLog('Listing projects');
+            const results = await neo4jService.run(LIST_PROJECTS_QUERY, {});
+            if (results.length === 0) {
+                return createSuccessResponse('No projects found. Use parse_typescript_project to add a project first.');
+            }
+            const projects = results.map((r) => ({
+                projectId: r.projectId,
+                name: r.name,
+                path: r.path,
+                status: r.status ?? 'unknown',
+                nodeCount: r.nodeCount,
+                edgeCount: r.edgeCount,
+                updatedAt: r.updatedAt?.toString() ?? 'Unknown',
+            }));
+            await debugLog('Projects listed', { count: projects.length });
+            // Format output for readability
+            const header = `Found ${projects.length} project(s):\n\n`;
+            const formatStats = (p) => {
+                if (p.status === 'complete' && p.nodeCount !== null) {
+                    return `  Stats: ${p.nodeCount} nodes, ${p.edgeCount ?? 0} edges`;
+                }
+                return '';
+            };
+            const projectList = projects
+                .map((p) => `- ${p.name} [${p.status}]\n` +
+                `  ID: ${p.projectId}\n` +
+                `  Path: ${p.path}\n` +
+                formatStats(p) +
+                (formatStats(p) ? '\n' : '') +
+                `  Updated: ${p.updatedAt}`)
+                .join('\n\n');
+            const tip = '\n\nTip: Use the project name (e.g., "' +
+                projects[0].name +
+                '") in other tools instead of the full projectId.';
+            return createSuccessResponse(header + projectList + tip);
+        }
+        catch (error) {
+            console.error('List projects error:', error);
+            await debugLog('List projects error', { error });
+            return createErrorResponse(error);
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

package/dist/mcp/tools/list-watchers.tool.js

@@ -0,0 +1,51 @@
+/**
+ * List Watchers Tool
+ * Lists all active file watchers
+ */
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { watchManager } from '../services/watch-manager.js';
+import { createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
+export const createListWatchersTool = (server) => {
+    server.registerTool(TOOL_NAMES.listWatchers, {
+        title: TOOL_METADATA[TOOL_NAMES.listWatchers].title,
+        description: TOOL_METADATA[TOOL_NAMES.listWatchers].description,
+        inputSchema: {},
+    }, async () => {
+        try {
+            await debugLog('Listing watchers');
+            const watchers = watchManager.listWatchers();
+            if (watchers.length === 0) {
+                return createSuccessResponse('No active file watchers.\n\n' +
+                    'To start watching a project:\n' +
+                    '- Use start_watch_project with a projectId\n' +
+                    '- Or use parse_typescript_project with watch: true (requires async: false)');
+            }
+            await debugLog('Watchers listed', { count: watchers.length });
+            const header = `Found ${watchers.length} active watcher(s):\n\n`;
+            const watcherList = watchers
+                .map((w) => {
+                const lines = [
+                    `- ${w.projectId} [${w.status}]`,
+                    `  Path: ${w.projectPath}`,
+                    `  Debounce: ${w.debounceMs}ms`,
+                    `  Pending changes: ${w.pendingChanges}`,
+                ];
+                if (w.lastUpdateTime) {
+                    lines.push(`  Last update: ${w.lastUpdateTime}`);
+                }
+                if (w.errorMessage) {
+                    lines.push(`  Error: ${w.errorMessage}`);
+                }
+                return lines.join('\n');
+            })
+                .join('\n\n');
+            const tip = '\n\nUse stop_watch_project with a project ID to stop watching.';
+            return createSuccessResponse(header + watcherList + tip);
+        }
+        catch (error) {
+            console.error('List watchers error:', error);
+            await debugLog('List watchers error', { error });
+            return createErrorResponse(error instanceof Error ? error : new Error(String(error)));
+        }
+    });
+};

package/dist/mcp/tools/natural-language-to-cypher.tool.js

@@ -6,7 +6,7 @@ import { z } from 'zod';
 import { NaturalLanguageToCypherService } from '../../core/embeddings/natural-language-to-cypher.service.js';
 import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
 import { TOOL_NAMES, TOOL_METADATA, MESSAGES } from '../constants.js';
-import { createErrorResponse, createSuccessResponse, formatQueryResults, debugLog } from '../utils.js';
+import { createErrorResponse, createSuccessResponse, formatQueryResults, debugLog, resolveProjectIdOrError, } from '../utils.js';
 // Service instance - initialized asynchronously
 let naturalLanguageToCypherService = null;
 /**
@@ -30,20 +30,43 @@ export const createNaturalLanguageToCypherTool = (server) => {
         title: TOOL_METADATA[TOOL_NAMES.naturalLanguageToCypher].title,
         description: TOOL_METADATA[TOOL_NAMES.naturalLanguageToCypher].description,
         inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
             query: z.string().describe('Natural language query to convert to Cypher'),
         },
-    }, async ({ query }) => {
+    }, async ({ projectId, query }) => {
+        const neo4jService = new Neo4jService();
         try {
+            // Resolve project ID from name, path, or ID
+            const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+            if (!projectResult.success)
+                return projectResult.error;
+            const resolvedProjectId = projectResult.projectId;
             if (!naturalLanguageToCypherService) {
-                await debugLog('Natural language service not available', { query });
+                await debugLog('Natural language service not available', { projectId: resolvedProjectId, query });
                 return createSuccessResponse(MESSAGES.errors.serviceNotInitialized);
             }
-            await debugLog('Natural language to Cypher conversion started', { query });
-            const cypherResult = await naturalLanguageToCypherService.promptToQuery(query);
-            const neo4jService = new Neo4jService();
-            // Execute the generated Cypher query
-            const results = await neo4jService.run(cypherResult.cypher, cypherResult.parameters ?? {});
+            await debugLog('Natural language to Cypher conversion started', { projectId: resolvedProjectId, query });
+            const cypherResult = await naturalLanguageToCypherService.promptToQuery(query, resolvedProjectId);
+            // Validate Cypher syntax using EXPLAIN (no execution, just parse)
+            const parameters = { ...cypherResult.parameters, projectId: resolvedProjectId };
+            try {
+                await neo4jService.run(`EXPLAIN ${cypherResult.cypher}`, parameters);
+            }
+            catch (validationError) {
+                const message = validationError instanceof Error ? validationError.message : String(validationError);
+                await debugLog('Generated Cypher validation failed', {
+                    cypher: cypherResult.cypher,
+                    error: message,
+                });
+                return createErrorResponse(`Generated Cypher query has syntax errors:\n\n` +
+                    `Query: ${cypherResult.cypher}\n\n` +
+                    `Error: ${message}\n\n` +
+                    `Try rephrasing your request or use a simpler query.`);
+            }
+            // Execute the validated query
+            const results = await neo4jService.run(cypherResult.cypher, parameters);
             await debugLog('Cypher query executed', {
+                projectId: resolvedProjectId,
                 cypher: cypherResult.cypher,
                 resultsCount: results.length,
             });
@@ -55,5 +78,8 @@ export const createNaturalLanguageToCypherTool = (server) => {
             await debugLog('Natural language to Cypher error', { query, error });
             return createErrorResponse(error);
         }
+        finally {
+            await neo4jService.close();
+        }
     });
 };