@zuvia-software-solutions/code-mapper 1.4.0

package/dist/core/incremental/watcher.js

@@ -0,0 +1,338 @@
+// code-mapper/src/core/incremental/watcher.ts
+/**
+ * @file File system watcher for incremental refresh
+ * @description Monitors source file changes using fs.watch (recursive) on macOS/Windows,
+ *   falling back to interval-based polling on platforms where recursive watching is
+ *   unavailable (Linux Node <19). Maintains a debounced dirty-file map that the
+ *   refresh scheduler drains on each tick
+ */
+import fs from 'fs';
+import path from 'path';
+import { toRelativeFilePath } from './types.js';
+import { SUPPORTED_EXTENSIONS } from '../../config/supported-languages.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Debounce window in ms — editors emit multiple fs events per save */
+const DEBOUNCE_MS = 500;
+/** Polling interval when recursive watch is unavailable or errors out */
+const POLL_INTERVAL_MS = 2_000;
+/** Directory names to ignore at any depth */
+const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.code-mapper',
+    '__pycache__',
+    '.next',
+    'target',
+    'vendor',
+    '.venv',
+]);
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Check whether any segment in a relative path matches an ignored directory */
+function isIgnoredPath(relativePath) {
+    const segments = relativePath.split('/');
+    return segments.some((seg) => IGNORED_DIRS.has(seg));
+}
+/** Check whether a filename has a supported source extension */
+function hasSupportedExtension(filename) {
+    const ext = path.extname(filename).toLowerCase();
+    return SUPPORTED_EXTENSIONS.has(ext);
+}
+/** Classify a file change by stat-ing the absolute path */
+async function classifyChange(absolutePath, knownBefore) {
+    try {
+        await fs.promises.stat(absolutePath);
+        // File exists now
+        return knownBefore ? 'modified' : 'created';
+    }
+    catch {
+        // File no longer exists
+        return 'deleted';
+    }
+}
+// ---------------------------------------------------------------------------
+// FileSystemWatcher
+// ---------------------------------------------------------------------------
+export class FileSystemWatcher {
+    repoRoot;
+    dirtyFiles = new Map();
+    // Debounce timers keyed by relative path
+    debounceTimers = new Map();
+    // Snapshot state used only by poll-based fallback
+    previousSnapshot = null;
+    // Active watcher / poll handle
+    fsWatcher = null;
+    pollTimer = null;
+    // Track known files so we can distinguish created vs modified
+    knownFiles = new Set();
+    running = false;
+    constructor(repoRoot) {
+        this.repoRoot = repoRoot;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /** Begin watching the repository for source file changes */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Seed knownFiles from the initial filesystem scan
+        await this.seedKnownFiles(this.repoRoot);
+        try {
+            this.startRecursiveWatch();
+        }
+        catch {
+            // Recursive watch unsupported or failed — fall back to polling
+            this.startPolling();
+        }
+    }
+    /** Stop watching and release all resources */
+    stop() {
+        this.running = false;
+        if (this.fsWatcher) {
+            this.fsWatcher.close();
+            this.fsWatcher = null;
+        }
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        // Clear any pending debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+    }
+    /** Returns true when there is at least one dirty file pending */
+    hasDirtyFiles() {
+        return this.dirtyFiles.size > 0 || this.debounceTimers.size > 0;
+    }
+    /**
+     * Flush all pending debounce timers so their changes become immediately
+     * visible in the dirty file map. Must be called before drain() to avoid
+     * missing edits that happened within the debounce window.
+     */
+    async flush() {
+        if (this.debounceTimers.size === 0)
+            return;
+        const pending = [];
+        for (const [relPath, timer] of this.debounceTimers) {
+            clearTimeout(timer);
+            pending.push(this.recordChange(relPath));
+        }
+        this.debounceTimers.clear();
+        await Promise.all(pending);
+    }
+    /**
+     * Re-inject dirty file entries that were previously drained but whose
+     * refresh failed. Ensures the next ensureFresh() retries them.
+     * Existing entries (from new edits since the drain) are NOT overwritten.
+     */
+    inject(entries) {
+        for (const entry of entries) {
+            // Don't overwrite a newer change that arrived after the failed drain
+            if (!this.dirtyFiles.has(entry.relativePath)) {
+                this.dirtyFiles.set(entry.relativePath, entry);
+            }
+        }
+    }
+    /**
+     * Return the current dirty file map and clear it
+     *
+     * Returns null if there are no dirty files, allowing callers to
+     * short-circuit without allocating
+     */
+    drain() {
+        if (this.dirtyFiles.size === 0)
+            return null;
+        const snapshot = new Map(this.dirtyFiles);
+        this.dirtyFiles.clear();
+        return snapshot;
+    }
+    // -------------------------------------------------------------------------
+    // Recursive fs.watch implementation (macOS / Windows)
+    // -------------------------------------------------------------------------
+    startRecursiveWatch() {
+        const watcher = fs.watch(this.repoRoot, { recursive: true }, (eventType, filename) => {
+            if (!filename)
+                return;
+            this.handleRawEvent(filename, eventType);
+        });
+        watcher.on('error', (err) => {
+            // EMFILE = too many open files — degrade gracefully to polling
+            if (err.code === 'EMFILE' || err.code === 'ENOSPC') {
+                watcher.close();
+                this.fsWatcher = null;
+                this.startPolling();
+                return;
+            }
+            // For other errors, log and attempt to continue
+            // The watcher may still be functional after transient errors
+        });
+        this.fsWatcher = watcher;
+    }
+    // -------------------------------------------------------------------------
+    // Raw event handling + debounce
+    // -------------------------------------------------------------------------
+    handleRawEvent(filename, _eventType) {
+        // Normalize to forward-slash relative path
+        const relativePath = filename.replace(/\\/g, '/');
+        if (isIgnoredPath(relativePath))
+            return;
+        if (!hasSupportedExtension(relativePath))
+            return;
+        const relPath = toRelativeFilePath(relativePath);
+        // Cancel any existing debounce timer for this path
+        const existing = this.debounceTimers.get(relPath);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.debounceTimers.delete(relPath);
+            void this.recordChange(relPath);
+        }, DEBOUNCE_MS);
+        this.debounceTimers.set(relPath, timer);
+    }
+    async recordChange(relPath) {
+        const absolutePath = path.join(this.repoRoot, relPath);
+        const wasKnown = this.knownFiles.has(relPath);
+        const changeKind = await classifyChange(absolutePath, wasKnown);
+        // Update known-file tracking
+        if (changeKind === 'deleted') {
+            this.knownFiles.delete(relPath);
+        }
+        else {
+            this.knownFiles.add(relPath);
+        }
+        const entry = {
+            relativePath: relPath,
+            changeKind,
+        };
+        this.dirtyFiles.set(relPath, entry);
+    }
+    // -------------------------------------------------------------------------
+    // Poll-based fallback (Linux Node <19, or after EMFILE)
+    // -------------------------------------------------------------------------
+    startPolling() {
+        if (this.pollTimer)
+            return;
+        // Take an initial snapshot synchronously so the first poll detects diffs
+        this.previousSnapshot = this.takeSnapshotSync(this.repoRoot);
+        this.pollTimer = setInterval(() => {
+            void this.pollOnce();
+        }, POLL_INTERVAL_MS);
+    }
+    async pollOnce() {
+        if (!this.running)
+            return;
+        const current = this.takeSnapshotSync(this.repoRoot);
+        const previous = this.previousSnapshot ?? new Map();
+        // Detect created and modified files
+        for (const [relPath, snap] of current) {
+            const prev = previous.get(relPath);
+            if (!prev) {
+                // New file
+                this.enqueuePollChange(relPath, 'created');
+            }
+            else if (prev.mtimeMs !== snap.mtimeMs || prev.size !== snap.size) {
+                // Modified file
+                this.enqueuePollChange(relPath, 'modified');
+            }
+        }
+        // Detect deleted files
+        for (const relPath of previous.keys()) {
+            if (!current.has(relPath)) {
+                this.enqueuePollChange(relPath, 'deleted');
+            }
+        }
+        this.previousSnapshot = current;
+    }
+    enqueuePollChange(relativePath, changeKind) {
+        const relPath = toRelativeFilePath(relativePath);
+        // Update known-file tracking
+        if (changeKind === 'deleted') {
+            this.knownFiles.delete(relPath);
+        }
+        else {
+            this.knownFiles.add(relPath);
+        }
+        const entry = {
+            relativePath: relPath,
+            changeKind,
+        };
+        this.dirtyFiles.set(relPath, entry);
+    }
+    /**
+     * Walk the repo tree synchronously and collect mtime+size for every
+     * supported source file
+     *
+     * Uses synchronous I/O because this runs on a short interval and needs
+     * a consistent snapshot — async walk would race with itself
+     */
+    takeSnapshotSync(dir, prefix = '') {
+        const result = new Map();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            // Permission denied or directory vanished — skip gracefully
+            return result;
+        }
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry.name))
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                const sub = this.takeSnapshotSync(fullPath, relPath);
+                for (const [k, v] of sub) {
+                    result.set(k, v);
+                }
+            }
+            else if (entry.isFile() && hasSupportedExtension(entry.name)) {
+                try {
+                    const stat = fs.statSync(fullPath);
+                    result.set(relPath, { mtimeMs: stat.mtimeMs, size: stat.size });
+                }
+                catch {
+                    // File vanished between readdir and stat — skip
+                }
+            }
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Seed known files
+    // -------------------------------------------------------------------------
+    /**
+     * Walk the repo tree and populate knownFiles so the first batch of
+     * watcher events can distinguish 'created' from 'modified'
+     */
+    async seedKnownFiles(dir, prefix = '') {
+        let entries;
+        try {
+            entries = await fs.promises.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry.name))
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await this.seedKnownFiles(fullPath, relPath);
+            }
+            else if (entry.isFile() && hasSupportedExtension(entry.name)) {
+                this.knownFiles.add(toRelativeFilePath(relPath));
+            }
+        }
+    }
+}

package/dist/core/ingestion/ast-cache.d.ts

@@ -0,0 +1,12 @@
+/** @file ast-cache.ts @description LRU cache for parsed tree-sitter AST trees with automatic WASM memory cleanup on eviction */
+import Parser from 'tree-sitter';
+export interface ASTCache {
+    get: (filePath: string) => Parser.Tree | undefined;
+    set: (filePath: string, tree: Parser.Tree) => void;
+    clear: () => void;
+    stats: () => {
+        size: number;
+        maxSize: number;
+    };
+}
+export declare const createASTCache: (maxSize?: number) => ASTCache;

package/dist/core/ingestion/ast-cache.js

@@ -0,0 +1,34 @@
+// code-mapper/src/core/ingestion/ast-cache.ts
+/** @file ast-cache.ts @description LRU cache for parsed tree-sitter AST trees with automatic WASM memory cleanup on eviction */
+import { LRUCache } from 'lru-cache';
+export const createASTCache = (maxSize = 50) => {
+    const effectiveMax = Math.max(maxSize, 1);
+    // Dispose handler runs automatically on eviction to free WASM memory
+    const cache = new LRUCache({
+        max: effectiveMax,
+        dispose: (tree) => {
+            try {
+                // web-tree-sitter uses tree.delete(); native trees are GC-managed
+                tree.delete?.();
+            }
+            catch (e) {
+                console.warn('Failed to delete tree from WASM memory', e);
+            }
+        }
+    });
+    return {
+        get: (filePath) => {
+            return cache.get(filePath);
+        },
+        set: (filePath, tree) => {
+            cache.set(filePath, tree);
+        },
+        clear: () => {
+            cache.clear();
+        },
+        stats: () => ({
+            size: cache.size,
+            maxSize: effectiveMax
+        })
+    };
+};

package/dist/core/ingestion/call-processor.d.ts

@@ -0,0 +1,34 @@
+/** @file call-processor.ts @description Resolves function/method call sites to target symbol nodes, supporting sequential AST-based and pre-extracted worker-based paths */
+import { KnowledgeGraph } from '../graph/types.js';
+import { ASTCache } from './ast-cache.js';
+import type { ResolutionContext } from './resolution-context.js';
+import type { ExtractedCall, ExtractedHeritage, ExtractedRoute, FileConstructorBindings } from './workers/parse-worker.js';
+export declare const processCalls: (graph: KnowledgeGraph, files: {
+    path: string;
+    content: string;
+}[], astCache: ASTCache, ctx: ResolutionContext, onProgress?: (current: number, total: number) => void) => Promise<ExtractedHeritage[]>;
+export declare const extractReturnTypeName: (raw: string, depth?: number) => string | undefined;
+/** Resolve pre-extracted call sites from workers (no AST parsing needed) */
+export declare const processCallsFromExtracted: (graph: KnowledgeGraph, extractedCalls: ExtractedCall[], ctx: ResolutionContext, onProgress?: (current: number, total: number) => void, constructorBindings?: FileConstructorBindings[]) => Promise<void>;
+/** Resolve pre-extracted Laravel routes to CALLS edges from route files to controller methods */
+export declare const processRoutesFromExtracted: (graph: KnowledgeGraph, extractedRoutes: ExtractedRoute[], ctx: ResolutionContext, onProgress?: (current: number, total: number) => void) => Promise<void>;
+/**
+ * Create DEPENDS_ON edges from constructor parameter types.
+ *
+ * For each Constructor (or constructor-like method like Python __init__),
+ * resolves its parameterTypes and creates DEPENDS_ON edges from the owning
+ * class to each resolved Class/Interface/Trait/Struct parameter type.
+ *
+ * This bridges DI: BookingService(IPaymentGateway) → DEPENDS_ON → IPaymentGateway
+ */
+export declare const createDependsOnEdges: (graph: KnowledgeGraph, ctx: ResolutionContext) => Promise<number>;
+/**
+ * Create PROVIDES edges from factory method return types.
+ *
+ * For methods/functions whose return type resolves to an Interface or Trait,
+ * creates a PROVIDES edge from the method to the interface. Heuristic filter:
+ * only short methods (< 20 lines) OR methods with DI-related framework annotations.
+ *
+ * This captures @Bean factories, provider methods, and factory functions.
+ */
+export declare const createProvidesEdges: (graph: KnowledgeGraph, ctx: ResolutionContext) => Promise<number>;