@zuvia-software-solutions/code-mapper 1.4.0

package/dist/core/semantic/tsgo-service.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file Singleton LSP client for tsgo (TypeScript native preview).
+ *
+ * Spawns `tsgo --lsp --stdio` as a persistent child process and provides
+ * high-level async methods for semantic operations:
+ *   - resolveDefinition(): cross-file go-to-definition (confidence 1.0 edges)
+ *   - findReferences(): all references to a symbol
+ *   - getHover(): type signature for a position
+ *
+ * The server stays warm for the lifetime of the MCP process. File changes
+ * are forwarded via didOpen/didChange so tsgo always has fresh state.
+ *
+ * Optional — only starts if the `@typescript/native-preview` package is installed.
+ */
+export interface TsgoDefinition {
+    filePath: string;
+    line: number;
+    character: number;
+}
+export interface TsgoReference {
+    filePath: string;
+    line: number;
+    character: number;
+}
+export declare class TsgoService {
+    private process;
+    private buf;
+    private responses;
+    private nextId;
+    private projectRoot;
+    private tsgoPath;
+    private ready;
+    private initPromise;
+    private openFiles;
+    constructor(projectRoot: string);
+    /**
+     * Start the tsgo LSP server. Returns true if successful, false if
+     * @typescript/native-preview is not installed or tsgo fails to start.
+     */
+    start(): Promise<boolean>;
+    /** Whether the server is running and ready for queries */
+    isReady(): boolean;
+    /** Resolve what a symbol at a given position points to (go-to-definition) */
+    resolveDefinition(absFilePath: string, line: number, character: number): Promise<TsgoDefinition | null>;
+    /** Find all references to the symbol at the given position */
+    findReferences(absFilePath: string, line: number, character: number): Promise<TsgoReference[]>;
+    /** Get the type signature at a position (hover) */
+    getHover(absFilePath: string, line: number, character: number): Promise<string | null>;
+    /** Notify tsgo that a file changed (call after editing a file) */
+    notifyFileChanged(absFilePath: string): Promise<void>;
+    /** Notify tsgo that a file was deleted */
+    notifyFileDeleted(absFilePath: string): Promise<void>;
+    /** Stop the tsgo process */
+    stop(): void;
+    private doStart;
+    private findTsgoBinary;
+    private onData;
+    private send;
+    private request;
+    private ensureOpen;
+    private fileUri;
+    private uriToRelative;
+}
+/** Get or create the singleton TsgoService for a project root */
+export declare function getTsgoService(projectRoot: string): TsgoService;
+/** Stop the singleton if running */
+export declare function stopTsgoService(): void;

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

@@ -0,0 +1,355 @@
+// code-mapper/src/core/semantic/tsgo-service.ts
+/**
+ * @file Singleton LSP client for tsgo (TypeScript native preview).
+ *
+ * Spawns `tsgo --lsp --stdio` as a persistent child process and provides
+ * high-level async methods for semantic operations:
+ *   - resolveDefinition(): cross-file go-to-definition (confidence 1.0 edges)
+ *   - findReferences(): all references to a symbol
+ *   - getHover(): type signature for a position
+ *
+ * The server stays warm for the lifetime of the MCP process. File changes
+ * are forwarded via didOpen/didChange so tsgo always has fresh state.
+ *
+ * Optional — only starts if the `@typescript/native-preview` package is installed.
+ */
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+// ---------------------------------------------------------------------------
+// LSP message helpers
+// ---------------------------------------------------------------------------
+function encodeLSP(msg) {
+    const json = JSON.stringify(msg);
+    return `Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`;
+}
+// ---------------------------------------------------------------------------
+// TsgoService
+// ---------------------------------------------------------------------------
+export class TsgoService {
+    process = null;
+    buf = '';
+    responses = new Map();
+    nextId = 1;
+    projectRoot;
+    tsgoPath = null;
+    ready = false;
+    initPromise = null;
+    openFiles = new Set();
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    // ── Public API ──────────────────────────────────────────────────────
+    /**
+     * Start the tsgo LSP server. Returns true if successful, false if
+     * @typescript/native-preview is not installed or tsgo fails to start.
+     */
+    async start() {
+        if (this.ready)
+            return true;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this.doStart();
+        return this.initPromise;
+    }
+    /** 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)
+            return null;
+        await this.ensureOpen(absFilePath);
+        const resp = await this.request('textDocument/definition', {
+            textDocument: { uri: this.fileUri(absFilePath) },
+            position: { line, character },
+        });
+        if (!resp)
+            return null;
+        const result = resp.result;
+        if (!result)
+            return null;
+        const defs = Array.isArray(result) ? result : [result];
+        if (defs.length === 0)
+            return null;
+        const d = defs[0];
+        const uri = d.uri || d.targetUri || '';
+        const range = d.range || d.targetSelectionRange;
+        if (!uri || !range)
+            return null;
+        return {
+            filePath: this.uriToRelative(uri),
+            line: range.start.line,
+            character: range.start.character,
+        };
+    }
+    /** Find all references to the symbol at the given position */
+    async findReferences(absFilePath, line, character) {
+        if (!this.ready)
+            return [];
+        await this.ensureOpen(absFilePath);
+        const resp = await this.request('textDocument/references', {
+            textDocument: { uri: this.fileUri(absFilePath) },
+            position: { line, character },
+            context: { includeDeclaration: false },
+        });
+        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,
+        }));
+    }
+    /** Get the type signature at a position (hover) */
+    async getHover(absFilePath, line, character) {
+        if (!this.ready)
+            return null;
+        await this.ensureOpen(absFilePath);
+        const resp = await this.request('textDocument/hover', {
+            textDocument: { uri: this.fileUri(absFilePath) },
+            position: { line, character },
+        });
+        if (!resp?.result)
+            return null;
+        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');
+        return null;
+    }
+    /** Notify tsgo that a file changed (call after editing a file) */
+    async notifyFileChanged(absFilePath) {
+        if (!this.ready)
+            return;
+        const uri = this.fileUri(absFilePath);
+        if (this.openFiles.has(uri)) {
+            // File was already open — send didChange with full content
+            const content = fs.readFileSync(absFilePath, 'utf-8');
+            this.send({
+                jsonrpc: '2.0',
+                method: 'textDocument/didChange',
+                params: {
+                    textDocument: { uri, version: Date.now() },
+                    contentChanges: [{ text: content }],
+                },
+            });
+        }
+        // If not open, next query will open it fresh
+    }
+    /** Notify tsgo that a file was deleted */
+    async notifyFileDeleted(absFilePath) {
+        if (!this.ready)
+            return;
+        const uri = this.fileUri(absFilePath);
+        if (this.openFiles.has(uri)) {
+            this.send({
+                jsonrpc: '2.0',
+                method: 'textDocument/didClose',
+                params: { textDocument: { uri } },
+            });
+            this.openFiles.delete(uri);
+        }
+    }
+    /** Stop the tsgo process */
+    stop() {
+        if (this.process && !this.process.killed) {
+            this.send({ jsonrpc: '2.0', id: this.nextId++, method: 'shutdown', params: null });
+            setTimeout(() => {
+                this.send({ jsonrpc: '2.0', method: 'exit', params: null });
+                setTimeout(() => {
+                    try {
+                        this.process?.kill();
+                    }
+                    catch { }
+                }, 500);
+            }, 200);
+        }
+        this.process = null;
+        this.ready = false;
+        this.initPromise = null;
+        this.openFiles.clear();
+        this.responses.clear();
+    }
+    // ── Internal ────────────────────────────────────────────────────────
+    async doStart() {
+        // Find the tsgo binary
+        this.tsgoPath = this.findTsgoBinary();
+        if (!this.tsgoPath) {
+            console.error('Code Mapper: tsgo not found — install @typescript/native-preview for semantic resolution');
+            return false;
+        }
+        try {
+            this.process = spawn(this.tsgoPath, ['--lsp', '--stdio'], {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                cwd: this.projectRoot,
+            });
+            this.process.stdout.on('data', (chunk) => this.onData(chunk));
+            this.process.stderr.on('data', () => { }); // suppress
+            this.process.on('exit', () => {
+                this.ready = false;
+                this.process = null;
+            });
+            // Initialize LSP handshake
+            const initResp = await this.request('initialize', {
+                processId: process.pid,
+                capabilities: {
+                    textDocument: {
+                        definition: { dynamicRegistration: true },
+                        references: { dynamicRegistration: true },
+                        hover: { contentFormat: ['plaintext'], dynamicRegistration: true },
+                    },
+                },
+                rootUri: `file://${this.projectRoot}`,
+            });
+            if (!initResp) {
+                console.error('Code Mapper: tsgo LSP initialize timed out');
+                this.stop();
+                return false;
+            }
+            // Send initialized notification
+            this.send({ jsonrpc: '2.0', method: 'initialized', params: {} });
+            this.ready = true;
+            console.error('Code Mapper: tsgo LSP ready (semantic resolution enabled)');
+            return true;
+        }
+        catch (err) {
+            console.error(`Code Mapper: tsgo LSP failed to start: ${err instanceof Error ? err.message : err}`);
+            this.stop();
+            return false;
+        }
+    }
+    findTsgoBinary() {
+        // Try resolving via the @typescript/native-preview 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 exe = path.join(path.dirname(pkgJsonPath), 'lib', 'tsgo');
+            if (fs.existsSync(exe))
+                return exe;
+        }
+        catch { }
+        // Try npx tsgo path
+        try {
+            const { execFileSync } = require('child_process');
+            const result = execFileSync('which', ['tsgo'], { encoding: 'utf-8', timeout: 3000 }).trim();
+            if (result && fs.existsSync(result))
+                return result;
+        }
+        catch { }
+        return null;
+    }
+    onData(chunk) {
+        this.buf += chunk.toString();
+        while (true) {
+            const m = this.buf.match(/Content-Length: (\d+)\r\n\r\n([\s\S]*)/);
+            if (!m)
+                break;
+            const len = parseInt(m[1]);
+            if (m[2].length < len)
+                break;
+            const body = m[2].slice(0, len);
+            this.buf = m[2].slice(len);
+            try {
+                const msg = JSON.parse(body);
+                if (msg.id !== undefined && msg.method) {
+                    // Server request (e.g., client/registerCapability) — acknowledge
+                    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);
+                }
+                // Notifications (no id, has method) are ignored
+            }
+            catch { }
+        }
+    }
+    send(msg) {
+        if (!this.process?.stdin?.writable)
+            return;
+        try {
+            this.process.stdin.write(encodeLSP(msg));
+        }
+        catch { }
+    }
+    request(method, params, timeoutMs = 15000) {
+        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();
+        });
+    }
+    async ensureOpen(absFilePath) {
+        const uri = this.fileUri(absFilePath);
+        if (this.openFiles.has(uri))
+            return;
+        try {
+            const content = fs.readFileSync(absFilePath, 'utf-8');
+            this.send({
+                jsonrpc: '2.0',
+                method: 'textDocument/didOpen',
+                params: {
+                    textDocument: {
+                        uri,
+                        languageId: 'typescript',
+                        version: 1,
+                        text: content,
+                    },
+                },
+            });
+            this.openFiles.add(uri);
+        }
+        catch { }
+    }
+    fileUri(absPath) {
+        return `file://${absPath}`;
+    }
+    uriToRelative(uri) {
+        const prefix = `file://${this.projectRoot}/`;
+        if (uri.startsWith(prefix))
+            return uri.slice(prefix.length);
+        // Try with triple slash
+        const prefix2 = `file:///${this.projectRoot}/`;
+        if (uri.startsWith(prefix2))
+            return uri.slice(prefix2.length);
+        return uri.replace(/^file:\/\/\/?/, '');
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+let instance = null;
+/** Get or create the singleton TsgoService for a project root */
+export function getTsgoService(projectRoot) {
+    if (!instance || instance['projectRoot'] !== projectRoot) {
+        instance?.stop();
+        instance = new TsgoService(projectRoot);
+    }
+    return instance;
+}
+/** Stop the singleton if running */
+export function stopTsgoService() {
+    instance?.stop();
+    instance = null;
+}

package/dist/core/tree-sitter/parser-loader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file parser-loader.ts
+ * @description Tree-sitter parser initialization and language grammar loading
+ *
+ * Supports 14 languages via native tree-sitter bindings
+ * Swift and Kotlin are optional dependencies
+ */
+import Parser from 'tree-sitter';
+import { SupportedLanguages } from '../../config/supported-languages.js';
+export declare const isLanguageAvailable: (language: SupportedLanguages) => boolean;
+export declare const loadParser: () => Promise<Parser>;
+export declare const loadLanguage: (language: SupportedLanguages, filePath?: string) => Promise<void>;

package/dist/core/tree-sitter/parser-loader.js

@@ -0,0 +1,71 @@
+// code-mapper/src/core/tree-sitter/parser-loader.ts
+/**
+ * @file parser-loader.ts
+ * @description Tree-sitter parser initialization and language grammar loading
+ *
+ * Supports 14 languages via native tree-sitter bindings
+ * Swift and Kotlin are optional dependencies
+ */
+import Parser from 'tree-sitter';
+import JavaScript from 'tree-sitter-javascript';
+import TypeScript from 'tree-sitter-typescript';
+import Python from 'tree-sitter-python';
+import Java from 'tree-sitter-java';
+import C from 'tree-sitter-c';
+import CPP from 'tree-sitter-cpp';
+import CSharp from 'tree-sitter-c-sharp';
+import Go from 'tree-sitter-go';
+import Rust from 'tree-sitter-rust';
+import PHP from 'tree-sitter-php';
+import Ruby from 'tree-sitter-ruby';
+import { createRequire } from 'node:module';
+import { SupportedLanguages } from '../../config/supported-languages.js';
+// tree-sitter-swift is an optional dependency — may not be installed
+const _require = createRequire(import.meta.url);
+let Swift = null;
+try {
+    Swift = _require('tree-sitter-swift');
+}
+catch { }
+// tree-sitter-kotlin is an optional dependency — may not be installed
+let Kotlin = null;
+try {
+    Kotlin = _require('tree-sitter-kotlin');
+}
+catch { }
+let parser = null;
+const languageMap = {
+    [SupportedLanguages.JavaScript]: JavaScript,
+    [SupportedLanguages.TypeScript]: TypeScript.typescript,
+    [`${SupportedLanguages.TypeScript}:tsx`]: TypeScript.tsx,
+    [SupportedLanguages.Python]: Python,
+    [SupportedLanguages.Java]: Java,
+    [SupportedLanguages.C]: C,
+    [SupportedLanguages.CPlusPlus]: CPP,
+    [SupportedLanguages.CSharp]: CSharp,
+    [SupportedLanguages.Go]: Go,
+    [SupportedLanguages.Rust]: Rust,
+    ...(Kotlin ? { [SupportedLanguages.Kotlin]: Kotlin } : {}),
+    [SupportedLanguages.PHP]: PHP.php_only,
+    [SupportedLanguages.Ruby]: Ruby,
+    ...(Swift ? { [SupportedLanguages.Swift]: Swift } : {}),
+};
+export const isLanguageAvailable = (language) => language in languageMap;
+export const loadParser = async () => {
+    if (parser)
+        return parser;
+    parser = new Parser();
+    return parser;
+};
+export const loadLanguage = async (language, filePath) => {
+    if (!parser)
+        await loadParser();
+    const key = language === SupportedLanguages.TypeScript && filePath?.endsWith('.tsx')
+        ? `${language}:tsx`
+        : language;
+    const lang = languageMap[key];
+    if (!lang) {
+        throw new Error(`Unsupported language: ${language}`);
+    }
+    parser.setLanguage(lang);
+};

package/dist/lib/memory-guard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file Memory-aware guard that replaces static limits with adaptive behavior.
+ *
+ * Every processing loop can check isUnderPressure() or isCritical() to decide
+ * whether to continue, shrink batches, or flush caches. The only hard limits
+ * that remain are physical constraints (tree-sitter 32MB buffer).
+ */
+declare class MemoryGuard {
+    private heapLimit;
+    constructor();
+    /** Re-read the heap limit (call after --max-old-space-size changes) */
+    refresh(): void;
+    /** Current heap usage in bytes */
+    private used;
+    /** True when heap usage exceeds 80% — start reducing batch sizes */
+    isUnderPressure(): boolean;
+    /** True when heap usage exceeds 92% — skip non-essential work */
+    isCritical(): boolean;
+    /** Bytes of heap still available, minus the reserved headroom */
+    availableBytes(): number;
+    /**
+     * Recommend a batch size based on available memory.
+     * @param perItemBytes Estimated memory per item in the batch
+     * @param defaultSize  Batch size to use when memory is plentiful
+     * @returns A batch size between 1 and defaultSize
+     */
+    adaptiveBatchSize(perItemBytes: number, defaultSize: number): number;
+    /** Force garbage collection if --expose-gc is enabled, no-op otherwise */
+    tryGC(): void;
+    /** Current usage as a human-readable string (for logging) */
+    summary(): string;
+}
+/** Singleton instance */
+export declare const memoryGuard: MemoryGuard;
+export {};

package/dist/lib/memory-guard.js

@@ -0,0 +1,70 @@
+// src/lib/memory-guard.ts
+/**
+ * @file Memory-aware guard that replaces static limits with adaptive behavior.
+ *
+ * Every processing loop can check isUnderPressure() or isCritical() to decide
+ * whether to continue, shrink batches, or flush caches. The only hard limits
+ * that remain are physical constraints (tree-sitter 32MB buffer).
+ */
+import v8 from 'v8';
+/** Fraction of heap at which we start backing off (smaller batches, cache flushes) */
+const PRESSURE_THRESHOLD = 0.80;
+/** Fraction of heap at which we skip non-essential work */
+const CRITICAL_THRESHOLD = 0.92;
+/** Minimum headroom to reserve (200 MB) — prevents running right up to the limit */
+const MIN_HEADROOM_BYTES = 200 * 1024 * 1024;
+class MemoryGuard {
+    heapLimit;
+    constructor() {
+        this.heapLimit = v8.getHeapStatistics().heap_size_limit;
+    }
+    /** Re-read the heap limit (call after --max-old-space-size changes) */
+    refresh() {
+        this.heapLimit = v8.getHeapStatistics().heap_size_limit;
+    }
+    /** Current heap usage in bytes */
+    used() {
+        return process.memoryUsage().heapUsed;
+    }
+    /** True when heap usage exceeds 80% — start reducing batch sizes */
+    isUnderPressure() {
+        return this.used() / this.heapLimit > PRESSURE_THRESHOLD;
+    }
+    /** True when heap usage exceeds 92% — skip non-essential work */
+    isCritical() {
+        return this.used() / this.heapLimit > CRITICAL_THRESHOLD;
+    }
+    /** Bytes of heap still available, minus the reserved headroom */
+    availableBytes() {
+        return Math.max(0, this.heapLimit - this.used() - MIN_HEADROOM_BYTES);
+    }
+    /**
+     * Recommend a batch size based on available memory.
+     * @param perItemBytes Estimated memory per item in the batch
+     * @param defaultSize  Batch size to use when memory is plentiful
+     * @returns A batch size between 1 and defaultSize
+     */
+    adaptiveBatchSize(perItemBytes, defaultSize) {
+        if (perItemBytes <= 0)
+            return defaultSize;
+        const available = this.availableBytes();
+        // Use at most 60% of available for the next batch (leave room for processing overhead)
+        const maxItems = Math.floor((available * 0.6) / perItemBytes);
+        return Math.max(1, Math.min(defaultSize, maxItems));
+    }
+    /** Force garbage collection if --expose-gc is enabled, no-op otherwise */
+    tryGC() {
+        if (typeof globalThis.gc === 'function') {
+            globalThis.gc();
+        }
+    }
+    /** Current usage as a human-readable string (for logging) */
+    summary() {
+        const usedMB = Math.round(this.used() / (1024 * 1024));
+        const limitMB = Math.round(this.heapLimit / (1024 * 1024));
+        const pct = Math.round((this.used() / this.heapLimit) * 100);
+        return `${usedMB}MB / ${limitMB}MB (${pct}%)`;
+    }
+}
+/** Singleton instance */
+export const memoryGuard = new MemoryGuard();

package/dist/lib/utils.d.ts

@@ -0,0 +1,3 @@
+/** @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;

package/dist/lib/utils.js

@@ -0,0 +1,6 @@
+// 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 */
+export const generateId = (label, name) => {
+    return `${label}:${name}`;
+};

package/dist/mcp/compatible-stdio-transport.d.ts

@@ -0,0 +1,32 @@
+/** @file compatible-stdio-transport.ts
+ *  @description MCP stdio transport that auto-detects content-length vs newline framing
+ *  Handles both official MCP SDK clients and simpler newline-delimited JSON clients */
+import type { Transport, TransportSendOptions } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { type JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+export type StdioFraming = 'content-length' | 'newline';
+export declare class CompatibleStdioServerTransport implements Transport {
+    private readonly _stdin;
+    private readonly _stdout;
+    private _readBuffer;
+    private _started;
+    private _framing;
+    /** Direct reference to the real write function, captured at construction time.
+     *  Immune to process.stdout.write being replaced (e.g. embedder.ts silences
+     *  stdout during ONNX model load, which would swallow MCP responses). */
+    private readonly _directWrite;
+    onmessage?: (message: JSONRPCMessage) => void;
+    onerror?: (error: Error) => void;
+    onclose?: () => void;
+    constructor(_stdin?: NodeJS.ReadableStream, _stdout?: NodeJS.WritableStream);
+    private readonly _ondata;
+    private readonly _onerror;
+    start(): Promise<void>;
+    private detectFraming;
+    private discardBufferedInput;
+    private readContentLengthMessage;
+    private readNewlineMessage;
+    private readMessage;
+    private processReadBuffer;
+    close(): Promise<void>;
+    send(message: JSONRPCMessage, _options?: TransportSendOptions): Promise<void>;
+}