@hydranium/core 1.0.0-next.31 → 1.0.0-next.313

package/src/node/rename-over-open-readers.ts

@@ -0,0 +1,94 @@
+/********************************************************************************
+ * 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 Clock, SystemClock } from '@hydranium/protocol';
+import * as fsp from 'node:fs/promises';
+
+/**
+ * Errnos Windows raises when a replacing `rename` meets a handle already on the
+ * destination open. POSIX renames are unaffected by open handles, so these
+ * cannot fire there and the retry below costs nothing.
+ */
+export const RENAME_CONTENTION_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+/**
+ * How long a replacing rename may keep retrying before it gives up.
+ *
+ * BOUNDED, not open-ended: a genuine permission fault raises the same errno as
+ * contention and is distinguishable from it only by never clearing, so an
+ * unbounded wait would convert a hard error into a hang.
+ *
+ * The figure is a judgement, not a measurement, and the honest bound on it is
+ * that the previous 2s was observed EXHAUSTED on a loaded Windows CI runner
+ * while no upper bound has been established. What would settle it is recording
+ * how long a real contended rename takes to clear. graceful-fs tolerates 60s
+ * for Windows rename contention, but that is weaker support than it looks: it
+ * retries only where the destination has GONE, which is the opposite of
+ * replacing one a reader holds open.
+ */
+export const RENAME_BUDGET_MS = 10_000;
+
+/**
+ * How long a miss is waited out on Windows before it counts as an absence,
+ * since a replacing rename there can hide the name from a reader for a while.
+ * Bounded: a real deletion differs only by never ending, so it pays the whole
+ * budget. The figure is a judgement, not an established bound.
+ */
+export const RENAME_GAP_BUDGET_MS = 2_000;
+
+/** Seams for the test, which cannot make a real rename fail on demand. */
+export interface RenameOverOpenReadersOptions {
+   readonly rename?: (from: string, to: string) => Promise<void>;
+   readonly budgetMs?: number;
+   readonly clock?: Clock;
+}
+
+/**
+ * `rename` the staged content over `destination`, retrying while Windows
+ * reports the destination as held open.
+ *
+ * The staging file exists so a reader never sees a half-written file, and on
+ * Windows the very presence of that reader is what makes the replacing rename
+ * fail — so the indivisible write breaks under exactly the contention it was
+ * built for, and it breaks intermittently, which is worse than never working.
+ * A reader's handle is released in milliseconds, so waiting turns a spurious
+ * failure into a slightly later success.
+ *
+ * Exhausting the budget rethrows the last failure, leaving the caller's cleanup
+ * and error contract unchanged. An errno OUTSIDE the contention set is rethrown
+ * without waiting at all: retrying a fault that will not clear only delays it.
+ */
+export async function renameOverOpenReaders(
+   staging: string,
+   destination: string,
+   options: RenameOverOpenReadersOptions = {}
+): Promise<void> {
+   const rename = options.rename ?? fsp.rename;
+   const clock = options.clock ?? new SystemClock();
+   const budgetMs = options.budgetMs ?? RENAME_BUDGET_MS;
+   // A stopwatch, not two `now()` readings: a wall-clock jump would end the
+   // budget early or stretch it.
+   const waited = clock.stopwatch();
+   for (let attempt = 0; ; attempt++) {
+      try {
+         await rename(staging, destination);
+         return;
+      } catch (err: unknown) {
+         const code = err instanceof Error && 'code' in err ? String((err as NodeJS.ErrnoException).code) : undefined;
+         if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || waited.elapsedMs >= budgetMs) {
+            throw err;
+         }
+         // Backs off to keep a long contention window from spinning, capped so
+         // a late attempt still lands promptly once the handle is released.
+         // Not `clock.setTimer`: it unrefs its timer, so a process with only
+         // this write pending could exit mid-backoff.
+         await new Promise(resolve => setTimeout(resolve, Math.min(2 ** attempt, 50)));
+      }
+   }
+}

package/src/node/server-diagnostics.ts

@@ -49,7 +49,7 @@ export function startServerDiagnostics(shared: ServerSharedServicesMinimal, opti
       productName,
       version,
       phaseDetailThresholdMs,
-      ...nodeLogPreambleSections(phaseDetailThresholdMs)
+      ...nodeLogPreambleSections(phaseDetailThresholdMs, options)
    });
    if (options.logInitialMemory ?? true) {
       shared.Tracer.for('Process').memory('Initial Memory');

package/src/node/server-state-snapshot.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Format } from '@hydranium/protocol';
+import { Format, type Stopwatch, SystemClock } from '@hydranium/protocol';
 import { DocumentState, type LangiumDocuments } from '@hydranium/langium';
 import { isCstShed } from '../langium/residency/cst-residency-service.js';
 import { performance } from 'node:perf_hooks';
@@ -15,7 +15,7 @@ import * as v8 from 'node:v8';
 
 /** Cumulative samples kept across calls so each snapshot can report deltas. */
 interface DeltaState {
-   atMs: number;
+   sinceSample: Stopwatch;
    cpu: NodeJS.CpuUsage;
    elu: { idle: number; active: number };
 }
@@ -62,7 +62,7 @@ export interface ServerStateSnapshotOptions {
  * requested via `options` ({@link ServerStateSnapshotOptions}).
  */
 export function formatServerState(documents?: LangiumDocuments, label?: string, options?: ServerStateSnapshotOptions): string {
-   const now = performance.now();
+   const sinceSample = new SystemClock().stopwatch();
    const mem = process.memoryUsage();
    const heap = v8.getHeapStatistics();
    const cpu = process.cpuUsage();
@@ -87,7 +87,7 @@ export function formatServerState(documents?: LangiumDocuments, label?: string,
          `native contexts ${heap.number_of_native_contexts}, detached contexts ${heap.number_of_detached_contexts}`
    );
    if (lastSample) {
-      const wallMs = now - lastSample.atMs;
+      const wallMs = lastSample.sinceSample.elapsedMs;
       const userMs = (cpu.user - lastSample.cpu.user) / 1000;
       const systemMs = (cpu.system - lastSample.cpu.system) / 1000;
       const cpuPct = wallMs > 0 ? Math.round(((userMs + systemMs) / wallMs) * 100) : 0;
@@ -138,7 +138,7 @@ export function formatServerState(documents?: LangiumDocuments, label?: string,
       }
    }
 
-   lastSample = { atMs: now, cpu, elu };
+   lastSample = { sinceSample, cpu, elu };
    return lines.join('\n');
 }
 

package/src/node/socket-launcher.ts

@@ -7,17 +7,30 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred } from '@hydranium/langium';
 import * as net from 'node:net';
-import type { Disposable, Logger } from '@hydranium/protocol';
+import { Deferred, describeError, describeErrorWithStack, type Disposable, type Logger } from '@hydranium/protocol';
 import { createMessageConnection, SocketMessageReader, SocketMessageWriter } from 'vscode-jsonrpc/node';
 import type { MessageConnection } from 'vscode-jsonrpc';
 import type { IntegratedServer } from '../launcher/integrated-server.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { initializeWorkspaceWithoutLsp, type WorkspaceFolderInput } from '../langium/workspace/initialize-workspace.js';
 
 /**
  * Construction-time options for {@link startSocketServer}.
  */
 export interface SocketServerOptions {
+   /**
+    * Shared services tree the head serves from. Without an LSP head the
+    * launcher brings its workspace up before listening, so a client never
+    * reaches a workspace that is not up.
+    */
+   readonly shared: ServerSharedServicesMinimal;
+   /**
+    * Workspace root(s) to initialize — a filesystem path or a `URI`. Required
+    * when no LSP head is composed, refused beside one: see
+    * {@link initializeWorkspaceWithoutLsp}.
+    */
+   readonly workspace?: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>;
    /**
     * Port to bind. Default `0` — OS-assigned ephemeral. Resolve the
     * actual port off {@link StartedSocketServer.port} once `started`
@@ -25,9 +38,25 @@ export interface SocketServerOptions {
     */
    readonly port?: number;
    /**
-    * Optional logger. If omitted, the launcher runs silently — the
-    * adopter is expected to surface lifecycle events through their own
-    * logging in {@link OnClientConnection} if needed.
+    * Interface to bind. Default `'127.0.0.1'` (LOCAL ONLY) — a head whose
+    * port is OS-assigned and announced over the LSP connection is
+    * reachable only by a client on the same machine anyway, so a wider
+    * binding exposes a port nothing off-box can address. Matches
+    * `startGlspServer`'s default, so the two socket heads agree.
+    *
+    * Pass `'::'` for every interface: that is the dual-stack any-address,
+    * so both IPv4 and IPv6 clients connect. `'0.0.0.0'` is NOT the same —
+    * it takes IPv4 only and refuses `::1`.
+    *
+    * An address no local interface holds fails the bind, so `started`
+    * rejects with `EADDRNOTAVAIL` rather than falling back to a wider one.
+    */
+   readonly host?: string;
+   /**
+    * Optional logger for lifecycle lines and each connection's protocol
+    * faults. If omitted, the launcher runs silently — the adopter is expected
+    * to surface lifecycle events through their own logging in
+    * {@link OnClientConnection} if needed.
     */
    readonly logger?: Logger;
    /** Tag included in lifecycle log lines. Default `"SocketServer"`. */
@@ -56,10 +85,12 @@ export type OnClientConnection = (connection: MessageConnection) => Disposable;
 /**
  * Live socket server handle returned by {@link startSocketServer}.
  *
- * - {@link IntegratedServer.started} resolves once `listen` resolves
- *   AND `port` is populated.
+ * - {@link IntegratedServer.started} resolves once the workspace is up,
+ *   where the launcher brings it up, AND `listen` resolves AND `port` is
+ *   populated. It rejects, and nothing listens, when the bring-up fails.
  * - {@link IntegratedServer.stopped} resolves when the underlying
- *   `net.Server` emits `close`.
+ *   `net.Server` emits `close`, or once a failed bring-up has rejected
+ *   `started`.
  * - {@link port} is undefined until `started` resolves.
  * - {@link close} triggers shutdown: disposes all active client
  *   connections and closes the underlying `net.Server`.
@@ -82,12 +113,17 @@ export interface StartedSocketServer extends IntegratedServer {
  * close / server shutdown. Adopters keep per-client instance creation
  * (their server objects) but don't re-implement the tracking machinery.
  *
+ * **Without an LSP head the launcher brings the workspace up, then
+ * listens**, as `startStdioServer` does: a request served before the
+ * bring-up starts keeps its cross-file references unresolved for good.
+ *
  * The port is only known once {@link StartedSocketServer.started} has
  * resolved, so announcing it — via {@link publishPortOnLspConnection} —
  * belongs after that await, not beside the call.
  */
 export function startSocketServer(options: SocketServerOptions, onClientConnection: OnClientConnection): StartedSocketServer {
    const port = options.port ?? 0;
+   const host = options.host ?? '127.0.0.1';
    const logger = options.logger;
    const tag = options.logTag ?? 'SocketServer';
    const started = new Deferred<void>();
@@ -100,7 +136,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
    const activeConnections: Array<{ connection: MessageConnection; adopterDisposable: Disposable }> = [];
 
    const netServer = net.createServer(socket => {
-      const connection = createMessageConnection(new SocketMessageReader(socket), new SocketMessageWriter(socket));
+      const connection = createMessageConnection(new SocketMessageReader(socket), new SocketMessageWriter(socket), logger?.with(tag));
       const adopterDisposable = onClientConnection(connection);
       const entry = { connection, adopterDisposable };
       activeConnections.push(entry);
@@ -115,7 +151,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
          try {
             adopterDisposable.dispose();
          } catch (err) {
-            logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${(err as Error)?.message ?? err}`);
+            logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${describeErrorWithStack(err)}`);
          }
          connection.dispose();
          const idx = activeConnections.indexOf(entry);
@@ -128,7 +164,34 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
       connection.listen();
    });
 
-   netServer.listen(port);
+   // The workspace manager logs a failed initialization itself; a refused
+   // `workspace` throws before `initializing` is set.
+   let initializing = false;
+   let closed = false;
+   const begin = async (): Promise<void> => {
+      const initialization = initializeWorkspaceWithoutLsp(options.shared, options.workspace);
+      initializing = true;
+      await initialization;
+      initializing = false;
+      // A `close` during the bring-up has resolved `stopped` already.
+      if (closed) {
+         started.reject(new Error(`${tag} was closed before it listened`));
+         return;
+      }
+      netServer.listen(port, host);
+   };
+   begin().catch((err: unknown) => {
+      if (initializing) {
+         logger?.debug(`[${tag}] Startup failed: the workspace did not initialize. ${describeError(err)}`);
+      } else {
+         logger?.error(`[${tag}] Startup failed: ${describeErrorWithStack(err)}`);
+      }
+      started.reject(err);
+      stopped.resolve();
+   });
+   // `started` is always observed internally, as `startStdioServer`'s is, so a
+   // caller that closes early and ignores it cannot crash the process.
+   void started.promise.catch(() => undefined);
    netServer.on('listening', () => {
       const addressInfo = netServer.address();
       if (!addressInfo) {
@@ -144,11 +207,11 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
          return;
       }
       handle.port = addressInfo.port;
-      logger?.info(`[${tag}] Ready to accept new client requests on port: ${addressInfo.port}`);
+      logger?.info(`[${tag}] Ready to accept new client requests on ${addressInfo.address} port: ${addressInfo.port}`);
       started.resolve();
    });
    netServer.on('error', err => {
-      logger?.error(`[${tag}] Error: ${err.message}`);
+      logger?.error(`[${tag}] Error: ${describeErrorWithStack(err)}`);
       started.reject(err);
    });
    netServer.on('close', () => {
@@ -158,7 +221,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
          try {
             entry.adopterDisposable.dispose();
          } catch (err) {
-            logger?.warn(`[${tag}] Adopter disposable threw on shutdown: ${(err as Error)?.message ?? err}`);
+            logger?.warn(`[${tag}] Adopter disposable threw on shutdown: ${describeErrorWithStack(err)}`);
          }
          entry.connection.dispose();
       }
@@ -173,6 +236,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
       started: started.promise,
       stopped: stopped.promise,
       close(): void {
+         closed = true;
          netServer.close();
       }
    };

package/src/node/startup-cpu-profile.ts

@@ -0,0 +1,94 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { DEFAULT_CPU_PROFILE_FILE_ENV } from '@hydranium/protocol';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { Session } from 'node:inspector';
+import { dirname } from 'node:path';
+import { isMainThread } from 'node:worker_threads';
+import { expandLogFilePlaceholders } from '../langium/diagnostics/logger.js';
+
+/**
+ * Marks the profile started on `globalThis` rather than in this module, since
+ * a second installed copy of the package loads its own module and would start
+ * a second session writing a profile of its own.
+ */
+const CPU_PROFILE_STARTED: unique symbol = Symbol.for('@hydranium/core#startupCpuProfileStarted');
+const processGlobal = globalThis as typeof globalThis & { [CPU_PROFILE_STARTED]?: true };
+
+/**
+ * Start profiling this process when {@link DEFAULT_CPU_PROFILE_FILE_ENV} is
+ * set, and write the profile once, on `exit` or on SIGTERM. Called when
+ * `@hydranium/core/node` loads, so every Node head is profiled from before its
+ * workspace load; a no-op on a second call, from any copy of the package, and
+ * in a `worker_threads` worker.
+ *
+ * `--cpu-prof` is no substitute: it writes only on a normal exit, and SIGTERM
+ * ends a process without one. The SIGTERM listener re-raises the signal when it
+ * is the only one, so the process still ends by it; another listener keeps
+ * control of the ending. Samples accumulate for the life of the process, so
+ * this is for test runs, not a production server.
+ *
+ * A head in a worker is not profiled: a worker's session would write the main
+ * thread's file, since threads share the pid, no signal reaches it, and its
+ * `exit` listeners run neither when it is terminated nor when the process ends.
+ *
+ * A `ProfileCapture` window runs beside it in its own inspector session.
+ */
+export function startCpuProfileFromEnv(): void {
+   const template = process.env[DEFAULT_CPU_PROFILE_FILE_ENV];
+   if (!template || !isMainThread || processGlobal[CPU_PROFILE_STARTED]) {
+      return;
+   }
+   processGlobal[CPU_PROFILE_STARTED] = true;
+   const session = new Session();
+   session.connect();
+   session.post('Profiler.enable');
+   session.post('Profiler.start');
+   let written = false;
+   // Synchronous throughout: an in-process session answers `post` before it
+   // returns, and nothing asynchronous runs after `exit`. The session is
+   // disconnected from the answer, so nothing here depends on that order.
+   const write = (): void => {
+      if (written) {
+         return;
+      }
+      written = true;
+      const file = expandLogFilePlaceholders(template);
+      session.post('Profiler.stop', (error, result) => {
+         try {
+            if (error) {
+               throw error;
+            }
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, JSON.stringify(result.profile));
+         } catch (err: unknown) {
+            process.stderr.write(
+               `[hydranium] Could not write the CPU profile to ${file}: ${err instanceof Error ? err.message : String(err)}\n`
+            );
+         }
+         session.disconnect();
+      });
+   };
+   process.once('exit', write);
+   // Registered until the write is done, not `once`: a `once` listener is gone
+   // before it runs, and with no listener left the default action ends the
+   // process on a second SIGTERM, which a host ending its process tree sends
+   // while the write is still running. Prepended: a `once` listener ahead of
+   // this one has removed itself by the time this counts, which would re-raise
+   // into its unfinished shutdown.
+   const writeOnSigterm = (): void => {
+      write();
+      process.removeListener('SIGTERM', writeOnSigterm);
+      if (process.listenerCount('SIGTERM') === 0) {
+         process.kill(process.pid, 'SIGTERM');
+      }
+   };
+   process.prependListener('SIGTERM', writeOnSigterm);
+}

package/src/node/stdio-launcher.ts

@@ -7,13 +7,12 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred } from '@hydranium/langium';
-import type { Disposable, Logger } from '@hydranium/protocol';
+import { Deferred, type Disposable, type Logger, describeError, describeErrorWithStack } from '@hydranium/protocol';
 import type { MessageConnection } from 'vscode-jsonrpc';
 import { createMessageConnection, StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node';
 import type { IntegratedServer } from '../launcher/integrated-server.js';
 import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
-import { initializeWorkspaceProgrammatically, type WorkspaceFolderInput } from '../langium/workspace/initialize-workspace.js';
+import { initializeWorkspaceWithoutLsp, type WorkspaceFolderInput } from '../langium/workspace/initialize-workspace.js';
 
 /** Construction-time options for {@link startStdioServer}. */
 export interface StdioServerOptions {
@@ -24,16 +23,17 @@ export interface StdioServerOptions {
     */
    readonly shared: ServerSharedServicesMinimal;
    /**
-    * Workspace root(s) to initialize — a filesystem path or a `URI`. Omit when
-    * the caller has already initialized the workspace itself, in which case the
-    * launcher only wires the transport.
+    * Workspace root(s) to initialize — a filesystem path or a `URI`. Required
+    * when no LSP head is composed, refused beside one: see
+    * {@link initializeWorkspaceWithoutLsp}.
     */
    readonly workspace?: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>;
    /**
-    * Optional logger for lifecycle lines. Omitted means silent — note that a
-    * logger writing to **stdout** would corrupt this head's protocol stream, so
-    * anything passed here must sink elsewhere. The framework's own `LspLogger`
-    * writes to stderr when no LSP connection is bound, which is correct here.
+    * Optional logger for lifecycle lines and the connection's protocol
+    * faults. Omitted means silent — note that a logger writing to **stdout**
+    * would corrupt this head's protocol stream, so anything passed here must
+    * sink elsewhere. The framework's own `LspLogger` writes to stderr when no
+    * LSP connection is bound, which is correct here.
     */
    readonly logger?: Logger;
    /** Tag included in lifecycle log lines. Default `"StdioServer"`. */
@@ -66,11 +66,10 @@ export interface StartedStdioServer extends IntegratedServer {
 
 /**
  * Start a **stdio**-based protocol head — the transport `hydranium-cli` speaks,
- * since `query` / `save` / `projects` / `watch` all spawn a server command and
- * drive JSON-RPC over its stdin/stdout. The socket counterpart is
- * `startSocketServer`; the two differ more
- * than the transport swap suggests, and the differences are the reason this is
- * a launcher rather than four lines in each adopter's entry.
+ * since its data-server subcommands spawn a server command and drive JSON-RPC
+ * over its stdin/stdout. The socket counterpart is `startSocketServer`; the two
+ * differ more than the transport swap suggests, and the differences are the
+ * reason this is a launcher rather than four lines in each adopter's entry.
  *
  * **One client, not N.** A socket head accepts arbitrarily many connections and
  * tracks them; a stdio head has exactly one peer — the process that spawned it
@@ -101,7 +100,8 @@ export function startStdioServer(
 
    const connection = createMessageConnection(
       new StreamMessageReader(options.input ?? process.stdin),
-      new StreamMessageWriter(options.output ?? process.stdout)
+      new StreamMessageWriter(options.output ?? process.stdout),
+      logger?.with(tag)
    );
    const adopterDisposable = onConnection(connection);
 
@@ -114,18 +114,24 @@ export function startStdioServer(
       try {
          adopterDisposable.dispose();
       } catch (err: unknown) {
-         logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${err instanceof Error ? err.message : String(err)}`);
+         logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${describeErrorWithStack(err)}`);
       }
       connection.dispose();
       stopped.resolve();
    };
    connection.onClose(() => close());
 
+   // The workspace manager logs a failed initialization itself; a refused
+   // `workspace` throws before `initializing` is set.
+   let initializing = false;
    const begin = async (): Promise<void> => {
+      const initialization = initializeWorkspaceWithoutLsp(options.shared, options.workspace);
+      initializing = true;
       if (options.workspace !== undefined) {
          logger?.info(`[${tag}] Initializing workspace`);
-         await initializeWorkspaceProgrammatically(options.shared, options.workspace);
       }
+      await initialization;
+      initializing = false;
       // Only now attach the reader — see the ordering note in the doc above.
       connection.listen();
       logger?.info(`[${tag}] Listening on stdio`);
@@ -137,7 +143,11 @@ export function startStdioServer(
          // A failed startup must not leave a half-live head: report it on
          // `started` and tear the connection down rather than listening over an
          // uninitialized workspace.
-         logger?.error(`[${tag}] Startup failed: ${err instanceof Error ? err.message : String(err)}`);
+         if (initializing) {
+            logger?.debug(`[${tag}] Startup failed: the workspace did not initialize. ${describeError(err)}`);
+         } else {
+            logger?.error(`[${tag}] Startup failed: ${describeErrorWithStack(err)}`);
+         }
          started.reject(err);
          close();
       }

package/src/testing/document-uri-policy-conformance.ts

@@ -96,7 +96,7 @@ export function documentUriPolicyConformance(
       // Computed here rather than tallied from the assertions above, so the
       // guard does not depend on the runner executing tests in declaration
       // order (a `--shuffle` run would otherwise read it as zero).
-      it(`at least one sample URI is loadable (checked: ${sampleUris.join(', ')})`, () => {
+      it(`at least one sample URI is loadable among ${sampleUris.join(', ')}`, () => {
          const loadable = sampleUris.filter(uri => makePolicy().loadUri(uri) !== undefined);
          expect(loadable.length > 0).toBe(true);
       });

package/src/testing/fake-document.ts

@@ -9,6 +9,7 @@
 
 import { DocumentState, type AstNode, type AstReflection, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
 import { buildAstNode } from '../langium/ast-extension/ast-node-builder.js';
+import { type AstDiagnostic } from '../langium/validation/document-validator.js';
 
 /**
  * Build a typed AST-node fixture for unit tests.
@@ -104,7 +105,7 @@ function stringifyFakeRoot(root: unknown): string {
  * staging. Override via `options.state` for tests that gate on earlier
  * phases.
  */
-export function makeFakeDocument<TAst extends AstNode = AstNode, TDiagnostic = unknown>(
+export function makeFakeDocument<TAst extends AstNode = AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
    uri: string | URI,
    root: TAst,
    options: FakeDocumentOptions<TAst, TDiagnostic> = {}

package/src/testing/index.ts

@@ -14,7 +14,7 @@
  * builders, the snapshot and URI-policy conformance primitives, the
  * structured-write pipeline driver, and a re-export of `langium/test`.
  *
- * Neutrality is gated (`scripts/check-neutral-bundles.mjs`). The test support
+ * Neutrality is gated (`scripts/check-neutral-bundles.mts`). The test support
  * that needs a real filesystem or a Node stream transport — the scratch
  * workspace, the golden corpus, the LSP transport and its harness — lives at
  * `@hydranium/core/testing/node`, on the same rule the package surface uses:
@@ -26,6 +26,7 @@ export * from './document-uri-policy-conformance.js';
 export * from './fake-description.js';
 export * from './fake-document.js';
 export * from './fake-reflection.js';
+// oxlint-disable-next-line import/export -- misreads export * from an npm package: https://github.com/oxc-project/oxc/pull/26872
 export * from './langium-test-helpers.js';
 export * from './make-noop-language-services.js';
 export * from './make-noop-shared-services.js';

package/src/testing/langium-test-helpers.ts

@@ -23,4 +23,5 @@
  * contracts stays Langium upstream, so a rename there surfaces here rather than
  * being absorbed by a hand-maintained list.
  */
+// oxlint-disable-next-line import/export -- misreads export * from an npm package: https://github.com/oxc-project/oxc/pull/26872
 export * from '@hydranium/langium/test';

package/src/testing/make-noop-shared-services.ts

@@ -9,6 +9,8 @@
 
 import { type Clock, DefaultTracer, type Logger, NoopLogger, SystemClock, type Tracer } from '@hydranium/protocol';
 import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.js';
+import { DefaultMessageRenderer, type MessageRenderer } from '../messages/renderer.js';
 
 /**
  * Overrides for {@link makeNoopSharedServices}. The three observability slots
@@ -29,6 +31,18 @@ export interface NoopSharedServicesOverrides {
    Logger?: Logger;
    /** Bound on the top-level `Tracer` slot. Default: a `DefaultTracer` over `Logger` + `Clock`. */
    Tracer?: Tracer;
+   /** Factory for the `ServerLocale` slot. Default: a real one, reporting no locale. */
+   ServerLocale?: (services: ServerSharedServicesMinimal) => ServerLocale;
+   /**
+    * Factory for the `MessageRenderer` slot. Default: the real
+    * {@link DefaultMessageRenderer}, whose no-catalogue behaviour is a
+    * pass-through — so the default is the framework's own behaviour, not a stub.
+    *
+    * A factory rather than an instance, because a renderer reads the tree it is
+    * bound into. Both slots are resolved lazily, so an override is honoured
+    * however late the caller reads them.
+    */
+   MessageRenderer?: (services: ServerSharedServicesMinimal) => MessageRenderer;
    /** Per-slot `workspace` overrides. Slots left out resolve to `undefined`. */
    workspace?: Record<string, unknown>;
    /** Any other minimal slot (`ServiceRegistry`, `AstReflection`, `additionalDocuments`, …). */
@@ -63,11 +77,21 @@ export interface NoopSharedServicesOverrides {
 export function makeNoopSharedServices<T extends ServerSharedServicesMinimal = ServerSharedServicesMinimal>(
    overrides: NoopSharedServicesOverrides = {}
 ): T {
-   const { Clock: clock, Logger: logger, Tracer: tracer, workspace, additionalDocuments, ...restTop } = overrides;
+   const {
+      Clock: clock,
+      Logger: logger,
+      Tracer: tracer,
+      ServerLocale: serverLocale,
+      MessageRenderer: messageRenderer,
+      workspace,
+      additionalDocuments,
+      ...restTop
+   } = overrides;
    const resolvedClock = clock ?? new SystemClock();
    const resolvedLogger = logger ?? new NoopLogger();
    const resolvedTracer = tracer ?? new DefaultTracer(resolvedLogger, resolvedClock);
-   return {
+   // Assembled in two steps, because both defaults read the tree they belong to.
+   const services = {
       Clock: resolvedClock,
       Logger: resolvedLogger,
       Tracer: resolvedTracer,
@@ -75,4 +99,28 @@ export function makeNoopSharedServices<T extends ServerSharedServicesMinimal = S
       ...restTop,
       workspace: { ...(workspace ?? {}) }
    } as unknown as T;
+   // Lazy, like Langium's own per-slot construction — and load-bearing here:
+   // both services emit an `instantiated` trace, so building them eagerly puts
+   // two lines into the capture of every test that passes a capturing logger
+   // and asserts on emptiness.
+   defineLazySlot(services, 'ServerLocale', () => serverLocale?.(services) ?? new DefaultServerLocale(services));
+   defineLazySlot(services, 'MessageRenderer', () => messageRenderer?.(services) ?? new DefaultMessageRenderer(services));
+   return services;
+}
+
+/** Install `name` as a memoized getter, so nothing is constructed until it is read. */
+function defineLazySlot(target: object, name: string, create: () => unknown): void {
+   let resolved: unknown;
+   let built = false;
+   Object.defineProperty(target, name, {
+      configurable: true,
+      enumerable: true,
+      get: () => {
+         if (!built) {
+            resolved = create();
+            built = true;
+         }
+         return resolved;
+      }
+   });
 }