@zuvia-software-solutions/code-mapper 1.4.0

package/dist/core/incremental/refresh-coordinator.js

@@ -0,0 +1,147 @@
+// code-mapper/src/core/incremental/refresh-coordinator.ts
+/**
+ * @file refresh-coordinator.ts
+ * @description Parent-side orchestrator that manages child process lifecycle for
+ *   incremental DB refreshes — forks the worker, sends dirty files over IPC,
+ *   and resolves/rejects the caller's promise based on the child's response
+ */
+import { fork } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { parseChildMessage, assertNever, } from './types.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const CHILD_SCRIPT = path.join(__dirname, 'child-process.js');
+/** Default timeout before the child is forcefully terminated */
+const DEFAULT_REFRESH_TIMEOUT_MS = 30_000;
+/** Grace period between SIGTERM and SIGKILL */
+const KILL_GRACE_MS = 5_000;
+// ---------------------------------------------------------------------------
+// Coordinator
+// ---------------------------------------------------------------------------
+export class RefreshCoordinator {
+    /** In-flight refreshes keyed by repo ID — ensures one refresh per repo at a time */
+    inFlight = new Map();
+    /**
+     * Trigger an incremental refresh for the given repo
+     *
+     * If a refresh for this repo is already in progress the existing promise is
+     * returned (deduplication). Otherwise a child process is forked, the dirty
+     * file list is sent over IPC, and the returned promise settles once the child
+     * reports success or failure
+     */
+    async refresh(repo, dirtyFiles, existingPaths, timeoutMs) {
+        const key = repo.id;
+        // Deduplicate — return the existing promise if already refreshing this repo
+        const existing = this.inFlight.get(key);
+        if (existing)
+            return existing;
+        const promise = this.doRefresh(repo, dirtyFiles, existingPaths, timeoutMs).finally(() => {
+            this.inFlight.delete(key);
+        });
+        this.inFlight.set(key, promise);
+        return promise;
+    }
+    // -------------------------------------------------------------------------
+    // Internal
+    // -------------------------------------------------------------------------
+    /**
+     * Core refresh logic — queries existing file paths from the DB, forks the
+     * child process, and wires up IPC + timeout handling
+     */
+    async doRefresh(repo, dirtyFiles, existingPaths, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            // Fork the worker child
+            const child = fork(CHILD_SCRIPT, [], {
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                env: {
+                    ...process.env,
+                    // Pass existing file paths via env so the child has full context
+                    CODE_MAPPER_EXISTING_PATHS: JSON.stringify(existingPaths),
+                },
+            });
+            let settled = false;
+            // -- Cleanup helper ---------------------------------------------------
+            const cleanup = () => {
+                child.removeAllListeners();
+                if (child.stdout)
+                    child.stdout.removeAllListeners();
+                if (child.stderr)
+                    child.stderr.removeAllListeners();
+                clearTimeout(timeoutHandle);
+                clearTimeout(killHandle);
+            };
+            const settle = (action, value) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                if (action === 'resolve') {
+                    resolve(value);
+                }
+                else {
+                    reject(value);
+                }
+            };
+            // -- Timeout handling -------------------------------------------------
+            let killHandle;
+            const effectiveTimeout = timeoutMs ?? DEFAULT_REFRESH_TIMEOUT_MS;
+            const timeoutHandle = setTimeout(() => {
+                // Graceful shutdown first
+                child.kill('SIGTERM');
+                killHandle = setTimeout(() => {
+                    child.kill('SIGKILL');
+                }, KILL_GRACE_MS);
+                settle('reject', new Error(`Incremental refresh timed out after ${effectiveTimeout}ms for repo ${repo.id}`));
+            }, effectiveTimeout);
+            // -- IPC message handling ---------------------------------------------
+            child.on('message', (raw) => {
+                let msg;
+                try {
+                    msg = parseChildMessage(raw);
+                }
+                catch (err) {
+                    settle('reject', new Error(`Invalid IPC message from child: ${err instanceof Error ? err.message : String(err)}`));
+                    child.kill('SIGTERM');
+                    return;
+                }
+                switch (msg.kind) {
+                    case 'progress':
+                        // Progress messages are informational — no action required
+                        break;
+                    case 'success':
+                        settle('resolve', msg.payload);
+                        break;
+                    case 'error':
+                        settle('reject', Object.assign(new Error(msg.message), msg.stack ? { childStack: msg.stack } : {}));
+                        break;
+                    default:
+                        assertNever(msg, `Unhandled child message kind: ${JSON.stringify(msg)}`);
+                }
+            });
+            // -- Child exit handling ----------------------------------------------
+            child.on('error', (err) => {
+                settle('reject', new Error(`Child process error: ${err.message}`));
+            });
+            child.on('exit', (code, signal) => {
+                // If already settled (success/error message arrived first), nothing to do
+                if (settled)
+                    return;
+                if (code !== 0) {
+                    settle('reject', new Error(`Child process exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'none'})`));
+                }
+            });
+            // -- Send the refresh command to the child ----------------------------
+            const message = {
+                kind: 'refresh',
+                payload: {
+                    repoRoot: repo.repoRoot,
+                    dbPath: repo.dbPath,
+                    storagePath: repo.storagePath,
+                    dirtyFiles,
+                },
+            };
+            child.send(message);
+        });
+    }
+}

package/dist/core/incremental/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file Shared type definitions for the incremental refresh system
+ * @description Branded types, discriminated union IPC protocol, boundary validators
+ *
+ * This module is imported by BOTH the parent (MCP server) and child (refresh worker)
+ * processes — it defines the compile-time-safe contract between them
+ */
+declare const __brand: unique symbol;
+type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/** Absolute filesystem path to a source file */
+export type AbsoluteFilePath = Brand<string, 'AbsoluteFilePath'>;
+/** Path relative to repo root (forward-slash normalized, matches graph filePath) */
+export type RelativeFilePath = Brand<string, 'RelativeFilePath'>;
+/** Absolute path to the LadybugDB database directory */
+export type DbPath = Brand<string, 'DbPath'>;
+/** Absolute path to the repository root */
+export type RepoRoot = Brand<string, 'RepoRoot'>;
+/** Stable repo identifier from LocalBackend */
+export type RepoId = Brand<string, 'RepoId'>;
+export declare function toAbsoluteFilePath(p: string): AbsoluteFilePath;
+export declare function toRelativeFilePath(p: string): RelativeFilePath;
+export declare function toDbPath(p: string): DbPath;
+export declare function toRepoRoot(p: string): RepoRoot;
+export declare function toRepoId(s: string): RepoId;
+export declare const FILE_CHANGE_KINDS: readonly ["modified", "created", "deleted"];
+export type FileChangeKind = typeof FILE_CHANGE_KINDS[number];
+/** A single file change detected by the watcher */
+export interface DirtyFileEntry {
+    readonly relativePath: RelativeFilePath;
+    readonly changeKind: FileChangeKind;
+}
+export declare const REFRESH_PHASES: readonly ["deleting-old-nodes", "parsing", "inserting-nodes", "resolving-imports", "resolving-calls", "resolving-heritage", "rebuilding-fts", "done"];
+export type RefreshPhase = typeof REFRESH_PHASES[number];
+/** Payload sent from parent to child to initiate a refresh */
+export interface RefreshPayload {
+    readonly repoRoot: RepoRoot;
+    readonly dbPath: DbPath;
+    readonly storagePath: string;
+    readonly dirtyFiles: readonly DirtyFileEntry[];
+}
+/** Messages from parent to child */
+export type ParentToChildMessage = {
+    readonly kind: 'refresh';
+    readonly payload: RefreshPayload;
+} | {
+    readonly kind: 'shutdown';
+};
+/** Result data returned by a successful refresh */
+export interface RefreshResult {
+    readonly filesProcessed: number;
+    readonly filesSkipped: number;
+    readonly nodesDeleted: number;
+    readonly nodesInserted: number;
+    readonly edgesInserted: number;
+    readonly durationMs: number;
+}
+/** Messages from child to parent */
+export type ChildToParentMessage = {
+    readonly kind: 'progress';
+    readonly phase: RefreshPhase;
+    readonly detail: string;
+} | {
+    readonly kind: 'success';
+    readonly payload: RefreshResult;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+    readonly stack?: string;
+};
+/** Validate and narrow an unknown IPC message from the parent */
+export declare function parseParentMessage(raw: unknown): ParentToChildMessage;
+/** Validate and narrow an unknown IPC message from the child */
+export declare function parseChildMessage(raw: unknown): ChildToParentMessage;
+/** Compile-time exhaustiveness check — use in default/else branches */
+export declare function assertNever(value: never, msg?: string): never;
+export {};

package/dist/core/incremental/types.js

@@ -0,0 +1,153 @@
+// code-mapper/src/core/incremental/types.ts
+/**
+ * @file Shared type definitions for the incremental refresh system
+ * @description Branded types, discriminated union IPC protocol, boundary validators
+ *
+ * This module is imported by BOTH the parent (MCP server) and child (refresh worker)
+ * processes — it defines the compile-time-safe contract between them
+ */
+import path from 'path';
+// Branded constructors with runtime validation
+export function toAbsoluteFilePath(p) {
+    if (!path.isAbsolute(p))
+        throw new TypeError(`Expected absolute path, got: ${p}`);
+    return p;
+}
+export function toRelativeFilePath(p) {
+    if (path.isAbsolute(p))
+        throw new TypeError(`Expected relative path, got: ${p}`);
+    return p.replace(/\\/g, '/');
+}
+export function toDbPath(p) {
+    if (!path.isAbsolute(p))
+        throw new TypeError(`Expected absolute DB path, got: ${p}`);
+    return p;
+}
+export function toRepoRoot(p) {
+    if (!path.isAbsolute(p))
+        throw new TypeError(`Expected absolute repo root, got: ${p}`);
+    return p;
+}
+export function toRepoId(s) {
+    if (!s)
+        throw new TypeError('RepoId cannot be empty');
+    return s;
+}
+// ---------------------------------------------------------------------------
+// File change kinds — const tuple is the single source of truth
+// ---------------------------------------------------------------------------
+export const FILE_CHANGE_KINDS = ['modified', 'created', 'deleted'];
+// ---------------------------------------------------------------------------
+// Refresh phases — const tuple is the single source of truth
+// ---------------------------------------------------------------------------
+export const REFRESH_PHASES = [
+    'deleting-old-nodes',
+    'parsing',
+    'inserting-nodes',
+    'resolving-imports',
+    'resolving-calls',
+    'resolving-heritage',
+    'rebuilding-fts',
+    'done',
+];
+// ---------------------------------------------------------------------------
+// Boundary validators — parse unknown IPC data into typed messages
+// ---------------------------------------------------------------------------
+function isObject(v) {
+    return typeof v === 'object' && v !== null;
+}
+function assertString(v, label) {
+    if (typeof v !== 'string')
+        throw new TypeError(`${label} must be a string, got ${typeof v}`);
+}
+function assertArray(v, label) {
+    if (!Array.isArray(v))
+        throw new TypeError(`${label} must be an array`);
+}
+/** Validate and narrow an unknown IPC message from the parent */
+export function parseParentMessage(raw) {
+    if (!isObject(raw))
+        throw new TypeError('IPC message must be an object');
+    assertString(raw.kind, 'kind');
+    if (raw.kind === 'shutdown')
+        return { kind: 'shutdown' };
+    if (raw.kind === 'refresh') {
+        if (!isObject(raw.payload))
+            throw new TypeError('refresh payload must be an object');
+        const p = raw.payload;
+        assertString(p.repoRoot, 'repoRoot');
+        assertString(p.dbPath, 'dbPath');
+        assertString(p.storagePath, 'storagePath');
+        assertArray(p.dirtyFiles, 'dirtyFiles');
+        const dirtyFiles = [];
+        for (const entry of p.dirtyFiles) {
+            if (!isObject(entry))
+                throw new TypeError('dirtyFiles entry must be an object');
+            assertString(entry.relativePath, 'relativePath');
+            assertString(entry.changeKind, 'changeKind');
+            if (!FILE_CHANGE_KINDS.includes(entry.changeKind)) {
+                throw new TypeError(`Invalid changeKind: ${entry.changeKind}`);
+            }
+            dirtyFiles.push({
+                relativePath: entry.relativePath,
+                changeKind: entry.changeKind,
+            });
+        }
+        return {
+            kind: 'refresh',
+            payload: {
+                repoRoot: p.repoRoot,
+                dbPath: p.dbPath,
+                storagePath: p.storagePath,
+                dirtyFiles,
+            },
+        };
+    }
+    throw new TypeError(`Unknown IPC message kind: ${raw.kind}`);
+}
+/** Validate and narrow an unknown IPC message from the child */
+export function parseChildMessage(raw) {
+    if (!isObject(raw))
+        throw new TypeError('IPC message must be an object');
+    assertString(raw.kind, 'kind');
+    if (raw.kind === 'progress') {
+        assertString(raw.phase, 'phase');
+        if (!REFRESH_PHASES.includes(raw.phase)) {
+            throw new TypeError(`Invalid refresh phase: ${raw.phase}`);
+        }
+        assertString(raw.detail, 'detail');
+        return { kind: 'progress', phase: raw.phase, detail: raw.detail };
+    }
+    if (raw.kind === 'success') {
+        if (!isObject(raw.payload))
+            throw new TypeError('success payload must be an object');
+        const p = raw.payload;
+        return {
+            kind: 'success',
+            payload: {
+                filesProcessed: Number(p.filesProcessed) || 0,
+                filesSkipped: Number(p.filesSkipped) || 0,
+                nodesDeleted: Number(p.nodesDeleted) || 0,
+                nodesInserted: Number(p.nodesInserted) || 0,
+                edgesInserted: Number(p.edgesInserted) || 0,
+                durationMs: Number(p.durationMs) || 0,
+            },
+        };
+    }
+    if (raw.kind === 'error') {
+        assertString(raw.message, 'message');
+        return {
+            kind: 'error',
+            message: raw.message,
+            stack: typeof raw.stack === 'string' ? raw.stack : undefined,
+        };
+    }
+    throw new TypeError(`Unknown child message kind: ${raw.kind}`);
+}
+// ---------------------------------------------------------------------------
+// Exhaustiveness guard
+// ---------------------------------------------------------------------------
+/** Compile-time exhaustiveness check — use in default/else branches */
+export function assertNever(value, msg) {
+    throw new Error(msg ?? `Unexpected value: ${JSON.stringify(value)}`);
+}

package/dist/core/incremental/watcher.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @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 { type RelativeFilePath, type RepoRoot, type DirtyFileEntry } from './types.js';
+export declare class FileSystemWatcher {
+    private readonly repoRoot;
+    private readonly dirtyFiles;
+    private readonly debounceTimers;
+    private previousSnapshot;
+    private fsWatcher;
+    private pollTimer;
+    private readonly knownFiles;
+    private running;
+    constructor(repoRoot: RepoRoot);
+    /** Begin watching the repository for source file changes */
+    start(): Promise<void>;
+    /** Stop watching and release all resources */
+    stop(): void;
+    /** Returns true when there is at least one dirty file pending */
+    hasDirtyFiles(): boolean;
+    /**
+     * 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.
+     */
+    flush(): Promise<void>;
+    /**
+     * 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: readonly DirtyFileEntry[]): void;
+    /**
+     * 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(): ReadonlyMap<RelativeFilePath, DirtyFileEntry> | null;
+    private startRecursiveWatch;
+    private handleRawEvent;
+    private recordChange;
+    private startPolling;
+    private pollOnce;
+    private enqueuePollChange;
+    /**
+     * 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
+     */
+    private takeSnapshotSync;
+    /**
+     * Walk the repo tree and populate knownFiles so the first batch of
+     * watcher events can distinguish 'created' from 'modified'
+     */
+    private seedKnownFiles;
+}