@hydranium/core 1.0.0-next.34 → 1.0.0-next.340

package/src/testing/node/lsp-server-connection.ts

@@ -8,17 +8,17 @@
  ********************************************************************************/
 
 import { type Harness } from '@hydranium/protocol/testing';
-import { makeDuplexStreamPair } from '@hydranium/protocol/testing/node';
+import { PassThrough, type TransformCallback } from 'node:stream';
 import { StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node';
 import { type Connection, ProposedFeatures } from 'vscode-languageserver/node';
+import { withHydraniumLspFeatures } from '../../lsp/connection-features.js';
+import { captureAppliedEdits } from './applied-edit-capture.js';
 // The node `createConnection` from `vscode-languageserver/node` is built for a
 // standalone server PROCESS: it wires `process.exit()` onto the input stream's
 // `end`/`close` events, onto the `exit` notification (via its watchDog), and onto
-// a parent-pid liveness timer, and it calls `endProtocolConnection()` (a write)
-// on stream close. In-process every one of those is fatal — destroying the
-// streams at teardown trips the `close` handler, which writes into the destroyed
-// stream (an uncatchable synchronous `ERR_STREAM_DESTROYED`) and/or exits the host
-// test runner. The lower-level common `createConnection(connectionFactory,
+// a parent-pid liveness timer. In-process every one of those is fatal —
+// destroying the streams at teardown trips the `close` handler, which exits the
+// host test runner. The lower-level common `createConnection(connectionFactory,
 // watchDog, features)` form does none of that: it lets us inject a no-op-`exit`
 // WatchDog and build the connection over the in-memory streams, so teardown is the
 // primitive's responsibility alone.
@@ -27,9 +27,9 @@ import { type Connection, ProposedFeatures } from 'vscode-languageserver/node';
 // package map the LSP 3.18 libs ship.)
 import { createConnection, type WatchDog } from 'vscode-languageserver';
 import {
-   ApplyWorkspaceEditRequest,
    CompletionRequest,
    DidChangeTextDocumentNotification,
+   DidCloseTextDocumentNotification,
    DidOpenTextDocumentNotification,
    HoverRequest,
    InitializeRequest,
@@ -48,8 +48,7 @@ import {
    type Position,
    type ProtocolConnection,
    type PublishDiagnosticsParams,
-   type SemanticTokens,
-   type WorkspaceEdit
+   type SemanticTokens
 } from 'vscode-languageserver-protocol/node';
 
 /**
@@ -122,7 +121,7 @@ export interface NextAppliedEditOptions {
     * and needed for the same reason: one write can fan out to several pushes.
     */
    readonly fromIndex?: number;
-   /** Reject after this long. Defaults to the in-process publish timeout. */
+   /** Reject after this long. Defaults to the harness's own timeout, which differs by tier. */
    readonly timeoutMs?: number;
    /**
     * Additional predicate the edit must satisfy. The framework coalesces
@@ -133,45 +132,9 @@ export interface NextAppliedEditOptions {
    readonly match?: (edit: AppliedEdit) => boolean;
 }
 
-/** Every URI a {@link WorkspaceEdit} addresses, in `documentChanges` then `changes` order. */
-function editedUris(edit: WorkspaceEdit): string[] {
-   const uris: string[] = [];
-   for (const change of edit.documentChanges ?? []) {
-      if ('textDocument' in change) {
-         uris.push(change.textDocument.uri);
-      } else if ('oldUri' in change) {
-         uris.push(change.oldUri, change.newUri);
-      } else {
-         uris.push(change.uri);
-      }
-   }
-   uris.push(...Object.keys(edit.changes ?? {}));
-   return uris;
-}
-
-/** Every text edit's `newText` in a {@link WorkspaceEdit}, concatenated in edit order. */
-function insertedText(edit: WorkspaceEdit): string {
-   const parts: string[] = [];
-   for (const change of edit.documentChanges ?? []) {
-      if ('edits' in change) {
-         for (const textEdit of change.edits) {
-            if ('newText' in textEdit) {
-               parts.push(textEdit.newText);
-            }
-         }
-      }
-   }
-   for (const textEdits of Object.values(edit.changes ?? {})) {
-      for (const textEdit of textEdits) {
-         parts.push(textEdit.newText);
-      }
-   }
-   return parts.join('');
-}
-
 /**
- * The in-process LSP transport seam — a real `Connection` over the in-memory
- * {@link makeDuplexStreamPair}, plus the client side, the diagnostics capture,
+ * The in-process LSP transport seam — a real `Connection` over a crossed pair
+ * of in-memory streams, plus the client side, the diagnostics capture,
  * and the typed request facades — with NO services attached. It is the lower
  * half of `makeLspHarness`, factored out so a caller can OWN the services
  * tree: build the tree around {@link serverConnection} (`createXxxServices({
@@ -192,7 +155,9 @@ export interface LspServerConnection extends Harness {
     * Seam: the server-side `Connection`, NOT yet attached to a server. The caller
     * composes the services tree onto it (`createXxxServices({ connection })`) and
     * calls `startLanguageServer(services.shared)`, which wires the LSP handlers
-    * and calls `connection.listen()`.
+    * and calls `connection.listen()`; a caller recording only applied edits
+    * skips `startLanguageServer` but still calls `listen()`, as
+    * {@link makeLspServerConnection} says.
     */
    readonly serverConnection: Connection;
    /** Seam: the raw client connection over the in-memory wire; escape hatch for unwrapped requests. */
@@ -226,6 +191,12 @@ export interface LspServerConnection extends Harness {
     * unhandled method.
     */
    readonly appliedEdits: ReadonlyArray<AppliedEdit>;
+   /** Bytes written in each direction of the in-process JSON-RPC wire. */
+   readonly wireBytes: () => {
+      readonly clientToServer: number;
+      readonly serverToClient: number;
+      readonly total: number;
+   };
 
    /**
     * Drive the real LSP `initialize` → `initialized` handshake and return the
@@ -247,6 +218,8 @@ export interface LspServerConnection extends Harness {
     * associates with a language (silent no-diagnostics). `version` defaults to 1.
     */
    openDocument(uri: string, text: string, languageId: string, version?: number): void;
+   /** Send `textDocument/didClose` for a document opened through this harness. */
+   closeDocument(uri: string): Promise<void>;
    /** Send `textDocument/didChange` for `uri` as a single full-text replacement at `version`. */
    changeDocument(uri: string, text: string, version: number): void;
 
@@ -293,7 +266,7 @@ export interface LspServerConnection extends Harness {
     *
     * **An egress push is asynchronous well past the call that triggers it** —
     * the framework coalesces per URI and drives the sync from a build-phase
-    * settle, so a `ModelService.update` resolves long before the push is sent.
+    * settle, so a session's `update` resolves long before the push is sent.
     * Record `appliedEdits.length`, drive the edit, then await this; reading the
     * capture on the line after the write proves nothing.
     */
@@ -308,8 +281,9 @@ export interface LspServerConnection extends Harness {
     *
     * Throwing from the handler surfaces to the server as an RPC failure, which
     * is the other branch (`applyEditToLanguageClient` invalidates and rethrows).
+    * A handler returning a promise holds the answer until it settles.
     */
-   setApplyEditHandler(handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult): void;
+   setApplyEditHandler(handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult | Promise<ApplyWorkspaceEditResult>): void;
 
    /**
     * Release every resource: the diagnostics and applyEdit subscriptions, the
@@ -319,6 +293,39 @@ export interface LspServerConnection extends Harness {
    dispose(): void;
 }
 
+/**
+ * A `PassThrough` that counts the bytes written through it. Counting here
+ * rather than in a `'data'` listener is what keeps the wire buffering: a
+ * listener switches the stream to flowing mode, and a message written before
+ * the server calls `listen()` is then delivered to the counter alone and lost.
+ */
+class CountingPassThrough extends PassThrough {
+   bytes = 0;
+
+   override _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void {
+      this.bytes += chunk.length;
+      callback(null, chunk);
+   }
+}
+
+/** A crossed pair of {@link CountingPassThrough}s, disposed as one. */
+function makeCountingStreamPair(): {
+   readonly clientToServer: CountingPassThrough;
+   readonly serverToClient: CountingPassThrough;
+   dispose(): void;
+} {
+   const clientToServer = new CountingPassThrough();
+   const serverToClient = new CountingPassThrough();
+   return {
+      clientToServer,
+      serverToClient,
+      dispose(): void {
+         clientToServer.destroy();
+         serverToClient.destroy();
+      }
+   };
+}
+
 /**
  * Build the in-process LSP transport seam (server `Connection` + client + wire +
  * diagnostics capture + typed facades) WITHOUT attaching a server. The caller
@@ -329,9 +336,13 @@ export interface LspServerConnection extends Harness {
  * (it owns the `createServices` callback + `startLanguageServer` + `buildWorkspace`);
  * use this primitive directly when the CALLER must own the tree — e.g. to attach
  * additional protocol heads (data-server, GLSP) onto the same `shared` services.
+ *
+ * To record only {@link LspServerConnection.appliedEdits}, skip
+ * `startLanguageServer`, call `serverConnection.listen()`, and open through
+ * `TextDocuments.notifyDidOpenTextDocument`.
  */
 export function makeLspServerConnection(): LspServerConnection {
-   const pair = makeDuplexStreamPair();
+   const pair = makeCountingStreamPair();
 
    // No-op watchDog: in-process, no LSP lifecycle event (parent-pid liveness, the
    // `exit` notification, …) may exit the host test runner — `dispose()` owns
@@ -347,11 +358,15 @@ export function makeLspServerConnection(): LspServerConnection {
       logger =>
          createProtocolConnection(new StreamMessageReader(pair.clientToServer), new StreamMessageWriter(pair.serverToClient), logger),
       watchDog,
-      ProposedFeatures.all
+      withHydraniumLspFeatures(ProposedFeatures.all)
    );
 
    // Client side mirrors the directions: reads serverToClient, writes clientToServer.
-   const client = createProtocolConnection(new StreamMessageReader(pair.serverToClient), new StreamMessageWriter(pair.clientToServer));
+   const client = createProtocolConnection(
+      new StreamMessageReader(pair.serverToClient),
+      new StreamMessageWriter(pair.clientToServer),
+      console
+   );
    client.listen();
 
    const diagnostics: PublishDiagnosticsParams[] = [];
@@ -381,32 +396,7 @@ export function makeLspServerConnection(): LspServerConnection {
       }
    });
 
-   const appliedEdits: AppliedEdit[] = [];
-   /**
-    * Waiters armed by {@link LspServerConnection.nextAppliedEdit}, fanned out to
-    * from the ONE handler below — `vscode-jsonrpc` keeps a single handler per
-    * REQUEST type just as it does per notification type, so a second
-    * `onRequest` would displace this one and leave the server's `applyEdit`
-    * unanswered.
-    */
-   const appliedEditWaiters: Array<(edit: AppliedEdit) => boolean> = [];
-   let applyEditHandler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult = () => ({ applied: true });
-   const appliedEditSubscription = client.onRequest(ApplyWorkspaceEditRequest.type, (params: ApplyWorkspaceEditParams) => {
-      const edit: AppliedEdit = { params, uris: editedUris(params.edit), text: insertedText(params.edit) };
-      // Record BEFORE the handler runs, so a handler that rejects the edit or
-      // throws still leaves the push observable — the send is what the egress
-      // assertion is about.
-      appliedEdits.push(edit);
-      for (const waiter of [...appliedEditWaiters]) {
-         if (waiter(edit)) {
-            const at = appliedEditWaiters.indexOf(waiter);
-            if (at >= 0) {
-               appliedEditWaiters.splice(at, 1);
-            }
-         }
-      }
-      return applyEditHandler(params);
-   });
+   const appliedEditCapture = captureAppliedEdits(client, DEFAULT_DIAGNOSTICS_TIMEOUT_MS);
 
    let disposed = false;
 
@@ -414,7 +404,12 @@ export function makeLspServerConnection(): LspServerConnection {
       serverConnection,
       client,
       diagnostics,
-      appliedEdits,
+      appliedEdits: appliedEditCapture.appliedEdits,
+      wireBytes: () => ({
+         clientToServer: pair.clientToServer.bytes,
+         serverToClient: pair.serverToClient.bytes,
+         total: pair.clientToServer.bytes + pair.serverToClient.bytes
+      }),
 
       async initialize(params?: Partial<InitializeParams>): Promise<InitializeResult> {
          const initializeParams: InitializeParams = {
@@ -455,6 +450,10 @@ export function makeLspServerConnection(): LspServerConnection {
          });
       },
 
+      async closeDocument(uri: string): Promise<void> {
+         await client.sendNotification(DidCloseTextDocumentNotification.type, { textDocument: { uri } });
+      },
+
       changeDocument(uri: string, text: string, version: number): void {
          client.sendNotification(DidChangeTextDocumentNotification.type, {
             textDocument: { uri, version },
@@ -521,51 +520,16 @@ export function makeLspServerConnection(): LspServerConnection {
          });
       },
 
-      nextAppliedEdit(uri: string, timeoutMsOrOptions?: number | NextAppliedEditOptions): Promise<AppliedEdit> {
-         const options: NextAppliedEditOptions =
-            typeof timeoutMsOrOptions === 'number' ? { timeoutMs: timeoutMsOrOptions } : (timeoutMsOrOptions ?? {});
-         const timeoutMs = options.timeoutMs ?? DEFAULT_DIAGNOSTICS_TIMEOUT_MS;
-         const { fromIndex, match } = options;
-         const matches = (edit: AppliedEdit): boolean => edit.uris.includes(uri) && (match?.(edit) ?? true);
-         if (fromIndex !== undefined) {
-            // Replay from the capture first, for the same reason
-            // `nextDiagnostics` does: the push may already have arrived, and a
-            // waiter only ever sees later ones.
-            const captured = appliedEdits.slice(Math.max(0, fromIndex)).find(matches);
-            if (captured) {
-               return Promise.resolve(captured);
-            }
-         }
-         return new Promise<AppliedEdit>((resolve, reject) => {
-            const waiter = (edit: AppliedEdit): boolean => {
-               if (!matches(edit)) {
-                  return false;
-               }
-               clearTimeout(timer);
-               resolve(edit);
-               return true;
-            };
-            const timer = setTimeout(() => {
-               const at = appliedEditWaiters.indexOf(waiter);
-               if (at >= 0) {
-                  appliedEditWaiters.splice(at, 1);
-               }
-               reject(new Error(`Timed out waiting for a workspace/applyEdit addressing ${uri}`));
-            }, timeoutMs);
-            appliedEditWaiters.push(waiter);
-         });
-      },
+      nextAppliedEdit: appliedEditCapture.nextAppliedEdit,
 
-      setApplyEditHandler(handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult): void {
-         applyEditHandler = handler;
-      },
+      setApplyEditHandler: appliedEditCapture.setApplyEditHandler,
 
       dispose(): void {
          if (disposed) {
             return;
          }
          disposed = true;
-         appliedEditSubscription.dispose();
+         appliedEditCapture.dispose();
          diagnosticsSubscription.dispose();
          client.dispose();
          serverConnection.dispose();

package/src/testing/node/scratch-workspace.ts

@@ -14,15 +14,15 @@
  *
  * Any test that drives a **write path** needs one, and the reason is not
  * obvious enough to rediscover per suite. The writes themselves are usually
- * in-memory — `ModelService.update` goes to the multi-client text store, and
+ * in-memory — a session's `update` goes to the multi-client text store, and
  * only `save` reaches disk — but a rebuild also runs the integrity rules, and
  * their default `'silent'` sync mode persists repairs through
  * `WritableFileSystemProvider.writeFile`. So a write-path test pointed at a
  * committed sample workspace can **rewrite the sample files**, after which
  * every later run asserts against already-repaired input: a suite that passes
  * while testing nothing. The same applies to a fixture built in place, which
- * additionally loses its explanatory comments, because the write-back goes
- * through the serializer.
+ * additionally comes back in the serializer's layout, because the write-back
+ * goes through it.
  *
  * The second reason is cleanup. Hand-rolled `mkdtempSync` without a matching
  * `rmSync` leaks a directory per test run into the OS temp dir, which nobody
@@ -49,7 +49,7 @@
  */
 
 import { URI } from '@hydranium/langium';
-import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as path from 'node:path';
 
@@ -106,7 +106,12 @@ export interface ScratchWorkspace {
  * returned {@link ScratchWorkspace.dispose} with an `afterEach`.
  */
 export function makeScratchWorkspace(options: ScratchWorkspaceOptions = {}): ScratchWorkspace {
-   const root = mkdtempSync(path.join(tmpdir(), options.prefix ?? 'hydranium-scratch-'));
+   // RESOLVED, because `tmpdir()` can itself be a symlink — on macOS it answers
+   // `/tmp`, which links to `/private/tmp`. A root the server canonicalises to a
+   // different path than the one it was handed registers documents under one
+   // spelling and reads them under the other, failing initialization with an
+   // ENOENT that names neither the link nor this call.
+   const root = realpathSync(mkdtempSync(path.join(tmpdir(), options.prefix ?? 'hydranium-scratch-')));
    if (options.seed) {
       cpSync(options.seed, root, { recursive: true });
    }

package/src/testing/node/spawned-server.ts

@@ -61,7 +61,8 @@ import {
    type ProtocolConnection,
    type PublishDiagnosticsParams
 } from 'vscode-languageserver-protocol/node';
-import { type NextDiagnosticsOptions } from './lsp-server-connection.js';
+import { captureAppliedEdits } from './applied-edit-capture.js';
+import { type AppliedEdit, type NextAppliedEditOptions, type NextDiagnosticsOptions } from './lsp-server-connection.js';
 
 /**
  * Default bound on the `initialize` handshake, and the reason there is one at
@@ -195,6 +196,21 @@ export interface SpawnedServer extends Harness {
     * whenever one action fans out.
     */
    nextDiagnostics(uri: string, timeoutMsOrOptions?: number | NextDiagnosticsOptions): Promise<Diagnostic[]>;
+   /**
+    * Every `workspace/applyEdit` the child sent, in arrival order; append-only,
+    * each answered `{ applied: true }` as a real language client does.
+    *
+    * A Hydranium server mirrors an edit only for a document this connection has
+    * opened, so a write to one never sent `didOpen` here produces no entry. A
+    * second `applyEdit` handler registered on {@link connection} displaces this
+    * capture.
+    */
+   readonly appliedEdits: ReadonlyArray<AppliedEdit>;
+   /**
+    * Resolve with the next captured `workspace/applyEdit` addressing `uri`,
+    * with the same `fromIndex` and `match` contract as the in-process tier's.
+    */
+   nextAppliedEdit(uri: string, timeoutMsOrOptions?: number | NextAppliedEditOptions): Promise<AppliedEdit>;
    /**
     * Graceful `shutdown` / `exit`, each bounded, then `SIGKILL`. Resolves with
     * the child's exit code — `null` when a signal ended it, which is itself the
@@ -203,6 +219,37 @@ export interface SpawnedServer extends Harness {
    dispose(): Promise<number | null>;
 }
 
+/**
+ * Every server started and not yet disposed, so {@link disposeSpawnedServers}
+ * can reach one a test forgot.
+ *
+ * Holds the server — and through it the `ChildProcess` — rather than a pid. A
+ * pid identifies a process only while that process is alive: once it exits the
+ * OS may reissue the number, and Windows does so within seconds. A teardown
+ * that signalled a recorded pid would therefore reach whatever holds it now,
+ * which on a concurrent build is another task's compiler or test runner.
+ */
+const liveServers = new Set<SpawnedServer>();
+
+/**
+ * Terminate every server this module started that has not been disposed, and
+ * forget them.
+ *
+ * Safe to call when none are outstanding, and safe to call twice. Nothing here
+ * can reach a process this module did not spawn, because every kill goes
+ * through the `ChildProcess` handle libuv holds and libuv will not signal a
+ * child it has already reaped.
+ *
+ * A suite that disposes each server as it finishes needs this only as a net; a
+ * suite that does not needs it, because an orphan holding a port or a pipe
+ * makes the NEXT run's verdict meaningless.
+ */
+export async function disposeSpawnedServers(): Promise<void> {
+   const outstanding = [...liveServers];
+   liveServers.clear();
+   await Promise.all(outstanding.map(server => server.dispose()));
+}
+
 /** The captured streams, quoted into a boot-failure message. */
 function bootDiagnosis(stdoutPrefix: string, stderr: string): string {
    return (
@@ -253,7 +300,7 @@ export async function startSpawnedServer(options: SpawnedServerOptions): Promise
       }
    });
 
-   const connection = createProtocolConnection(child.stdout, child.stdin);
+   const connection = createProtocolConnection(child.stdout, child.stdin, console);
    const diagnostics: PublishDiagnosticsParams[] = [];
    /**
     * Waiters armed by {@link SpawnedServer.nextDiagnostics}, fanned out to from
@@ -272,6 +319,7 @@ export async function startSpawnedServer(options: SpawnedServerOptions): Promise
    connection.onNotification(LogMessageNotification.type, params => {
       logMessages.push(params);
    });
+   const appliedEditCapture = captureAppliedEdits(connection, RESPONSE_TIMEOUT_MS);
    connection.listen();
 
    const killTimeoutMs = options.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS;
@@ -390,7 +438,7 @@ export async function startSpawnedServer(options: SpawnedServerOptions): Promise
       return exitCode;
    }
 
-   return {
+   const server: SpawnedServer = {
       connection,
       pid: child.pid,
       initializeResult,
@@ -439,9 +487,15 @@ export async function startSpawnedServer(options: SpawnedServerOptions): Promise
             waiters.add(notify);
          });
       },
+      appliedEdits: appliedEditCapture.appliedEdits,
+      nextAppliedEdit: appliedEditCapture.nextAppliedEdit,
       dispose(): Promise<number | null> {
+         appliedEditCapture.dispose();
+         liveServers.delete(server);
          disposal ??= terminate();
          return disposal;
       }
    };
+   liveServers.add(server);
+   return server;
 }

package/src/testing/node/unhandled-rejections.ts

@@ -0,0 +1,31 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Run a Node-only assertion while collecting process-level unhandled rejection
+ * events. The callback owns the event-loop drain and can therefore choose the
+ * right observation window for the operation under test.
+ *
+ * Inside the window a rejection reaches only the array: while any listener is
+ * registered, Node hands none to its default handler and Vitest reports none as
+ * an error. A callback that never asserts on the array therefore hides every
+ * rejection it provokes.
+ */
+export async function captureUnhandledRejections<T>(callback: (rejections: unknown[]) => Promise<T>): Promise<T> {
+   const rejections: unknown[] = [];
+   const listener = (reason: unknown): void => {
+      rejections.push(reason);
+   };
+   process.on('unhandledRejection', listener);
+   try {
+      return await callback(rejections);
+   } finally {
+      process.off('unhandledRejection', listener);
+   }
+}

package/src/testing/parse-semantic-root.ts

@@ -55,7 +55,7 @@
 
 import { type AstNode, AstUtils, type LangiumCoreServices, URI } from '@hydranium/langium';
 import { type ParseHelperOptions, parseHelper } from '@hydranium/langium/test';
-import type { WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import type { WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
 
 /** The one field this module reads off a lexer or parser error. */
 interface ParseErrorMessage {