@hydranium/core 1.0.0-next.10

package/lib/testing/node/generated-workspace.js

@@ -0,0 +1,134 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Scaffolding for a generated on-disk corpus: the seeded PRNG, the
+ * overwrite permit, the newline normalisation and the per-extension tally.
+ * The caller supplies only the content.
+ *
+ * # Why the corpus is generated rather than committed
+ *
+ * A volume fixture is what a profiling run, a `watch` claim and any
+ * incremental-rebuild claim measure against, and it is several hundred files.
+ * Committing a deterministic generator and gitignoring its output keeps the
+ * artefact reproducible by any contributor at a fixed seed without the
+ * repository carrying the files.
+ *
+ * # Determinism is the whole contract, and it is fragile
+ *
+ * A performance figure is only readable beside another figure taken over the
+ * same input, so "same parameters, same bytes" is not a nicety. Three things
+ * break it and all three are handled here rather than left to each generator:
+ * `Math.random` (hence {@link GeneratedWorkspaceWriter.random}, a seeded
+ * mulberry32), a timestamp anywhere in the output (hence nothing written here
+ * records one), and platform line endings (hence
+ * {@link GeneratedWorkspaceWriter.write} normalising to LF).
+ *
+ * The draw order is the caller's responsibility, and it is the one that catches
+ * people out: the PRNG is a single stream, so a generator that reorders its
+ * emission — or draws conditionally on something it did not draw before —
+ * produces a different corpus at the same seed.
+ *
+ * # Size is a parameter because the signal is a CURVE
+ *
+ * An O(n²) regression in discovery, indexing, scope or linking is invisible in
+ * a single measurement: it shows up as the large/small ratio outrunning the
+ * file-count ratio. That is why this is a callable module rather than only a
+ * script — a bench runs it in-process at two sizes instead of shelling out —
+ * and why a generator built on it should take its sizes as options rather than
+ * fixing one N.
+ *
+ * # The marker is a permit, not a label
+ *
+ * Generating wipes the target directory, the caller names that directory, and
+ * the default is typically inside the repository. So the wipe needs
+ * authorisation: an absent directory, an empty one, or one already carrying the
+ * marker file. Anything else throws rather than deleting a tree this generator
+ * did not write.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import * as path from 'node:path';
+/** Default name of the file that records — and authorises — a generated corpus. */
+export const GENERATED_WORKSPACE_MARKER = '.hydranium-generated-workspace';
+/**
+ * A deterministic 32-bit PRNG (mulberry32). Deliberately not `Math.random`: a
+ * corpus that varies per run cannot carry a comparable measurement.
+ */
+function makeRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let mixed = state;
+        mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
+        mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+        return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Prepare `root` for a fresh corpus, or throw naming the marker that would
+ * have authorised the wipe.
+ */
+function prepareRoot(root, marker) {
+    if (existsSync(root)) {
+        const entries = readdirSync(root);
+        if (entries.length > 0 && !entries.includes(marker)) {
+            throw new Error(`Refusing to overwrite ${root}: it is not empty and carries no ${marker} marker. ` +
+                'Point the output at a fresh directory, or delete this one yourself.');
+        }
+        rmSync(root, { recursive: true, force: true });
+    }
+    mkdirSync(root, { recursive: true });
+}
+/**
+ * Generate a corpus under `options.root` and return what was written.
+ *
+ * The marker is written BEFORE `emit` runs, so an emission that throws
+ * half-way leaves a directory the next run is still permitted to wipe. Writing
+ * it afterwards would strand a partial corpus that has to be deleted by hand,
+ * and it buys nothing: the marker only ever lands in a directory this function
+ * has just created or been authorised to clear.
+ */
+export function makeGeneratedWorkspace(options) {
+    const root = path.resolve(options.root);
+    const marker = options.marker ?? GENERATED_WORKSPACE_MARKER;
+    const seed = options.seed ?? 0;
+    if (!Number.isInteger(seed)) {
+        throw new Error(`seed must be an integer, got ${String(seed)}`);
+    }
+    prepareRoot(root, marker);
+    const random = makeRandom(seed);
+    const files = {};
+    let total = 0;
+    const writeFile = (target, content) => {
+        mkdirSync(path.dirname(target), { recursive: true });
+        writeFileSync(target, content.replace(/\r\n/g, '\n'), 'utf8');
+    };
+    // Nothing here records a timestamp, which is the other half of the
+    // byte-reproducibility property the seeded stream gives.
+    writeFile(path.join(root, marker), `${JSON.stringify({ generator: options.generator, seed, ...options.parameters }, undefined, 2)}\n`);
+    options.emit({
+        root,
+        random,
+        randomInt: (minimum, maximum) => minimum + Math.floor(random() * (maximum - minimum + 1)),
+        write(relativePath, content) {
+            const target = path.join(root, relativePath);
+            writeFile(target, content);
+            const extension = path.extname(relativePath);
+            files[extension] = (files[extension] ?? 0) + 1;
+            total += 1;
+            return target;
+        },
+        directory(relativePath) {
+            const target = path.join(root, relativePath);
+            mkdirSync(target, { recursive: true });
+            return target;
+        }
+    });
+    return { root, seed, marker, files, total };
+}
+//# sourceMappingURL=generated-workspace.js.map

package/lib/testing/node/generated-workspace.js.map

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

package/lib/testing/node/golden-corpus.d.ts

@@ -0,0 +1,50 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/** One committed golden fixture: a source file whose serialized form is under test. */
+export interface GoldenFixture {
+    /** File name with the matched extension stripped — the `$name` for `it.each`/`describe.each`. */
+    readonly name: string;
+    /** Full file name including extension. */
+    readonly fileName: string;
+    /** Absolute path to the fixture on disk. */
+    readonly path: string;
+    /** Verbatim file contents (UTF-8), including any trailing newline. */
+    readonly text: string;
+}
+export interface MakeGoldenCorpusOptions {
+    /**
+     * Only include files ending with this extension, leading dot included. Omit
+     * to include every regular file in the directory. The extension is stripped
+     * from {@link GoldenFixture.name}.
+     */
+    readonly extension?: string;
+    /**
+     * Fewest fixtures the corpus must yield; below it {@link makeGoldenCorpus}
+     * throws. Default `1`.
+     *
+     * `describe.each([])` registers zero tests and reports a green suite, so an
+     * empty corpus passes as coverage — the throw is what makes it observable.
+     * `0` opts out, for a caller that treats an empty directory as valid.
+     */
+    readonly minimum?: number;
+}
+/**
+ * Read a directory of committed golden fixtures into a deterministic,
+ * name-sorted list a runner can drive with `it.each`/`describe.each`. See the
+ * module comment for the golden-file mechanism this implements. The corpus is
+ * discovered here; the grammar-specific `parse`/`serialize` the byte-stability
+ * assertion needs are supplied adopter-side.
+ *
+ * Reads synchronously so the corpus is available at test-collection time
+ * (when `it.each` expands). Sub-directories are ignored — a flat corpus keeps
+ * the `$name` labels unambiguous. Throws below
+ * {@link MakeGoldenCorpusOptions.minimum}.
+ */
+export declare function makeGoldenCorpus(directory: string, options?: MakeGoldenCorpusOptions): GoldenFixture[];
+//# sourceMappingURL=golden-corpus.d.ts.map

package/lib/testing/node/golden-corpus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden-corpus.d.ts","sourceRoot":"","sources":["../../../src/testing/node/golden-corpus.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAyClF,uFAAuF;AACvF,MAAM,WAAW,aAAa;IAC3B,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,aAAa,EAAE,CAuB1G"}

package/lib/testing/node/golden-corpus.js

@@ -0,0 +1,80 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Golden-file testing for grammar serializers.
+ *
+ * # The idea
+ *
+ * A *golden file* holds the exact expected output of some process, committed
+ * to the repo as the source of truth. The test runs the process and compares
+ * its output against the golden byte-for-byte; a mismatch fails and shows a
+ * readable diff. A *golden corpus* is just a directory of such files — one
+ * per case — spanning the matrix of inputs worth pinning.
+ *
+ * Here the process under test is a grammar serializer (AST → source text).
+ * Each golden is a source file written in the serializer's canonical output
+ * format; the corpus test parses it, re-serializes, and asserts the result
+ * reproduces the file exactly. So any change to the serializer's *formatting*
+ * — an indent width, a clause order, a stray trailing space — stops
+ * reproducing the goldens and surfaces as a concrete, reviewable diff instead
+ * of a silent behavioural drift.
+ *
+ * # Why files, not runner snapshots
+ *
+ * The artifact under test IS an output *format*, so it belongs in a real,
+ * diffable, hand-authored file. A runner's `.snap` snapshot is runner-
+ * specific, and its `-u` "update" flag rubber-stamps whatever the code now
+ * emits — exactly the regression a golden test exists to catch. A committed
+ * golden makes an update a deliberate edit that a reviewer sees.
+ *
+ * # Division of labour
+ *
+ * This module is the framework-side *mechanism* — discover + read files —
+ * and is grammar-agnostic. The *content* (the goldens themselves and the
+ * parse/serialize wiring) is adopter-side, because a serializer's output is
+ * always specific to its grammar. Pair {@link makeGoldenCorpus} with
+ * `makeAstSnapshot` for the structural round-trip half of the corpus.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/**
+ * Read a directory of committed golden fixtures into a deterministic,
+ * name-sorted list a runner can drive with `it.each`/`describe.each`. See the
+ * module comment for the golden-file mechanism this implements. The corpus is
+ * discovered here; the grammar-specific `parse`/`serialize` the byte-stability
+ * assertion needs are supplied adopter-side.
+ *
+ * Reads synchronously so the corpus is available at test-collection time
+ * (when `it.each` expands). Sub-directories are ignored — a flat corpus keeps
+ * the `$name` labels unambiguous. Throws below
+ * {@link MakeGoldenCorpusOptions.minimum}.
+ */
+export function makeGoldenCorpus(directory, options = {}) {
+    const { extension, minimum = 1 } = options;
+    const fixtures = readdirSync(directory, { withFileTypes: true })
+        .filter(entry => entry.isFile())
+        .filter(entry => extension === undefined || entry.name.endsWith(extension))
+        .map(entry => {
+        const path = join(directory, entry.name);
+        return {
+            name: extension === undefined ? entry.name : basename(entry.name, extension),
+            fileName: entry.name,
+            path,
+            text: readFileSync(path, 'utf8')
+        };
+    })
+        .sort((left, right) => (left.fileName < right.fileName ? -1 : left.fileName > right.fileName ? 1 : 0));
+    if (fixtures.length < minimum) {
+        const filter = extension === undefined ? 'no extension filter' : `extension '${extension}'`;
+        throw new Error(`golden corpus at ${directory} yielded ${fixtures.length} fixture(s) with ${filter}, expected at least ${minimum}. ` +
+            'An empty corpus makes `describe.each` register zero tests, so the suite would pass without asserting anything.');
+    }
+    return fixtures;
+}
+//# sourceMappingURL=golden-corpus.js.map

package/lib/testing/node/golden-corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden-corpus.js","sourceRoot":"","sources":["../../../src/testing/node/golden-corpus.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAgC3C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,UAAmC,EAAE;IACtF,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IAC3C,MAAM,QAAQ,GAAG,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAC5D,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;SAC/B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;SAC1E,GAAG,CAAC,KAAK,CAAC,EAAE;QACV,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO;YACJ,IAAI,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC;YAC5E,QAAQ,EAAE,KAAK,CAAC,IAAI;YACpB,IAAI;YACJ,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;SAClC,CAAC;IACL,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1G,IAAI,QAAQ,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,cAAc,SAAS,GAAG,CAAC;QAC5F,MAAM,IAAI,KAAK,CACZ,oBAAoB,SAAS,YAAY,QAAQ,CAAC,MAAM,oBAAoB,MAAM,uBAAuB,OAAO,IAAI;YACjH,gHAAgH,CACrH,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AACnB,CAAC"}

package/lib/testing/node/index.d.ts

@@ -0,0 +1,28 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * `@hydranium/core/testing/node` — the test support that needs a Node runtime:
+ * the scratch-workspace, golden-corpus and generated-workspace fixtures (all
+ * three reach the real filesystem), the in-process LSP transport
+ * (`vscode-jsonrpc/node` stream readers), the all-in-one LSP harness (a
+ * `vscode-languageserver/node` `Connection`), and the subprocess tier, which
+ * spawns a built entry as a child process.
+ *
+ * Separate from `./testing` so that barrel stays browser-neutral and can be
+ * gated as such. Each module here names a capability a browser genuinely lacks,
+ * so this is a real split rather than a packaging preference — the same
+ * distinction the package surface draws between `.` and `./node`.
+ */
+export * from './generated-workspace.js';
+export * from './golden-corpus.js';
+export * from './lsp-harness.js';
+export * from './lsp-server-connection.js';
+export * from './scratch-workspace.js';
+export * from './spawned-server.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/testing/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;GAYG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC"}

package/lib/testing/node/index.js

@@ -0,0 +1,28 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * `@hydranium/core/testing/node` — the test support that needs a Node runtime:
+ * the scratch-workspace, golden-corpus and generated-workspace fixtures (all
+ * three reach the real filesystem), the in-process LSP transport
+ * (`vscode-jsonrpc/node` stream readers), the all-in-one LSP harness (a
+ * `vscode-languageserver/node` `Connection`), and the subprocess tier, which
+ * spawns a built entry as a child process.
+ *
+ * Separate from `./testing` so that barrel stays browser-neutral and can be
+ * gated as such. Each module here names a capability a browser genuinely lacks,
+ * so this is a real split rather than a packaging preference — the same
+ * distinction the package surface draws between `.` and `./node`.
+ */
+export * from './generated-workspace.js';
+export * from './golden-corpus.js';
+export * from './lsp-harness.js';
+export * from './lsp-server-connection.js';
+export * from './scratch-workspace.js';
+export * from './spawned-server.js';
+//# sourceMappingURL=index.js.map

package/lib/testing/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;GAYG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC"}

package/lib/testing/node/lsp-harness.d.ts

@@ -0,0 +1,139 @@
+/********************************************************************************
+ * 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 { LangiumSharedServices } from '@hydranium/langium/lsp';
+import type { Connection } from 'vscode-languageserver/node';
+import { type WorkspaceFolderInput } from '../../langium/workspace/initialize-workspace.js';
+import type { ServerSharedServicesMinimal } from '../../langium/shared-services.js';
+import { type LspServerConnection } from './lsp-server-connection.js';
+/**
+ * The composed shared-services tree the `MakeLspHarnessOptions.createServices`
+ * callback must return. It is both a framework {@link ServerSharedServicesMinimal}
+ * (so the harness can drive {@link buildWorkspaceProgrammatically}) and a Langium
+ * {@link LangiumSharedServices} (so the harness can hand it to
+ * {@link startLanguageServer}, which wires the LSP handlers onto the connection).
+ * Every real adopter tree (`createXxxServices(...).shared`) satisfies both.
+ */
+export type LspHarnessSharedServices = ServerSharedServicesMinimal & LangiumSharedServices;
+/**
+ * Configuration for {@link makeLspHarness}, in two forms.
+ *
+ * SINGLE-HEAD (`createServices`) — the all-in-one convenience: the harness OWNS
+ * the transport and tree creation. It builds the in-process connection and hands
+ * it to the adopter factory, which composes the shared services around it, e.g.
+ * `connection => createMyLangServices({ connection }).shared`. The callback owns the
+ * filesystem choice (EmptyFileSystem for didOpen-only tests, NodeFileSystem for
+ * fixture-backed workspace tests) and any adopter modules.
+ *
+ * MULTI-HEAD (`connection` + `services`) — the symmetric "take the tree" form,
+ * matching the data-server and GLSP harnesses, which attach to a caller-built
+ * tree. Because Langium binds the connection INTO the tree at
+ * `createXxxServices({ connection })`, the caller makes the wire first
+ * ({@link makeLspServerConnection}), builds the ONE shared tree around its
+ * `serverConnection`, then hands BOTH the wire and `.shared` to the harness — so
+ * the SAME tree feeds the LSP head here and the other heads elsewhere. The
+ * harness still attaches the LSP head ({@link startLanguageServer}) and owns the
+ * wire's teardown via {@link LspHarness.dispose}.
+ */
+export type MakeLspHarnessOptions = LspHarnessCreateServicesOptions | LspHarnessAttachOptions;
+/** SINGLE-HEAD form — the harness builds the transport and the tree. */
+export interface LspHarnessCreateServicesOptions {
+    /**
+     * Compose the shared services against the supplied server {@link Connection}
+     * (the server side of the in-process stream pair). Invoked once,
+     * synchronously, before {@link startLanguageServer} wires the LSP handlers.
+     */
+    createServices: (connection: Connection) => LspHarnessSharedServices;
+}
+/** MULTI-HEAD form — the caller owns the transport and the tree; the harness attaches. */
+export interface LspHarnessAttachOptions {
+    /**
+     * The in-process LSP transport the caller built ({@link makeLspServerConnection})
+     * and composed the tree around. The harness drives its facades and owns its
+     * teardown.
+     */
+    connection: LspServerConnection;
+    /**
+     * The composed shared services (`createXxxServices({ connection }).shared`)
+     * built around `connection.serverConnection`. The harness attaches the LSP head
+     * to it via {@link startLanguageServer}.
+     */
+    services: LspHarnessSharedServices;
+}
+/**
+ * Wiring bundle returned by {@link makeLspHarness} — the in-process replacement
+ * for the subprocess stdio smoke. It is the {@link LspServerConnection} transport
+ * seam (real `Connection` over the in-memory wire, the diagnostics and
+ * applyEdit captures, typed
+ * `completion`/`hover`/`semanticTokens`/`nextDiagnostics`/`nextAppliedEdit`
+ * facades, lifecycle `initialize`/`shutdown`, document-sync
+ * `openDocument`/`changeDocument`, idempotent `dispose`) PLUS the two members the
+ * all-in-one harness owns that the bare transport does not:
+ *
+ * - `services` — the **subject**, the composed shared-services tree the harness
+ *   stood the LSP server up on (the harness created it via `createServices` and
+ *   attached the server via `startLanguageServer`);
+ * - `buildWorkspace` — the deterministic project-state seed.
+ *
+ * The transport's own `serverConnection` is intentionally NOT surfaced here. In
+ * the single-head form the harness owns the connection, so a caller never needs
+ * it; in the multi-head attach form the caller already holds the
+ * {@link LspServerConnection} it passed in (and built the tree around its
+ * `serverConnection`), so it never needs the harness to re-surface it.
+ */
+export type LspHarness = Omit<LspServerConnection, 'serverConnection'> & {
+    /** Subject: the composed shared services running the in-process LSP server. */
+    readonly services: ServerSharedServicesMinimal;
+    /**
+     * Deterministic project-state seed: awaits
+     * {@link buildWorkspaceProgrammatically} (discovery + build every document to
+     * `Validated`, awaited to settle).
+     *
+     * STANDALONE — it performs its own workspace init, so do NOT also call
+     * {@link LspServerConnection.initialize} on the same harness. Per LSP,
+     * `initialize` is once-only ("may only be sent once"); a second workspace init
+     * cancels the first build. Building also publishes diagnostics over the
+     * connection asynchronously, so a `dispose()` racing those is a known
+     * limitation of this state-only path.
+     *
+     * **A test that needs BOTH project state AND live wire requests should call
+     * `initialize({ workspaceFolders })` instead of this** — that settles the
+     * workspace before resolving, so it is a single init with nothing racy left
+     * to await. Combining the two is the failure mode worth naming, because it is
+     * silent: the second init cancels the first and diagnostics are then never
+     * published for ANY document, so every wire assertion times out pointing at
+     * the transport rather than at the cause.
+     */
+    buildWorkspace(folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>): Promise<void>;
+};
+/**
+ * Wire a real Langium LSP server through its real `Connection` and the LSP
+ * wire **in-process** — no subprocess, no built binary. The in-process
+ * replacement for the subprocess stdio smoke: same real connection +
+ * lifecycle, built on the {@link makeLspServerConnection} transport primitive
+ * and on {@link buildWorkspaceProgrammatically} for the deterministic workspace
+ * seed.
+ *
+ * Two forms (see {@link MakeLspHarnessOptions}). SINGLE-HEAD (`createServices`):
+ * the all-in-one convenience — the harness builds the transport, calls
+ * `createServices` with its server connection, and attaches the LSP head.
+ * MULTI-HEAD (`connection` + `services`): the symmetric "take the tree" form —
+ * the caller built the wire ({@link makeLspServerConnection}) and the ONE shared
+ * tree around it, and the harness attaches the LSP head to that `services` while
+ * the data-server / GLSP heads attach to the same tree.
+ *
+ * This does NOT test provider *logic* — `langium/test` (`expectCompletion`,
+ * `expectHover`, `validationHelper`, …, re-exported from
+ * `@hydranium/core/testing`) already covers that by calling providers directly.
+ * The harness owns the wire + lifecycle layer the provider-direct helpers skip:
+ * `initialize`/`initialized`, the `didOpen`/`didChange` → `DocumentBuilder` →
+ * `publishDiagnostics` round-trip over the wire, JSON-RPC serialization, and
+ * `shutdown`/`exit`.
+ */
+export declare function makeLspHarness(options: MakeLspHarnessOptions): LspHarness;
+//# sourceMappingURL=lsp-harness.d.ts.map

package/lib/testing/node/lsp-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp-harness.d.ts","sourceRoot":"","sources":["../../../src/testing/node/lsp-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAAkC,KAAK,oBAAoB,EAAE,MAAM,iDAAiD,CAAC;AAC5H,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AACpF,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAAG,2BAA2B,GAAG,qBAAqB,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,qBAAqB,GAAG,+BAA+B,GAAG,uBAAuB,CAAC;AAE9F,wEAAwE;AACxE,MAAM,WAAW,+BAA+B;IAC7C;;;;OAIG;IACH,cAAc,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,wBAAwB,CAAC;CACvE;AAED,0FAA0F;AAC1F,MAAM,WAAW,uBAAuB;IACrC;;;;OAIG;IACH,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,QAAQ,EAAE,wBAAwB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,GAAG;IACtE,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,2BAA2B,CAAC;IAC/C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrG,CAAC;AA8BF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAuDzE"}

package/lib/testing/node/lsp-harness.js

@@ -0,0 +1,119 @@
+/********************************************************************************
+ * 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 { IntegrityService } from '../../langium/integrity/index.js';
+import { startLanguageServer } from '../../lsp/index.js';
+import { buildWorkspaceProgrammatically } from '../../langium/workspace/initialize-workspace.js';
+import { makeLspServerConnection } from './lsp-server-connection.js';
+/**
+ * Await the workspace init that an `initialize({ workspaceFolders })` kicked
+ * off, so the caller can use the workspace on return.
+ *
+ * This is the gate the transport's own `initialize` cannot provide: it holds
+ * only the connection, while settling needs the services tree. Without it
+ * **`initialize({ workspaceFolders })` returns with ZERO documents
+ * registered**, because the `initialized` notification is fire-and-forget and
+ * discovery has not run yet.
+ *
+ * **The landmark is {@link IntegrityService.SettledState}, NOT
+ * `DocumentState.Validated`.** The init build links and indexes but does not
+ * validate — which is precisely why {@link buildWorkspaceProgrammatically}
+ * exists and appends its own `{ validation: true }` pass. Waiting on `Validated`
+ * hangs forever against a workspace nobody asked to validate. Linking, not
+ * validation, is what "the workspace is usable" means.
+ *
+ * One await, deliberately. Queueing a no-op `WorkspaceLock.read` first does NOT
+ * drain the init write — measured, and the read resolves immediately with no
+ * documents registered, because the write is not yet enqueued when
+ * `initialize()` returns. `waitUntil` does all the work, registering a
+ * build-phase listener that a later build satisfies. An empty workspace folder
+ * resolves rather than hanging.
+ */
+async function settleInitializedWorkspace(services) {
+    await services.workspace.DocumentBuilder.waitUntil(IntegrityService.SettledState);
+}
+/**
+ * Wire a real Langium LSP server through its real `Connection` and the LSP
+ * wire **in-process** — no subprocess, no built binary. The in-process
+ * replacement for the subprocess stdio smoke: same real connection +
+ * lifecycle, built on the {@link makeLspServerConnection} transport primitive
+ * and on {@link buildWorkspaceProgrammatically} for the deterministic workspace
+ * seed.
+ *
+ * Two forms (see {@link MakeLspHarnessOptions}). SINGLE-HEAD (`createServices`):
+ * the all-in-one convenience — the harness builds the transport, calls
+ * `createServices` with its server connection, and attaches the LSP head.
+ * MULTI-HEAD (`connection` + `services`): the symmetric "take the tree" form —
+ * the caller built the wire ({@link makeLspServerConnection}) and the ONE shared
+ * tree around it, and the harness attaches the LSP head to that `services` while
+ * the data-server / GLSP heads attach to the same tree.
+ *
+ * This does NOT test provider *logic* — `langium/test` (`expectCompletion`,
+ * `expectHover`, `validationHelper`, …, re-exported from
+ * `@hydranium/core/testing`) already covers that by calling providers directly.
+ * The harness owns the wire + lifecycle layer the provider-direct helpers skip:
+ * `initialize`/`initialized`, the `didOpen`/`didChange` → `DocumentBuilder` →
+ * `publishDiagnostics` round-trip over the wire, JSON-RPC serialization, and
+ * `shutdown`/`exit`.
+ */
+export function makeLspHarness(options) {
+    // Attach form: the caller owns the transport + tree. Convenience form: the
+    // harness builds the transport and the adopter factory composes the tree.
+    const transport = 'connection' in options ? options.connection : makeLspServerConnection();
+    const services = 'connection' in options ? options.services : options.createServices(transport.serverConnection);
+    // Wires the LSP handlers onto the transport's server connection and calls
+    // `connection.listen()`.
+    startLanguageServer(services);
+    return {
+        services,
+        client: transport.client,
+        diagnostics: transport.diagnostics,
+        /**
+         * The transport handshake, plus the workspace settle the transport cannot
+         * do on its own — see {@link settleInitializedWorkspace}. Only when
+         * `workspaceFolders` are actually supplied: the no-folders default has no
+         * discovery to wait for.
+         *
+         * With this, `initialize({ workspaceFolders })` is the single call a test
+         * needing BOTH project state and live wire requests should make — the path
+         * {@link LspHarness.buildWorkspace} points at. Do NOT combine the two:
+         * they are separate workspace inits, the second cancels the first, and the
+         * observable result is that diagnostics are never published at all — for
+         * any document, so every assertion times out accusing the transport.
+         *
+         * **What the settle is and is not needed for, measured rather than
+         * assumed.** It matters for a test that INSPECTS STATE after initialize:
+         * without it there are zero documents registered on return. It is NOT
+         * needed by a test that awaits a wire round-trip first — such a suite
+         * passes with the settle removed, because awaiting `nextDiagnostics`
+         * incidentally gives discovery time to finish. So this closes a footgun
+         * rather than fixing a failing test; do not expect removing it to turn
+         * anything red.
+         */
+        initialize: async (params) => {
+            const result = await transport.initialize(params);
+            if (params?.workspaceFolders && params.workspaceFolders.length > 0) {
+                await settleInitializedWorkspace(services);
+            }
+            return result;
+        },
+        shutdown: transport.shutdown,
+        openDocument: transport.openDocument,
+        changeDocument: transport.changeDocument,
+        completion: transport.completion,
+        hover: transport.hover,
+        semanticTokens: transport.semanticTokens,
+        nextDiagnostics: transport.nextDiagnostics,
+        appliedEdits: transport.appliedEdits,
+        nextAppliedEdit: transport.nextAppliedEdit,
+        setApplyEditHandler: transport.setApplyEditHandler,
+        buildWorkspace: folders => buildWorkspaceProgrammatically(services, folders),
+        dispose: transport.dispose
+    };
+}
+//# sourceMappingURL=lsp-harness.js.map

package/lib/testing/node/lsp-harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp-harness.js","sourceRoot":"","sources":["../../../src/testing/node/lsp-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,8BAA8B,EAA6B,MAAM,iDAAiD,CAAC;AAE5H,OAAO,EAAE,uBAAuB,EAA4B,MAAM,4BAA4B,CAAC;AA2G/F;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,KAAK,UAAU,0BAA0B,CAAC,QAAkC;IACzE,MAAM,QAAQ,CAAC,SAAS,CAAC,eAAe,CAAC,SAAS,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC1D,2EAA2E;IAC3E,0EAA0E;IAC1E,MAAM,SAAS,GAAG,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,uBAAuB,EAAE,CAAC;IAC3F,MAAM,QAAQ,GAAG,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IACjH,0EAA0E;IAC1E,yBAAyB;IACzB,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAE9B,OAAO;QACJ,QAAQ;QACR,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC;;;;;;;;;;;;;;;;;;;;;WAqBG;QACH,UAAU,EAAE,KAAK,EAAC,MAAM,EAAC,EAAE;YACxB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAClD,IAAI,MAAM,EAAE,gBAAgB,IAAI,MAAM,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAClE,MAAM,0BAA0B,CAAC,QAAQ,CAAC,CAAC;YAC9C,CAAC;YACD,OAAO,MAAM,CAAC;QACjB,CAAC;QACD,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,cAAc,EAAE,SAAS,CAAC,cAAc;QACxC,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,cAAc,EAAE,SAAS,CAAC,cAAc;QACxC,eAAe,EAAE,SAAS,CAAC,eAAe;QAC1C,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,eAAe,EAAE,SAAS,CAAC,eAAe;QAC1C,mBAAmB,EAAE,SAAS,CAAC,mBAAmB;QAClD,cAAc,EAAE,OAAO,CAAC,EAAE,CAAC,8BAA8B,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC5E,OAAO,EAAE,SAAS,CAAC,OAAO;KAC5B,CAAC;AACL,CAAC"}