@hydranium/core 1.0.0-next.23 → 1.0.0-next.230

package/src/documents/language-client-text-shadow.ts

@@ -1,175 +0,0 @@
-/********************************************************************************
- * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
- *
- * This program and the accompanying materials are made available under the
- * terms of the MIT License which is available in the project root.
- *
- * SPDX-License-Identifier: MIT
- ********************************************************************************/
-
-import { diffLines } from 'diff';
-import { Range, type TextEdit, uinteger } from 'vscode-languageserver';
-import { TextDocument } from 'vscode-languageserver-textdocument';
-
-/**
- * The minimum surface the shadow needs from a `HydraniumTextDocuments`:
- * a `create` method that materialises a fresh text document via the
- * configured `TextDocumentsConfiguration`. Declared as a narrow
- * structural interface so the manager satisfies it without an explicit
- * import (sidestepping the circular `HydraniumTextDocuments → shadow → manager`
- * dependency) and so tests can stub it with a minimal object literal.
- */
-export interface ShadowDocumentSource {
-   create(uri: string, languageId: string, version: number, content: string): TextDocument;
-}
-
-/** The range every full-document replace emitted here carries. */
-const FULL_RANGE = Range.create(0, 0, uinteger.MAX_VALUE, uinteger.MAX_VALUE);
-
-/**
- * Whether `edits` is the single full-document replace {@link LanguageClientTextShadow.computeEdits}
- * emits when it has no usable baseline.
- *
- * The distinction matters at the `workspace/applyEdit` egress: a full replace is
- * position-INDEPENDENT and therefore lands correctly on any client buffer, while
- * a line-keyed diff only lands correctly on the exact text it was diffed
- * against. Only the latter needs a client-version gate.
- */
-export function isFullReplace(edits: readonly TextEdit[]): boolean {
-   if (edits.length !== 1) {
-      return false;
-   }
-   const { start, end } = edits[0].range;
-   return start.line === FULL_RANGE.start.line && start.character === FULL_RANGE.start.character && end.line === FULL_RANGE.end.line;
-}
-
-/**
- * Tracks the text content the language client (typically Monaco) is believed to
- * currently hold so outgoing `workspace/applyEdit` requests can ship minimal
- * diffs instead of full-document replaces.
- *
- * Why it matters: a full-range replace on a moderately-sized YAML or DSL source
- * forces Monaco to re-tokenise the entire document (observed multi-second hangs
- * on large diagrams), whereas line-level diffs usually reduce that to a handful
- * of small edits.
- *
- * Update points the caller is responsible for:
- *  - {@link computeEdits} after each outgoing server→client sync (updates the shadow optimistically).
- *  - {@link set} when the server receives a `didChange` from the language client (the client now
- *    holds that text; we shouldn't resend it).
- *  - {@link invalidate} when the client rejects an edit (`applied=false`) or a doc is closed —
- *    the shadow is now stale and the next sync must fall back to a full replace.
- */
-export class LanguageClientTextShadow {
-   protected shadow = new Map<string, string>();
-
-   /**
-    * @param onFallback invoked when {@link computeEdits} falls back to a full-range replace due to
-    *    apply-verify mismatch. Useful for logging regressions.
-    * @param documents the {@link ShadowDocumentSource} used to materialise the throwaway probe
-    *    document in {@link computeEdits}. In production this is the owning
-    *    `HydraniumTextDocuments` (whose `create` threads through its configured
-    *    `TextDocumentsConfiguration`); tests pass a minimal stub. Routing
-    *    through the manager rather than `TextDocument.create` directly avoids the
-    *    `instanceof FullTextDocument` gate in the bare LSP `TextDocument.update`,
-    *    keeping the verifier honest for adopters with a custom text-document type.
-    */
-   constructor(
-      protected onFallback: (uri: string, reason: string) => void,
-      protected documents: ShadowDocumentSource
-   ) {}
-
-   /** Record the text the language client is known to hold (e.g. after a `didChange` echo). */
-   set(uri: string, text: string): void {
-      this.shadow.set(uri, text);
-   }
-
-   /**
-    * The text the language client is believed to hold, or `undefined` when
-    * there is no baseline (first sync, or after an {@link invalidate}).
-    *
-    * Read at the `workspace/applyEdit` egress BEFORE {@link computeEdits},
-    * which overwrites it: a push's minimal edits are keyed to this text, so an
-    * echo of that push carries ranges addressing it and nothing else. Losing
-    * it is what makes an incremental echo unreconstructable, and applying such
-    * an echo to the already-advanced synced text duplicates every inserted
-    * line.
-    */
-   get(uri: string): string | undefined {
-      return this.shadow.get(uri);
-   }
-
-   /** Forget the shadow for a URI; next {@link computeEdits} falls back to a full-document replace. */
-   invalidate(uri: string): void {
-      this.shadow.delete(uri);
-   }
-
-   /**
-    * Return the minimal LSP {@link TextEdit}s required to bring the language client's content from
-    * the tracked shadow to `newText`. Updates the shadow to `newText` so subsequent calls diff
-    * against it.
-    *
-    *  - Empty array when the shadow already equals `newText` (caller should skip the RPC).
-    *  - Full-range replace when there is no shadow (first sync or post-{@link invalidate}).
-    *  - Line-level diff otherwise. Before returning, we locally reconstruct `newText` by applying
-    *    the diff to `old`; if that doesn't match, we fall back to a full-range replace and notify
-    *    the fallback callback. This catches any algorithmic regression in {@link diffToEdits}
-    *    without risking client corruption.
-    */
-   computeEdits(uri: string, newText: string): TextEdit[] {
-      const old = this.shadow.get(uri);
-      if (old === newText) {
-         return [];
-      }
-      this.shadow.set(uri, newText);
-      const fullReplace: TextEdit = { range: FULL_RANGE, newText };
-      if (old === undefined) {
-         return [fullReplace];
-      }
-      const edits = diffToEdits(old, newText);
-      const verifyDoc = this.documents.create(uri, 'plaintext', 0, old);
-      if (TextDocument.applyEdits(verifyDoc, edits) !== newText) {
-         this.onFallback(uri, 'apply-verify-mismatch');
-         return [fullReplace];
-      }
-      return edits;
-   }
-}
-
-/**
- * Convert a {@link diffLines} result to a list of LSP {@link TextEdit}s keyed on line positions
- * in the *old* text. Contiguous added/removed hunks are coalesced into a single replace so the
- * client sees one edit per changed region.
- */
-export function diffToEdits(oldText: string, newText: string): TextEdit[] {
-   const hunks = diffLines(oldText, newText);
-   const edits: TextEdit[] = [];
-   let oldLine = 0;
-   let i = 0;
-   while (i < hunks.length) {
-      const hunk = hunks[i];
-      if (!hunk.added && !hunk.removed) {
-         oldLine += hunk.count ?? 0;
-         i++;
-         continue;
-      }
-      // Coalesce a run of add/remove hunks into a single replace for this region.
-      let removedLines = 0;
-      let addedText = '';
-      while (i < hunks.length && (hunks[i].added || hunks[i].removed)) {
-         if (hunks[i].removed) {
-            removedLines += hunks[i].count ?? 0;
-         }
-         if (hunks[i].added) {
-            addedText += hunks[i].value;
-         }
-         i++;
-      }
-      edits.push({
-         range: Range.create(oldLine, 0, oldLine + removedLines, 0),
-         newText: addedText
-      });
-      oldLine += removedLines;
-   }
-   return edits;
-}

package/src/lsp/instrument-connection.ts

@@ -1,66 +0,0 @@
-/********************************************************************************
- * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
- *
- * This program and the accompanying materials are made available under the
- * terms of the MIT License which is available in the project root.
- *
- * SPDX-License-Identifier: MIT
- ********************************************************************************/
-
-import type { LatencyCollector } from '@hydranium/protocol';
-
-type RequestHandler = (...args: unknown[]) => unknown;
-
-/**
- * Wrap an LSP `Connection` so every request handler registered through
- * `onRequest` is timed into `latency` under its method name — the LSP analog of
- * the data-server RPC chokepoint. Langium's `startLanguageServer` registers
- * `onCompletion`/`onHover`/… one handler at a time, so there is no single
- * dispatch point; but every registration funnels through the ONE `onRequest`
- * on the shared `Connection`, so decorating it catches every method with no
- * Langium fork and no per-handler code.
- *
- * Opt in where the head creates the connection, before it hands it to the
- * services factory — wrapping it afterwards is too late, because Langium has
- * already registered its handlers against the raw connection.
- *
- * `onRequest` has several overloads: most register a handler for a specific
- * method (a string, or a typed request whose `.method` names it) and one is the
- * `StarRequestHandler` catch-all `onRequest(handler)`. The star form fires only
- * for methods with no registered handler, so timing it would be misleading — it
- * is passed through untouched. Every other member of the connection is
- * forwarded unchanged.
- *
- * When `latency` is `undefined` the seam is off: the connection is returned
- * unchanged (no Proxy, no per-request timing), so a head can pass the result of
- * an env-gated factory (`latencyFromEnv()`) straight through and pay nothing
- * when latency is not enabled.
- */
-export function instrumentLspConnection<C extends object>(connection: C, latency: LatencyCollector | undefined): C {
-   if (!latency) {
-      return connection;
-   }
-   return new Proxy(connection, {
-      get(target, property, receiver): unknown {
-         const value: unknown = Reflect.get(target, property, receiver);
-         if (property !== 'onRequest' || typeof value !== 'function') {
-            return value;
-         }
-         const onRequest = value as (...args: unknown[]) => unknown;
-         return (...args: unknown[]): unknown => {
-            const [first, handler] = args;
-            // Star form `onRequest(handler)` — pass through; it is not a timer.
-            if (typeof first === 'function' || typeof handler !== 'function') {
-               return onRequest.apply(target, args);
-            }
-            const method = typeof first === 'string' ? first : (first as { method?: unknown }).method;
-            if (typeof method !== 'string') {
-               return onRequest.apply(target, args);
-            }
-            const original = handler as RequestHandler;
-            const timed: RequestHandler = (...handlerArgs) => latency.time(method, () => original(...handlerArgs));
-            return onRequest.apply(target, [first, timed, ...args.slice(2)]);
-         };
-      }
-   });
-}

package/src/node/process-memory.ts

@@ -1,299 +0,0 @@
-/********************************************************************************
- * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
- *
- * This program and the accompanying materials are made available under the
- * terms of the MIT License which is available in the project root.
- *
- * SPDX-License-Identifier: MIT
- ********************************************************************************/
-
-/*
- * Node-only process- and pod-level memory introspection plus heap-snapshot
- * writing. Everything here is generic OS-level code (V8 stats, cgroup v2/v1,
- * `/proc`); the only host-specific part is naming the processes, which a head
- * supplies through a `ProcessClassifier`.
- */
-
-import { Format } from '@hydranium/protocol';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import * as v8 from 'node:v8';
-
-/**
- * Format a one-shot memory snapshot of the CURRENT process (heap, rss, external, V8 limit).
- * Suited to a process that hosts no Langium documents (e.g. a host backend); for the
- * language-server process with document counts, see `formatServerState`.
- */
-export function formatProcessMemory(label: string): string {
-   const mem = process.memoryUsage();
-   const heap = v8.getHeapStatistics();
-   const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
-   return [
-      `${label}:`,
-      `  heap      ${Format.bytes(mem.heapUsed)} used / ${Format.bytes(mem.heapTotal)} total / ` +
-         `${Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`,
-      `  rss       ${Format.bytes(mem.rss)}, external ${Format.bytes(mem.external)}, arrayBuffers ${Format.bytes(mem.arrayBuffers)}`,
-      `  uptime    ${Math.round(process.uptime())}s, pid ${process.pid}`
-   ].join('\n');
-}
-
-/**
- * Compose an absolute artifact file path of the form `<prefix>[-<label>].<ext>` inside
- * {@link directory} (e.g. the workspace folder, so it lands on the persistent volume in cloud and
- * is visible in the file explorer), falling back to the OS temp dir when the directory is missing
- * or does not exist. The {@link prefix} carries the origin-first stem (e.g. `server-cpu`) and, when
- * a non-empty {@link label} is given (a named capture window), it is sanitised (non-word characters
- * → `_`, truncated to 40 chars) and appended as `-<label>`; an empty label yields the bare
- * `<prefix>.<ext>` so the manifest `kind` equals the filename stem. No timestamp — a fresh session
- * directory per run keeps names stable and collision-free. Shared by the heap-snapshot writer and
- * the sampled-profile capture so heap / CPU / allocation artefacts land identically, differing only
- * by extension.
- */
-export function snapshotFilePath(directory: string | undefined, label: string, prefix: string, ext: string): string {
-   const safeLabel = label ? label.replace(/[^\w.-]+/g, '_').slice(0, 40) : '';
-   const dir = directory && fs.existsSync(directory) ? directory : os.tmpdir();
-   const stem = safeLabel ? `${prefix}-${safeLabel}` : prefix;
-   return path.join(dir, `${stem}.${ext}`);
-}
-
-/**
- * Write a V8 heap snapshot of the CURRENT process to {@link directory}, falling back to the OS temp
- * dir when it is missing (see {@link snapshotFilePath}). `v8.writeHeapSnapshot` runs a full GC first and
- * briefly pauses the process; it also transiently inflates RSS while serialising. Returns the
- * absolute file path. The {@link prefix} (default `server-heap`, the origin-first stem) and
- * {@link label} are folded into the name.
- */
-export function writeHeapSnapshotToDir(directory: string | undefined, label: string, prefix = 'server-heap'): string {
-   const filePath = snapshotFilePath(directory, label, prefix, 'heapsnapshot');
-   v8.writeHeapSnapshot(filePath);
-   return filePath;
-}
-
-const CGROUP_ROOT = '/sys/fs/cgroup';
-
-function readNumber(file: string): number | undefined {
-   try {
-      const text = fs.readFileSync(file, 'utf8').trim();
-      if (text === 'max') {
-         return Number.POSITIVE_INFINITY;
-      }
-      const value = Number(text);
-      return Number.isFinite(value) ? value : undefined;
-   } catch {
-      return undefined;
-   }
-}
-
-/** Parse a `key value` per-line file (cgroup memory.stat) into a map. */
-function readKeyedBytes(file: string): Record<string, number> {
-   const out: Record<string, number> = {};
-   try {
-      for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
-         const [key, value] = line.trim().split(/\s+/);
-         if (key && value !== undefined) {
-            const num = Number(value);
-            if (Number.isFinite(num)) {
-               out[key] = num;
-            }
-         }
-      }
-   } catch {
-      // file absent or unreadable; caller handles the empty map.
-   }
-   return out;
-}
-
-interface ProcInfo {
-   pid: number;
-   rssBytes: number;
-   label: string;
-}
-
-interface RawProc extends ProcInfo {
-   ppid: number;
-}
-
-/** A readable role for a process, whether it belongs to the app, and whether exactly one is expected. */
-export interface ProcessRole {
-   /** Human-readable role shown in the snapshot. */
-   role: string;
-   /** Whether this process is part of the application (vs. tooling/debugger), counted in the app total. */
-   isApp: boolean;
-   /**
-    * Set when at most one instance of this role should exist; `formatPodMemory` warns when more than
-    * one is found (e.g. a duplicated/ghost language server).
-    */
-   singletonExpected?: boolean;
-}
-
-/** Map a raw command line to a {@link ProcessRole}. A head supplies this to label its own processes. */
-export type ProcessClassifier = (cmdline: string) => ProcessRole;
-
-/** Generic fallback: every process is shown under the app heading, labelled by its (truncated) command line. */
-const defaultProcessClassifier: ProcessClassifier = cmdline => ({ role: cmdline ? cmdline.slice(0, 60) : 'process', isApp: true });
-
-/** Read /proc for every visible process: pid, ppid, RSS, and a command label. */
-function readAllProcs(): RawProc[] {
-   const procs: RawProc[] = [];
-   let entries: string[] = [];
-   try {
-      entries = fs.readdirSync('/proc');
-   } catch {
-      return procs;
-   }
-   for (const entry of entries) {
-      if (!/^\d+$/.test(entry)) {
-         continue;
-      }
-      let status = '';
-      try {
-         status = fs.readFileSync(`/proc/${entry}/status`, 'utf8');
-      } catch {
-         continue;
-      }
-      const rssMatch = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
-      if (!rssMatch) {
-         continue;
-      }
-      const ppid = Number(status.match(/^PPid:\s+(\d+)/m)?.[1] ?? 0);
-      let label = '';
-      try {
-         label = fs.readFileSync(`/proc/${entry}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
-      } catch {
-         // fall back to the process name from status below.
-      }
-      if (!label) {
-         label = status.match(/^Name:\s+(.+)$/m)?.[1] ?? `pid ${entry}`;
-      }
-      procs.push({ pid: Number(entry), ppid, rssBytes: Number(rssMatch[1]) * 1024, label });
-   }
-   return procs;
-}
-
-/**
- * Sum and list per-process RSS. When {@link rootPid} is given, restrict to that process and its
- * descendants (the app's own process tree), which keeps the figure meaningful in local dev where
- * /proc otherwise shows the whole machine. In a container's PID namespace the tree is effectively
- * all the pod's processes anyway.
- */
-function collectProcessRss(rootPid?: number): { total: number; processes: ProcInfo[]; scoped: boolean } {
-   const all = readAllProcs();
-   let selected: RawProc[] = all;
-   let scoped = false;
-   if (rootPid !== undefined) {
-      const childrenByPpid = new Map<number, RawProc[]>();
-      for (const proc of all) {
-         (childrenByPpid.get(proc.ppid) ?? childrenByPpid.set(proc.ppid, []).get(proc.ppid)!).push(proc);
-      }
-      const tree: RawProc[] = [];
-      const queue = all.filter(proc => proc.pid === rootPid);
-      while (queue.length > 0) {
-         const proc = queue.shift()!;
-         tree.push(proc);
-         queue.push(...(childrenByPpid.get(proc.pid) ?? []));
-      }
-      if (tree.length > 0) {
-         selected = tree;
-         scoped = true;
-      }
-   }
-   const total = selected.reduce((sum, proc) => sum + proc.rssBytes, 0);
-   selected.sort((a, b) => b.rssBytes - a.rssBytes);
-   return { total, processes: selected, scoped };
-}
-
-/** Options for {@link formatPodMemory}. */
-export interface PodMemoryOptions {
-   /** Map a process command line to a readable role; lets a head label its own processes. */
-   classify?: ProcessClassifier;
-   /** Heading for the in-app process group (default `Application`). */
-   appLabel?: string;
-}
-
-/**
- * Format a pod/container-level memory snapshot read from the cgroup this process belongs to
- * (cgroup v2 `memory.current`/`peak`/`max`/`stat`, falling back to cgroup v1). This is the figure
- * the Kubernetes OOM-killer watches — it covers every process in the pod plus page cache and kernel
- * memory, so it is higher than any single `process.memoryUsage().rss`. Also sums per-process RSS so
- * the per-process split is visible. Explains itself when no cgroup memory controller is present
- * (e.g. local dev outside a container).
- */
-export function formatPodMemory(options: PodMemoryOptions = {}): string {
-   const classify = options.classify ?? defaultProcessClassifier;
-   const appLabel = options.appLabel ?? 'Application';
-   const lines: string[] = ['Pod memory snapshot:'];
-
-   const v2Current = path.join(CGROUP_ROOT, 'memory.current');
-   const v1Usage = path.join(CGROUP_ROOT, 'memory', 'memory.usage_in_bytes');
-
-   if (fs.existsSync(v2Current)) {
-      const current = readNumber(v2Current);
-      const peak = readNumber(path.join(CGROUP_ROOT, 'memory.peak'));
-      const max = readNumber(path.join(CGROUP_ROOT, 'memory.max'));
-      const stat = readKeyedBytes(path.join(CGROUP_ROOT, 'memory.stat'));
-      lines.push('  cgroup    v2');
-      lines.push(`  current   ${current !== undefined ? Format.bytes(current) : 'n/a'}`);
-      lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a (kernel too old for memory.peak)'}`);
-      lines.push(`  limit     ${max === Number.POSITIVE_INFINITY ? 'unlimited' : max !== undefined ? Format.bytes(max) : 'n/a'}`);
-      if (Object.keys(stat).length > 0) {
-         lines.push(
-            `  breakdown anon ${Format.bytes(stat.anon ?? 0)} (heaps/stacks), file ${Format.bytes(stat.file ?? 0)} (page cache), ` +
-               `kernel ${Format.bytes(stat.kernel ?? stat.slab ?? 0)}, sock ${Format.bytes(stat.sock ?? 0)}`
-         );
-      }
-   } else if (fs.existsSync(v1Usage)) {
-      const v1 = path.join(CGROUP_ROOT, 'memory');
-      const current = readNumber(v1Usage);
-      const peak = readNumber(path.join(v1, 'memory.max_usage_in_bytes'));
-      const limit = readNumber(path.join(v1, 'memory.limit_in_bytes'));
-      const stat = readKeyedBytes(path.join(v1, 'memory.stat'));
-      lines.push('  cgroup    v1');
-      lines.push(`  current   ${current !== undefined ? Format.bytes(current) : 'n/a'}`);
-      lines.push(`  peak      ${peak !== undefined ? Format.bytes(peak) : 'n/a'}`);
-      // v1 reports a huge sentinel for "unlimited"; treat anything >= 2^60 as unlimited.
-      lines.push(`  limit     ${limit !== undefined && limit < 2 ** 60 ? Format.bytes(limit) : 'unlimited'}`);
-      if (Object.keys(stat).length > 0) {
-         lines.push(
-            `  breakdown rss ${Format.bytes(stat.rss ?? 0)}, cache ${Format.bytes(stat.cache ?? 0)} (page cache), ` +
-               `kernel ${Format.bytes(stat.kernel ?? 0)}`
-         );
-      }
-   } else {
-      lines.push('  cgroup    no memory controller under /sys/fs/cgroup (not running in a container?)');
-   }
-
-   // Root at this process so local dev reports only the app's tree, not the whole machine.
-   const { processes } = collectProcessRss(process.pid);
-   if (processes.length > 0) {
-      const classified = processes.map(proc => ({ ...proc, ...classify(proc.label) }));
-      const appProcs = classified.filter(proc => proc.isApp);
-      const otherProcs = classified.filter(proc => !proc.isApp);
-      const appTotal = appProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
-
-      lines.push('');
-      lines.push(`  ${appLabel}: ${Format.bytes(appTotal)} across ${appProcs.length} process(es)`);
-      for (const proc of appProcs) {
-         lines.push(`    ${Format.bytes(proc.rssBytes).padStart(10)}  ${proc.role}  (pid ${proc.pid})`);
-      }
-      const singletonCounts = new Map<string, number>();
-      for (const proc of appProcs) {
-         if (proc.singletonExpected) {
-            singletonCounts.set(proc.role, (singletonCounts.get(proc.role) ?? 0) + 1);
-         }
-      }
-      for (const [role, count] of singletonCounts) {
-         if (count > 1) {
-            lines.push(`  WARNING: ${count} instances of "${role}" running - likely ghost process(es); expected 1`);
-         }
-      }
-      if (otherProcs.length > 0) {
-         const otherTotal = otherProcs.reduce((sum, proc) => sum + proc.rssBytes, 0);
-         lines.push(`  Other (tooling/debugger, not counted above): ${Format.bytes(otherTotal)} across ${otherProcs.length} process(es)`);
-      }
-      lines.push('  Note: in a real pod the cgroup figure above is the OOM ceiling; this per-process');
-      lines.push('  split is for attribution. Local dev may include debugger processes (excluded here).');
-   }
-
-   return lines.join('\n');
-}