code-graph-context 1.1.0 → 2.0.1

package/dist/mcp/handlers/traversal.handler.js

@@ -2,40 +2,109 @@
  * Traversal Handler
  * Handles graph traversal operations with formatting and pagination
  */
+import path from 'path';
 import { MAX_TRAVERSAL_DEPTH } from '../../constants.js';
+import { getCommonRoot, normalizeFilePath, toRelativePath } from '../../core/utils/path-utils.js';
 import { QUERIES } from '../../storage/neo4j/neo4j.service.js';
 import { DEFAULTS } from '../constants.js';
-import { createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
+import { createErrorResponse, createSuccessResponse, debugLog, truncateCode } from '../utils.js';
 export class TraversalHandler {
     neo4jService;
-    static NODE_NOT_FOUND_QUERY = 'MATCH (n) WHERE n.id = $nodeId RETURN n';
+    static NODE_NOT_FOUND_QUERY = 'MATCH (n) WHERE n.id = $nodeId AND n.projectId = $projectId RETURN n';
+    static GET_NODE_BY_FILE_PATH_QUERY = 'MATCH (sf:SourceFile {filePath: $filePath}) WHERE sf.projectId = $projectId RETURN sf.id AS nodeId LIMIT 1';
+    // Fallback: search by filePath ending (for partial paths) or by name
+    static GET_NODE_BY_FILE_PATH_FUZZY_QUERY = `
+    MATCH (sf:SourceFile)
+    WHERE sf.projectId = $projectId
+      AND (sf.filePath ENDS WITH $filePath OR sf.filePath ENDS WITH $fileName OR sf.name = $fileName)
+    RETURN sf.id AS nodeId, sf.filePath AS filePath
+    ORDER BY sf.filePath
+    LIMIT 5
+  `;
     constructor(neo4jService) {
         this.neo4jService = neo4jService;
     }
-    async traverseFromNode(nodeId, embedding, options = {}) {
-        const { maxDepth = DEFAULTS.traversalDepth, skip = DEFAULTS.skipOffset, direction = 'BOTH', relationshipTypes, includeStartNodeDetails = true, includeCode = false, maxNodesPerChain = 5, summaryOnly = false, title = `Node Traversal from: ${nodeId}`, snippetLength = DEFAULTS.codeSnippetLength, useWeightedTraversal = false, } = options;
+    /**
+     * Resolves a file path to a SourceFile node ID
+     * Tries exact match first, then fuzzy match by path ending or filename
+     * @param filePath - The file path to look up (can be absolute, relative, or just filename)
+     * @param projectId - The project ID to scope the search
+     * @returns The node ID if found, null otherwise
+     */
+    async resolveNodeIdFromFilePath(filePath, projectId) {
+        // Normalize the input path
+        const normalizedInput = normalizeFilePath(filePath);
+        // Try exact match first with normalized path
+        const exactResult = await this.neo4jService.run(TraversalHandler.GET_NODE_BY_FILE_PATH_QUERY, {
+            filePath: normalizedInput,
+            projectId,
+        });
+        if (exactResult.length > 0) {
+            return exactResult[0].nodeId;
+        }
+        // Extract filename for fuzzy matching using path module
+        const fileName = path.basename(filePath);
+        // For ends-with matching, use the original path without leading ./ or /
+        const pathForMatching = filePath.replace(/^\.[\\/]/, '').replace(/^[\\/]/, '');
+        // Try fuzzy match
+        const fuzzyResult = await this.neo4jService.run(TraversalHandler.GET_NODE_BY_FILE_PATH_FUZZY_QUERY, {
+            filePath: '/' + pathForMatching,
+            fileName,
+            projectId,
+        });
+        if (fuzzyResult.length === 1) {
+            // Single match - use it
+            return fuzzyResult[0].nodeId;
+        }
+        else if (fuzzyResult.length > 1) {
+            // Multiple matches - throw error to let caller provide better guidance
+            await debugLog('Multiple file matches found', {
+                searchPath: filePath,
+                matches: fuzzyResult.map((r) => r.filePath),
+            });
+            const matchList = fuzzyResult.map((r) => `  - ${r.filePath}`).join('\n');
+            throw new Error(`Ambiguous file path "${filePath}" matches multiple files:\n${matchList}\n\nPlease provide a more specific path.`);
+        }
+        return null;
+    }
+    async traverseFromNode(nodeId, embedding, options) {
+        const { projectId, maxDepth = DEFAULTS.traversalDepth, skip = DEFAULTS.skipOffset, limit = 50, direction = 'BOTH', relationshipTypes, includeStartNodeDetails = true, includeCode = false, maxNodesPerChain = 5, summaryOnly = false, title = `Node Traversal from: ${nodeId}`, snippetLength = DEFAULTS.codeSnippetLength, useWeightedTraversal = false, maxTotalNodes = 50, } = options;
         try {
-            await debugLog('Starting node traversal', { nodeId, maxDepth, skip });
-            const startNode = await this.getStartNode(nodeId);
+            await debugLog('Starting node traversal', { nodeId, projectId, maxDepth, skip });
+            const startNode = await this.getStartNode(nodeId, projectId);
             if (!startNode) {
-                return createErrorResponse(`Node with ID "${nodeId}" not found.`);
+                return createErrorResponse(`Node with ID "${nodeId}" not found in project "${projectId}".`);
             }
             const maxNodesPerDepth = Math.ceil(maxNodesPerChain * 1.5);
             const traversalData = useWeightedTraversal
-                ? await this.performTraversalByDepth(nodeId, embedding, maxDepth, maxNodesPerDepth, direction, relationshipTypes)
-                : await this.performTraversal(nodeId, embedding, maxDepth, skip, direction, relationshipTypes);
+                ? await this.performTraversalByDepth(nodeId, projectId, embedding, maxDepth, maxNodesPerDepth, direction, relationshipTypes)
+                : await this.performTraversal(nodeId, projectId, embedding, maxDepth, skip, direction, relationshipTypes);
             if (!traversalData) {
                 return createSuccessResponse(`No connections found for node "${nodeId}".`);
             }
-            const result = summaryOnly
+            let result = summaryOnly
                 ? this.formatSummaryOnlyJSON(startNode, traversalData, title)
-                : this.formatTraversalJSON(startNode, traversalData, title, includeStartNodeDetails, includeCode, maxNodesPerChain, snippetLength);
+                : this.formatTraversalJSON(startNode, traversalData, title, includeStartNodeDetails, includeCode, maxNodesPerChain, snippetLength, maxTotalNodes, skip, limit);
+            // Auto-summarize if output is too large (>50KB)
+            const MAX_OUTPUT_BYTES = 50000;
+            let resultStr = JSON.stringify(result);
+            if (!summaryOnly && resultStr.length > MAX_OUTPUT_BYTES) {
+                await debugLog('Output too large, auto-summarizing', {
+                    originalSize: resultStr.length,
+                    maxSize: MAX_OUTPUT_BYTES,
+                });
+                result = this.formatSummaryOnlyJSON(startNode, traversalData, title);
+                result.autoSummarized = true;
+                result.originalSize = resultStr.length;
+                resultStr = JSON.stringify(result);
+            }
             await debugLog('Traversal completed', {
                 connectionsFound: traversalData.connections.length,
                 uniqueFiles: this.getUniqueFileCount(traversalData.connections),
+                outputSize: resultStr.length,
             });
             return {
-                content: [{ type: 'text', text: JSON.stringify(result) }],
+                content: [{ type: 'text', text: resultStr }],
             };
         }
         catch (error) {
@@ -44,15 +113,23 @@ export class TraversalHandler {
             return createErrorResponse(error);
         }
     }
-    async getStartNode(nodeId) {
-        const startNodeResult = await this.neo4jService.run(TraversalHandler.NODE_NOT_FOUND_QUERY, { nodeId });
+    async getStartNode(nodeId, projectId) {
+        const startNodeResult = await this.neo4jService.run(TraversalHandler.NODE_NOT_FOUND_QUERY, { nodeId, projectId });
         return startNodeResult.length > 0 ? startNodeResult[0].n : null;
     }
-    async performTraversal(nodeId, embedding, maxDepth, skip, direction = 'BOTH', relationshipTypes) {
+    async performTraversal(nodeId, projectId, embedding, maxDepth, skip, direction = 'BOTH', relationshipTypes) {
         const traversal = await this.neo4jService.run(QUERIES.EXPLORE_ALL_CONNECTIONS(Math.min(maxDepth, MAX_TRAVERSAL_DEPTH), direction, relationshipTypes), {
             nodeId,
+            projectId,
             skip: parseInt(skip.toString()),
         });
+        await debugLog('Traversal query executed', {
+            direction,
+            maxDepth,
+            nodeId,
+            resultCount: traversal.length,
+            connectionsCount: traversal[0]?.result?.connections?.length ?? 0,
+        });
         if (traversal.length === 0) {
             return null;
         }
@@ -62,7 +139,7 @@ export class TraversalHandler {
             graph: result.graph ?? { nodes: [], relationships: [] },
         };
     }
-    async performTraversalByDepth(nodeId, embedding, maxDepth, maxNodesPerDepth, direction = 'BOTH', relationshipTypes) {
+    async performTraversalByDepth(nodeId, projectId, embedding, maxDepth, maxNodesPerDepth, direction = 'BOTH', relationshipTypes) {
         // Track visited nodes to avoid cycles
         const visitedNodeIds = new Set([nodeId]);
         // Track the path (chain of relationships) to reach each node
@@ -85,6 +162,7 @@ export class TraversalHandler {
                 currentDepth: parseInt(depth.toString()),
                 queryEmbedding: embedding,
                 depthDecay: 0.85,
+                projectId,
             });
             if (traversalResults.length === 0) {
                 console.log(`No connections found at depth ${depth}`);
@@ -159,33 +237,51 @@ export class TraversalHandler {
     getUniqueFileCount(connections) {
         return new Set(connections.map((c) => c.node.properties.filePath).filter(Boolean)).size;
     }
-    formatTraversalJSON(startNode, traversalData, title, includeStartNodeDetails, includeCode, maxNodesPerChain, snippetLength) {
+    formatTraversalJSON(startNode, traversalData, title, includeStartNodeDetails, includeCode, maxNodesPerChain, snippetLength, maxTotalNodes = 50, skip = 0, limit = 50) {
         // JSON:API normalization - collect all unique nodes
         const nodeMap = new Map();
         // Get common root path from all nodes
-        const allNodes = [startNode, ...traversalData.connections.map((c) => c.node)];
-        const projectRoot = this.getCommonRootPath(allNodes);
+        const allFilePaths = [startNode, ...traversalData.connections.map((c) => c.node)]
+            .map((n) => n.properties.filePath)
+            .filter(Boolean);
+        const projectRoot = getCommonRoot(allFilePaths);
         // Add start node to map
         if (includeStartNodeDetails) {
             const startNodeData = this.formatNodeJSON(startNode, includeCode, snippetLength, projectRoot);
             nodeMap.set(startNode.properties.id, startNodeData);
         }
-        // Collect all unique nodes from connections
-        traversalData.connections.forEach((conn) => {
+        // Collect all unique nodes from connections (limited by maxTotalNodes)
+        let nodeCount = nodeMap.size;
+        let truncatedNodes = 0;
+        for (const conn of traversalData.connections) {
             const nodeId = conn.node.properties.id;
             if (!nodeMap.has(nodeId)) {
+                if (nodeCount >= maxTotalNodes) {
+                    truncatedNodes++;
+                    continue;
+                }
                 nodeMap.set(nodeId, this.formatNodeJSON(conn.node, includeCode, snippetLength, projectRoot));
+                nodeCount++;
             }
-        });
+        }
         const byDepth = this.groupConnectionsByDepth(traversalData.connections);
+        const totalConnections = traversalData.connections.length;
         return {
             projectRoot,
-            totalConnections: traversalData.connections.length,
+            totalConnections,
             uniqueFiles: this.getUniqueFileCount(traversalData.connections),
             maxDepth: Object.keys(byDepth).length > 0 ? Math.max(...Object.keys(byDepth).map((d) => parseInt(d))) : 0,
             startNodeId: includeStartNodeDetails ? startNode.properties.id : undefined,
             nodes: Object.fromEntries(nodeMap),
             depths: this.formatConnectionsByDepthWithReferences(byDepth, maxNodesPerChain),
+            pagination: {
+                skip,
+                limit,
+                returned: nodeMap.size,
+                totalConnections,
+                hasNextPage: skip + limit < totalConnections,
+            },
+            ...(truncatedNodes > 0 && { nodesTruncated: truncatedNodes }),
         };
     }
     formatSummaryOnlyJSON(startNode, traversalData, title) {
@@ -193,13 +289,15 @@ export class TraversalHandler {
         const totalConnections = traversalData.connections.length;
         const maxDepthFound = Object.keys(byDepth).length > 0 ? Math.max(...Object.keys(byDepth).map((d) => parseInt(d))) : 0;
         const uniqueFiles = this.getUniqueFileCount(traversalData.connections);
-        const allNodes = [startNode, ...traversalData.connections.map((c) => c.node)];
-        const projectRoot = this.getCommonRootPath(allNodes);
+        const allFilePaths = [startNode, ...traversalData.connections.map((c) => c.node)]
+            .map((n) => n.properties.filePath)
+            .filter(Boolean);
+        const projectRoot = getCommonRoot(allFilePaths);
         const fileMap = new Map();
         traversalData.connections.forEach((conn) => {
             const filePath = conn.node.properties.filePath;
             if (filePath) {
-                const relativePath = this.makeRelativePath(filePath, projectRoot);
+                const relativePath = toRelativePath(filePath, projectRoot);
                 fileMap.set(relativePath, (fileMap.get(relativePath) ?? 0) + 1);
             }
         });
@@ -224,24 +322,17 @@ export class TraversalHandler {
         const result = {
             id: node.properties.id,
             type: node.properties.semanticType ?? node.labels.at(-1) ?? 'Unknown',
-            filePath: projectRoot ? this.makeRelativePath(node.properties.filePath, projectRoot) : node.properties.filePath,
+            filePath: projectRoot ? toRelativePath(node.properties.filePath, projectRoot) : node.properties.filePath,
         };
         if (node.properties.name) {
             result.name = node.properties.name;
         }
         if (includeCode && node.properties.sourceCode && node.properties.coreType !== 'SourceFile') {
-            const code = node.properties.sourceCode;
-            const maxLength = snippetLength; // Use the provided snippet length
-            if (code.length <= maxLength) {
-                result.sourceCode = code;
-            }
-            else {
-                // Show first half and last half of the snippet
-                const half = Math.floor(maxLength / 2);
-                result.sourceCode =
-                    code.substring(0, half) + '\n\n... [truncated] ...\n\n' + code.substring(code.length - half);
-                result.hasMore = true;
-                result.truncated = code.length - maxLength;
+            const truncateResult = truncateCode(node.properties.sourceCode, snippetLength);
+            result.sourceCode = truncateResult.text;
+            if (truncateResult.hasMore) {
+                result.hasMore = truncateResult.hasMore;
+                result.truncated = truncateResult.truncated;
             }
         }
         return result;
@@ -269,36 +360,4 @@ export class TraversalHandler {
             };
         });
     }
-    getCommonRootPath(nodes) {
-        const filePaths = nodes.map((n) => n.properties.filePath).filter(Boolean);
-        if (filePaths.length === 0)
-            return process.cwd();
-        // Split all paths into parts
-        const pathParts = filePaths.map((p) => p.split('/'));
-        // Find common prefix
-        const commonParts = [];
-        const firstPath = pathParts[0];
-        for (let i = 0; i < firstPath.length; i++) {
-            const part = firstPath[i];
-            if (pathParts.every((p) => p[i] === part)) {
-                commonParts.push(part);
-            }
-            else {
-                break;
-            }
-        }
-        return commonParts.join('/') || '/';
-    }
-    makeRelativePath(absolutePath, projectRoot) {
-        if (!absolutePath)
-            return '';
-        if (!projectRoot || projectRoot === '/')
-            return absolutePath;
-        // Ensure both paths end consistently
-        const root = projectRoot.endsWith('/') ? projectRoot : projectRoot + '/';
-        if (absolutePath.startsWith(root)) {
-            return absolutePath.substring(root.length);
-        }
-        return absolutePath;
-    }
 }

package/dist/mcp/mcp.server.js

@@ -4,10 +4,11 @@
  * MCP Server - Main Entry Point
  * Clean, modular architecture for the Code Graph Context MCP Server
  */
-// Load environment variables from .env file
-import dotenv from 'dotenv';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+// Load environment variables from .env file - must run before other imports use env vars
+// eslint-disable-next-line import/order
+import dotenv from 'dotenv';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Go up two levels from dist/mcp/mcp.server.js to the root
@@ -16,7 +17,9 @@ dotenv.config({ path: join(rootDir, '.env') });
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { MCP_SERVER_CONFIG, MESSAGES } from './constants.js';
-import { initializeServices } from './services.js';
+import { performIncrementalParse } from './handlers/incremental-parse.handler.js';
+import { watchManager } from './services/watch-manager.js';
+import { initializeServices } from './service-init.js';
 import { registerAllTools } from './tools/index.js';
 import { debugLog } from './utils.js';
 /**
@@ -31,9 +34,19 @@ const startServer = async () => {
     });
     // Register all tools
     registerAllTools(server);
-    // Initialize external services (non-blocking)
-    initializeServices().catch((error) => {
-        debugLog('Service initialization error', error);
+    // Configure watch manager with incremental parse handler and MCP server
+    watchManager.setIncrementalParseHandler(performIncrementalParse);
+    watchManager.setMcpServer(server.server);
+    // Initialize external services (non-blocking but with proper error handling)
+    initializeServices().catch(async (error) => {
+        // Await the debugLog to ensure it completes before potential exit
+        await debugLog('Service initialization error', error);
+        // Log to stderr so it's visible even if debug file fails
+        console.error(JSON.stringify({
+            level: 'error',
+            message: 'Service initialization failed',
+            error: error instanceof Error ? error.message : String(error),
+        }));
     });
     // Create and connect transport
     console.error(JSON.stringify({ level: 'info', message: MESSAGES.server.creatingTransport }));
@@ -42,6 +55,32 @@ const startServer = async () => {
     await server.connect(transport);
     console.error(JSON.stringify({ level: 'info', message: MESSAGES.server.connected }));
 };
+/**
+ * Graceful shutdown handler
+ */
+const shutdown = async (signal) => {
+    console.error(JSON.stringify({ level: 'info', message: `Received ${signal}, shutting down...` }));
+    try {
+        await watchManager.stopAllWatchers();
+        await debugLog('Shutdown complete', { signal });
+    }
+    catch (error) {
+        console.error(JSON.stringify({ level: 'error', message: 'Error during shutdown', error: String(error) }));
+    }
+    process.exit(0);
+};
+// Register exception handlers to catch native crashes
+process.on('uncaughtException', async (error) => {
+    console.error(JSON.stringify({ level: 'error', message: 'Uncaught exception', error: String(error), stack: error.stack }));
+    await debugLog('Uncaught exception', { error: String(error), stack: error.stack });
+});
+process.on('unhandledRejection', async (reason) => {
+    console.error(JSON.stringify({ level: 'error', message: 'Unhandled rejection', reason: String(reason) }));
+    await debugLog('Unhandled rejection', { reason: String(reason) });
+});
+// Register shutdown handlers
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));
 // Start the server
 console.error(JSON.stringify({ level: 'info', message: MESSAGES.server.startingServer }));
 await startServer();

package/dist/mcp/service-init.js

@@ -0,0 +1,79 @@
+/**
+ * Service Initialization
+ * Handles initialization of external services like Neo4j schema and OpenAI assistant
+ */
+import fs from 'fs/promises';
+import { join } from 'path';
+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';
+/**
+ * Initialize all external services required by the MCP server
+ */
+export const initializeServices = async () => {
+    await Promise.all([initializeNeo4jSchema(), initializeNaturalLanguageService()]);
+};
+/**
+ * Dynamically discover schema from the actual graph contents.
+ * This is framework-agnostic - it discovers what's actually in the graph.
+ */
+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 from APOC and discovering actual graph structure
+ */
+const initializeNeo4jSchema = async () => {
+    try {
+        const neo4jService = new Neo4jService();
+        const rawSchema = await neo4jService.getSchema();
+        // 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(schema, null, LOG_CONFIG.jsonIndentation));
+        await debugLog('Neo4j schema cached successfully', { schemaPath });
+    }
+    catch (error) {
+        await debugLog('Failed to initialize Neo4j schema', error);
+        // Don't throw - service can still function without cached schema
+    }
+};

package/dist/mcp/services/job-manager.js

@@ -0,0 +1,165 @@
+/**
+ * Job Manager Service
+ * Tracks background parsing jobs for async mode
+ */
+import { randomBytes } from 'crypto';
+const generateJobId = () => {
+    return `job_${randomBytes(8).toString('hex')}`;
+};
+const createInitialProgress = () => ({
+    phase: 'pending',
+    filesTotal: 0,
+    filesProcessed: 0,
+    nodesImported: 0,
+    edgesImported: 0,
+    currentChunk: 0,
+    totalChunks: 0,
+});
+// Cleanup interval: 5 minutes
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+// Maximum concurrent jobs to prevent memory exhaustion
+const MAX_JOBS = 100;
+class JobManager {
+    jobs = new Map();
+    cleanupInterval = null;
+    constructor() {
+        // Start automatic cleanup scheduler
+        this.startCleanupScheduler();
+    }
+    /**
+     * Start the automatic cleanup scheduler.
+     * Runs every 5 minutes to remove old completed/failed jobs.
+     */
+    startCleanupScheduler() {
+        if (this.cleanupInterval)
+            return; // Already running
+        this.cleanupInterval = setInterval(() => {
+            const cleaned = this.cleanupOldJobs();
+            if (cleaned > 0) {
+                console.log(`[JobManager] Cleaned up ${cleaned} old jobs`);
+            }
+        }, CLEANUP_INTERVAL_MS);
+        // Don't prevent Node.js from exiting if this is the only timer
+        this.cleanupInterval.unref();
+    }
+    /**
+     * Stop the cleanup scheduler (useful for testing or shutdown)
+     */
+    stopCleanupScheduler() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+    /**
+     * Create a new parsing job
+     * @throws Error if maximum job limit is reached
+     */
+    createJob(projectPath, projectId) {
+        // SECURITY: Enforce maximum job limit to prevent memory exhaustion
+        if (this.jobs.size >= MAX_JOBS) {
+            // Try to cleanup old jobs first
+            const cleaned = this.cleanupOldJobs(0); // Remove all completed/failed jobs
+            if (this.jobs.size >= MAX_JOBS) {
+                throw new Error(`Maximum job limit (${MAX_JOBS}) reached. ` +
+                    `${this.listJobs('running').length} jobs are currently running. ` +
+                    `Please wait for jobs to complete or cancel existing jobs.`);
+            }
+            if (cleaned > 0) {
+                console.log(`[JobManager] Auto-cleaned ${cleaned} old jobs to make room for new job`);
+            }
+        }
+        const id = generateJobId();
+        const now = new Date();
+        const job = {
+            id,
+            status: 'pending',
+            projectId,
+            projectPath,
+            progress: createInitialProgress(),
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.jobs.set(id, job);
+        return id;
+    }
+    /**
+     * Start a job (transition from pending to running)
+     */
+    startJob(jobId) {
+        const job = this.jobs.get(jobId);
+        if (job) {
+            job.status = 'running';
+            job.updatedAt = new Date();
+        }
+    }
+    /**
+     * Update job progress
+     */
+    updateProgress(jobId, progress) {
+        const job = this.jobs.get(jobId);
+        if (job) {
+            job.progress = { ...job.progress, ...progress };
+            job.updatedAt = new Date();
+        }
+    }
+    /**
+     * Mark job as completed with results
+     */
+    completeJob(jobId, result) {
+        const job = this.jobs.get(jobId);
+        if (job) {
+            job.status = 'completed';
+            job.result = result;
+            job.progress.phase = 'complete';
+            job.updatedAt = new Date();
+        }
+    }
+    /**
+     * Mark job as failed with error message
+     */
+    failJob(jobId, error) {
+        const job = this.jobs.get(jobId);
+        if (job) {
+            job.status = 'failed';
+            job.error = error;
+            job.updatedAt = new Date();
+        }
+    }
+    /**
+     * Get a job by ID
+     */
+    getJob(jobId) {
+        return this.jobs.get(jobId);
+    }
+    /**
+     * List all jobs (optionally filter by status)
+     */
+    listJobs(status) {
+        const jobs = Array.from(this.jobs.values());
+        if (status) {
+            return jobs.filter((job) => job.status === status);
+        }
+        return jobs;
+    }
+    /**
+     * Clean up old completed/failed jobs
+     * @param maxAgeMs Maximum age in milliseconds (default: 1 hour)
+     */
+    cleanupOldJobs(maxAgeMs = 3600000) {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [id, job] of this.jobs.entries()) {
+            if (job.status === 'completed' || job.status === 'failed') {
+                const age = now - job.updatedAt.getTime();
+                if (age > maxAgeMs) {
+                    this.jobs.delete(id);
+                    cleaned++;
+                }
+            }
+        }
+        return cleaned;
+    }
+}
+// Singleton instance
+export const jobManager = new JobManager();