code-graph-context 1.1.0 → 2.0.0

package/dist/core/workspace/workspace-detector.js

@@ -0,0 +1,221 @@
+/**
+ * Workspace Detector
+ * Auto-discovers monorepo structure (Turborepo, pnpm, yarn, npm workspaces)
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+import YAML from 'yaml';
+import { debugLog } from '../utils/file-utils.js';
+export class WorkspaceDetector {
+    /**
+     * Detect workspace configuration from a root path
+     */
+    async detect(rootPath) {
+        const absoluteRoot = path.resolve(rootPath);
+        // Check for different workspace types in order of specificity
+        const type = await this.detectWorkspaceType(absoluteRoot);
+        if (type === 'single') {
+            // Single project, not a monorepo
+            return {
+                type: 'single',
+                rootPath: absoluteRoot,
+                packages: await this.getSingleProjectPackage(absoluteRoot),
+            };
+        }
+        // Get workspace patterns and enumerate packages
+        const patterns = await this.getWorkspacePatterns(absoluteRoot, type);
+        const packages = await this.enumeratePackages(absoluteRoot, patterns);
+        await debugLog('Workspace detected', { type, packageCount: packages.length });
+        return {
+            type,
+            rootPath: absoluteRoot,
+            packages,
+        };
+    }
+    /**
+     * Detect the type of workspace/monorepo
+     */
+    async detectWorkspaceType(rootPath) {
+        // Check for Turborepo (has turbo.json)
+        const turboJsonPath = path.join(rootPath, 'turbo.json');
+        const hasTurboJson = await this.fileExists(turboJsonPath);
+        await debugLog('Checking for turbo.json', { path: turboJsonPath, exists: hasTurboJson });
+        if (hasTurboJson) {
+            return 'turborepo';
+        }
+        // Check for pnpm workspaces (has pnpm-workspace.yaml)
+        const pnpmWorkspacePath = path.join(rootPath, 'pnpm-workspace.yaml');
+        const hasPnpmWorkspace = await this.fileExists(pnpmWorkspacePath);
+        await debugLog('Checking for pnpm-workspace.yaml', { path: pnpmWorkspacePath, exists: hasPnpmWorkspace });
+        if (hasPnpmWorkspace) {
+            return 'pnpm';
+        }
+        // Check package.json for workspaces field
+        const packageJsonPath = path.join(rootPath, 'package.json');
+        if (await this.fileExists(packageJsonPath)) {
+            try {
+                const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
+                if (packageJson.workspaces) {
+                    // Yarn uses workspaces array or object with packages
+                    if (Array.isArray(packageJson.workspaces)) {
+                        return 'yarn';
+                    }
+                    if (packageJson.workspaces.packages) {
+                        return 'yarn';
+                    }
+                    // npm also uses workspaces
+                    return 'npm';
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+        await debugLog('No workspace markers found', { rootPath, result: 'single' });
+        return 'single';
+    }
+    /**
+     * Get workspace glob patterns based on workspace type
+     */
+    async getWorkspacePatterns(rootPath, type) {
+        switch (type) {
+            case 'turborepo':
+            case 'pnpm': {
+                // pnpm-workspace.yaml defines packages
+                const pnpmWorkspacePath = path.join(rootPath, 'pnpm-workspace.yaml');
+                if (await this.fileExists(pnpmWorkspacePath)) {
+                    try {
+                        const content = await fs.readFile(pnpmWorkspacePath, 'utf-8');
+                        const config = YAML.parse(content);
+                        if (config?.packages && Array.isArray(config.packages)) {
+                            return config.packages;
+                        }
+                    }
+                    catch {
+                        // Fall through to defaults
+                    }
+                }
+                // Turborepo default patterns
+                return ['apps/*', 'packages/*'];
+            }
+            case 'yarn':
+            case 'npm': {
+                // Read from package.json workspaces
+                const packageJsonPath = path.join(rootPath, 'package.json');
+                try {
+                    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
+                    if (Array.isArray(packageJson.workspaces)) {
+                        return packageJson.workspaces;
+                    }
+                    if (packageJson.workspaces?.packages) {
+                        return packageJson.workspaces.packages;
+                    }
+                }
+                catch {
+                    // Fall through to defaults
+                }
+                return ['packages/*'];
+            }
+            default:
+                return [];
+        }
+    }
+    /**
+     * Enumerate all packages matching workspace patterns
+     */
+    async enumeratePackages(rootPath, patterns) {
+        const packages = [];
+        const seenPaths = new Set();
+        await debugLog('Enumerating packages with patterns', { patterns, rootPath });
+        for (const pattern of patterns) {
+            // Handle negation patterns (start with !)
+            if (pattern.startsWith('!')) {
+                continue; // Skip negation patterns in enumeration
+            }
+            // Glob for directories matching the pattern
+            const matches = await glob(pattern, {
+                cwd: rootPath,
+                absolute: true,
+                nodir: false,
+                mark: true, // Adds trailing slash to directories
+            });
+            await debugLog('Glob pattern matched', { pattern, matchCount: matches.length, sample: matches.slice(0, 5) });
+            // Filter to only directories (those ending with /)
+            const directories = matches.filter((m) => m.endsWith('/') || !m.includes('.'));
+            await debugLog('After directory filter', { pattern, directoryCount: directories.length });
+            for (const match of directories) {
+                // Remove trailing slash if present
+                const packagePath = match.endsWith('/') ? match.slice(0, -1) : match;
+                // Skip if already seen
+                if (seenPaths.has(packagePath))
+                    continue;
+                seenPaths.add(packagePath);
+                // Check if this is a valid package (has package.json)
+                const packageJsonPath = path.join(packagePath, 'package.json');
+                if (!(await this.fileExists(packageJsonPath))) {
+                    continue;
+                }
+                // Read package name
+                let packageName;
+                try {
+                    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
+                    packageName = packageJson.name ?? path.basename(packagePath);
+                }
+                catch {
+                    packageName = path.basename(packagePath);
+                }
+                // Check for tsconfig
+                const tsConfigPath = path.join(packagePath, 'tsconfig.json');
+                const hasTsConfig = await this.fileExists(tsConfigPath);
+                packages.push({
+                    name: packageName,
+                    path: packagePath,
+                    tsConfigPath: hasTsConfig ? tsConfigPath : null,
+                    relativePath: path.relative(rootPath, packagePath),
+                });
+            }
+        }
+        // Sort by path for consistent ordering
+        packages.sort((a, b) => a.path.localeCompare(b.path));
+        return packages;
+    }
+    /**
+     * Get package info for a single (non-monorepo) project
+     */
+    async getSingleProjectPackage(rootPath) {
+        const packageJsonPath = path.join(rootPath, 'package.json');
+        let packageName = path.basename(rootPath);
+        if (await this.fileExists(packageJsonPath)) {
+            try {
+                const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
+                packageName = packageJson.name ?? packageName;
+            }
+            catch {
+                // Use directory name
+            }
+        }
+        const tsConfigPath = path.join(rootPath, 'tsconfig.json');
+        const hasTsConfig = await this.fileExists(tsConfigPath);
+        return [
+            {
+                name: packageName,
+                path: rootPath,
+                tsConfigPath: hasTsConfig ? tsConfigPath : null,
+                relativePath: '.',
+            },
+        ];
+    }
+    /**
+     * Check if a file exists
+     */
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/mcp/constants.js

@@ -22,6 +22,11 @@ export const TOOL_NAMES = {
     parseTypescriptProject: 'parse_typescript_project',
     testNeo4jConnection: 'test_neo4j_connection',
     impactAnalysis: 'impact_analysis',
+    checkParseStatus: 'check_parse_status',
+    listProjects: 'list_projects',
+    startWatchProject: 'start_watch_project',
+    stopWatchProject: 'stop_watch_project',
+    listWatchers: 'list_watchers',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
@@ -33,6 +38,9 @@ export const TOOL_METADATA = {
         title: 'Search Codebase',
         description: `Search the codebase using semantic similarity to find relevant code, functions, classes, and implementations.
 
+**Before searching:**
+Use list_projects to see available projects and get the project name/ID to search.
+
 Returns normalized JSON with source code snippets. Uses JSON:API pattern to deduplicate nodes.
 
 **Default Usage (Recommended)**:
@@ -53,11 +61,48 @@ Use these parameters ONLY if you encounter token limit errors (>25,000 tokens):
 **Progressive Strategy**:
 1. Try with defaults first
 2. If token error: Use maxDepth=1, includeCode=false for structure
-3. Then traverse deeper or Read specific files for full code`,
+3. Then traverse deeper or Read specific files for full code
+
+**Compact Mode** (for exploration without full source code):
+- includeCode: false → Returns just names, types, and file paths
+- snippetLength: 200 → Smaller code previews
+- maxNodesPerChain: 2 → Fewer relationship chains per depth`,
     },
     [TOOL_NAMES.naturalLanguageToCypher]: {
         title: 'Natural Language to Cypher',
-        description: 'Convert natural language queries into Cypher queries for Neo4j. This tool is useful for generating specific queries based on user requests about the codebase.',
+        description: `Convert natural language queries into Cypher queries for Neo4j.
+
+**Before using:**
+Use list_projects to see available projects and get the project name.
+
+**When to use:**
+- For complex queries that search_codebase can't handle
+- When you need custom filtering or aggregation
+- To explore specific relationship patterns
+
+**Parameters:**
+- projectId: Project name, path, or ID (use list_projects to find)
+- query: Natural language description of what you want to find
+
+**Examples:**
+- "Find all classes with more than 5 methods"
+- "List functions that have more than 3 parameters"
+- "Find files that import from a path containing 'utils'"
+- "Show interfaces with 'Response' in their name"
+- "Find all exported functions"
+
+**Tips:**
+- Import nodes store file paths, not module names (use 'path containing X')
+- Node types: SourceFile, ClassDeclaration, FunctionDeclaration, MethodDeclaration, InterfaceDeclaration
+- Relationships: CONTAINS, IMPORTS, HAS_PARAMETER, IMPLEMENTS, EXTENDS, HAS_MEMBER
+- For NestJS, use semanticType property instead of decorators (e.g., semanticType = 'NestController')
+
+**Query Phrasing:**
+Phrase queries using properties known to exist (filePath, name) rather than abstract concepts:
+- Use "in account folder" or "filePath contains /account/" instead of "in account module"
+- Use "classes extending DbService" not "services that extend DbService" (Service is a decorator, not a type)
+- Use "with name containing 'Controller'" instead of "controllers"
+The tool performs better with concrete, schema-aligned language.`,
     },
     [TOOL_NAMES.traverseFromNode]: {
         title: 'Traverse from Node',
@@ -74,14 +119,41 @@ Advanced options (use when needed):
 - summaryOnly: Set to true for just file paths and statistics without detailed traversal
 
 Best practices:
+- Use list_projects first to see available projects
 - Start with search_codebase to find initial nodes
 - Default includes source code snippets for immediate context
 - Set includeCode: false for high-level architecture view only
-- Use summaryOnly: true for a quick overview of many connections`,
+- Use summaryOnly: true for a quick overview of many connections
+
+**Compact Mode** (for exploration without full source code):
+- summaryOnly: true → Returns only file paths and statistics
+- includeCode: false → Structure without source code
+- snippetLength: 200 → Smaller code previews
+- maxTotalNodes: 20 → Limit total unique nodes returned`,
     },
     [TOOL_NAMES.parseTypescriptProject]: {
         title: 'Parse TypeScript Project',
-        description: 'Parse a TypeScript/NestJS project and store in Neo4j graph',
+        description: `Parse a TypeScript/NestJS project and build a code graph in Neo4j.
+
+**IMPORTANT: Always use async mode for parsing:**
+- Set async: true to avoid timeouts on large codebases
+- Use check_parse_status to monitor progress
+
+**Workflow:**
+1. Call with async: true and projectPath
+2. Note the returned jobId
+3. Poll check_parse_status({ jobId }) until completed
+4. Use list_projects to confirm the project was added
+
+**Parameters:**
+- projectPath (required): Absolute path to the project root
+- async (recommended: true): Run parsing in background
+- clearExisting: Set true to replace existing graph for this project
+- projectId: Optional custom ID (auto-generated from path if omitted)
+
+**Example:**
+parse_typescript_project({ projectPath: "/path/to/project", async: true })
+→ Returns jobId for polling`,
     },
     [TOOL_NAMES.testNeo4jConnection]: {
         title: 'Test Neo4j Connection & APOC',
@@ -91,6 +163,9 @@ Best practices:
         title: 'Impact Analysis',
         description: `Analyze the impact of modifying a code node. Shows what depends on this node and helps assess risk before making changes.
 
+**Before analyzing:**
+Use list_projects to see available projects and get the project name.
+
 Returns:
 - Risk level (LOW/MEDIUM/HIGH/CRITICAL) based on dependency count and relationship types
 - Direct dependents: nodes that directly reference the target
@@ -105,6 +180,78 @@ Parameters:
 
 Use this before refactoring to understand blast radius of changes.`,
     },
+    [TOOL_NAMES.checkParseStatus]: {
+        title: 'Check Parse Status',
+        description: `Check the status of an async parsing job started with parse_typescript_project({ async: true }).
+
+Returns:
+- Job status (pending/running/completed/failed)
+- Progress: phase, files processed, chunks completed
+- Nodes and edges imported so far
+- Final result on completion or error message on failure
+
+Use this to poll for progress when parsing large codebases asynchronously.`,
+    },
+    [TOOL_NAMES.listProjects]: {
+        title: 'List Projects',
+        description: `List all parsed projects in the database with their IDs, names, and paths.
+
+Returns:
+- projectId: The full project ID (e.g., "proj_a1b2c3d4e5f6")
+- name: Friendly project name from package.json (e.g., "backend")
+- path: Full filesystem path to the project
+- updatedAt: When the project was last parsed
+
+Use the name or path in other tools instead of the cryptic projectId.`,
+    },
+    [TOOL_NAMES.startWatchProject]: {
+        title: 'Start Watch Project',
+        description: `Start watching a project for file changes and automatically update the graph.
+
+**Parameters:**
+- projectPath (required): Absolute path to the project root
+- tsconfigPath (required): Path to tsconfig.json
+- projectId (optional): Custom project ID (auto-generated if omitted)
+- debounceMs (optional): Delay before processing changes (default: 1000ms)
+
+**Behavior:**
+- Watches for .ts file changes (add/change/delete)
+- Automatically triggers incremental graph updates
+- Sends MCP notifications for progress updates
+- Excludes node_modules, dist, build, .git, *.d.ts, *.js
+
+**Usage:**
+start_watch_project({ projectPath: "/path/to/project", tsconfigPath: "/path/to/project/tsconfig.json" })
+
+Use list_watchers to see active watchers, stop_watch_project to stop.`,
+    },
+    [TOOL_NAMES.stopWatchProject]: {
+        title: 'Stop Watch Project',
+        description: `Stop watching a project for file changes.
+
+**Parameters:**
+- projectId (required): Project ID to stop watching
+
+**Usage:**
+stop_watch_project({ projectId: "proj_abc123..." })
+
+Use list_watchers to see active watchers.`,
+    },
+    [TOOL_NAMES.listWatchers]: {
+        title: 'List Watchers',
+        description: `List all active file watchers.
+
+Returns information about each watcher:
+- projectId: The project being watched
+- projectPath: File system path
+- status: active, paused, or error
+- debounceMs: Configured debounce delay
+- pendingChanges: Number of queued file changes
+- lastUpdateTime: When the graph was last updated
+- errorMessage: Error details if status is "error"
+
+Use stop_watch_project to stop a watcher.`,
+    },
 };
 // Default Values
 export const DEFAULTS = {
@@ -112,8 +259,9 @@ export const DEFAULTS = {
     skipOffset: 0,
     batchSize: 500,
     maxResultsDisplayed: 30,
-    codeSnippetLength: 1000,
+    codeSnippetLength: 500, // Reduced from 1000 to control output size
     chainSnippetLength: 700,
+    maxEmbeddingChars: 30000, // ~7500 tokens, under 8192 limit for text-embedding-3-large
 };
 // Messages
 export const MESSAGES = {

package/dist/mcp/handlers/cross-file-edge.helpers.js

@@ -0,0 +1,19 @@
+/**
+ * Cross-File Edge Helpers
+ * Shared utilities for managing cross-file edges during incremental parsing
+ */
+import { QUERIES } from '../../storage/neo4j/neo4j.service.js';
+export const deleteSourceFileSubgraphs = async (neo4jService, filePaths, projectId) => {
+    await neo4jService.run(QUERIES.DELETE_SOURCE_FILE_SUBGRAPHS, { filePaths, projectId });
+};
+export const loadExistingNodesForEdgeDetection = async (neo4jService, excludeFilePaths, projectId) => {
+    const queryResult = await neo4jService.run(QUERIES.GET_EXISTING_NODES_FOR_EDGE_DETECTION, {
+        excludeFilePaths,
+        projectId,
+    });
+    return queryResult;
+};
+export const getCrossFileEdges = async (neo4jService, filePaths, projectId) => {
+    const queryResult = await neo4jService.run(QUERIES.GET_CROSS_FILE_EDGES, { filePaths, projectId });
+    return queryResult;
+};

package/dist/mcp/handlers/file-change-detection.js

@@ -0,0 +1,105 @@
+/**
+ * File Change Detection
+ * Shared utilities for detecting changed files for incremental parsing
+ */
+import { stat, realpath } from 'fs/promises';
+import { resolve, sep } from 'path';
+import { glob } from 'glob';
+import { EXCLUDE_PATTERNS_GLOB } from '../../constants.js';
+import { QUERIES } from '../../storage/neo4j/neo4j.service.js';
+import { hashFile } from '../../utils/file-utils.js';
+/**
+ * Detect which files have changed and need reparsing.
+ * Compares current files on disk with indexed files in Neo4j.
+ *
+ * SECURITY: Validates that all file paths stay within the project directory
+ * after symlink resolution to prevent path traversal attacks.
+ *
+ * @param projectPath - Root path of the project
+ * @param neo4jService - Neo4j service instance
+ * @param projectId - Project ID for scoping queries
+ * @param options - Optional configuration
+ * @returns Files that need reparsing and files that were deleted
+ */
+export const detectChangedFiles = async (projectPath, neo4jService, projectId, options = {}) => {
+    const { logWarnings = true } = options;
+    // SECURITY: Resolve project path to real path to handle symlinks consistently
+    const realProjectPath = await realpath(projectPath);
+    const relativeFiles = await glob('**/*.{ts,tsx}', { cwd: projectPath, ignore: EXCLUDE_PATTERNS_GLOB });
+    // SECURITY: Validate each file stays within project directory after symlink resolution
+    const validatedFiles = [];
+    for (const relFile of relativeFiles) {
+        const absolutePath = resolve(projectPath, relFile);
+        try {
+            const realFilePath = await realpath(absolutePath);
+            // Check that resolved path is within project
+            if (realFilePath.startsWith(realProjectPath + sep) || realFilePath === realProjectPath) {
+                // Use realFilePath for consistent path matching with Neo4j
+                validatedFiles.push(realFilePath);
+            }
+            else if (logWarnings) {
+                console.warn(`SECURITY: Skipping file outside project directory: ${relFile}`);
+            }
+        }
+        catch {
+            // File may have been deleted between glob and realpath - skip it
+            if (logWarnings) {
+                console.warn(`File no longer accessible: ${relFile}`);
+            }
+        }
+    }
+    const currentFiles = new Set(validatedFiles);
+    // Get indexed files from Neo4j
+    const queryResult = await neo4jService.run(QUERIES.GET_SOURCE_FILE_TRACKING_INFO, { projectId });
+    const indexedFiles = queryResult;
+    const indexedMap = new Map(indexedFiles.map((f) => [f.filePath, f]));
+    const filesToReparse = [];
+    const filesToDelete = [];
+    // Check each current file against indexed state
+    for (const filePath of currentFiles) {
+        const indexed = indexedMap.get(filePath);
+        if (!indexed) {
+            // New file - needs parsing
+            filesToReparse.push(filePath);
+            continue;
+        }
+        try {
+            const fileStats = await stat(filePath);
+            const currentHash = await hashFile(filePath);
+            // Only skip if mtime, size, AND hash all match (correctness over optimization)
+            if (fileStats.mtimeMs === indexed.mtime &&
+                fileStats.size === indexed.size &&
+                currentHash === indexed.contentHash) {
+                continue;
+            }
+            // Any mismatch means file changed
+            filesToReparse.push(filePath);
+        }
+        catch (error) {
+            const nodeError = error;
+            if (nodeError.code === 'ENOENT') {
+                // File was deleted between glob and stat - will be caught in deletion logic below
+                if (logWarnings) {
+                    console.warn(`File deleted between glob and stat: ${filePath}`);
+                }
+            }
+            else if (nodeError.code === 'EACCES') {
+                // Permission denied - assume changed to be safe
+                if (logWarnings) {
+                    console.warn(`Permission denied reading file: ${filePath}`);
+                }
+                filesToReparse.push(filePath);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    // Find deleted files (indexed but no longer on disk)
+    for (const indexedPath of indexedMap.keys()) {
+        if (!currentFiles.has(indexedPath)) {
+            filesToDelete.push(indexedPath);
+        }
+    }
+    return { filesToReparse, filesToDelete };
+};