code-graph-context 2.0.1 → 2.3.0

package/README.md

@@ -20,12 +20,17 @@ A Model Context Protocol (MCP) server that builds rich code graphs to provide de
 - **Natural Language Querying**: Convert natural language questions into Cypher queries using OpenAI assistants API
 - **Framework-Aware & Customizable**: Built-in NestJS schema with ability to define custom framework patterns via configuration
 - **Weighted Graph Traversal**: Intelligent traversal that scores paths based on relationship importance, query relevance, and depth
-- **Workspace & Monorepo Support**: Auto-detects Turborepo, pnpm, Yarn, and npm workspaces
+- **Workspace & Monorepo Support**: Auto-detects Nx, Turborepo, pnpm, Yarn, and npm workspaces
+- **Parallel Parsing**: Multi-threaded parsing with configurable worker pool for maximum CPU utilization
 - **Async Parsing**: Background parsing with Worker threads for large codebases without blocking the MCP server
 - **Streaming Import**: Chunked processing for projects with 100+ files to prevent memory issues
+- **TypeAlias Support**: Full parsing of TypeScript type aliases into graph nodes
 - **Incremental Parsing**: Only reparse changed files for faster updates
 - **File Watching**: Real-time monitoring with automatic incremental graph updates on file changes
 - **Impact Analysis**: Assess refactoring risk with dependency analysis (LOW/MEDIUM/HIGH/CRITICAL scoring)
+- **Dead Code Detection**: Find unreferenced exports, uncalled private methods, unused interfaces with confidence scoring
+- **Duplicate Code Detection**: Identify structural duplicates (identical AST) and semantic duplicates (similar logic via embeddings)
+- **Swarm Coordination**: Multi-agent stigmergic coordination through pheromone markers with exponential decay
 - **High Performance**: Optimized Neo4j storage with vector indexing for fast retrieval
 - **MCP Integration**: Seamless integration with Claude Code and other MCP-compatible tools
 
@@ -249,6 +254,11 @@ npm run build
 | `stop_watch_project` | Stop file watching for a project | **Resource management** - stop monitoring |
 | `list_watchers` | List all active file watchers | **Monitoring** - see what's being watched |
 | `natural_language_to_cypher` | Convert natural language to Cypher | **Advanced queries** - complex graph queries |
+| `detect_dead_code` | Find unreferenced exports, uncalled methods, unused interfaces | **Code cleanup** - identify potentially removable code |
+| `detect_duplicate_code` | Find structural and semantic code duplicates | **Refactoring** - identify DRY violations |
+| `swarm_pheromone` | Leave pheromone markers on code nodes | **Multi-agent** - stigmergic coordination |
+| `swarm_sense` | Query pheromones in the code graph | **Multi-agent** - sense what other agents are doing |
+| `swarm_cleanup` | Bulk delete pheromones | **Multi-agent** - cleanup after swarm completion |
 | `test_neo4j_connection` | Verify database connectivity | **Health check** - troubleshooting |
 
 > **Note**: All query tools (`search_codebase`, `traverse_from_node`, `impact_analysis`, `natural_language_to_cypher`) require a `projectId` parameter. Use `list_projects` to discover available projects.
@@ -562,7 +572,155 @@ await mcp.call('test_neo4j_connection');
 APOC plugin available with 438 functions"
 ```
 
-#### 5. File Watching Tools
+#### 5. `detect_dead_code` - Code Cleanup Analysis
+**Purpose**: Identify potentially dead code including unreferenced exports, uncalled private methods, and unused interfaces.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `projectId` | string | required | Project ID, name, or path |
+| `excludePatterns` | string[] | [] | Additional file patterns to exclude (e.g., `["*.config.ts"]`) |
+| `excludeSemanticTypes` | string[] | [] | Additional semantic types to exclude (e.g., `["EntityClass"]`) |
+| `minConfidence` | enum | "LOW" | Minimum confidence: "LOW", "MEDIUM", "HIGH" |
+| `summaryOnly` | boolean | false | Return only statistics, not full list |
+| `limit` | number | 100 | Maximum items to return |
+| `offset` | number | 0 | Pagination offset |
+
+**Response Structure:**
+```json
+{
+  "summary": "Found 15 potentially dead code items",
+  "riskLevel": "MEDIUM",
+  "statistics": {
+    "total": 15,
+    "byConfidence": { "HIGH": 5, "MEDIUM": 7, "LOW": 3 },
+    "byCategory": { "internal-unused": 10, "library-export": 3, "ui-component": 2 },
+    "byType": { "FunctionDeclaration": 8, "InterfaceDeclaration": 4, "MethodDeclaration": 3 }
+  },
+  "deadCode": [
+    {
+      "nodeId": "proj_xxx:FunctionDeclaration:abc123",
+      "name": "unusedHelper",
+      "type": "FunctionDeclaration",
+      "filePath": "/src/utils/helpers.ts",
+      "lineNumber": 42,
+      "confidence": "HIGH",
+      "confidenceReason": "Exported but never imported anywhere",
+      "category": "internal-unused",
+      "reason": "Exported but never imported or referenced"
+    }
+  ]
+}
+```
+
+**Framework-Aware Exclusions:**
+- Automatically excludes NestJS entry points (controllers, modules, guards, etc.)
+- Excludes common entry point files (`main.ts`, `*.module.ts`, `*.controller.ts`)
+- Excludes Next.js/React patterns (`page.tsx`, `layout.tsx`, `route.tsx`)
+
+```typescript
+// Basic usage
+await mcp.call('detect_dead_code', {
+  projectId: 'my-backend'
+});
+
+// High confidence only with custom exclusions
+await mcp.call('detect_dead_code', {
+  projectId: 'my-backend',
+  minConfidence: 'HIGH',
+  excludePatterns: ['*.seed.ts', '*.fixture.ts'],
+  excludeSemanticTypes: ['EntityClass', 'DTOClass']
+});
+```
+
+#### 6. `detect_duplicate_code` - DRY Violation Detection
+**Purpose**: Identify duplicate code using structural (identical AST) and semantic (similar embeddings) analysis.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `projectId` | string | required | Project ID, name, or path |
+| `type` | enum | "all" | Detection type: "structural", "semantic", "all" |
+| `scope` | enum | "all" | Scope: "methods", "functions", "classes", "all" |
+| `minSimilarity` | number | 0.8 | Minimum similarity threshold (0.5-1.0) |
+| `maxResults` | number | 50 | Maximum duplicate groups to return |
+| `includeCode` | boolean | true | Include source code snippets |
+| `summaryOnly` | boolean | false | Return only statistics |
+
+**Response Structure:**
+```json
+{
+  "summary": "Found 8 duplicate code groups across 12 files",
+  "statistics": {
+    "totalGroups": 8,
+    "totalDuplicates": 24,
+    "byType": {
+      "structural": { "groups": 3, "items": 9 },
+      "semantic": { "groups": 5, "items": 15 }
+    },
+    "byConfidence": { "HIGH": 4, "MEDIUM": 3, "LOW": 1 }
+  },
+  "duplicates": [
+    {
+      "groupId": "dup_1",
+      "type": "structural",
+      "similarity": 1.0,
+      "confidence": "HIGH",
+      "category": "cross-file",
+      "recommendation": "Extract to shared utility",
+      "items": [
+        {
+          "nodeId": "proj_xxx:MethodDeclaration:abc",
+          "name": "formatDate",
+          "filePath": "/src/utils/date.ts",
+          "lineNumber": 15,
+          "sourceCode": "formatDate(date: Date): string { ... }"
+        },
+        {
+          "nodeId": "proj_xxx:MethodDeclaration:def",
+          "name": "formatDate",
+          "filePath": "/src/helpers/formatting.ts",
+          "lineNumber": 42,
+          "sourceCode": "formatDate(date: Date): string { ... }"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Detection Types:**
+- **Structural**: Identical normalized code (same AST after removing comments, normalizing names)
+- **Semantic**: Similar logic via vector embeddings (requires embeddings enabled during parse)
+
+**Categories:**
+- `ui-component`: Duplicates in UI component directories
+- `cross-app`: Duplicates across monorepo apps
+- `same-file`: Duplicates within the same file
+- `cross-file`: Duplicates across different files
+
+```typescript
+// Find all duplicates
+await mcp.call('detect_duplicate_code', {
+  projectId: 'my-backend'
+});
+
+// Only structural duplicates in methods
+await mcp.call('detect_duplicate_code', {
+  projectId: 'my-backend',
+  type: 'structural',
+  scope: 'methods'
+});
+
+// High similarity semantic duplicates
+await mcp.call('detect_duplicate_code', {
+  projectId: 'my-backend',
+  type: 'semantic',
+  minSimilarity: 0.9
+});
+```
+
+#### 7. File Watching Tools
 **Purpose**: Monitor file changes and automatically update the graph.
 
 ```typescript
@@ -601,6 +759,67 @@ await mcp.call('stop_watch_project', {
 - 1000 pending events per watcher
 - Graceful cleanup on server shutdown
 
+#### 8. Swarm Coordination Tools
+**Purpose**: Enable multiple parallel agents to coordinate work through stigmergic pheromone markers in the code graph—no direct messaging needed.
+
+**Core Concepts:**
+- **Pheromones**: Markers attached to graph nodes that decay over time
+- **swarmId**: Groups related agents for bulk cleanup when done
+- **Workflow States**: `exploring`, `claiming`, `modifying`, `completed`, `blocked` (mutually exclusive per agent+node)
+- **Flags**: `warning`, `proposal`, `needs_review` (can coexist with workflow states)
+
+**Pheromone Types & Decay:**
+| Type | Half-Life | Use |
+|------|-----------|-----|
+| `exploring` | 2 min | Browsing/reading |
+| `modifying` | 10 min | Active work |
+| `claiming` | 1 hour | Ownership |
+| `completed` | 24 hours | Done |
+| `warning` | Never | Danger |
+| `blocked` | 5 min | Stuck |
+| `proposal` | 1 hour | Awaiting approval |
+| `needs_review` | 30 min | Review requested |
+
+```typescript
+// Orchestrator: Generate swarm ID and spawn agents
+const swarmId = `swarm_${Date.now()}`;
+
+// Agent: Check what's claimed before working
+await mcp.call('swarm_sense', {
+  projectId: 'my-backend',
+  swarmId,
+  types: ['claiming', 'modifying']
+});
+
+// Agent: Claim a node before working
+await mcp.call('swarm_pheromone', {
+  projectId: 'my-backend',
+  nodeId: 'proj_xxx:ClassDeclaration:abc123',  // From search_codebase or traverse_from_node
+  type: 'claiming',
+  agentId: 'agent_1',
+  swarmId
+});
+
+// Agent: Mark complete when done
+await mcp.call('swarm_pheromone', {
+  projectId: 'my-backend',
+  nodeId: 'proj_xxx:ClassDeclaration:abc123',
+  type: 'completed',
+  agentId: 'agent_1',
+  swarmId,
+  data: { summary: 'Added soft delete support' }
+});
+
+// Orchestrator: Clean up when swarm is done
+await mcp.call('swarm_cleanup', {
+  projectId: 'my-backend',
+  swarmId,
+  keepTypes: ['warning']  // Preserve warnings
+});
+```
+
+**Important**: Node IDs must come from graph tool responses (`search_codebase`, `traverse_from_node`). Never fabricate node IDs—they are hash-based strings like `proj_xxx:ClassDeclaration:abc123`.
+
 ### Workflow Examples
 
 #### Example 1: Understanding Authentication Flow

package/dist/constants.js

@@ -1,4 +1,12 @@
 export const MAX_TRAVERSAL_DEPTH = 5;
+// Logging Configuration (shared between core and mcp)
+export const LOG_CONFIG = {
+    debugLogFile: 'debug-search.log',
+    separator: '---',
+    jsonIndent: 2,
+    // Alias for backwards compatibility with mcp code
+    jsonIndentation: 2,
+};
 // Shared exclude patterns for file parsing and change detection
 // Regex patterns (escaped dots, anchored to end)
 export const EXCLUDE_PATTERNS_REGEX = [
@@ -9,6 +17,12 @@ export const EXCLUDE_PATTERNS_REGEX = [
     '\\.d\\.ts$',
     '\\.spec\\.ts$',
     '\\.test\\.ts$',
+    // Common config and test infrastructure files
+    'jest\\.config\\.ts$',
+    '-e2e/',
+    'test-setup\\.ts$',
+    'global-setup\\.ts$',
+    'global-teardown\\.ts$',
 ];
 // Glob patterns for use with glob library
 export const EXCLUDE_PATTERNS_GLOB = [
@@ -19,4 +33,157 @@ export const EXCLUDE_PATTERNS_GLOB = [
     '**/*.d.ts',
     '**/*.spec.ts',
     '**/*.test.ts',
+    // Common config and test infrastructure files
+    '**/jest.config.ts',
+    '**/*-e2e/**',
+    '**/test-setup.ts',
+    '**/global-setup.ts',
+    '**/global-teardown.ts',
 ];
+// ============================================
+// CALLS Edge Detection - Built-in Identifiers
+// Skip these when extracting CALLS edges to reduce noise
+// ============================================
+/** Built-in function names to skip when extracting CALLS edges */
+export const BUILT_IN_FUNCTIONS = new Set([
+    'console',
+    'setTimeout',
+    'setInterval',
+    'clearTimeout',
+    'clearInterval',
+    'parseInt',
+    'parseFloat',
+    'isNaN',
+    'isFinite',
+    'encodeURI',
+    'decodeURI',
+    'encodeURIComponent',
+    'decodeURIComponent',
+    'JSON',
+    'Math',
+    'Date',
+    'Object',
+    'Array',
+    'String',
+    'Number',
+    'Boolean',
+    'Symbol',
+    'BigInt',
+    'Promise',
+    'require',
+    'eval',
+]);
+/** Built-in method names to skip when extracting CALLS edges */
+export const BUILT_IN_METHODS = new Set([
+    // Array methods
+    'push',
+    'pop',
+    'shift',
+    'unshift',
+    'slice',
+    'splice',
+    'concat',
+    'join',
+    'reverse',
+    'sort',
+    'indexOf',
+    'lastIndexOf',
+    'includes',
+    'find',
+    'findIndex',
+    'filter',
+    'map',
+    'reduce',
+    'reduceRight',
+    'every',
+    'some',
+    'forEach',
+    'flat',
+    'flatMap',
+    'fill',
+    'entries',
+    'keys',
+    'values',
+    // String methods
+    'charAt',
+    'charCodeAt',
+    'substring',
+    'substr',
+    'split',
+    'trim',
+    'trimStart',
+    'trimEnd',
+    'toLowerCase',
+    'toUpperCase',
+    'replace',
+    'replaceAll',
+    'match',
+    'search',
+    'startsWith',
+    'endsWith',
+    'padStart',
+    'padEnd',
+    'repeat',
+    // Object methods
+    'hasOwnProperty',
+    'toString',
+    'valueOf',
+    'toJSON',
+    // Promise methods
+    'then',
+    'catch',
+    'finally',
+    // Console methods
+    'log',
+    'error',
+    'warn',
+    'info',
+    'debug',
+    'trace',
+    'dir',
+    'table',
+    // Common utilities
+    'bind',
+    'call',
+    'apply',
+]);
+/** Built-in class names to skip when extracting constructor calls */
+export const BUILT_IN_CLASSES = new Set([
+    'Array',
+    'Object',
+    'String',
+    'Number',
+    'Boolean',
+    'Date',
+    'RegExp',
+    'Error',
+    'TypeError',
+    'RangeError',
+    'SyntaxError',
+    'ReferenceError',
+    'Map',
+    'Set',
+    'WeakMap',
+    'WeakSet',
+    'Promise',
+    'Proxy',
+    'Reflect',
+    'Symbol',
+    'BigInt',
+    'ArrayBuffer',
+    'DataView',
+    'Int8Array',
+    'Uint8Array',
+    'Int16Array',
+    'Uint16Array',
+    'Int32Array',
+    'Uint32Array',
+    'Float32Array',
+    'Float64Array',
+    'URL',
+    'URLSearchParams',
+    'TextEncoder',
+    'TextDecoder',
+    'Buffer',
+    'EventEmitter',
+]);

package/dist/core/config/fairsquare-framework-schema.js

@@ -311,11 +311,12 @@ export const FAIRSQUARE_FRAMEWORK_SCHEMA = {
                             }
                             if (vendorName) {
                                 // Initialize map if not exists
+                                // Store nodeId (string) for serialization support in parallel parsing
                                 if (!sharedContext?.has('vendorControllers')) {
                                     sharedContext?.set('vendorControllers', new Map());
                                 }
                                 const vendorControllerMap = sharedContext?.get('vendorControllers');
-                                vendorControllerMap.set(vendorName, parsedNode);
+                                vendorControllerMap.set(vendorName, parsedNode.id);
                             }
                         }
                         return {};
@@ -747,14 +748,14 @@ export const FAIRSQUARE_FRAMEWORK_SCHEMA = {
                 const isTargetController = parsedTargetNode.semanticType === FairSquareSemanticNodeType.FS_CONTROLLER;
                 if (!isSourceService || !isTargetController)
                     return false;
-                // Get vendor controller map
+                // Get vendor controller map (stores vendorName → nodeId for serialization)
                 const vendorControllerMap = sharedContext?.get('vendorControllers');
                 if (!vendorControllerMap)
                     return false;
-                // Check if target is a vendor controller
+                // Check if target is a vendor controller by matching nodeId
                 let vendorName = '';
-                for (const [name, controllerNode] of vendorControllerMap) {
-                    if (controllerNode.id === parsedTargetNode.id) {
+                for (const [name, nodeId] of vendorControllerMap) {
+                    if (nodeId === parsedTargetNode.id) {
                         vendorName = name;
                         break;
                     }
@@ -768,10 +769,11 @@ export const FAIRSQUARE_FRAMEWORK_SCHEMA = {
                 return propertyTypes.includes(expectedClientName);
             },
             contextExtractor: (parsedSourceNode, parsedTargetNode, allParsedNodes, sharedContext) => {
+                // Map stores vendorName → nodeId
                 const vendorControllerMap = sharedContext?.get('vendorControllers');
                 let vendorName = '';
-                for (const [name, controllerNode] of vendorControllerMap) {
-                    if (controllerNode.id === parsedTargetNode.id) {
+                for (const [name, nodeId] of vendorControllerMap) {
+                    if (nodeId === parsedTargetNode.id) {
                         vendorName = name;
                         break;
                     }

package/dist/core/config/schema.js

@@ -17,6 +17,7 @@ export var CoreNodeType;
     CoreNodeType["ENUM_DECLARATION"] = "EnumDeclaration";
     CoreNodeType["FUNCTION_DECLARATION"] = "FunctionDeclaration";
     CoreNodeType["VARIABLE_DECLARATION"] = "VariableDeclaration";
+    CoreNodeType["TYPE_ALIAS"] = "TypeAlias";
     // Class Members
     CoreNodeType["METHOD_DECLARATION"] = "MethodDeclaration";
     CoreNodeType["PROPERTY_DECLARATION"] = "PropertyDeclaration";
@@ -118,6 +119,7 @@ export const CORE_TYPESCRIPT_SCHEMA = {
         [CoreNodeType.FUNCTION_DECLARATION]: 'getFunctions',
         [CoreNodeType.IMPORT_DECLARATION]: 'getImportDeclarations',
         [CoreNodeType.VARIABLE_DECLARATION]: 'getDeclarations', // Called on VariableStatement
+        [CoreNodeType.TYPE_ALIAS]: 'getTypeAliases',
         [CoreNodeType.ENUM_DECLARATION]: 'getEnums',
         [CoreNodeType.CONSTRUCTOR_DECLARATION]: 'getConstructors',
         [CoreNodeType.EXPORT_DECLARATION]: 'getExportDeclarations',
@@ -154,6 +156,8 @@ export const CORE_TYPESCRIPT_SCHEMA = {
                 [CoreNodeType.FUNCTION_DECLARATION]: CoreEdgeType.CONTAINS,
                 [CoreNodeType.IMPORT_DECLARATION]: CoreEdgeType.CONTAINS,
                 [CoreNodeType.ENUM_DECLARATION]: CoreEdgeType.CONTAINS,
+                [CoreNodeType.VARIABLE_DECLARATION]: CoreEdgeType.CONTAINS,
+                [CoreNodeType.TYPE_ALIAS]: CoreEdgeType.CONTAINS,
             },
             neo4j: {
                 labels: ['SourceFile', 'TypeScript'],
@@ -470,6 +474,12 @@ export const CORE_TYPESCRIPT_SCHEMA = {
                     extraction: { method: 'ast', source: 'getName' },
                     neo4j: { indexed: true, unique: false, required: true },
                 },
+                {
+                    name: 'isExported',
+                    type: 'boolean',
+                    extraction: { method: 'static', defaultValue: false }, // We'll set this manually
+                    neo4j: { indexed: true, unique: false, required: true },
+                },
             ],
             relationships: [],
             children: {},
@@ -480,6 +490,27 @@ export const CORE_TYPESCRIPT_SCHEMA = {
                 skipEmbedding: true,
             },
         },
+        [CoreNodeType.TYPE_ALIAS]: {
+            coreType: CoreNodeType.TYPE_ALIAS,
+            astNodeKind: 265,
+            astGetter: 'getTypeAliases',
+            properties: [
+                {
+                    name: 'name',
+                    type: 'string',
+                    extraction: { method: 'ast', source: 'getName' },
+                    neo4j: { indexed: true, unique: false, required: true },
+                },
+            ],
+            relationships: [],
+            children: {},
+            neo4j: {
+                labels: ['TypeAlias', 'TypeScript'],
+                primaryLabel: 'TypeAlias',
+                indexed: ['name'],
+                skipEmbedding: true,
+            },
+        },
         [CoreNodeType.CONSTRUCTOR_DECLARATION]: {
             coreType: CoreNodeType.CONSTRUCTOR_DECLARATION,
             astNodeKind: 175,
@@ -767,8 +798,16 @@ export const CORE_TYPESCRIPT_SCHEMA = {
         },
         [CoreEdgeType.CALLS]: {
             coreType: CoreEdgeType.CALLS,
-            sourceTypes: [CoreNodeType.METHOD_DECLARATION, CoreNodeType.FUNCTION_DECLARATION],
-            targetTypes: [CoreNodeType.METHOD_DECLARATION, CoreNodeType.FUNCTION_DECLARATION],
+            sourceTypes: [
+                CoreNodeType.METHOD_DECLARATION,
+                CoreNodeType.FUNCTION_DECLARATION,
+                CoreNodeType.CONSTRUCTOR_DECLARATION,
+            ],
+            targetTypes: [
+                CoreNodeType.METHOD_DECLARATION,
+                CoreNodeType.FUNCTION_DECLARATION,
+                CoreNodeType.CONSTRUCTOR_DECLARATION,
+            ],
             properties: [
                 {
                     name: 'confidence',