code-graph-context 1.0.0 → 2.0.0

package/dist/core/utils/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 './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 };
+};

package/dist/core/utils/file-utils.js

@@ -0,0 +1,20 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+const DEBUG_LOG_FILE = 'debug-search.log';
+const LOG_SEPARATOR = '---';
+const JSON_INDENT = 2;
+export const hashFile = async (filePath) => {
+    const content = await fs.readFile(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+};
+export const debugLog = async (message, data) => {
+    const timestamp = new Date().toISOString();
+    const logEntry = `[${timestamp}] ${message}\n${data ? JSON.stringify(data, null, JSON_INDENT) : ''}\n${LOG_SEPARATOR}\n`;
+    try {
+        await fs.appendFile(path.join(process.cwd(), DEBUG_LOG_FILE), logEntry);
+    }
+    catch (error) {
+        console.error('Failed to write debug log:', error);
+    }
+};

package/dist/core/utils/index.js

@@ -0,0 +1,3 @@
+export * from './progress-reporter.js';
+export * from './project-id.js';
+export * from './retry.js';

package/dist/core/utils/path-utils.js

@@ -0,0 +1,75 @@
+/**
+ * Path Utilities
+ * Centralized path normalization functions using Node.js path module
+ */
+import path from 'path';
+/**
+ * Normalize a file path to absolute, consistent format
+ * - Resolves relative paths against cwd
+ * - Normalizes separators and removes trailing slashes
+ */
+export const normalizeFilePath = (filePath) => {
+    if (!filePath)
+        return '';
+    // Resolve to absolute if relative
+    const absolute = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+    // Normalize (resolves .. and . segments, consistent separators)
+    return path.normalize(absolute);
+};
+/**
+ * Convert absolute path to relative from a root directory
+ * - Uses path.relative() for correct handling
+ * - Returns absolute if path is outside root
+ */
+export const toRelativePath = (absolutePath, projectRoot) => {
+    if (!absolutePath)
+        return '';
+    if (!projectRoot)
+        return absolutePath;
+    const relative = path.relative(projectRoot, absolutePath);
+    // If relative path starts with '..', it's outside the root - return absolute
+    if (relative.startsWith('..')) {
+        return absolutePath;
+    }
+    return relative;
+};
+/**
+ * Find common root directory from array of file paths
+ * - Uses path.dirname() and path.sep correctly
+ * - Handles edge cases (single file, no common root)
+ */
+export const getCommonRoot = (filePaths) => {
+    const validPaths = filePaths.filter(Boolean);
+    if (validPaths.length === 0)
+        return process.cwd();
+    if (validPaths.length === 1)
+        return path.dirname(validPaths[0]);
+    const parts = validPaths.map((p) => p.split(path.sep));
+    const commonParts = [];
+    for (let i = 0; i < parts[0].length; i++) {
+        const segment = parts[0][i];
+        if (parts.every((p) => p[i] === segment)) {
+            commonParts.push(segment);
+        }
+        else {
+            break;
+        }
+    }
+    return commonParts.join(path.sep) || path.sep;
+};
+/**
+ * Check if a path is absolute
+ * - Cross-platform using path.isAbsolute()
+ */
+export const isAbsolutePath = (filePath) => {
+    return path.isAbsolute(filePath);
+};
+/**
+ * Normalize path for comparison/matching
+ * - Consistent separators using path.normalize()
+ */
+export const normalizeForComparison = (filePath) => {
+    if (!filePath)
+        return '';
+    return path.normalize(filePath);
+};

package/dist/core/utils/progress-reporter.js

@@ -0,0 +1,112 @@
+/**
+ * Progress Reporter
+ * Provides progress updates during long-running operations like parsing large codebases
+ */
+export class ProgressReporter {
+    callback;
+    startTime = Date.now();
+    /**
+     * Set the progress callback function
+     */
+    setCallback(callback) {
+        this.callback = callback;
+        this.startTime = Date.now();
+    }
+    /**
+     * Report progress update
+     */
+    async report(update) {
+        if (!this.callback)
+            return;
+        // Add elapsed time to details
+        const enrichedUpdate = {
+            ...update,
+            details: {
+                ...update.details,
+                elapsedMs: Date.now() - this.startTime,
+            },
+        };
+        try {
+            await this.callback(enrichedUpdate);
+        }
+        catch (error) {
+            // Don't let progress reporting errors interrupt the main operation
+            console.warn('Progress callback error:', error);
+        }
+    }
+    /**
+     * Report discovery phase progress
+     */
+    async reportDiscovery(filesFound, message) {
+        await this.report({
+            phase: 'discovery',
+            current: filesFound,
+            total: filesFound,
+            message: message ?? `Discovered ${filesFound} files`,
+        });
+    }
+    /**
+     * Report parsing phase progress
+     */
+    async reportParsing(current, total, currentFile, chunkIndex, totalChunks) {
+        await this.report({
+            phase: 'parsing',
+            current,
+            total,
+            message: `Parsing files: ${current}/${total}`,
+            details: {
+                filesProcessed: current,
+                currentFile,
+                chunkIndex,
+                totalChunks,
+            },
+        });
+    }
+    /**
+     * Report importing phase progress
+     */
+    async reportImporting(nodesCreated, edgesCreated, total) {
+        await this.report({
+            phase: 'importing',
+            current: nodesCreated + edgesCreated,
+            total,
+            message: `Importing: ${nodesCreated} nodes, ${edgesCreated} edges`,
+            details: {
+                nodesCreated,
+                edgesCreated,
+            },
+        });
+    }
+    /**
+     * Report edge resolution phase
+     */
+    async reportResolving(resolved, total) {
+        await this.report({
+            phase: 'resolving',
+            current: resolved,
+            total,
+            message: `Resolving cross-file edges: ${resolved}/${total}`,
+        });
+    }
+    /**
+     * Report completion
+     */
+    async reportComplete(nodesCreated, edgesCreated) {
+        await this.report({
+            phase: 'complete',
+            current: 1,
+            total: 1,
+            message: `Complete: ${nodesCreated} nodes, ${edgesCreated} edges`,
+            details: {
+                nodesCreated,
+                edgesCreated,
+            },
+        });
+    }
+    /**
+     * Reset the start time (call when starting a new operation)
+     */
+    reset() {
+        this.startTime = Date.now();
+    }
+}

package/dist/core/utils/project-id.js

@@ -0,0 +1,176 @@
+import crypto from 'crypto';
+import { basename, resolve } from 'path';
+/**
+ * Project ID prefix for generated IDs
+ */
+const PROJECT_ID_PREFIX = 'proj_';
+/**
+ * Generates a deterministic projectId from an absolute project path.
+ * The projectId is a short hash that uniquely identifies the project.
+ *
+ * @param projectPath - The absolute path to the project root
+ * @returns A deterministic projectId in format 'proj_<hash>'
+ *
+ * @example
+ * generateProjectId('/Users/dev/my-api') // => 'proj_a1b2c3d4e5f6'
+ */
+export const generateProjectId = (projectPath) => {
+    // Normalize to absolute path
+    const absolutePath = resolve(projectPath);
+    // Create a deterministic hash of the path
+    const hash = crypto.createHash('sha256').update(absolutePath).digest('hex').substring(0, 12);
+    return `${PROJECT_ID_PREFIX}${hash}`;
+};
+/**
+ * Validates that a projectId has the correct format.
+ *
+ * @param projectId - The projectId to validate
+ * @returns true if the projectId is valid, false otherwise
+ *
+ * @example
+ * validateProjectId('proj_a1b2c3d4e5f6') // => true
+ * validateProjectId('invalid') // => false
+ */
+export const validateProjectId = (projectId) => {
+    if (!projectId || typeof projectId !== 'string') {
+        return false;
+    }
+    // Must start with prefix
+    if (!projectId.startsWith(PROJECT_ID_PREFIX)) {
+        return false;
+    }
+    // Must have exactly 12 hex characters after prefix
+    const hash = projectId.slice(PROJECT_ID_PREFIX.length);
+    if (hash.length !== 12) {
+        return false;
+    }
+    // Hash must be valid hex
+    return /^[a-f0-9]{12}$/.test(hash);
+};
+/**
+ * Resolves a projectId from either an explicit value or a project path.
+ * If projectId is provided, it's validated and returned.
+ * If not, generates one from the projectPath.
+ *
+ * @param projectPath - The project path (required)
+ * @param projectId - Optional explicit projectId
+ * @returns The resolved projectId
+ * @throws Error if explicit projectId is invalid
+ *
+ * @example
+ * resolveProjectId('/Users/dev/my-api') // => 'proj_a1b2c3d4e5f6'
+ * resolveProjectId('/Users/dev/my-api', 'proj_custom12345') // => 'proj_custom12345'
+ */
+export const resolveProjectId = (projectPath, projectId) => {
+    if (projectId) {
+        if (!validateProjectId(projectId)) {
+            throw new Error(`Invalid projectId format: '${projectId}'. Expected format: 'proj_<12-hex-chars>' (e.g., 'proj_a1b2c3d4e5f6')`);
+        }
+        return projectId;
+    }
+    return generateProjectId(projectPath);
+};
+/**
+ * Extracts a friendly project name from a path or package.json.
+ * Falls back to directory basename if package.json not available.
+ *
+ * @param projectPath - The project root path
+ * @returns The project name
+ */
+export const getProjectName = async (projectPath) => {
+    const absolutePath = resolve(projectPath);
+    try {
+        // Try to read package.json for the name
+        const fs = await import('fs/promises');
+        const packageJsonPath = `${absolutePath}/package.json`;
+        const content = await fs.readFile(packageJsonPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        if (pkg.name) {
+            return pkg.name;
+        }
+    }
+    catch {
+        // No package.json or invalid - fall back to directory name
+    }
+    // Use directory basename as fallback
+    return basename(absolutePath);
+};
+/**
+ * Query to find project by name, path, or projectId
+ */
+export const FIND_PROJECT_QUERY = `
+  MATCH (p:Project)
+  WHERE p.name = $input OR p.path = $input OR p.projectId = $input
+  RETURN p.projectId AS projectId
+  LIMIT 1
+`;
+/**
+ * Query to create/update a Project node with status
+ */
+export const UPSERT_PROJECT_QUERY = `
+  MERGE (p:Project {projectId: $projectId})
+  SET p.name = $name,
+      p.path = $path,
+      p.status = $status,
+      p.updatedAt = datetime()
+  RETURN p.projectId AS projectId
+`;
+/**
+ * Query to update Project node status after completion/failure
+ */
+export const UPDATE_PROJECT_STATUS_QUERY = `
+  MATCH (p:Project {projectId: $projectId})
+  SET p.status = $status,
+      p.nodeCount = $nodeCount,
+      p.edgeCount = $edgeCount,
+      p.updatedAt = datetime()
+  RETURN p.projectId AS projectId
+`;
+/**
+ * Query to list all projects with status
+ */
+export const LIST_PROJECTS_QUERY = `
+  MATCH (p:Project)
+  RETURN p.projectId AS projectId, p.name AS name, p.path AS path,
+         p.status AS status, p.nodeCount AS nodeCount, p.edgeCount AS edgeCount,
+         p.updatedAt AS updatedAt
+  ORDER BY p.updatedAt DESC
+`;
+/**
+ * Resolves a flexible project input (name, path, or projectId) to a valid projectId.
+ * Looks up the project in Neo4j if needed.
+ *
+ * @param input - Project name ("backend"), path ("/Users/.../backend"), or projectId
+ * @param resolver - Neo4j service or compatible resolver
+ * @returns The resolved projectId
+ * @throws Error if project not found
+ *
+ * @example
+ * // Valid projectId passes through
+ * resolveProjectIdFromInput('proj_a1b2c3d4e5f6', neo4j) // => 'proj_a1b2c3d4e5f6'
+ *
+ * // Name looks up in Neo4j
+ * resolveProjectIdFromInput('backend', neo4j) // => 'proj_a1b2c3d4e5f6'
+ *
+ * // Path looks up in Neo4j, or generates if not found
+ * resolveProjectIdFromInput('/Users/dev/backend', neo4j) // => 'proj_a1b2c3d4e5f6'
+ */
+export const resolveProjectIdFromInput = async (input, resolver) => {
+    // Already valid projectId format? Return as-is
+    if (validateProjectId(input)) {
+        return input;
+    }
+    // Try to find by name or path in Neo4j
+    const result = await resolver.run(FIND_PROJECT_QUERY, { input });
+    if (result.length > 0 && result[0].projectId) {
+        return result[0].projectId;
+    }
+    // If looks like a path, generate the projectId from it
+    // Check for Unix paths (/, ./, ..) and Windows paths (C:\, D:/, etc.)
+    const isUnixPath = input.startsWith('/') || input.startsWith('./') || input.startsWith('..');
+    const isWindowsPath = /^[a-zA-Z]:[\\/]/.test(input);
+    if (isUnixPath || isWindowsPath) {
+        return generateProjectId(input);
+    }
+    throw new Error(`Project not found: "${input}". Run parse_typescript_project first or use list_projects to see available projects.`);
+};

package/dist/core/utils/retry.js

@@ -0,0 +1,41 @@
+/**
+ * Retry utilities with exponential backoff
+ */
+export const DEFAULT_RETRY_OPTIONS = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    shouldRetry: (error) => {
+        // Retry on rate limits and transient errors
+        return (error.status === 429 ||
+            error.code === 'ETIMEDOUT' ||
+            error.message?.includes('timeout') ||
+            error.message?.includes('ECONNRESET'));
+    },
+};
+/**
+ * Execute a function with automatic retry and exponential backoff.
+ * @param fn The async function to execute
+ * @param options Retry configuration options
+ * @returns The result of the function
+ */
+export const withRetry = async (fn, options = {}) => {
+    const opts = { ...DEFAULT_RETRY_OPTIONS, ...options };
+    let lastError;
+    for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === opts.maxRetries || !opts.shouldRetry?.(error)) {
+                throw error;
+            }
+            // Exponential backoff with jitter
+            const delay = Math.min(opts.baseDelayMs * Math.pow(2, attempt) + Math.random() * 1000, opts.maxDelayMs);
+            console.warn(`Retry attempt ${attempt + 1}/${opts.maxRetries} after ${Math.round(delay)}ms. Error: ${error.message}`);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+};

package/dist/core/workspace/index.js

@@ -0,0 +1,4 @@
+/**
+ * Workspace module exports
+ */
+export { WorkspaceDetector } from './workspace-detector.js';