@hydranium/core 1.0.0-next.10

package/lib/testing/make-test-services.d.ts

@@ -0,0 +1,217 @@
+/********************************************************************************
+ * 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, type Logger, type Project, type Tracer, type TransferDiagnostic, type TransferElement } from '@hydranium/protocol';
+import type { Harness } from '@hydranium/protocol/testing';
+import { type AstNode, type AstNodeDescription, type WorkspaceLock } from '@hydranium/langium';
+import type { ModelService, ModelServiceOptions } from '../langium/model-service/model-service.js';
+import type { ServerSharedServices } from '../langium/module.js';
+import { TransferEncoder } from '../langium/transfer/transfer-encoder.js';
+import { type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
+import type { FakeDocumentOptions } from './fake-document.js';
+import { type StubDocumentBuilder } from './stub-document-builder.js';
+import { type StubIndexManager } from './stub-index-manager.js';
+import { type StubLangiumDocuments } from './stub-langium-documents.js';
+import { type StubAstDocumentManager } from './stub-ast-document-manager.js';
+import { type StubProjectManager } from './stub-project-manager.js';
+import { type StubSelfSaveRegistry } from './stub-self-save-registry.js';
+import { type StubHydraniumTextDocuments } from './stub-hydranium-text-documents.js';
+import { type StubLanguageDescriptor, type StubServiceRegistry } from './stub-service-registry.js';
+import { type StubWritableFileSystem } from './stub-writable-file-system.js';
+/**
+ * Honest shape of the `services` tree assembled by {@link makeTestServices}.
+ * Captures exactly the slots the bundle binds — narrower than the full
+ * {@link ServerSharedServices} that production code consumes, with no
+ * placeholder for slots that don't appear in the literal (`AstNodeLocator`,
+ * `WorkspaceManager`, etc.). The boundary cast from this type
+ * to `ServerSharedServices` in {@link makeTestServices} is therefore the
+ * single named place where the "stub stands in for the full service tree"
+ * assertion happens.
+ */
+export interface TestSharedServices<TAst extends AstNode = AstNode, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement, TProject extends Project = Project> {
+    readonly Clock: Clock;
+    readonly Logger: Logger;
+    readonly Tracer: Tracer;
+    /**
+     * Present only when {@link MakeTestServicesOptions.languages} was passed.
+     * Omitted otherwise so a bundle without declared languages keeps failing
+     * loudly on the slot rather than answering from an empty registry — see
+     * the option's doc for why that default is deliberate.
+     */
+    readonly ServiceRegistry?: StubServiceRegistry;
+    readonly workspace: {
+        LangiumDocuments: StubLangiumDocuments<TAst, TDiagnostic>;
+        DocumentBuilder: StubDocumentBuilder;
+        TextDocuments: StubHydraniumTextDocuments;
+        AstDocumentManager: StubAstDocumentManager<TAst, TDiagnostic>;
+        FileSystemProvider: StubWritableFileSystem;
+        SelfSaveRegistry: StubSelfSaveRegistry;
+        ProjectManager: StubProjectManager<TProject>;
+        DocumentUriPolicy: DocumentUriPolicy;
+        /**
+         * Present only when {@link MakeTestServicesOptions.seedIndex} was passed.
+         * Omitted otherwise for the same reason as `ServiceRegistry` — see that
+         * option's doc.
+         */
+        IndexManager?: StubIndexManager;
+        /**
+         * The REAL `HydraniumWorkspaceLock`, not a stub — it is a few lines of
+         * promise queueing with no I/O, and `ModelService`'s build path serialises
+         * through it, so a no-op stub would hide exactly the interleaving the lock
+         * exists to prevent. The framework subclass rather than Langium's default
+         * because it also marks the write scope that `ModelService`'s reentrancy
+         * guard reads; binding the default here would make the guard untestable
+         * through this tree and let a reentrant write pass unnoticed.
+         */
+        WorkspaceLock: WorkspaceLock;
+    };
+    readonly model: {
+        TransferEncoder: TransferEncoder<unknown, TDiagnostic>;
+        ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
+    };
+}
+/** Optional configuration for {@link makeTestServices}. */
+export interface MakeTestServicesOptions<TAst extends AstNode = AstNode, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement, TProject extends Project = Project> {
+    /**
+     * Serialiser used by the bundled `StubModelService`. The stub tree
+     * routes no per-language `Serializer` (the stub languages bind no-op slots),
+     * so the framework's own serialize path is unavailable here — supply this
+     * whenever a test asserts on the produced text.
+     *
+     * Default: `JSON.stringify(root)` — deterministic and grammar-free, suitable
+     * for tests that don't assert on the produced text.
+     */
+    serialize?: (uri: string, root: TTransfer) => string;
+    /**
+     * Languages to register on a {@link StubServiceRegistry} bound on the
+     * `ServiceRegistry` slot. This is how a test gets multi-language routing:
+     * production code under test then resolves per-URI through Langium's real
+     * lookup ladder instead of a per-file hand-rolled registry object.
+     *
+     * **Default: no `ServiceRegistry` slot at all.** Binding an empty registry
+     * by default would silently change behaviour for the tests that rely on the
+     * slot being absent — `ModelService.updateRewriteService` optional-chains it
+     * precisely for those bundles — so a registry appears only when a test asks
+     * for one.
+     */
+    languages?: readonly StubLanguageDescriptor[];
+    /**
+     * Documents to declare open with a client-supplied `languageId`, as
+     * `{ [uri]: languageId }`. Forwarded to {@link makeStubServiceRegistry};
+     * only meaningful alongside {@link languages}.
+     */
+    openLanguageIds?: Readonly<Record<string, string>>;
+    /**
+     * Clock bound on the `Clock` shared slot. Pass `makeFakeClock()` to drive
+     * time-gated logic deterministically; defaults to a real {@link SystemClock}.
+     */
+    clock?: Clock;
+    /**
+     * Logger bound on the `Logger` slot AND wrapped by the `Tracer` slot, so a
+     * capturing logger sees both plain log lines and tracer-emitted timing/warn
+     * lines. Defaults to a {@link NoopLogger}.
+     */
+    logger?: Logger;
+    /** Initial documents to seed the {@link StubLangiumDocuments} with. */
+    seedDocuments?: ReadonlyArray<{
+        uri: string;
+        root: TAst;
+        options?: FakeDocumentOptions<TAst, TDiagnostic>;
+    }>;
+    /** Initial projects to seed the {@link StubProjectManager} with. */
+    seedProjects?: readonly TProject[];
+    /**
+     * Global-index entries to seed a {@link StubIndexManager} with, bound on the
+     * `IndexManager` slot. This is how a test reaches the global scope —
+     * `DefaultScopeProvider` reads that slot — so a scope assertion can
+     * distinguish "closed" from "falls through to the index".
+     *
+     * **Default: no `IndexManager` slot at all**, matching {@link languages}.
+     * Binding an empty stub by default would answer every global-index read with
+     * an empty result instead of failing on the unbound slot, which is the
+     * silent-`undefined` failure the boundary cast below is annotated for; a
+     * suite that never asks for an index would then pass for a new reason.
+     */
+    seedIndex?: readonly AstNodeDescription[];
+    /**
+     * Policy bound on the `DocumentUriPolicy` slot. Defaults to
+     * {@link DefaultDocumentUriPolicy} (syntactic normalize). Pass a stub that
+     * resolves chosen URIs to a shared canonical form to exercise the
+     * symlink-divergence bridges without touching the filesystem.
+     */
+    documentUriPolicy?: DocumentUriPolicy;
+    /**
+     * Override the {@link ModelService} factory. Use for tests that want a
+     * custom subclass with `normalize` / lifecycle hooks; the default builds
+     * a `StubModelService` from `options.serialize`.
+     */
+    modelService?: (services: ServerSharedServices<TProject>) => ModelService<TAst, TDiagnostic, TTransfer>;
+    /**
+     * Framework {@link ModelServiceOptions} for the DEFAULT stub service, so a
+     * test can reach an option-gated path (`serializeBuilds`, the slow-warn
+     * threshold) without supplying a whole {@link modelService} factory. Ignored
+     * when `modelService` is given — that factory owns its own construction.
+     */
+    modelServiceOptions?: ModelServiceOptions;
+    /**
+     * Override the {@link TransferEncoder} factory. Default: framework
+     * {@link TransferEncoder} with no overrides.
+     */
+    transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<unknown, TDiagnostic>;
+}
+/**
+ * Bundle returned by {@link makeTestServices}. Exposes the assembled
+ * {@link ServerSharedServices} tree plus every stub the bundle composed,
+ * so tests can introspect or mutate the underlying state without re-wiring
+ * the tree. Each stub member is named after the slot it is bound on.
+ *
+ * This is the core harness and satisfies the uniform {@link Harness}
+ * contract — `services` is the **subject** (the assembled service tree the
+ * production code under test runs against), the individual `*` stubs are the
+ * **seam** (the doubles tests introspect / mutate), and `dispose()` is the
+ * uniform teardown hook (a no-op: the stubs hold only in-memory state,
+ * released with the bundle when it goes out of scope).
+ */
+export interface TestServicesBundle<TAst extends AstNode = AstNode, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement, TProject extends Project = Project> extends Harness {
+    readonly services: ServerSharedServices<TProject>;
+    readonly documents: StubLangiumDocuments<TAst, TDiagnostic>;
+    readonly textDocuments: StubHydraniumTextDocuments;
+    readonly astDocumentManager: StubAstDocumentManager<TAst, TDiagnostic>;
+    readonly documentBuilder: StubDocumentBuilder;
+    readonly fileSystem: StubWritableFileSystem;
+    readonly selfSaveRegistry: StubSelfSaveRegistry;
+    readonly projectManager: StubProjectManager<TProject>;
+    readonly documentUriPolicy: DocumentUriPolicy;
+    /**
+     * The registry bound on the `ServiceRegistry` slot, or `undefined` when no
+     * {@link MakeTestServicesOptions.languages} were declared.
+     */
+    readonly serviceRegistry: StubServiceRegistry | undefined;
+    /**
+     * The stub bound on the `IndexManager` slot, or `undefined` when no
+     * {@link MakeTestServicesOptions.seedIndex} was passed.
+     */
+    readonly indexManager: StubIndexManager | undefined;
+    readonly modelService: ModelService<TAst, TDiagnostic, TTransfer>;
+    readonly transferEncoder: TransferEncoder<unknown, TDiagnostic>;
+    readonly logger: Logger;
+    /** The clock bound on the `Clock` slot — a `makeFakeClock()` if one was passed. */
+    readonly clock: Clock;
+}
+/**
+ * Build a {@link ServerSharedServices} tree backed by the framework's
+ * testing stubs. The returned bundle exposes both the tree and the
+ * individual stubs so tests can introspect.
+ *
+ * **Scope.** Langium-layer stubs only — no GLSP-shaped fixtures. Tests for
+ * code that runs against real Langium services (grammar parsing, scope
+ * computation, etc.) should keep using `bootstrapLangium(...)` rather than
+ * this bundle.
+ */
+export declare function makeTestServices<TAst extends AstNode = AstNode, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement, TProject extends Project = Project>(options?: MakeTestServicesOptions<TAst, TDiagnostic, TTransfer, TProject>): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject>;
+//# sourceMappingURL=make-test-services.d.ts.map

package/lib/testing/make-test-services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-test-services.d.ts","sourceRoot":"","sources":["../../src/testing/make-test-services.ts"],"names":[],"mappings":"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"}

package/lib/testing/make-test-services.js

@@ -0,0 +1,128 @@
+/********************************************************************************
+ * 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 { DefaultTracer, NoopLogger, SystemClock } from '@hydranium/protocol';
+import { TransferEncoder } from '../langium/transfer/transfer-encoder.js';
+import { DefaultDocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
+import { HydraniumWorkspaceLock } from '../langium/workspace/hydranium-workspace-lock.js';
+import { makeStubDocumentBuilder } from './stub-document-builder.js';
+import { makeStubIndexManager } from './stub-index-manager.js';
+import { makeStubLangiumDocuments } from './stub-langium-documents.js';
+import { makeStubModelService } from './stub-model-service.js';
+import { makeStubAstDocumentManager } from './stub-ast-document-manager.js';
+import { makeStubProjectManager } from './stub-project-manager.js';
+import { makeStubSelfSaveRegistry } from './stub-self-save-registry.js';
+import { makeStubHydraniumTextDocuments } from './stub-hydranium-text-documents.js';
+import { makeStubServiceRegistry } from './stub-service-registry.js';
+import { makeStubWritableFileSystem } from './stub-writable-file-system.js';
+/**
+ * Build a {@link ServerSharedServices} tree backed by the framework's
+ * testing stubs. The returned bundle exposes both the tree and the
+ * individual stubs so tests can introspect.
+ *
+ * **Scope.** Langium-layer stubs only — no GLSP-shaped fixtures. Tests for
+ * code that runs against real Langium services (grammar parsing, scope
+ * computation, etc.) should keep using `bootstrapLangium(...)` rather than
+ * this bundle.
+ */
+export function makeTestServices(options = {}) {
+    const documents = makeStubLangiumDocuments(options.seedDocuments);
+    const textDocuments = makeStubHydraniumTextDocuments();
+    const documentBuilder = makeStubDocumentBuilder();
+    const selfSaveRegistry = makeStubSelfSaveRegistry();
+    const fileSystem = makeStubWritableFileSystem(selfSaveRegistry);
+    const projectManager = makeStubProjectManager(options.seedProjects);
+    const astDocumentManager = makeStubAstDocumentManager(textDocuments, fileSystem, documents);
+    const logger = options.logger ?? new NoopLogger();
+    const clock = options.clock ?? new SystemClock();
+    const tracer = new DefaultTracer(logger, clock);
+    const documentUriPolicy = options.documentUriPolicy ?? new DefaultDocumentUriPolicy();
+    const serviceRegistry = options.languages
+        ? makeStubServiceRegistry(options.languages, { openLanguageIds: options.openLanguageIds })
+        : undefined;
+    const indexManager = options.seedIndex ? makeStubIndexManager(options.seedIndex) : undefined;
+    // Build the literal at its honest narrow type (TestSharedServices) so
+    // signature drift on any of these slots produces a compile error here, then
+    // cast at the boundary to ServerSharedServices so production consumers that
+    // expect the full service tree can accept it. The cast is `as unknown as`
+    // because TestSharedServices is structurally narrower (no AstNodeLocator,
+    // IndexManager, WorkspaceManager, …); production code that reads one of
+    // those slots off the bundle fails at runtime.
+    //
+    // **So adding a new service READ to a production path means adding the slot
+    // here too.** Nothing enforces it: the cast below erases the difference, so
+    // the omission surfaces as a runtime `undefined` inside whichever package
+    // happens to drive that path — typically several layers from the change, and
+    // in a package that did not touch the edit. Prefer the REAL service when it
+    // is dependency-free (as `HydraniumWorkspaceLock` is) — a no-op stub of a
+    // synchronisation primitive hides the very interleaving it exists to prevent.
+    //
+    // `model.TransferEncoder` / `model.ModelService` are populated below
+    // (after the factories run); the literal uses unsafe casts to
+    // partially-built objects to satisfy TestSharedServices, then patches
+    // them in.
+    const services = {
+        Clock: clock,
+        Logger: logger,
+        Tracer: tracer,
+        // Spread rather than assigned so the slot is genuinely ABSENT (not
+        // present-and-undefined) when no languages were declared — `'ServiceRegistry'
+        // in services` is what an optional-chaining production path effectively asks.
+        ...(serviceRegistry ? { ServiceRegistry: serviceRegistry } : {}),
+        workspace: {
+            LangiumDocuments: documents,
+            DocumentBuilder: documentBuilder,
+            TextDocuments: textDocuments,
+            AstDocumentManager: astDocumentManager,
+            FileSystemProvider: fileSystem,
+            SelfSaveRegistry: selfSaveRegistry,
+            ProjectManager: projectManager,
+            DocumentUriPolicy: documentUriPolicy,
+            // Spread for the same reason as `ServiceRegistry` above — the slot must
+            // be genuinely ABSENT, not present-and-undefined, when no index was seeded.
+            ...(indexManager ? { IndexManager: indexManager } : {}),
+            WorkspaceLock: new HydraniumWorkspaceLock()
+        },
+        model: {}
+    };
+    const sharedServices = services;
+    const serialize = options.serialize ?? ((_uri, root) => JSON.stringify(root));
+    const transferEncoder = options.transferEncoder
+        ? options.transferEncoder(sharedServices)
+        : new TransferEncoder(sharedServices);
+    const modelService = options.modelService
+        ? options.modelService(sharedServices)
+        : makeStubModelService(sharedServices, serialize, options.modelServiceOptions);
+    const mutableModel = services.model;
+    mutableModel.TransferEncoder = transferEncoder;
+    mutableModel.ModelService = modelService;
+    return {
+        services: sharedServices,
+        documents,
+        textDocuments,
+        astDocumentManager,
+        documentBuilder,
+        fileSystem,
+        selfSaveRegistry,
+        projectManager,
+        documentUriPolicy,
+        serviceRegistry,
+        indexManager,
+        modelService,
+        transferEncoder,
+        logger,
+        clock,
+        dispose: () => {
+            // No-op: the bundled stubs hold only in-memory state (maps, arrays),
+            // released with the bundle when it goes out of scope. The hook exists
+            // to satisfy the uniform Harness contract so teardown is always
+            // `harness.dispose()` regardless of which harness.
+        }
+    };
+}
+//# sourceMappingURL=make-test-services.js.map

package/lib/testing/make-test-services.js.map

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

package/lib/testing/make-test-tracer.d.ts

@@ -0,0 +1,67 @@
+/********************************************************************************
+ * 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, type Logger, type LogLevel, type Tracer } from '@hydranium/protocol';
+/**
+ * No-op {@link Tracer} for tests — discards all output with real fluent
+ * behaviour. Use to fill the `Tracer` slot of a hand-rolled fake services tree
+ * when the test doesn't assert on emitted output. Equivalent to
+ * `new DefaultTracer()` (which already defaults to a {@link NoopLogger} +
+ * {@link SystemClock}); the named helper reads better at call sites and gives a
+ * single place to evolve the test tracer.
+ */
+export declare function makeNoopTracer(): Tracer;
+/**
+ * No-op {@link Logger} for tests — discards all output with real fluent
+ * behaviour (`for`/`sub`/`with` derive no-op children; `withUri`
+ * short-circuits to the same instance). Use to fill
+ * a `Logger` slot, or to satisfy a service/function that takes a bare `Logger`,
+ * when the test doesn't assert on emitted output. Equivalent to
+ * `new NoopLogger()`; the named helper is the bare-logger sibling of
+ * {@link makeNoopTracer} and gives a single place to evolve the test logger.
+ * Prefer this over hand-rolling a `{ for, sub, with, trace } as unknown as
+ * Logger` stub — those omit methods and drift from the real surface.
+ */
+export declare function makeNoopLogger(): Logger;
+/** A captured emission: log level + rendered message. */
+export interface CapturedLine {
+    readonly level: LogLevel;
+    readonly message: string;
+}
+/** A {@link Logger} whose emitted lines are captured for assertions. */
+export interface CapturingLogger {
+    readonly logger: Logger;
+    /** Every line emitted through the logger (and its derived children), in order. */
+    readonly lines: CapturedLine[];
+}
+/**
+ * Capturing {@link Logger} for tests that assert on emitted output. Backed by a
+ * complete {@link NoopLogger} subclass — so every emit method and `for`/`sub`/
+ * `with`/`withUri` derivation works fluently — that records each emitted line
+ * into {@link CapturingLogger.lines}. Derived child loggers share the same sink.
+ * Emission is still threshold-gated, so set the level (`Logger.setLevel(...)`)
+ * to the tier under test — `'trace'` captures everything. Prefer this over
+ * hand-rolling a capturing `{ info, warn, ... } as unknown as Logger` stub.
+ */
+export declare function makeCapturingLogger(): CapturingLogger;
+/** A {@link Tracer} whose emitted lines are captured for assertions. */
+export interface CapturingTracer {
+    readonly tracer: Tracer;
+    /** Every line emitted through the tracer (and its derived children), in order. */
+    readonly lines: CapturedLine[];
+}
+/**
+ * Capturing {@link Tracer} for tests that assert on emitted output. Wraps a
+ * {@link makeCapturingLogger} in a {@link DefaultTracer} so timing/profiling
+ * lines are captured alongside plain log lines. Emission is threshold-gated, so
+ * set the level (`Logger.setLevel(...)`) to the tier under test. Pass a
+ * {@link Clock} to share the test's fake-time axis; defaults to
+ * {@link SystemClock}.
+ */
+export declare function makeCapturingTracer(clock?: Clock): CapturingTracer;
+//# sourceMappingURL=make-test-tracer.d.ts.map

package/lib/testing/make-test-tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-test-tracer.d.ts","sourceRoot":"","sources":["../../src/testing/make-test-tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAiB,KAAK,MAAM,EAAE,KAAK,QAAQ,EAA2B,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElI;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC1B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC3B;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,CAWrD;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,KAAyB,GAAG,eAAe,CAGrF"}

package/lib/testing/make-test-tracer.js

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * 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 { DefaultTracer, NoopLogger, SystemClock } from '@hydranium/protocol';
+/**
+ * No-op {@link Tracer} for tests — discards all output with real fluent
+ * behaviour. Use to fill the `Tracer` slot of a hand-rolled fake services tree
+ * when the test doesn't assert on emitted output. Equivalent to
+ * `new DefaultTracer()` (which already defaults to a {@link NoopLogger} +
+ * {@link SystemClock}); the named helper reads better at call sites and gives a
+ * single place to evolve the test tracer.
+ */
+export function makeNoopTracer() {
+    return new DefaultTracer();
+}
+/**
+ * No-op {@link Logger} for tests — discards all output with real fluent
+ * behaviour (`for`/`sub`/`with` derive no-op children; `withUri`
+ * short-circuits to the same instance). Use to fill
+ * a `Logger` slot, or to satisfy a service/function that takes a bare `Logger`,
+ * when the test doesn't assert on emitted output. Equivalent to
+ * `new NoopLogger()`; the named helper is the bare-logger sibling of
+ * {@link makeNoopTracer} and gives a single place to evolve the test logger.
+ * Prefer this over hand-rolling a `{ for, sub, with, trace } as unknown as
+ * Logger` stub — those omit methods and drift from the real surface.
+ */
+export function makeNoopLogger() {
+    return new NoopLogger();
+}
+/**
+ * Capturing {@link Logger} for tests that assert on emitted output. Backed by a
+ * complete {@link NoopLogger} subclass — so every emit method and `for`/`sub`/
+ * `with`/`withUri` derivation works fluently — that records each emitted line
+ * into {@link CapturingLogger.lines}. Derived child loggers share the same sink.
+ * Emission is still threshold-gated, so set the level (`Logger.setLevel(...)`)
+ * to the tier under test — `'trace'` captures everything. Prefer this over
+ * hand-rolling a capturing `{ info, warn, ... } as unknown as Logger` stub.
+ */
+export function makeCapturingLogger() {
+    const lines = [];
+    class Capturing extends NoopLogger {
+        emit(level, _label, message) {
+            lines.push({ level, message });
+        }
+        derive(component) {
+            return new Capturing(component);
+        }
+    }
+    return { logger: new Capturing(), lines };
+}
+/**
+ * Capturing {@link Tracer} for tests that assert on emitted output. Wraps a
+ * {@link makeCapturingLogger} in a {@link DefaultTracer} so timing/profiling
+ * lines are captured alongside plain log lines. Emission is threshold-gated, so
+ * set the level (`Logger.setLevel(...)`) to the tier under test. Pass a
+ * {@link Clock} to share the test's fake-time axis; defaults to
+ * {@link SystemClock}.
+ */
+export function makeCapturingTracer(clock = new SystemClock()) {
+    const { logger, lines } = makeCapturingLogger();
+    return { tracer: new DefaultTracer(logger, clock), lines };
+}
+//# sourceMappingURL=make-test-tracer.js.map

package/lib/testing/make-test-tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-test-tracer.js","sourceRoot":"","sources":["../../src/testing/make-test-tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAc,aAAa,EAA8B,UAAU,EAAE,WAAW,EAAe,MAAM,qBAAqB,CAAC;AAElI;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC3B,OAAO,IAAI,aAAa,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc;IAC3B,OAAO,IAAI,UAAU,EAAE,CAAC;AAC3B,CAAC;AAeD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB;IAChC,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,MAAM,SAAU,SAAQ,UAAU;QACZ,IAAI,CAAC,KAAe,EAAE,MAAc,EAAE,OAAe;YACrE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QAClC,CAAC;QACkB,MAAM,CAAC,SAAiB;YACxC,OAAO,IAAI,SAAS,CAAC,SAAS,CAAS,CAAC;QAC3C,CAAC;KACH;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAe,IAAI,WAAW,EAAE;IACjE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,mBAAmB,EAAE,CAAC;IAChD,OAAO,EAAE,MAAM,EAAE,IAAI,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;AAC9D,CAAC"}

package/lib/testing/node/generated-workspace.d.ts

@@ -0,0 +1,95 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/** Default name of the file that records — and authorises — a generated corpus. */
+export declare const GENERATED_WORKSPACE_MARKER = ".hydranium-generated-workspace";
+/** The write surface {@link makeGeneratedWorkspace} hands to {@link GeneratedWorkspaceOptions.emit}. */
+export interface GeneratedWorkspaceWriter {
+    /** Absolute, resolved path of the corpus root. Already created and empty. */
+    readonly root: string;
+    /**
+     * Next value of the seeded stream, in `[0, 1)`.
+     *
+     * One stream for the whole corpus, drawn in emission order — so this is
+     * reproducible only as long as the emission order is. Prefer drawing
+     * unconditionally over drawing inside a branch.
+     */
+    random(): number;
+    /** An integer in `[minimum, maximum]`, both inclusive, off the same stream. */
+    randomInt(minimum: number, maximum: number): number;
+    /**
+     * Write `content` at `relativePath` under {@link root}, creating parent
+     * directories, and count it in the summary's tally. Returns the absolute
+     * path.
+     *
+     * Line endings are normalised to LF, without which the corpus is not
+     * byte-identical across platforms and the determinism contract holds only on
+     * one OS.
+     */
+    write(relativePath: string, content: string): string;
+    /** Create a directory under {@link root} and return its absolute path. */
+    directory(relativePath: string): string;
+}
+/** Inputs to {@link makeGeneratedWorkspace}. */
+export interface GeneratedWorkspaceOptions {
+    /** Directory to write into. Created if absent; wiped if the marker permits it. */
+    readonly root: string;
+    /**
+     * Identifies the generator in the marker file, so a corpus found on disk
+     * says what produced it. Free-form; a package-qualified name reads best.
+     */
+    readonly generator: string;
+    /**
+     * Recorded in the marker alongside the seed — the sizes the corpus was
+     * generated at, which is what makes a measurement taken over it
+     * interpretable later.
+     */
+    readonly parameters?: Readonly<Record<string, number | string | boolean>>;
+    /** Seed for the content stream. Defaults to `0`; the same seed reproduces the corpus byte for byte. */
+    readonly seed?: number;
+    /** Marker file name. Defaults to {@link GENERATED_WORKSPACE_MARKER}. */
+    readonly marker?: string;
+    /** Emit the content. Called once, after the root is prepared and the marker written. */
+    emit(writer: GeneratedWorkspaceWriter): void;
+}
+/** What {@link makeGeneratedWorkspace} wrote. */
+export interface GeneratedWorkspaceSummary {
+    /** Absolute, resolved corpus root. */
+    readonly root: string;
+    /** Seed actually used, after the default. */
+    readonly seed: number;
+    /** Marker file name actually used, relative to {@link root}. */
+    readonly marker: string;
+    /**
+     * How many files `emit` wrote, keyed by extension WITH the leading dot
+     * (`'.domain'`). The marker is not counted; everything `emit` wrote is,
+     * including any README, so a caller wanting a model-file subtotal adds up
+     * the extensions it considers model files.
+     *
+     * A tally is worth returning rather than leaving to the caller because it is
+     * the cheap assertion that catches the expensive defect: a generator whose
+     * nested loops skip a file still reports the size it was asked for, and the
+     * corpus is then quietly smaller than the number a measurement is filed
+     * under. Read it against a count taken off the filesystem, not instead of
+     * one — this counts the calls, so it cannot see a failed write.
+     */
+    readonly files: Readonly<Record<string, number>>;
+    /** Total files `emit` wrote, the marker excluded. */
+    readonly total: number;
+}
+/**
+ * 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 declare function makeGeneratedWorkspace(options: GeneratedWorkspaceOptions): GeneratedWorkspaceSummary;
+//# sourceMappingURL=generated-workspace.d.ts.map

package/lib/testing/node/generated-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-workspace.d.ts","sourceRoot":"","sources":["../../../src/testing/node/generated-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAmDlF,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,mCAAmC,CAAC;AAE3E,wGAAwG;AACxG,MAAM,WAAW,wBAAwB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,MAAM,IAAI,MAAM,CAAC;IACjB,+EAA+E;IAC/E,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD;;;;;;;;OAQG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACrD,0EAA0E;IAC1E,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1C;AAED,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACvC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAC1E,uGAAuG;IACvG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,wFAAwF;IACxF,IAAI,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C;AAED,iDAAiD;AACjD,MAAM,WAAW,yBAAyB;IACvC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACzB;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,yBAAyB,GAAG,yBAAyB,CAyCpG"}