@zachsents/ts-mcp 0.3.3 → 0.3.6

package/dist/lsp-client.js

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { extname } from "node:path";
 import { z } from "zod";
 const REQUEST_TIMEOUT_MS = 30_000;
+/** JSON-RPC response and server-request envelope accepted from TypeScript. */
 const jsonRpcMessageSchema = z.object({
     jsonrpc: z.literal("2.0"),
     id: z.union([z.number(), z.string()]).optional(),
@@ -17,22 +18,12 @@ const jsonRpcMessageSchema = z.object({
     })
         .optional(),
 });
-const hoverResultSchema = z.object({
-    contents: z.unknown(),
-});
-/** MarkupContent shape: `{ kind, value }` or just a raw `{ value }` string */
-const markupContentSchema = z.object({ value: z.string() });
-// Shared LSP building blocks
+/** Shared LSP position shape. */
 const positionSchema = z.object({ line: z.number(), character: z.number() });
 const rangeSchema = z.object({ start: positionSchema, end: positionSchema });
-// Definition/references response — can be Location or LocationLink
+/** Location shape returned by definition and reference requests. */
 const locationSchema = z.object({ uri: z.string(), range: rangeSchema });
-const locationLinkSchema = z.object({
-    targetUri: z.string(),
-    targetRange: rangeSchema,
-    targetSelectionRange: rangeSchema.optional(),
-});
-// Diagnostics
+/** Diagnostic item shape returned by TypeScript. */
 const diagnosticItemSchema = z.object({
     range: rangeSchema,
     severity: z.number().optional(),
@@ -40,30 +31,9 @@ const diagnosticItemSchema = z.object({
     source: z.string().optional(),
     message: z.string(),
 });
-const diagnosticResultSchema = z.object({
-    kind: z.string(),
-    items: z.array(diagnosticItemSchema),
-});
-// Code actions
+/** Text-edit shape shared by code actions and workspace edits. */
 const textEditSchema = z.object({ range: rangeSchema, newText: z.string() });
-const codeActionSchema = z.object({
-    title: z.string(),
-    kind: z.string().optional(),
-    diagnostics: z.array(diagnosticItemSchema).optional(),
-    edit: z
-        .object({
-        changes: z.record(z.string(), z.array(textEditSchema)).optional(),
-    })
-        .optional(),
-});
 const SEVERITY_LABELS = ["", "error", "warning", "info", "hint"];
-// Document symbols — tsgo returns flat SymbolInformation[], not hierarchical
-const symbolInformationSchema = z.object({
-    name: z.string(),
-    kind: z.number(),
-    containerName: z.string().optional(),
-    location: locationSchema,
-});
 const SYMBOL_KIND_LABELS = {
     1: "file",
     2: "module",
@@ -81,27 +51,13 @@ const SYMBOL_KIND_LABELS = {
     22: "enum member",
     26: "type parameter",
 };
-// Workspace edit (shared by rename and code actions)
-const workspaceEditSchema = z.object({
-    changes: z.record(z.string(), z.array(textEditSchema)).optional(),
-});
-// Inlay hints
-const inlayHintLabelSchema = z.union([
-    z.string(),
-    z.array(z.object({ value: z.string() })),
-]);
-const inlayHintSchema = z.object({
-    position: positionSchema,
-    label: inlayHintLabelSchema,
-    kind: z.number().optional(),
-});
 const INLAY_HINT_KIND_LABELS = {
     1: "type",
     2: "parameter",
 };
 /**
- * LSP JSON-RPC client that communicates with a tsgo process over stdio. Handles
- * Content-Length message framing, request/response correlation,
+ * LSP JSON-RPC client that communicates with a TypeScript process over stdio.
+ * Handles Content-Length message framing, request/response correlation,
  * server-initiated requests (e.g. client/registerCapability), and automatic
  * document open/change tracking.
  */
@@ -114,13 +70,20 @@ export class LspClient {
     buffer = Buffer.alloc(0);
     documents = new Map();
     alive = true;
+    /**
+     * Start a TypeScript LSP child process.
+     *
+     * @param binaryPath - Absolute path to the native tsc binary.
+     * @param rootUri - LSP root URI for the project.
+     * @throws When the child process does not expose piped stdio.
+     */
     constructor(binaryPath, rootUri) {
         this.rootUri = rootUri;
         this.proc = spawn(binaryPath, ["--lsp", "--stdio"], {
             stdio: ["pipe", "pipe", "pipe"],
         });
         if (!this.proc.stdin || !this.proc.stdout) {
-            throw new Error("Failed to create tsgo process with piped stdio");
+            throw new Error("Failed to create TypeScript process with piped stdio");
         }
         this.stdin = this.proc.stdin;
         this.proc.stdout.on("data", (chunk) => {
@@ -130,22 +93,36 @@ export class LspClient {
         this.proc.on("exit", (code) => {
             this.alive = false;
             for (const [, req] of this.pending) {
-                req.reject(new Error(`tsgo exited with code ${code}`));
+                req.reject(new Error(`TypeScript exited with code ${code}`));
                 clearTimeout(req.timer);
             }
             this.pending.clear();
         });
     }
-    /** Create and initialize a new LSP client for a project root */
+    /**
+     * Create and initialize a new LSP client for a project root
+     *
+     * @param binaryPath - Absolute path to the native tsc binary.
+     * @param rootUri - LSP root URI for the project.
+     * @returns An initialized LSP client.
+     */
     static async create(binaryPath, rootUri) {
         const client = new LspClient(binaryPath, rootUri);
         await client.initialize();
         return client;
     }
+    /** @returns Whether the child process is available for requests. */
     get isAlive() {
         return this.alive;
     }
-    /** Get hover information at a position in a file */
+    /**
+     * Get hover information at a position in a file
+     *
+     * @param filePath - Absolute path to the source file.
+     * @param line - Zero-based source line.
+     * @param character - Zero-based character offset.
+     * @returns Rendered hover content, or null when unavailable.
+     */
     async hover(filePath, line, character) {
         if (!this.alive)
             throw new Error("LSP client is not alive");
@@ -155,12 +132,19 @@ export class LspClient {
             textDocument: { uri },
             position: { line, character },
         });
-        const parsed = hoverResultSchema.safeParse(result);
+        const parsed = z.object({ contents: z.unknown() }).safeParse(result);
         if (!parsed.success)
             return null;
         return formatHoverContents(parsed.data.contents);
     }
-    /** Get definition location(s) for a symbol at a position */
+    /**
+     * Get definition location(s) for a symbol at a position
+     *
+     * @param filePath - Absolute path to the source file.
+     * @param line - Zero-based source line.
+     * @param character - Zero-based character offset.
+     * @returns Definition locations reported for the selected symbol.
+     */
     async definition(filePath, line, character) {
         if (!this.alive)
             throw new Error("LSP client is not alive");
@@ -172,7 +156,12 @@ export class LspClient {
         });
         return parseLocations(result);
     }
-    /** Pull diagnostics for a file */
+    /**
+     * Pull diagnostics for a file
+     *
+     * @param filePath - Absolute path to the source file.
+     * @returns Diagnostics reported for the file.
+     */
     async diagnostics(filePath) {
         if (!this.alive)
             throw new Error("LSP client is not alive");
@@ -181,44 +170,74 @@ export class LspClient {
         const result = await this.sendRequest("textDocument/diagnostic", {
             textDocument: { uri },
         });
-        const parsed = diagnosticResultSchema.safeParse(result);
+        const parsed = z
+            .object({
+            kind: z.string(),
+            items: z.array(diagnosticItemSchema),
+        })
+            .safeParse(result);
         if (!parsed.success)
             return [];
-        return parsed.data.items.map((item) => ({
-            line: item.range.start.line,
-            character: item.range.start.character,
-            endLine: item.range.end.line,
-            endCharacter: item.range.end.character,
-            severity: SEVERITY_LABELS[item.severity ?? 1] ?? "error",
-            message: item.message,
-            code: item.code,
+        return parsed.data.items.map(({ code, message, range, severity }) => ({
+            line: range.start.line,
+            character: range.start.character,
+            endLine: range.end.line,
+            endCharacter: range.end.character,
+            severity: SEVERITY_LABELS[severity ?? 1] ?? "error",
+            message,
+            code,
         }));
     }
-    /** Get code actions for a range, optionally scoped to specific diagnostics */
+    /**
+     * Get code actions for a range, optionally scoped to specific diagnostics
+     *
+     * @param filePath - Absolute path to the source file.
+     * @param range - Source range to inspect.
+     * @param range.start - Inclusive start position.
+     * @param range.start.line - Zero-based start line.
+     * @param range.start.character - Zero-based start character.
+     * @param range.end - Exclusive end position.
+     * @param range.end.line - Zero-based end line.
+     * @param range.end.character - Zero-based end character.
+     * @param diagnostics - Diagnostics used to scope available actions.
+     * @returns Code actions returned for the range.
+     */
     async codeActions(filePath, range, diagnostics = []) {
         if (!this.alive)
             throw new Error("LSP client is not alive");
         const uri = pathToUri(filePath);
         await this.ensureDocumentOpen(filePath, uri);
-        const lspDiagnostics = diagnostics.map((d) => ({
-            range: {
-                start: { line: d.line, character: d.character },
-                end: { line: d.endLine, character: d.endCharacter },
-            },
-            severity: SEVERITY_LABELS.indexOf(d.severity) || 1,
-            message: d.message,
-            ...(d.code != null ? { code: d.code } : {}),
-        }));
         const result = await this.sendRequest("textDocument/codeAction", {
             textDocument: { uri },
             range,
-            context: { diagnostics: lspDiagnostics },
+            context: {
+                diagnostics: diagnostics.map(({ character, code, endCharacter, endLine, line, message, severity, }) => ({
+                    range: {
+                        start: { line, character },
+                        end: { line: endLine, character: endCharacter },
+                    },
+                    severity: SEVERITY_LABELS.indexOf(severity) || 1,
+                    message,
+                    ...(code != null ? { code } : {}),
+                })),
+            },
         });
         if (!Array.isArray(result))
             return [];
         const actions = [];
         for (const item of result) {
-            const parsed = codeActionSchema.safeParse(item);
+            const parsed = z
+                .object({
+                title: z.string(),
+                kind: z.string().optional(),
+                diagnostics: z.array(diagnosticItemSchema).optional(),
+                edit: z
+                    .object({
+                    changes: z.record(z.string(), z.array(textEditSchema)).optional(),
+                })
+                    .optional(),
+            })
+                .safeParse(item);
             if (!parsed.success || !parsed.data.edit)
                 continue;
             actions.push({
@@ -229,7 +248,12 @@ export class LspClient {
         }
         return actions;
     }
-    /** Get a structured outline of all symbols in a file */
+    /**
+     * Get a structured outline of all symbols in a file
+     *
+     * @param filePath - Absolute path to the source file.
+     * @returns The file's hierarchical symbol outline.
+     */
     async documentSymbols(filePath) {
         if (!this.alive)
             throw new Error("LSP client is not alive");
@@ -240,7 +264,15 @@ export class LspClient {
             return [];
         return buildSymbolTree(result);
     }
-    /** Rename a symbol across the project */
+    /**
+     * Rename a symbol across the project
+     *
+     * @param filePath - Absolute path to the source file.
+     * @param line - Zero-based source line.
+     * @param character - Zero-based character offset.
+     * @param newName - Replacement symbol name.
+     * @returns Text edits required to perform the rename.
+     */
     async rename(filePath, line, character, newName) {
         if (!this.alive)
             throw new Error("LSP client is not alive");
@@ -253,7 +285,14 @@ export class LspClient {
         });
         return parseWorkspaceEdit(result);
     }
-    /** Get inferred type annotations for a line range */
+    /**
+     * Get inferred type annotations for a line range
+     *
+     * @param filePath - Absolute path to the source file.
+     * @param startLine - Zero-based inclusive start line.
+     * @param endLine - Zero-based exclusive end line.
+     * @returns Inlay hints reported for the requested range.
+     */
     async inlayHints(filePath, startLine, endLine) {
         if (!this.alive)
             throw new Error("LSP client is not alive");
@@ -270,23 +309,38 @@ export class LspClient {
             return [];
         const hints = [];
         for (const item of result) {
-            const parsed = inlayHintSchema.safeParse(item);
+            const parsed = z
+                .object({
+                position: positionSchema,
+                label: z.union([
+                    z.string(),
+                    z.array(z.object({ value: z.string() })),
+                ]),
+                kind: z.number().optional(),
+            })
+                .safeParse(item);
             if (!parsed.success)
                 continue;
             const label = parsed.data.label;
-            const text = typeof label === "string"
-                ? label
-                : label.map((part) => part.value).join("");
             hints.push({
                 line: parsed.data.position.line,
                 character: parsed.data.position.character,
-                text,
+                text: typeof label === "string"
+                    ? label
+                    : label.map((part) => part.value).join(""),
                 kind: INLAY_HINT_KIND_LABELS[parsed.data.kind ?? 0] ?? "unknown",
             });
         }
         return hints;
     }
-    /** Find all references to a symbol at a position */
+    /**
+     * Find all references to a symbol at a position
+     *
+     * @param filePath - Absolute path to the source file.
+     * @param line - Zero-based source line.
+     * @param character - Zero-based character offset.
+     * @returns Locations that reference the selected symbol.
+     */
     async references(filePath, line, character) {
         if (!this.alive)
             throw new Error("LSP client is not alive");
@@ -313,6 +367,7 @@ export class LspClient {
         }
         this.proc.kill();
     }
+    /** Initialize the LSP session. */
     async initialize() {
         await this.sendRequest("initialize", {
             processId: process.pid,
@@ -326,16 +381,15 @@ export class LspClient {
         this.sendNotification("initialized", {});
     }
     /**
-     * Re-read all previously opened documents from disk and push changes to tsgo.
-     * This ensures that edits to imported/dependency files are picked up before
-     * we query a file that depends on them.
+     * Re-read all previously opened documents from disk and push changes to
+     * TypeScript. This ensures that edits to imported/dependency files are picked
+     * up before we query a file that depends on them.
      */
     async refreshOpenDocuments() {
         for (const [uri, state] of this.documents) {
-            const filePath = uriToPath(uri);
             let content;
             try {
-                content = await readFile(filePath, "utf-8");
+                content = await readFile(uriToPath(uri), "utf-8");
             }
             catch {
                 continue;
@@ -350,7 +404,12 @@ export class LspClient {
             }
         }
     }
-    /** Open a document in the LSP if needed, or update it if contents changed */
+    /**
+     * Open a document in the LSP if needed, or update it if contents changed
+     *
+     * @param filePath - Absolute path to the source file.
+     * @param uri - LSP document URI for the file.
+     */
     async ensureDocumentOpen(filePath, uri) {
         await this.refreshOpenDocuments();
         const content = await readFile(filePath, "utf-8");
@@ -376,27 +435,52 @@ export class LspClient {
             this.documents.set(uri, { version, content });
         }
     }
+    /**
+     * Send an LSP request and await its response.
+     *
+     * @param method - LSP method name.
+     * @param params - JSON-RPC request parameters.
+     */
     sendRequest(method, params) {
         return new Promise((resolve, reject) => {
             const id = this.nextId++;
-            const timer = setTimeout(() => {
-                this.pending.delete(id);
-                reject(new Error(`Request "${method}" timed out after ${REQUEST_TIMEOUT_MS}ms`));
-            }, REQUEST_TIMEOUT_MS);
-            this.pending.set(id, { resolve, reject, timer });
+            this.pending.set(id, {
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`Request "${method}" timed out after ${REQUEST_TIMEOUT_MS}ms`));
+                }, REQUEST_TIMEOUT_MS),
+            });
             this.send({ jsonrpc: "2.0", id, method, params });
         });
     }
+    /**
+     * Send an LSP notification.
+     *
+     * @param method - LSP method name.
+     * @param params - JSON-RPC notification parameters.
+     */
     sendNotification(method, params) {
         this.send({ jsonrpc: "2.0", method, params });
     }
+    /**
+     * Respond to a server-initiated LSP request.
+     *
+     * @param id - Identifier of the server request.
+     * @param result - JSON-RPC response result.
+     */
     sendResponse(id, result) {
         this.send({ jsonrpc: "2.0", id, result });
     }
+    /**
+     * Write a framed JSON-RPC message to the child process.
+     *
+     * @param message - JSON-RPC message to serialize and send.
+     */
     send(message) {
         const body = JSON.stringify(message);
-        const header = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`;
-        this.stdin.write(header + body);
+        this.stdin.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
     }
     /** Parse Content-Length framed messages from the buffer */
     drainBuffer() {
@@ -404,24 +488,29 @@ export class LspClient {
             const headerEnd = this.buffer.indexOf("\r\n\r\n");
             if (headerEnd === -1)
                 return;
-            const header = this.buffer.subarray(0, headerEnd).toString("ascii");
-            const match = header.match(/Content-Length:\s*(\d+)/);
+            const match = this.buffer
+                .subarray(0, headerEnd)
+                .toString("ascii")
+                .match(/Content-Length:\s*(\d+)/);
             if (!match) {
                 this.buffer = this.buffer.subarray(headerEnd + 4);
                 continue;
             }
-            const contentLength = Number.parseInt(match[1] ?? "0", 10);
             const bodyStart = headerEnd + 4;
-            const bodyEnd = bodyStart + contentLength;
+            const bodyEnd = bodyStart + Number.parseInt(match[1] ?? "0", 10);
             if (this.buffer.length < bodyEnd)
                 return;
-            const body = this.buffer.subarray(bodyStart, bodyEnd).toString("utf-8");
+            const parsed = jsonRpcMessageSchema.safeParse(JSON.parse(this.buffer.subarray(bodyStart, bodyEnd).toString("utf-8")));
             this.buffer = this.buffer.subarray(bodyEnd);
-            const parsed = jsonRpcMessageSchema.safeParse(JSON.parse(body));
             if (parsed.success)
                 this.handleMessage(parsed.data);
         }
     }
+    /**
+     * Route a parsed JSON-RPC message.
+     *
+     * @param message - Validated JSON-RPC message from the server.
+     */
     handleMessage(message) {
         // Response to one of our requests (numeric id, no method)
         if (typeof message.id === "number" && !message.method) {
@@ -444,22 +533,36 @@ export class LspClient {
         }
     }
 }
+/**
+ * Convert a file path to an LSP file URI.
+ *
+ * @param filePath - Absolute path to convert.
+ * @returns The corresponding file URI.
+ */
 function pathToUri(filePath) {
     return `file://${filePath}`;
 }
+/**
+ * Convert an LSP file URI to a file path.
+ *
+ * @param uri - File URI to convert.
+ * @returns The corresponding absolute file path.
+ */
 function uriToPath(uri) {
     return uri.replace(/^file:\/\//, "");
 }
 /**
  * Parse Location[] or LocationLink[] from an LSP response into LspLocation[].
  * Handles single objects, arrays, and null.
+ *
+ * @param result - Raw LSP definition response.
+ * @returns Normalized definition locations.
  */
 function parseLocations(result) {
     if (result == null)
         return [];
-    const items = Array.isArray(result) ? result : [result];
     const locations = [];
-    for (const item of items) {
+    for (const item of Array.isArray(result) ? result : [result]) {
         const loc = locationSchema.safeParse(item);
         if (loc.success) {
             locations.push({
@@ -469,7 +572,13 @@ function parseLocations(result) {
             });
             continue;
         }
-        const link = locationLinkSchema.safeParse(item);
+        const link = z
+            .object({
+            targetUri: z.string(),
+            targetRange: rangeSchema,
+            targetSelectionRange: rangeSchema.optional(),
+        })
+            .safeParse(item);
         if (link.success) {
             const range = link.data.targetSelectionRange ?? link.data.targetRange;
             locations.push({
@@ -484,11 +593,21 @@ function parseLocations(result) {
 /**
  * Build a symbol tree from flat SymbolInformation[]. Uses containerName to
  * reconstruct parent-child relationships.
+ *
+ * @param items - Raw LSP symbol information records.
+ * @returns A hierarchical symbol outline.
  */
 function buildSymbolTree(items) {
     const flat = [];
     for (const item of items) {
-        const parsed = symbolInformationSchema.safeParse(item);
+        const parsed = z
+            .object({
+            name: z.string(),
+            kind: z.number(),
+            containerName: z.string().optional(),
+            location: locationSchema,
+        })
+            .safeParse(item);
         if (!parsed.success)
             continue;
         flat.push({
@@ -522,17 +641,25 @@ function buildSymbolTree(items) {
     }
     return roots;
 }
-/** Parse a WorkspaceEdit into flat LspTextEdit[] */
+/**
+ * Parse a WorkspaceEdit into flat LspTextEdit[]
+ *
+ * @param result - Raw LSP workspace edit.
+ * @returns Flattened text edits.
+ */
 function parseWorkspaceEdit(result) {
-    const parsed = workspaceEditSchema.safeParse(result);
+    const parsed = z
+        .object({
+        changes: z.record(z.string(), z.array(textEditSchema)).optional(),
+    })
+        .safeParse(result);
     if (!parsed.success || !parsed.data.changes)
         return [];
     const edits = [];
     for (const [editUri, textEdits] of Object.entries(parsed.data.changes)) {
-        const file = uriToPath(editUri);
         for (const te of textEdits) {
             edits.push({
-                file,
+                file: uriToPath(editUri),
                 startLine: te.range.start.line,
                 startCharacter: te.range.start.character,
                 endLine: te.range.end.line,
@@ -543,9 +670,14 @@ function parseWorkspaceEdit(result) {
     }
     return edits;
 }
+/**
+ * Return the LSP language identifier for a source file.
+ *
+ * @param filePath - Source file path.
+ * @returns The matching LSP language identifier.
+ */
 function getLanguageId(filePath) {
-    const ext = extname(filePath);
-    switch (ext) {
+    switch (extname(filePath)) {
         case ".ts":
         case ".mts":
         case ".cts":
@@ -565,6 +697,9 @@ function getLanguageId(filePath) {
 /**
  * Extract text from LSP hover contents. Handles MarkupContent (`{ value }`),
  * plain strings, and arrays of either.
+ *
+ * @param contents - Raw LSP hover content.
+ * @returns Rendered hover text, or null when the content is unsupported.
  */
 function formatHoverContents(contents) {
     const str = z.string().safeParse(contents);
@@ -574,7 +709,7 @@ function formatHoverContents(contents) {
         const parts = contents.map(formatHoverContents).filter(Boolean);
         return parts.length > 0 ? parts.join("\n\n") : null;
     }
-    const markup = markupContentSchema.safeParse(contents);
+    const markup = z.object({ value: z.string() }).safeParse(contents);
     if (markup.success)
         return markup.data.value;
     return null;