@hydranium/core 1.0.0-next.37 → 1.0.0-next.370

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/node/validate-workspace.ts

@@ -48,7 +48,7 @@ export interface ValidationCounts {
 export interface WorkspaceValidationResult {
    /** Number of `LangiumDocument`s in the built workspace. */
    documents: number;
-   /** Every problem found, grouped contiguously by document, in the order the documents were given. */
+   /** Every problem found, grouped contiguously by document, in the order the documents were given, and by position within one. */
    findings: ValidationFinding[];
    /** Per-severity totals over {@link findings}. */
    counts: ValidationCounts;
@@ -94,7 +94,13 @@ export function collectValidationResult(
    const counts: ValidationCounts = { error: 0, warning: 0, info: 0, hint: 0 };
    for (const document of documents) {
       const relativeUri = wsRelativePath(document.uri);
-      for (const diagnostic of (document.diagnostics ?? []) as Diagnostic[]) {
+      // Langium appends the lexer, parser, linker and validator diagnostics phase after phase,
+      // so a reader scanning a file top to bottom needs them sorted. The sort is stable, so
+      // diagnostics at one position keep the order their phases produced them in.
+      const diagnostics = [...((document.diagnostics ?? []) as Diagnostic[])].sort(
+         (a, b) => a.range.start.line - b.range.start.line || a.range.start.character - b.range.start.character
+      );
+      for (const diagnostic of diagnostics) {
          const severity = severityLabel(diagnostic.severity);
          counts[severity] += 1;
          findings.push({

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';