@zuvia-software-solutions/code-mapper 1.4.0 → 2.0.1

package/dist/core/semantic/tsgo-service.js

@@ -13,9 +13,15 @@
  *
  * Optional — only starts if the `@typescript/native-preview` package is installed.
  */
-import { spawn } from 'child_process';
+import { spawn, execFileSync } from 'child_process';
+import { createRequire } from 'module';
 import fs from 'fs';
 import path from 'path';
+const esmRequire = createRequire(import.meta.url);
+function verbose(...args) {
+    if (process.env['CODE_MAPPER_VERBOSE'])
+        console.error('[tsgo]', ...args);
+}
 // ---------------------------------------------------------------------------
 // LSP message helpers
 // ---------------------------------------------------------------------------
@@ -28,8 +34,9 @@ function encodeLSP(msg) {
 // ---------------------------------------------------------------------------
 export class TsgoService {
     process = null;
-    buf = '';
     responses = new Map();
+    /** Pending resolve callbacks keyed by request ID — event-driven, no polling */
+    pending = new Map();
     nextId = 1;
     projectRoot;
     tsgoPath = null;
@@ -52,32 +59,50 @@ export class TsgoService {
         this.initPromise = this.doStart();
         return this.initPromise;
     }
+    /** Get the resolved project root (where tsconfig.json was found) */
+    getProjectRoot() {
+        return this.projectRoot;
+    }
     /** Whether the server is running and ready for queries */
     isReady() {
         return this.ready;
     }
     /** Resolve what a symbol at a given position points to (go-to-definition) */
     async resolveDefinition(absFilePath, line, character) {
-        if (!this.ready)
+        if (!this.ready) {
+            console.error('[tsgo-service] resolveDefinition called but not ready');
             return null;
+        }
         await this.ensureOpen(absFilePath);
         const resp = await this.request('textDocument/definition', {
             textDocument: { uri: this.fileUri(absFilePath) },
             position: { line, character },
-        });
-        if (!resp)
+        }, 3000);
+        if (!resp) {
+            verbose('definition timeout', absFilePath, line, character);
             return null;
-        const result = resp.result;
-        if (!result)
+        }
+        if (resp['error']) {
+            verbose('definition error', resp['error']);
+            return null;
+        }
+        const result = resp['result'];
+        if (!result) {
+            verbose('definition null result', absFilePath, line);
             return null;
+        }
         const defs = Array.isArray(result) ? result : [result];
-        if (defs.length === 0)
+        if (defs.length === 0) {
+            verbose('definition empty', absFilePath, line);
             return null;
+        }
         const d = defs[0];
         const uri = d.uri || d.targetUri || '';
         const range = d.range || d.targetSelectionRange;
-        if (!uri || !range)
+        if (!uri || !range) {
+            verbose('definition missing uri/range', d);
             return null;
+        }
         return {
             filePath: this.uriToRelative(uri),
             line: range.start.line,
@@ -94,14 +119,17 @@ export class TsgoService {
             position: { line, character },
             context: { includeDeclaration: false },
         });
-        if (!resp?.result)
+        if (!resp?.['result'])
             return [];
-        const refs = resp.result;
-        return refs.map((r) => ({
-            filePath: this.uriToRelative(r.uri),
-            line: r.range.start.line,
-            character: r.range.start.character,
-        }));
+        const refs = resp['result'];
+        return refs.map((r) => {
+            const range = r['range'];
+            return {
+                filePath: this.uriToRelative(r['uri']),
+                line: range.start.line,
+                character: range.start.character,
+            };
+        });
     }
     /** Get the type signature at a position (hover) */
     async getHover(absFilePath, line, character) {
@@ -112,17 +140,23 @@ export class TsgoService {
             textDocument: { uri: this.fileUri(absFilePath) },
             position: { line, character },
         });
-        if (!resp?.result)
+        if (!resp?.['result'])
             return null;
-        const contents = resp.result.contents;
+        const contents = resp['result']['contents'];
         if (!contents)
             return null;
         if (typeof contents === 'string')
             return contents;
-        if (contents.value)
-            return contents.value;
-        if (Array.isArray(contents))
-            return contents.map((c) => c.value || c).join('\n');
+        if (typeof contents === 'object' && !Array.isArray(contents) && 'value' in contents) {
+            return contents['value'];
+        }
+        if (Array.isArray(contents)) {
+            return contents.map((c) => {
+                if (typeof c === 'object' && c !== null && 'value' in c)
+                    return c['value'];
+                return c;
+            }).join('\n');
+        }
         return null;
     }
     /** Notify tsgo that a file changed (call after editing a file) */
@@ -158,6 +192,30 @@ export class TsgoService {
             this.openFiles.delete(uri);
         }
     }
+    /** Pre-open multiple files in one batch (fire-and-forget, no await per file) */
+    preOpenFiles(absFilePaths) {
+        if (!this.ready)
+            return;
+        for (const absPath of absFilePaths) {
+            const uri = this.fileUri(absPath);
+            if (this.openFiles.has(uri))
+                continue;
+            try {
+                const content = fs.readFileSync(absPath, 'utf-8');
+                this.send({
+                    jsonrpc: '2.0',
+                    method: 'textDocument/didOpen',
+                    params: {
+                        textDocument: { uri, languageId: 'typescript', version: 1, text: content },
+                    },
+                });
+                this.openFiles.add(uri);
+            }
+            catch {
+                // File may not exist or be unreadable — skip silently
+            }
+        }
+    }
     /** Stop the tsgo process */
     stop() {
         if (this.process && !this.process.killed) {
@@ -177,14 +235,19 @@ export class TsgoService {
         this.initPromise = null;
         this.openFiles.clear();
         this.responses.clear();
+        // Resolve all pending requests as null (timed out)
+        for (const cb of this.pending.values()) {
+            cb({ id: -1, error: { message: 'tsgo stopped' } });
+        }
+        this.pending.clear();
     }
     // ── Internal ────────────────────────────────────────────────────────
     async doStart() {
-        // Find the tsgo binary
+        // Find the tsgo binary — fail fast if not found
         this.tsgoPath = this.findTsgoBinary();
         if (!this.tsgoPath) {
-            console.error('Code Mapper: tsgo not found — install @typescript/native-preview for semantic resolution');
-            return false;
+            throw new Error('tsgo binary not found. Install: npm install -D @typescript/native-preview\n' +
+                'Or remove --tsgo flag to disable semantic resolution.');
         }
         try {
             this.process = spawn(this.tsgoPath, ['--lsp', '--stdio'], {
@@ -192,8 +255,13 @@ export class TsgoService {
                 cwd: this.projectRoot,
             });
             this.process.stdout.on('data', (chunk) => this.onData(chunk));
-            this.process.stderr.on('data', () => { }); // suppress
-            this.process.on('exit', () => {
+            this.process.stderr.on('data', (chunk) => {
+                const msg = chunk.toString().trim();
+                if (msg)
+                    console.error(`[tsgo-service] stderr: ${msg}`);
+            });
+            this.process.on('exit', (code, signal) => {
+                console.error(`[tsgo-service] process exited (code=${code}, signal=${signal})`);
                 this.ready = false;
                 this.process = null;
             });
@@ -210,9 +278,8 @@ export class TsgoService {
                 rootUri: `file://${this.projectRoot}`,
             });
             if (!initResp) {
-                console.error('Code Mapper: tsgo LSP initialize timed out');
                 this.stop();
-                return false;
+                throw new Error('tsgo LSP initialize timed out — the project may be too large or tsgo crashed');
             }
             // Send initialized notification
             this.send({ jsonrpc: '2.0', method: 'initialized', params: {} });
@@ -227,51 +294,73 @@ export class TsgoService {
         }
     }
     findTsgoBinary() {
-        // Try resolving via the @typescript/native-preview package
+        // Try resolving via the @typescript/native-preview platform package
         try {
-            const platform = process.platform;
-            const arch = process.arch;
-            const pkgName = `@typescript/native-preview-${platform}-${arch}`;
-            const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
+            const pkgName = `@typescript/native-preview-${process.platform}-${process.arch}`;
+            const pkgJsonPath = esmRequire.resolve(`${pkgName}/package.json`);
             const exe = path.join(path.dirname(pkgJsonPath), 'lib', 'tsgo');
             if (fs.existsSync(exe))
                 return exe;
         }
         catch { }
-        // Try npx tsgo path
+        // Try which/where
         try {
-            const { execFileSync } = require('child_process');
-            const result = execFileSync('which', ['tsgo'], { encoding: 'utf-8', timeout: 3000 }).trim();
+            const cmd = process.platform === 'win32' ? 'where' : 'which';
+            const result = execFileSync(cmd, ['tsgo'], { encoding: 'utf-8', timeout: 3000 }).trim();
             if (result && fs.existsSync(result))
                 return result;
         }
         catch { }
         return null;
     }
+    rawBuf = Buffer.alloc(0);
     onData(chunk) {
-        this.buf += chunk.toString();
+        // Accumulate raw bytes — Content-Length is byte count, not character count
+        this.rawBuf = Buffer.concat([this.rawBuf, chunk]);
         while (true) {
-            const m = this.buf.match(/Content-Length: (\d+)\r\n\r\n([\s\S]*)/);
-            if (!m)
+            // Find header/body separator
+            const sep = this.rawBuf.indexOf('\r\n\r\n');
+            if (sep === -1)
                 break;
-            const len = parseInt(m[1]);
-            if (m[2].length < len)
+            // Parse Content-Length from header section
+            const header = this.rawBuf.subarray(0, sep).toString('ascii');
+            const lenMatch = header.match(/Content-Length:\s*(\d+)/i);
+            if (!lenMatch?.[1]) {
+                // Malformed header — skip past separator and retry
+                this.rawBuf = this.rawBuf.subarray(sep + 4);
+                continue;
+            }
+            const bodyLen = parseInt(lenMatch[1], 10);
+            const bodyStart = sep + 4; // after \r\n\r\n
+            // Wait for full body to arrive
+            if (this.rawBuf.length < bodyStart + bodyLen)
                 break;
-            const body = m[2].slice(0, len);
-            this.buf = m[2].slice(len);
+            // Extract body bytes and advance buffer
+            const bodyBuf = this.rawBuf.subarray(bodyStart, bodyStart + bodyLen);
+            this.rawBuf = this.rawBuf.subarray(bodyStart + bodyLen);
             try {
-                const msg = JSON.parse(body);
-                if (msg.id !== undefined && msg.method) {
+                const msg = JSON.parse(bodyBuf.toString('utf-8'));
+                if (msg['id'] !== undefined && msg['method']) {
                     // Server request (e.g., client/registerCapability) — acknowledge
-                    this.send({ jsonrpc: '2.0', id: msg.id, result: null });
+                    this.send({ jsonrpc: '2.0', id: msg['id'], result: null });
                 }
-                else if (msg.id !== undefined) {
-                    // Response to our request
-                    this.responses.set(msg.id, msg);
+                else if (msg['id'] !== undefined) {
+                    // Response to our request — dispatch to pending callback immediately
+                    const id = msg['id'];
+                    const cb = this.pending.get(id);
+                    if (cb) {
+                        cb(msg);
+                    }
+                    else {
+                        // Callback not registered yet — store for pickup
+                        this.responses.set(id, msg);
+                    }
                 }
                 // Notifications (no id, has method) are ignored
             }
-            catch { }
+            catch (err) {
+                console.error(`[tsgo-service] onData parse error: ${err instanceof Error ? err.message : err}`);
+            }
         }
     }
     send(msg) {
@@ -280,24 +369,31 @@ export class TsgoService {
         try {
             this.process.stdin.write(encodeLSP(msg));
         }
-        catch { }
+        catch (err) {
+            console.error(`[tsgo-service] send error: ${err instanceof Error ? err.message : err}`);
+        }
     }
-    request(method, params, timeoutMs = 15000) {
+    request(method, params, timeoutMs = 30000) {
         const id = this.nextId++;
         this.send({ jsonrpc: '2.0', id, method, params });
         return new Promise((resolve) => {
-            const start = Date.now();
-            const check = () => {
-                if (this.responses.has(id)) {
-                    const resp = this.responses.get(id);
-                    this.responses.delete(id);
-                    return resolve(resp);
-                }
-                if (Date.now() - start > timeoutMs)
-                    return resolve(null);
-                setTimeout(check, 20);
-            };
-            check();
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                resolve(null);
+            }, timeoutMs);
+            this.pending.set(id, (resp) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve(resp);
+            });
+            // Check if response already arrived before we registered the callback
+            if (this.responses.has(id)) {
+                const resp = this.responses.get(id);
+                this.responses.delete(id);
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve(resp);
+            }
         });
     }
     async ensureOpen(absFilePath) {
@@ -319,8 +415,11 @@ export class TsgoService {
                 },
             });
             this.openFiles.add(uri);
+            verbose('opened', absFilePath);
+        }
+        catch (err) {
+            verbose('ensureOpen FAILED', absFilePath, err instanceof Error ? err.message : err);
         }
-        catch { }
     }
     fileUri(absPath) {
         return `file://${absPath}`;

package/dist/lib/tsgo-test.d.ts

@@ -0,0 +1,2 @@
+/** tsgo test: calls generateId cross-file — should get confidence 1.0 edge */
+export declare function makeNodeId(label: string, name: string): string;

package/dist/lib/tsgo-test.js

@@ -0,0 +1,6 @@
+import { generateId } from './utils.js';
+/** tsgo test: calls generateId cross-file — should get confidence 1.0 edge */
+export function makeNodeId(label, name) {
+    const id = generateId(label, name);
+    return `verified-${id}`;
+}

package/dist/lib/type-utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file Shared type-level utilities — single source of truth.
+ *
+ * Brand<T, B>     — nominal branding for stringly-typed values
+ * assertNever()   — exhaustiveness guard for switch/if chains
+ */
+declare const __brand: unique symbol;
+/**
+ * Nominal brand: `Brand<string, 'Foo'>` is assignable FROM nothing
+ * except via an explicit constructor that validates at runtime.
+ */
+export type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/**
+ * Compile-time exhaustiveness check.
+ *
+ * Place in the `default` / final `else` branch of a switch/if chain
+ * over a discriminated union.  If a variant is unhandled the compiler
+ * will error because `value` won't narrow to `never`.
+ *
+ * Also throws at runtime as a safety net.
+ */
+export declare function assertNever(value: never, msg?: string): never;
+export {};

package/dist/lib/type-utils.js

@@ -0,0 +1,22 @@
+// code-mapper/src/lib/type-utils.ts
+/**
+ * @file Shared type-level utilities — single source of truth.
+ *
+ * Brand<T, B>     — nominal branding for stringly-typed values
+ * assertNever()   — exhaustiveness guard for switch/if chains
+ */
+// ---------------------------------------------------------------------------
+// Exhaustiveness guard
+// ---------------------------------------------------------------------------
+/**
+ * Compile-time exhaustiveness check.
+ *
+ * Place in the `default` / final `else` branch of a switch/if chain
+ * over a discriminated union.  If a variant is unhandled the compiler
+ * will error because `value` won't narrow to `never`.
+ *
+ * Also throws at runtime as a safety net.
+ */
+export function assertNever(value, msg) {
+    throw new Error(msg ?? `Unexpected value: ${JSON.stringify(value)}`);
+}

package/dist/lib/utils.d.ts

@@ -1,3 +1,4 @@
 /** @file utils.ts @description Shared utility functions for the code-mapper pipeline */
-/** Generate a graph node ID from its label and name */
-export declare const generateId: (label: string, name: string) => string;
+import { type NodeId } from '../core/db/schema.js';
+/** Generate a branded graph node ID from its label and name */
+export declare const generateId: (label: string, name: string) => NodeId;

package/dist/lib/utils.js

@@ -1,6 +1,7 @@
 // code-mapper/src/lib/utils.ts
 /** @file utils.ts @description Shared utility functions for the code-mapper pipeline */
-/** Generate a graph node ID from its label and name */
+import { toNodeId } from '../core/db/schema.js';
+/** Generate a branded graph node ID from its label and name */
 export const generateId = (label, name) => {
-    return `${label}:${name}`;
+    return toNodeId(`${label}:${name}`);
 };

package/dist/mcp/compatible-stdio-transport.js

@@ -105,7 +105,7 @@ export class CompatibleStdioServerTransport {
             this.discardBufferedInput();
             throw new Error('Missing Content-Length header from MCP client');
         }
-        const contentLength = Number.parseInt(match[1], 10);
+        const contentLength = Number.parseInt(match[1] ?? '', 10);
         if (!Number.isFinite(contentLength) || contentLength < 0) {
             this.discardBufferedInput();
             throw new Error('Invalid Content-Length header from MCP client');

package/dist/mcp/local/local-backend.d.ts

@@ -1,17 +1,17 @@
 /** @file local-backend.ts
  *  @description Tool implementations using local .code-mapper/ indexes
  *  Supports multiple indexed repositories via a global registry
- *  LadybugDB connections are opened lazily per repo on first query */
+ *  SQLite connections are opened lazily per repo on first query */
 import { type RegistryEntry } from '../../storage/repo-manager.js';
 /** Quick test-file detection for filtering impact results across all supported languages */
 export declare function isTestFilePath(filePath: string): boolean;
-/** Valid LadybugDB node labels for safe Cypher query construction */
+/** Valid node labels for safe query construction */
 export declare const VALID_NODE_LABELS: Set<string>;
 /** Valid relation types for impact analysis filtering */
 export declare const VALID_RELATION_TYPES: Set<string>;
-/** Regex to detect write operations in user-supplied Cypher queries */
-export declare const CYPHER_WRITE_RE: RegExp;
-/** Check if a Cypher query contains write operations */
+/** Regex to detect write operations in user-supplied SQL queries */
+export declare const SQL_WRITE_RE: RegExp;
+/** Check if a SQL query contains write operations */
 export declare function isWriteQuery(query: string): boolean;
 export interface CodebaseContext {
     projectName: string;
@@ -27,7 +27,6 @@ interface RepoHandle {
     name: string;
     repoPath: string;
     storagePath: string;
-    lbugPath: string;
     indexedAt: string;
     lastCommit: string;
     stats?: RegistryEntry['stats'];
@@ -35,15 +34,18 @@ interface RepoHandle {
 export declare class LocalBackend {
     private repos;
     private contextCache;
-    private initializedRepos;
     private watchers;
     /** Per-repo promise chain that serializes ensureFresh calls.
      *  Prevents race: Call 2 skipping refresh while Call 1 is still writing. */
     private refreshLocks;
+    /** Per-repo tsgo LSP service instances for live semantic enrichment */
+    private tsgoServices;
+    /** Get (or lazily start) a tsgo LSP service for a repo. Returns null if unavailable. */
+    private getTsgo;
+    /** Get (or lazily open) the SQLite database for a repo. */
+    private getDb;
     /** Hard ceiling — beyond this, incremental is unreliable, warn prominently */
     private static readonly MAX_INCREMENTAL_FILES;
-    /** Optional tsgo LSP service for confidence-1.0 semantic resolution */
-    private tsgoEnabled;
     /** Start file system watcher for a repo to detect source changes */
     private startWatcher;
     /**
@@ -60,48 +62,14 @@ export declare class LocalBackend {
     /** Check for file changes and refresh the DB + embeddings before a tool call */
     private doEnsureFresh;
     /**
-     * Tables that are global metadata — NOT deleted per-file during incremental refresh.
-     */
-    private static readonly SKIP_DELETE_TABLES;
-    /** Tables requiring backtick-quoting in Cypher (reserved words) */
-    private static readonly BACKTICK_TABLES;
-    private static quoteTable;
-    private static escapeCypher;
-    /**
-     * In-process incremental refresh — parses dirty files with tree-sitter and
-     * writes directly to the DB through the existing connection pool.
-     *
-     * This avoids the LadybugDB lock conflict that prevented the child-process
-     * approach from working: LadybugDB on macOS holds an exclusive file lock
-     * even for read-only connections, and db.close() segfaults via N-API.
+     * In-process incremental refresh — delegates to the shared refreshFiles module.
      */
     private inProcessRefresh;
-    /**
-     * Update CodeEmbedding rows for dirty files so semantic search is never stale.
-     *
-     * Runs ONLY when the repo previously had embeddings (stats.embeddings > 0).
-     * Steps:
-     *   1. Delete stale CodeEmbedding rows for all dirty file paths (always)
-     *   2. Query new embeddable nodes for modified/created files
-     *   3. Generate text → batch embed using the warm MCP singleton model
-     *   4. Insert new CodeEmbedding rows
-     *   5. Drop + recreate HNSW vector index
-     *
-     * If the embedding model fails to load, stale rows are still deleted —
-     * semantic search returns fewer results but never wrong ones.
-     */
-    private refreshEmbeddings;
-    private rebuildVectorIndex;
-    /**
-     * Initialize from the global registry, returns true if at least one repo is available.
-     * @param opts.tsgo — Enable tsgo semantic resolution (confidence-1.0 call edges)
-     */
-    init(opts?: {
-        tsgo?: boolean;
-    }): Promise<boolean>;
+    /** Initialize from the global registry, returns true if at least one repo is available */
+    init(): Promise<boolean>;
     /**
      * Re-read the global registry and update the in-memory repo map
-     * LadybugDB connections for removed repos idle-timeout naturally
+     * SQLite connections for removed repos are cleaned up on prune
      */
     private refreshRepos;
     /** Generate a stable repo ID from name + path (appends hash on collision) */
@@ -124,7 +92,9 @@ export declare class LocalBackend {
         lastCommit: string;
         stats?: any;
     }>>;
-    /** Extract signature from content: the declaration line(s), not the full body */
+    /** Find the narrowest symbol node enclosing a given file position (for tsgo ref merging) */
+    private findNodeAtPosition;
+    /** Extract signature from content. For interfaces/types, returns the full body (fields ARE the signature). */
     private extractSignature;
     /** Short file path: strip common prefix if all paths share it */
     private shortPath;
@@ -148,24 +118,27 @@ export declare class LocalBackend {
      */
     private query;
     /**
-     * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
+     * BM25 keyword search helper — uses SQLite FTS5 for always-fresh results
      */
     private bm25Search;
     /**
      * Semantic vector search helper
      */
     private semanticSearch;
-    executeCypher(repoName: string, query: string): Promise<any>;
-    private cypher;
-    /** Format raw Cypher result rows as a markdown table, with raw fallback */
-    private formatCypherAsMarkdown;
+    executeSql(repoName: string, query: string): Promise<any>;
+    private sqlQuery;
+    /** Format raw SQL result rows as a markdown table, with raw fallback */
+    private formatSqlAsMarkdown;
     /** Aggregate same-named clusters by heuristicLabel, filtering tiny clusters (<5 symbols) */
     private aggregateClusters;
     private overview;
-    /** Context tool: 360-degree symbol view with categorized refs and disambiguation */
+    /**
+     * File overview: list all symbols in a file with signatures and caller/callee counts.
+     * Triggered when context() is called with file_path only (no name/uid).
+     */
+    private fileOverview;
+    /** Context tool: 360-degree symbol view, file overview, or disambiguation */
     private context;
-    /** Legacy explore for backwards compatibility with resources.ts */
-    private explore;
     /** Detect changes: git-diff impact analysis mapping changed lines to symbols and processes */
     private detectChanges;
     /** Rename tool: multi-file coordinated rename using graph (high confidence) + text search */