@hydranium/core 1.0.0-next.28 → 1.0.0-next.280

package/src/node/socket-launcher.ts

@@ -7,9 +7,8 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred } from '@hydranium/langium';
 import * as net from 'node:net';
-import type { Disposable, Logger } from '@hydranium/protocol';
+import { Deferred, 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';
@@ -25,9 +24,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"`. */
@@ -88,6 +103,7 @@ export interface StartedSocketServer extends IntegratedServer {
  */
 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 +116,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 +131,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 +144,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
       connection.listen();
    });
 
-   netServer.listen(port);
+   netServer.listen(port, host);
    netServer.on('listening', () => {
       const addressInfo = netServer.address();
       if (!addressInfo) {
@@ -144,11 +160,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 +174,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();
       }

package/src/node/stdio-launcher.ts

@@ -7,8 +7,7 @@
  * 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';
@@ -30,10 +29,11 @@ export interface StdioServerOptions {
     */
    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,17 +114,21 @@ 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.
+   let initializing = false;
    const begin = async (): Promise<void> => {
       if (options.workspace !== undefined) {
          logger?.info(`[${tag}] Initializing workspace`);
+         initializing = true;
          await initializeWorkspaceProgrammatically(options.shared, options.workspace);
+         initializing = false;
       }
       // Only now attach the reader — see the ordering note in the doc above.
       connection.listen();
@@ -137,7 +141,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

@@ -7,7 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { DocumentState, type AstNode, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+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.
@@ -23,12 +25,29 @@ import { DocumentState, type AstNode, type LangiumDocument, UriUtils, type URI }
  * framework synthetic node, and marking it would change scope/index behaviour.
  * A test that wants a genuine synthetic node calls `markSynthetic` explicitly.
  *
+ * **Without a `reflection`, the fixture carries only what the test spells out**,
+ * which is a shape production never produces: a parsed or built node always has
+ * its grammar-declared containment arrays, so a fixture that omits one lets a
+ * test pass against an impossible node, and lets code that walks a list crash
+ * only under test. Pass the grammar's reflection whenever the type is a real
+ * one and the code under test reads a collection off it. Fixtures typed against
+ * ad-hoc names have no reflection to pass and keep the plain form.
+ *
  * @param node the node shape — `$type` is required; every other property is a
  *   value the test cares about (`$container`, cross-reference values, internal
- *   `_id` fields, …). The object is returned by reference, not copied.
+ *   `_id` fields, …).
+ * @param reflection when given, pre-fills the grammar's declared defaults the
+ *   same way {@link buildAstNode} does, and the result is a fresh object rather
+ *   than `node` itself. Omitted, `node` is returned by reference.
  */
-export function makeFakeAstNode<TAst extends AstNode = AstNode>(node: { $type: string } & Record<string, unknown>): TAst {
-   return node as unknown as TAst;
+export function makeFakeAstNode<TAst extends AstNode = AstNode>(
+   node: { $type: string } & Record<string, unknown>,
+   reflection?: AstReflection
+): TAst {
+   if (!reflection) {
+      return node as unknown as TAst;
+   }
+   return buildAstNode<TAst>(reflection, node.$type, node);
 }
 
 /**
@@ -86,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;
+      }
+   });
 }