code-graph-context 0.1.0 → 1.1.0

package/dist/mcp/services.js

@@ -4,7 +4,7 @@
  */
 import fs from 'fs/promises';
 import { join } from 'path';
-import { Neo4jService } from '../storage/neo4j/neo4j.service.js';
+import { Neo4jService, QUERIES } from '../storage/neo4j/neo4j.service.js';
 import { FILE_PATHS, LOG_CONFIG } from './constants.js';
 import { initializeNaturalLanguageService } from './tools/natural-language-to-cypher.tool.js';
 import { debugLog } from './utils.js';
@@ -15,141 +15,62 @@ export const initializeServices = async () => {
     await Promise.all([initializeNeo4jSchema(), initializeNaturalLanguageService()]);
 };
 /**
- * Enrich raw Neo4j schema with FairSquare domain context
+ * Dynamically discover schema from the actual graph contents.
+ * This is framework-agnostic - it discovers what's actually in the graph.
  */
-const enrichSchemaWithDomainContext = (rawSchema) => {
-    return {
-        rawSchema,
-        domainContext: {
-            framework: 'FairSquare',
-            description: 'Custom TypeScript framework for microservices with dependency injection and repository patterns',
-            nodeTypes: {
-                Controller: {
-                    description: 'HTTP request handlers that extend the Controller base class',
-                    purpose: 'Entry points for HTTP API endpoints',
-                    commonProperties: ['name', 'filePath', 'sourceCode'],
-                    exampleQuery: 'MATCH (c:Controller) WHERE c.name =~ ".*Credit.*" RETURN c',
-                },
-                Service: {
-                    description: 'Business logic layer with @Injectable decorator',
-                    purpose: 'Encapsulate business logic and orchestrate data operations',
-                    commonProperties: ['name', 'filePath', 'dependencies'],
-                    exampleQuery: 'MATCH (s:Service)-[:INJECTS]->(dep) RETURN s.name, collect(dep.name) as dependencies',
-                },
-                Repository: {
-                    description: 'Data access layer that extends Repository base class',
-                    purpose: 'Abstract database operations and provide data access interface',
-                    commonProperties: ['name', 'filePath', 'dals'],
-                    exampleQuery: 'MATCH (r:Repository)-[:USES_DAL]->(d:DAL) RETURN r.name, collect(d.name) as dals',
-                },
-                DAL: {
-                    description: 'Data Access Layer - direct database interaction classes',
-                    purpose: 'Execute database queries and manage data persistence',
-                    commonProperties: ['name', 'filePath'],
-                    exampleQuery: 'MATCH (d:DAL)<-[:USES_DAL]-(r:Repository) RETURN d.name, count(r) as usedByCount',
-                },
-                PermissionManager: {
-                    description: 'Security layer for authorization checks',
-                    purpose: 'Control access to resources and validate permissions',
-                    commonProperties: ['name', 'filePath'],
-                    exampleQuery: 'MATCH (c:Controller)-[:PROTECTED_BY]->(pm:PermissionManager) RETURN c.name, pm.name',
-                },
-                VendorClient: {
-                    description: 'External service integration clients',
-                    purpose: 'Interface with third-party APIs and services',
-                    commonProperties: ['name', 'filePath'],
-                    exampleQuery: 'MATCH (v:VendorClient)<-[:INJECTS]-(s) RETURN v.name, collect(s.name) as usedBy',
-                },
-                RouteDefinition: {
-                    description: 'Explicit route definitions from route files. CRITICAL: Individual route details (method, path, authenticated, handler, controllerName) are stored in the "context" property as a JSON string.',
-                    purpose: 'Map HTTP paths and methods to controller handlers',
-                    commonProperties: ['name', 'context', 'filePath', 'sourceCode'],
-                    contextStructure: 'The context property contains JSON with structure: {"routes": [{"method": "POST", "path": "/v1/endpoint", "controllerName": "SomeController", "handler": "methodName", "authenticated": true}]}',
-                    parsingInstructions: 'To get individual routes: (1) Parse JSON with apoc.convert.fromJsonMap(rd.context) (2) UNWIND the routes array (3) Access route.method, route.path, route.handler, route.authenticated, route.controllerName',
-                    exampleQuery: 'MATCH (rd:RouteDefinition) WITH rd, apoc.convert.fromJsonMap(rd.context) AS ctx UNWIND ctx.routes AS route RETURN route.method, route.path, route.controllerName, route.handler, route.authenticated ORDER BY route.path',
-                },
-                HttpEndpoint: {
-                    description: 'Methods that handle HTTP requests',
-                    purpose: 'Process incoming HTTP requests and return responses',
-                    commonProperties: ['name', 'filePath', 'sourceCode'],
-                    exampleQuery: 'MATCH (e:HttpEndpoint)<-[r:ROUTES_TO_HANDLER]-(rd) WHERE apoc.convert.fromJsonMap(r.context).authenticated = true RETURN e.name, apoc.convert.fromJsonMap(r.context).path as path',
-                },
-            },
-            relationships: {
-                INJECTS: {
-                    description: 'Dependency injection relationship from @Injectable decorator',
-                    direction: 'OUTGOING',
-                    example: 'Controller -[:INJECTS]-> Service',
-                    commonPatterns: ['Controller -> Service', 'Service -> Repository', 'Service -> VendorClient'],
-                },
-                USES_DAL: {
-                    description: 'Repository uses Data Access Layer for database operations',
-                    direction: 'OUTGOING',
-                    example: 'Repository -[:USES_DAL]-> DAL',
-                    commonPatterns: ['Repository -> DAL'],
-                },
-                ROUTES_TO: {
-                    description: 'Route definition points to a Controller',
-                    direction: 'OUTGOING',
-                    example: 'RouteDefinition -[:ROUTES_TO]-> Controller',
-                    commonPatterns: ['RouteDefinition -> Controller'],
-                },
-                ROUTES_TO_HANDLER: {
-                    description: 'Route definition points to a specific handler method',
-                    direction: 'OUTGOING',
-                    example: 'RouteDefinition -[:ROUTES_TO_HANDLER]-> HttpEndpoint',
-                    contextProperties: ['path', 'method', 'authenticated', 'handler', 'controllerName'],
-                    contextNote: 'IMPORTANT: context is stored as a JSON string. Access properties using apoc.convert.fromJsonMap(r.context).propertyName',
-                    commonPatterns: ['RouteDefinition -> HttpEndpoint (Method)'],
-                },
-                PROTECTED_BY: {
-                    description: 'Controller is protected by a PermissionManager',
-                    direction: 'OUTGOING',
-                    example: 'Controller -[:PROTECTED_BY]-> PermissionManager',
-                    commonPatterns: ['Controller -> PermissionManager'],
-                },
-            },
-            commonQueryPatterns: [
-                {
-                    intent: 'Find all HTTP endpoints',
-                    query: 'MATCH (e:HttpEndpoint) RETURN e.name, e.filePath',
-                },
-                {
-                    intent: 'Find service dependency chain',
-                    query: 'MATCH path = (c:Controller)-[:INJECTS*1..3]->(s) RETURN [n in nodes(path) | n.name] as chain',
-                },
-                {
-                    intent: 'Find all authenticated routes',
-                    query: 'MATCH (rd:RouteDefinition)-[r:ROUTES_TO_HANDLER]->(m) WHERE apoc.convert.fromJsonMap(r.context).authenticated = true RETURN apoc.convert.fromJsonMap(r.context).path as path, apoc.convert.fromJsonMap(r.context).method as method, m.name',
-                },
-                {
-                    intent: 'Find controllers without permission managers',
-                    query: 'MATCH (c:Controller) WHERE NOT (c)-[:PROTECTED_BY]->(:PermissionManager) RETURN c.name',
-                },
-                {
-                    intent: 'Find what services a controller uses',
-                    query: 'MATCH (c:Controller {name: $controllerName})-[:INJECTS]->(s:Service) RETURN s.name',
-                },
-                {
-                    intent: 'Find complete execution path from controller to database',
-                    query: 'MATCH path = (c:Controller)-[:INJECTS*1..3]->(r:Repository)-[:USES_DAL]->(d:DAL) WHERE c.name = $controllerName RETURN [n in nodes(path) | n.name] as executionPath',
-                },
-            ],
-        },
-    };
+const discoverSchemaFromGraph = async (neo4jService) => {
+    try {
+        // Discover actual node types, relationships, and patterns from the graph
+        const [nodeTypes, relationshipTypes, semanticTypes, commonPatterns] = await Promise.all([
+            neo4jService.run(QUERIES.DISCOVER_NODE_TYPES),
+            neo4jService.run(QUERIES.DISCOVER_RELATIONSHIP_TYPES),
+            neo4jService.run(QUERIES.DISCOVER_SEMANTIC_TYPES),
+            neo4jService.run(QUERIES.DISCOVER_COMMON_PATTERNS),
+        ]);
+        return {
+            nodeTypes: nodeTypes.map((r) => ({
+                label: r.label,
+                count: typeof r.nodeCount === 'object' ? r.nodeCount.toNumber() : r.nodeCount,
+                properties: r.sampleProperties || [],
+            })),
+            relationshipTypes: relationshipTypes.map((r) => ({
+                type: r.relationshipType,
+                count: typeof r.relCount === 'object' ? r.relCount.toNumber() : r.relCount,
+                connections: r.connections || [],
+            })),
+            semanticTypes: semanticTypes.map((r) => ({
+                type: r.semanticType,
+                count: typeof r.count === 'object' ? r.count.toNumber() : r.count,
+            })),
+            commonPatterns: commonPatterns.map((r) => ({
+                from: r.fromType,
+                relationship: r.relType,
+                to: r.toType,
+                count: typeof r.count === 'object' ? r.count.toNumber() : r.count,
+            })),
+        };
+    }
+    catch (error) {
+        await debugLog('Failed to discover schema from graph', error);
+        return null;
+    }
 };
 /**
- * Initialize Neo4j schema by fetching and caching it locally
+ * Initialize Neo4j schema by fetching from APOC and discovering actual graph structure
  */
 const initializeNeo4jSchema = async () => {
     try {
         const neo4jService = new Neo4jService();
         const rawSchema = await neo4jService.getSchema();
-        // Enrich schema with FairSquare domain context
-        const enrichedSchema = enrichSchemaWithDomainContext(rawSchema);
+        // Dynamically discover what's actually in the graph
+        const discoveredSchema = await discoverSchemaFromGraph(neo4jService);
+        const schema = {
+            rawSchema,
+            discoveredSchema,
+        };
         const schemaPath = join(process.cwd(), FILE_PATHS.schemaOutput);
-        await fs.writeFile(schemaPath, JSON.stringify(enrichedSchema, null, LOG_CONFIG.jsonIndentation));
-        await debugLog('Neo4j schema cached successfully with domain context', { schemaPath });
+        await fs.writeFile(schemaPath, JSON.stringify(schema, null, LOG_CONFIG.jsonIndentation));
+        await debugLog('Neo4j schema cached successfully', { schemaPath });
     }
     catch (error) {
         await debugLog('Failed to initialize Neo4j schema', error);

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

@@ -0,0 +1,253 @@
+/**
+ * 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 } 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: {
+            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 ({ nodeId, filePath, maxDepth = 4, frameworkConfig }) => {
+        try {
+            if (!nodeId && !filePath) {
+                return createErrorResponse('Either nodeId or filePath must be provided');
+            }
+            await debugLog('Impact analysis started', { nodeId, filePath, maxDepth, frameworkConfig });
+            const neo4jService = new Neo4jService();
+            // 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 });
+                if (targetResult.length === 0) {
+                    return createErrorResponse(`Node with ID "${nodeId}" not found`);
+                }
+                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 });
+                directDependents = normalizeDependents(directResult);
+            }
+            else {
+                // File-based analysis
+                targetInfo = {
+                    id: filePath,
+                    name: filePath.split('/').pop() ?? filePath,
+                    type: 'SourceFile',
+                    filePath: filePath,
+                };
+                // Get all external dependents on this file
+                const fileResult = await neo4jService.run(QUERIES.GET_FILE_IMPACT, { filePath });
+                directDependents = normalizeDependents(fileResult);
+            }
+            // Get transitive dependents if nodeId provided
+            let transitiveDependents = [];
+            if (nodeId && maxDepth > 1) {
+                const transitiveResult = await neo4jService.run(QUERIES.GET_TRANSITIVE_DEPENDENTS(maxDepth), { nodeId });
+                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);
+        }
+    });
+};
+// 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

@@ -3,6 +3,7 @@
  * Centralized tool creation and registration
  */
 import { createHelloTool } from './hello.tool.js';
+import { createImpactAnalysisTool } from './impact-analysis.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';
@@ -19,6 +20,7 @@ export const registerAllTools = (server) => {
     createSearchCodebaseTool(server);
     createTraverseFromNodeTool(server);
     createNaturalLanguageToCypherTool(server);
+    createImpactAnalysisTool(server);
     // Register project parsing tool
     createParseTypescriptProjectTool(server);
 };