@hydranium/core 1.0.0-next.39 → 1.0.0-next.391

package/lib/node/process-memory.js

@@ -1,252 +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) {
-    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, label, prefix, ext) {
-    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, label, prefix = 'server-heap') {
-    const filePath = snapshotFilePath(directory, label, prefix, 'heapsnapshot');
-    v8.writeHeapSnapshot(filePath);
-    return filePath;
-}
-const CGROUP_ROOT = '/sys/fs/cgroup';
-function readNumber(file) {
-    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) {
-    const out = {};
-    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;
-}
-/** Generic fallback: every process is shown under the app heading, labelled by its (truncated) command line. */
-const defaultProcessClassifier = 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() {
-    const procs = [];
-    let entries = [];
-    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) {
-    const all = readAllProcs();
-    let selected = all;
-    let scoped = false;
-    if (rootPid !== undefined) {
-        const childrenByPpid = new Map();
-        for (const proc of all) {
-            (childrenByPpid.get(proc.ppid) ?? childrenByPpid.set(proc.ppid, []).get(proc.ppid)).push(proc);
-        }
-        const tree = [];
-        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 };
-}
-/**
- * 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 = {}) {
-    const classify = options.classify ?? defaultProcessClassifier;
-    const appLabel = options.appLabel ?? 'Application';
-    const lines = ['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();
-        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');
-}
-//# sourceMappingURL=process-memory.js.map

package/lib/node/process-memory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"process-memory.js","sourceRoot":"","sources":["../../src/node/process-memory.ts"],"names":[],"mappings":"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"}

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

@@ -1,211 +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 setOpenedText} when the client opens a document the server did not baseline for it —
- *    an equality-only baseline, since that text is a snapshot rather than a tracked one.
- *  - {@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>();
-
-   /**
-    * Per URI, the text the client declared it opened the document with, held
-    * only until a real baseline exists. Consulted by {@link computeEdits} when
-    * there is no shadow, and dropped on {@link invalidate}: a snapshot that
-    * outlived what the client holds would let the equality check skip an edit
-    * the client still needs.
-    */
-   protected opened = 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);
-   }
-
-   /**
-    * Record the buffer the language client declared at `didOpen`, for a URI
-    * with no baseline yet.
-    *
-    * Deliberately NOT a {@link set}: this text is only ever compared for
-    * EQUALITY, never diffed against. A line-keyed diff is position-dependent,
-    * so keying one to a `didOpen` snapshot the client may have moved past
-    * splices its buffer — the failure {@link computeEdits}'s full-replace
-    * fallback exists to avoid.
-    */
-   setOpenedText(uri: string, text: string): void {
-      this.opened.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);
-      // Drops the opened snapshot too, and this is the only place that has to:
-      // `computeEdits` clears it whenever it consults it, so the sole way it can
-      // outlive what the client holds is surviving under a live shadow until that
-      // shadow is dropped here.
-      this.opened.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),
-    *    or when there is no shadow and the client opened the document with exactly `newText`
-    *    (see {@link setOpenedText}) — pushing it anyway dirties the client's buffer on open.
-    *  - 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) {
-         // The opened snapshot has served its purpose either way: the shadow above
-         // is now the baseline, so leaving it would only risk a later stale match.
-         const openedText = this.opened.get(uri);
-         this.opened.delete(uri);
-         return openedText === newText ? [] : [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)]);
-         };
-      }
-   });
-}