@hienlh/ppm 0.20.9 → 0.21.0

package/src/web/lib/lsp/lsp-client.ts

@@ -0,0 +1,321 @@
+/**
+ * The browser half of the language-server bridge.
+ *
+ * One connection per project, shared by every editor open on it, because the
+ * server shares one language-server process the same way. Editors register a
+ * document and get back a status; providers ask questions through `request`.
+ *
+ * Two things this has to get right that a naive client does not:
+ *
+ * - **Reconnects lose the server's document state.** The socket layer replays
+ *   messages it had queued, but a document opened before the drop was never
+ *   queued, so the language server would answer questions about a file it has
+ *   never been told the contents of. On the bridge's `hello` every registered
+ *   document is opened again from its current text.
+ * - **A request must always settle.** Monaco awaits provider promises; one that
+ *   never resolves leaves the suggest widget spinning with no way out. Every
+ *   request has a timeout, and a dropped socket rejects everything in flight.
+ */
+import { WsClient } from "@/lib/ws-client";
+
+export interface LspServerInfo {
+  id: string;
+  displayName: string;
+  rootPath: string;
+}
+
+export interface LspMissingServer {
+  id: string;
+  displayName: string;
+  installHint: string;
+}
+
+export type LspDocumentStatus =
+  | { state: "opening" }
+  | { state: "ready"; languageId: string; server: LspServerInfo; projectPath: string; capabilities: Record<string, unknown> }
+  | { state: "unavailable"; reason: string; server: LspMissingServer | null; message: string };
+
+/** What an editor gives the connection so a document can be re-sent after a drop. */
+export interface LspDocumentSource {
+  getText: () => string;
+  getVersion: () => number;
+  /**
+   * The Monaco model's own URI.
+   *
+   * Monaco names models `inmemory://model/N`, which no language server has
+   * heard of. The bridge keeps both names so it can translate the server's
+   * `file:` URIs back into something Monaco can match against this model.
+   */
+  clientUri: string;
+}
+
+/** How long a provider request may wait before it is treated as lost. */
+const REQUEST_TIMEOUT_MS = 15_000;
+
+interface Pending {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+  /** Detach the caller's abort listener; a request settles once, however it settles. */
+  detach?: () => void;
+}
+
+/** Stop a pending request costing anything, whatever settles it. */
+function settle(pending: Pending): void {
+  clearTimeout(pending.timer);
+  pending.detach?.();
+}
+
+interface Registered {
+  source: LspDocumentSource;
+  status: LspDocumentStatus;
+}
+
+export class LspConnection {
+  private readonly ws: WsClient;
+  private readonly docs = new Map<string, Registered>();
+  private readonly pending = new Map<number, Pending>();
+  private readonly notificationListeners = new Set<(method: string, params: unknown) => void>();
+  private readonly statusListeners = new Set<(path: string, status: LspDocumentStatus) => void>();
+  private nextId = 1;
+
+  constructor(readonly projectName: string) {
+    this.ws = new WsClient(`/ws/project/${encodeURIComponent(projectName)}/lsp`);
+    this.ws.onMessage((event) => this.receive(event));
+    this.ws.connect();
+  }
+
+  // ── Documents ───────────────────────────────────────────────────────────
+
+  open(path: string, source: LspDocumentSource): void {
+    this.docs.set(path, { source, status: { state: "opening" } });
+    this.setStatus(path, { state: "opening" });
+    this.sendOpen(path);
+  }
+
+  private sendOpen(path: string): void {
+    const entry = this.docs.get(path);
+    if (!entry) return;
+    this.send({
+      t: "open",
+      path,
+      version: entry.source.getVersion(),
+      text: entry.source.getText(),
+      clientUri: entry.source.clientUri,
+    });
+  }
+
+  close(path: string): void {
+    if (!this.docs.delete(path)) return;
+    this.send({ t: "close", path });
+  }
+
+  /**
+   * Report an edit.
+   *
+   * `changes` are LSP content changes against `version - 1`. The bridge checks
+   * that, and asks for a full resend if the sequence ever skips — a silently
+   * desynchronised server answers every later question about lines that no
+   * longer exist.
+   */
+  change(path: string, version: number, changes: Array<{ range: unknown; text: string }>): void {
+    if (!this.docs.has(path)) return;
+    this.send({ t: "change", path, version, changes });
+  }
+
+  save(path: string, text: string): void {
+    if (!this.docs.has(path)) return;
+    this.send({ t: "save", path, text });
+  }
+
+  statusOf(path: string): LspDocumentStatus | undefined {
+    return this.docs.get(path)?.status;
+  }
+
+  // ── Requests ────────────────────────────────────────────────────────────
+
+  /**
+   * `signal` is how a provider whose answer is no longer wanted stops the work.
+   *
+   * It is not a nicety: a language server answers one request at a time, so every superseded
+   * completion sits in front of the one the user is actually waiting for. Monaco hands every
+   * provider a `CancellationToken` and cancels the moment the next keystroke arrives; until
+   * this existed, nothing here listened to it and `$/cancelRequest` was only ever sent on a
+   * 15-second timeout.
+   */
+  request<T>(
+    path: string,
+    method: string,
+    params: unknown,
+    options: { timeoutMs?: number; signal?: AbortSignal } = {},
+  ): Promise<T> {
+    const entry = this.docs.get(path);
+    if (!entry || entry.status.state !== "ready") {
+      return Promise.reject(new Error(`No language server is ready for ${path}`));
+    }
+    const { timeoutMs = REQUEST_TIMEOUT_MS, signal } = options;
+    if (signal?.aborted) return Promise.reject(new Error(`${method} was cancelled`));
+    const id = this.nextId++;
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        this.send({ t: "cancel", id });
+        reject(new Error(`${method} timed out`));
+      }, timeoutMs);
+      const onAbort = () => {
+        if (!this.pending.delete(id)) return;
+        clearTimeout(timer);
+        // no detach: the listener is `once`, and this is it
+        this.send({ t: "cancel", id });
+        reject(new Error(`${method} was cancelled`));
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this.pending.set(id, {
+        resolve: resolve as (v: unknown) => void,
+        reject,
+        timer,
+        detach: signal ? () => signal.removeEventListener("abort", onAbort) : undefined,
+      });
+      this.send({ t: "request", id, path, method, params });
+    });
+  }
+
+  // ── Events ──────────────────────────────────────────────────────────────
+
+  onNotification(listener: (method: string, params: unknown) => void): () => void {
+    this.notificationListeners.add(listener);
+    return () => this.notificationListeners.delete(listener);
+  }
+
+  onStatus(listener: (path: string, status: LspDocumentStatus) => void): () => void {
+    this.statusListeners.add(listener);
+    return () => this.statusListeners.delete(listener);
+  }
+
+  // ── Plumbing ────────────────────────────────────────────────────────────
+
+  private send(message: unknown): void {
+    this.ws.send(JSON.stringify(message));
+  }
+
+  private receive(event: MessageEvent): void {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(typeof event.data === "string" ? event.data : "");
+    } catch {
+      return;
+    }
+
+    switch (msg.t) {
+      case "hello":
+        // A fresh socket, so the server knows nothing about our documents.
+        for (const path of this.docs.keys()) this.sendOpen(path);
+        break;
+
+      case "ready":
+        this.setStatus(String(msg.path), {
+          state: "ready",
+          languageId: String(msg.languageId),
+          server: msg.server as LspServerInfo,
+          projectPath: String(msg.projectPath ?? ""),
+          capabilities: (msg.capabilities as Record<string, unknown>) ?? {},
+        });
+        break;
+
+      case "unavailable":
+        this.setStatus(String(msg.path), {
+          state: "unavailable",
+          reason: String(msg.reason),
+          server: (msg.server as LspMissingServer | null) ?? null,
+          message: String(msg.message),
+        });
+        break;
+
+      case "resync": {
+        // The bridge saw a version gap. Send the whole document rather than
+        // another delta onto a copy we know is wrong.
+        const path = String(msg.path);
+        const entry = this.docs.get(path);
+        if (entry) {
+          this.send({ t: "change", path, version: entry.source.getVersion(), text: entry.source.getText() });
+        }
+        break;
+      }
+
+      case "response": {
+        const pending = this.pending.get(Number(msg.id));
+        if (!pending) return;
+        settle(pending);
+        this.pending.delete(Number(msg.id));
+        pending.resolve(msg.result);
+        break;
+      }
+
+      case "error": {
+        const pending = this.pending.get(Number(msg.id));
+        if (!pending) return;
+        settle(pending);
+        this.pending.delete(Number(msg.id));
+        pending.reject(new Error(String(msg.message)));
+        break;
+      }
+
+      case "notification":
+        for (const listener of this.notificationListeners) {
+          listener(String(msg.method), msg.params);
+        }
+        break;
+    }
+  }
+
+  private setStatus(path: string, status: LspDocumentStatus): void {
+    const entry = this.docs.get(path);
+    if (entry) entry.status = status;
+    for (const listener of this.statusListeners) listener(path, status);
+  }
+
+  dispose(): void {
+    for (const pending of this.pending.values()) {
+      settle(pending);
+      pending.reject(new Error("The language server connection was closed"));
+    }
+    this.pending.clear();
+    this.docs.clear();
+    this.notificationListeners.clear();
+    this.statusListeners.clear();
+    this.ws.disconnect();
+  }
+}
+
+// ── Per-project sharing ────────────────────────────────────────────────────
+
+const connections = new Map<string, { connection: LspConnection; holders: number }>();
+
+/**
+ * The connection for a project, created on first use.
+ *
+ * Shared and reference-counted: several editors on one project must not each
+ * open a socket, since the server would then treat them as separate clients
+ * and could not tell that they are looking at the same documents.
+ */
+export function acquireLspConnection(projectName: string): LspConnection {
+  const existing = connections.get(projectName);
+  if (existing) {
+    existing.holders++;
+    return existing.connection;
+  }
+  const connection = new LspConnection(projectName);
+  connections.set(projectName, { connection, holders: 1 });
+  return connection;
+}
+
+/** True when that was the last holder, so the project has no editor open any more. */
+export function releaseLspConnection(projectName: string): boolean {
+  const existing = connections.get(projectName);
+  if (!existing) return false;
+  existing.holders--;
+  if (existing.holders > 0) return false;
+  connections.delete(projectName);
+  existing.connection.dispose();
+  return true;
+}

package/src/web/lib/lsp/lsp-documents.ts

@@ -0,0 +1,39 @@
+/**
+ * Which language-server document a Monaco model belongs to.
+ *
+ * Monaco hands a provider a model, not a project or a path, so this is the only
+ * way a provider registered globally for "typescript" can tell whose file it is
+ * being asked about. Keyed by the model's URI string because that is what the
+ * provider has in hand, and because two tabs on the same file share one model.
+ *
+ * A model that is not registered here has no language server, and every
+ * provider returns nothing for it rather than guessing — an untitled buffer, a
+ * diff pane, or a file in a project whose socket has not connected yet.
+ */
+import type * as MonacoType from "monaco-editor";
+import type { LspConnection } from "./lsp-client";
+
+export interface LspDocument {
+  connection: LspConnection;
+  /** Project-relative path, which is what the bridge expects. */
+  path: string;
+}
+
+const documents = new Map<string, LspDocument>();
+
+export function registerLspDocument(model: MonacoType.editor.ITextModel, document: LspDocument): void {
+  documents.set(model.uri.toString(), document);
+}
+
+export function unregisterLspDocument(model: MonacoType.editor.ITextModel): void {
+  documents.delete(model.uri.toString());
+}
+
+export function lspDocumentFor(model: MonacoType.editor.ITextModel): LspDocument | undefined {
+  return documents.get(model.uri.toString());
+}
+
+/** The document behind a `file:` URI a server reported, for cross-file results. */
+export function lspDocumentForUri(uri: string): LspDocument | undefined {
+  return documents.get(uri);
+}

package/src/web/lib/lsp/lsp-monaco.ts

@@ -0,0 +1,214 @@
+/**
+ * Translation between LSP's shapes and Monaco's.
+ *
+ * The two were designed from the same model, so most of this is mechanical.
+ * The parts that are not are exactly the parts worth isolating here:
+ *
+ * - **Positions are numbered differently.** LSP counts lines and characters
+ *   from zero; Monaco counts both from one. An off-by-one does not throw and
+ *   does not look broken — it quietly asks the server about the token next to
+ *   the cursor, so completions and hovers are confidently about the wrong
+ *   thing. This is the single most likely bug in the whole bridge.
+ * - **The kind enums share names and not numbers.** LSP's `CompletionItemKind`
+ *   starts `Text = 1, Method = 2`; Monaco's starts `Method = 0, Function = 1`.
+ *   Passing one through as the other yields plausible-but-wrong icons on every
+ *   suggestion, so the tables below map by *name* and let Monaco supply its own
+ *   numbers.
+ *
+ * The tables are plain data so they can be checked without a Monaco instance;
+ * only the functions that need Monaco's enums take it as an argument.
+ */
+import type * as MonacoType from "monaco-editor";
+
+// ── Geometry ───────────────────────────────────────────────────────────────
+
+export interface LspPosition {
+  line: number;
+  character: number;
+}
+
+export interface LspRange {
+  start: LspPosition;
+  end: LspPosition;
+}
+
+/** Monaco position (1-based) to LSP position (0-based). */
+/**
+ * Monaco's cancellation as an `AbortSignal`.
+ *
+ * Everything below the providers — the client, the socket, the session — is plain web
+ * platform and knows nothing about Monaco, so this is where the two meet. Passing it on is
+ * not a nicety: a language server answers one request at a time, so a superseded completion
+ * sits in front of the one the user is waiting for, and `$/cancelRequest` is the only thing
+ * that takes it out of the queue.
+ */
+export function abortSignalFor(token: MonacoType.CancellationToken | undefined): AbortSignal | undefined {
+  if (!token) return undefined;
+  const controller = new AbortController();
+  if (token.isCancellationRequested) controller.abort();
+  else token.onCancellationRequested(() => controller.abort());
+  return controller.signal;
+}
+
+export function toLspPosition(position: MonacoType.IPosition): LspPosition {
+  return { line: position.lineNumber - 1, character: position.column - 1 };
+}
+
+/** LSP position (0-based) to the Monaco pair. */
+export function fromLspPosition(position: LspPosition): { lineNumber: number; column: number } {
+  return { lineNumber: position.line + 1, column: position.character + 1 };
+}
+
+export function toLspRange(range: MonacoType.IRange): LspRange {
+  return {
+    start: { line: range.startLineNumber - 1, character: range.startColumn - 1 },
+    end: { line: range.endLineNumber - 1, character: range.endColumn - 1 },
+  };
+}
+
+export function fromLspRange(range: LspRange): MonacoType.IRange {
+  return {
+    startLineNumber: range.start.line + 1,
+    startColumn: range.start.character + 1,
+    endLineNumber: range.end.line + 1,
+    endColumn: range.end.character + 1,
+  };
+}
+
+// ── Kind tables, mapped by name ────────────────────────────────────────────
+
+/** LSP CompletionItemKind number to the name of Monaco's member. */
+export const COMPLETION_KIND_NAMES: Record<number, keyof typeof MonacoType.languages.CompletionItemKind> = {
+  1: "Text", 2: "Method", 3: "Function", 4: "Constructor", 5: "Field",
+  6: "Variable", 7: "Class", 8: "Interface", 9: "Module", 10: "Property",
+  11: "Unit", 12: "Value", 13: "Enum", 14: "Keyword", 15: "Snippet",
+  16: "Color", 17: "File", 18: "Reference", 19: "Folder", 20: "EnumMember",
+  21: "Constant", 22: "Struct", 23: "Event", 24: "Operator", 25: "TypeParameter",
+};
+
+/**
+ * LSP SymbolKind number to the name of Monaco's member.
+ *
+ * Written out rather than computed as `kind - 1`. The offset happens to hold
+ * for every current value, but it is a coincidence of two independent enums,
+ * and a table that is wrong is easier to see than arithmetic that is.
+ */
+export const SYMBOL_KIND_NAMES: Record<number, keyof typeof MonacoType.languages.SymbolKind> = {
+  1: "File", 2: "Module", 3: "Namespace", 4: "Package", 5: "Class",
+  6: "Method", 7: "Property", 8: "Field", 9: "Constructor", 10: "Enum",
+  11: "Interface", 12: "Function", 13: "Variable", 14: "Constant", 15: "String",
+  16: "Number", 17: "Boolean", 18: "Array", 19: "Object", 20: "Key",
+  21: "Null", 22: "EnumMember", 23: "Struct", 24: "Event", 25: "Operator",
+  26: "TypeParameter",
+};
+
+/** LSP DiagnosticSeverity to the name of Monaco's MarkerSeverity member. */
+export const SEVERITY_NAMES: Record<number, keyof typeof MonacoType.MarkerSeverity> = {
+  1: "Error", 2: "Warning", 3: "Info", 4: "Hint",
+};
+
+/** LSP DocumentHighlightKind to Monaco's member name. */
+export const HIGHLIGHT_KIND_NAMES: Record<number, keyof typeof MonacoType.languages.DocumentHighlightKind> = {
+  1: "Text", 2: "Read", 3: "Write",
+};
+
+export function completionKind(
+  monaco: typeof MonacoType,
+  kind: number | undefined,
+): MonacoType.languages.CompletionItemKind {
+  const name = COMPLETION_KIND_NAMES[kind ?? 0];
+  // An unknown kind becomes Text, which is what an editor shows for "something
+  // I have no icon for" — never a wrong icon.
+  return monaco.languages.CompletionItemKind[name ?? "Text"];
+}
+
+export function symbolKind(monaco: typeof MonacoType, kind: number | undefined): MonacoType.languages.SymbolKind {
+  const name = SYMBOL_KIND_NAMES[kind ?? 0];
+  return monaco.languages.SymbolKind[name ?? "Variable"];
+}
+
+export function markerSeverity(monaco: typeof MonacoType, severity: number | undefined): MonacoType.MarkerSeverity {
+  // LSP says an absent severity is up to the client; treating it as an error
+  // would put a red squiggle on something the server was unsure about, so it
+  // becomes a warning.
+  const name = SEVERITY_NAMES[severity ?? 0];
+  return monaco.MarkerSeverity[name ?? "Warning"];
+}
+
+export function highlightKind(
+  monaco: typeof MonacoType,
+  kind: number | undefined,
+): MonacoType.languages.DocumentHighlightKind {
+  const name = HIGHLIGHT_KIND_NAMES[kind ?? 0];
+  return monaco.languages.DocumentHighlightKind[name ?? "Text"];
+}
+
+// ── Documentation ─────────────────────────────────────────────────────────
+
+export type LspMarkup = string | { kind?: string; value: string } | { language: string; value: string };
+
+/**
+ * Whatever a server sent as documentation, as a Monaco markdown string.
+ *
+ * Servers use all three historical shapes: a bare string, a `MarkupContent`,
+ * and the deprecated `MarkedString` with a language for a fenced block. A
+ * plain string is *not* passed through as markdown — underscores and asterisks
+ * in an identifier would render as emphasis and the text would silently lose
+ * characters.
+ */
+export function toMarkdown(content: LspMarkup | LspMarkup[] | null | undefined): MonacoType.IMarkdownString | undefined {
+  if (content == null) return undefined;
+
+  if (Array.isArray(content)) {
+    const parts = content.map(toMarkdown).filter((p): p is MonacoType.IMarkdownString => Boolean(p?.value));
+    if (parts.length === 0) return undefined;
+    return { value: parts.map((p) => p.value).join("\n\n---\n\n"), isTrusted: false };
+  }
+
+  if (typeof content === "string") {
+    return { value: escapeMarkdown(content), isTrusted: false };
+  }
+
+  if ("language" in content) {
+    return { value: fence(content.language, content.value), isTrusted: false };
+  }
+
+  const value = content.kind === "markdown" ? content.value : escapeMarkdown(content.value);
+  return { value, isTrusted: false };
+}
+
+function fence(language: string, code: string): string {
+  return ["```" + language, code, "```"].join("\n");
+}
+
+/** Neutralise the characters that would otherwise render as formatting. */
+function escapeMarkdown(text: string): string {
+  return text.replace(/([\\`*_{}[\]()#+\-.!|>~])/g, "\\$1");
+}
+
+// ── Edits ─────────────────────────────────────────────────────────────────
+
+export interface LspTextEdit {
+  range: LspRange;
+  newText: string;
+}
+
+/** A single LSP edit as a Monaco model edit. */
+export function toModelEdit(edit: LspTextEdit): MonacoType.editor.ISingleEditOperation {
+  return { range: fromLspRange(edit.range), text: edit.newText };
+}
+
+/**
+ * Order edits so applying them in sequence is safe.
+ *
+ * A server returns edits against the *original* document, in no particular
+ * order. Applying an earlier one first shifts the offsets of every edit after
+ * it, so a formatting result or an organise-imports action lands scrambled.
+ * Applying from the bottom up leaves earlier positions untouched.
+ */
+export function sortEditsBottomUp(edits: LspTextEdit[]): LspTextEdit[] {
+  return [...edits].sort((a, b) =>
+    b.range.start.line - a.range.start.line ||
+    b.range.start.character - a.range.start.character,
+  );
+}