@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,104 @@
+/********************************************************************************
+ * 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 { asCanonicalUri } from '@hydranium/protocol';
+import { UriUtils } from '@hydranium/langium';
+import { type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
+
+/**
+ * The runner primitives the suite emits through. Vitest and Jest both supply
+ * structurally-compatible `describe`/`it`/`expect`, so the kit takes them as a
+ * parameter rather than importing a runner — keeping it usable from either, and
+ * keeping `@hydranium/core/testing` free of a hard runner dependency (the
+ * barrel is consumed by Jest adopters too).
+ */
+export interface DocumentUriPolicyConformanceHooks {
+   describe(name: string, body: () => void): void;
+   it(name: string, body: () => void): void;
+   expect(actual: unknown): { toBe(expected: unknown): void };
+}
+
+/** Options for {@link documentUriPolicyConformance}. */
+export interface DocumentUriPolicyConformanceOptions {
+   /**
+    * URIs the contract is checked against. A policy that strengthens identity
+    * (realpath) should include a divergent (symlinked) and an absent sample so
+    * the resolve / fallback branches are exercised. Defaults to a syntactic
+    * spread (dot segments, spaces, a non-`file:` scheme) that any policy honours.
+    */
+   readonly sampleUris?: readonly string[];
+}
+
+const DEFAULT_SAMPLE_URIS = ['file:///a/b.fake', 'file:///a/../b.fake', 'file:///My Folder/x.fake', 'builtin:///Element.fake'];
+
+/**
+ * Reusable contract suite for any {@link DocumentUriPolicy} implementation —
+ * the framework's `DefaultDocumentUriPolicy` / `RealpathDocumentUriPolicy` and
+ * any adopter policy. Pins the two invariants the document-identity story
+ * rests on, so a change to either method — or an adopter binding a
+ * custom policy — cannot silently reintroduce the canonical/load divergence:
+ *
+ * 1. **`canonicalUri` is idempotent** — feeding it an already-canonical URI
+ *    (e.g. a `LangiumDocument.uri` straight off the build) is a fixed point.
+ * 2. **Present-case agreement** — whenever `loadUri(u)` is defined (the URI is
+ *    loadable), its normalised form equals `canonicalUri(u)`. This is the
+ *    "two methods, one policy" guarantee: the key the document is stored under
+ *    and the URI it is loaded from must denote the same identity, or a
+ *    subscriber keyed by one misses events delivered under the other.
+ *
+ * The miss case is deliberately NOT constrained (the default returns the URI
+ * unchanged from `loadUri`; a realpath policy returns `undefined`) — only the
+ * present case must agree.
+ *
+ * The agreement check is vacuous for a sample that is not loadable, so the
+ * suite also emits a guard asserting that at least ONE sample is: an
+ * existence-aware policy (realpath, or an adopter's) bound against the
+ * fictional {@link DEFAULT_SAMPLE_URIS} resolves every one of them to
+ * `undefined`, and would otherwise report an all-green suite that checked
+ * nothing.
+ *
+ * @param hooks the test runner's `describe`/`it`/`expect`
+ * @param suiteName label for the emitted `describe` block
+ * @param makePolicy fresh policy per assertion (no shared mutable state)
+ */
+export function documentUriPolicyConformance(
+   hooks: DocumentUriPolicyConformanceHooks,
+   suiteName: string,
+   makePolicy: () => DocumentUriPolicy,
+   options: DocumentUriPolicyConformanceOptions = {}
+): void {
+   const { describe, it, expect } = hooks;
+   const sampleUris = options.sampleUris ?? DEFAULT_SAMPLE_URIS;
+
+   describe(suiteName, () => {
+      for (const uri of sampleUris) {
+         it(`canonicalUri is idempotent for ${uri}`, () => {
+            const once = makePolicy().canonicalUri(uri);
+            expect(makePolicy().canonicalUri(once)).toBe(once);
+         });
+
+         it(`canonicalUri agrees with loadUri when ${uri} is loadable`, () => {
+            const policy = makePolicy();
+            const loaded = policy.loadUri(uri);
+            if (loaded === undefined) {
+               return; // not loadable: the agreement invariant is vacuous here
+            }
+            expect(policy.canonicalUri(uri)).toBe(asCanonicalUri(UriUtils.normalize(loaded)));
+         });
+      }
+
+      // 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(', ')})`, () => {
+         const loadable = sampleUris.filter(uri => makePolicy().loadUri(uri) !== undefined);
+         expect(loadable.length > 0).toBe(true);
+      });
+   });
+}

package/src/testing/fake-description.ts

@@ -0,0 +1,52 @@
+/********************************************************************************
+ * 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 AstNodeDescription, URI } from '@hydranium/langium';
+
+/**
+ * Options for {@link makeFakeDescription}. Extends `Partial<AstNodeDescription>`
+ * (override any standard field) plus the tier-index extras (`tier`, `projectId`)
+ * that live on a `TieredAstNodeDescription` — attached without the caller
+ * writing an `as unknown as` cast.
+ */
+export interface FakeDescriptionOptions extends Partial<AstNodeDescription> {
+   /** Visibility tier (`'local' | 'project' | 'public' | 'universal'`) to stamp on the description. */
+   tier?: string;
+   /** Owning project id, for project/public-tier descriptions. */
+   projectId?: string;
+}
+
+/**
+ * Build an {@link AstNodeDescription} fixture for scope / candidate / tier tests.
+ *
+ * Defaults model distinct nodes: `type: 'Fake'`, `documentUri: memory://test`,
+ * and a per-name `path` (`'/' + name`) so distinct names key as distinct nodes
+ * under the canonical filter (which keys on `documentUri#path`). Tier-sibling
+ * cases that model ONE node under several names pass an explicit shared `path`.
+ * `tier` / `projectId` are stamped on when provided; the cast that needs (those
+ * fields live on `TieredAstNodeDescription`, not on `AstNodeDescription`) is
+ * encapsulated here so call sites stay cast-free. The description sibling of
+ * `makeFakeAstNode`.
+ */
+export function makeFakeDescription(name: string, opts: FakeDescriptionOptions = {}): AstNodeDescription {
+   const description: AstNodeDescription = {
+      name,
+      type: opts.type ?? 'Fake',
+      documentUri: opts.documentUri ?? URI.parse('memory://test'),
+      path: opts.path ?? '/' + name,
+      node: opts.node
+   };
+   if (opts.tier !== undefined) {
+      (description as unknown as Record<string, string>).tier = opts.tier;
+   }
+   if (opts.projectId !== undefined) {
+      (description as unknown as Record<string, string>).projectId = opts.projectId;
+   }
+   return description;
+}

package/src/testing/fake-document.ts

@@ -0,0 +1,120 @@
+/********************************************************************************
+ * 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 { DocumentState, type AstNode, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+
+/**
+ * Build a typed AST-node fixture for unit tests.
+ *
+ * Langium AST node types are nominal interfaces generated from the grammar, so
+ * an object literal can never structurally satisfy one — every test that needs
+ * a node otherwise writes `{ $type: 'X', … } as unknown as SomeNode`. This
+ * helper encapsulates that single unavoidable cast in one audited place and
+ * hands back a value typed as `T`, so call sites stay cast-free and
+ * intention-revealing.
+ *
+ * It deliberately does NOT set the `$synthetic` marker: a test fixture is not a
+ * framework synthetic node, and marking it would change scope/index behaviour.
+ * A test that wants a genuine synthetic node calls `markSynthetic` explicitly.
+ *
+ * @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.
+ */
+export function makeFakeAstNode<TAst extends AstNode = AstNode>(node: { $type: string } & Record<string, unknown>): TAst {
+   return node as unknown as TAst;
+}
+
+/**
+ * Options for {@link makeFakeDocument}.
+ *
+ * `text` defaults to a cycle-safe JSON rendering of `root` so fingerprint-based
+ * dedup paths (e.g. `DataServer.dispatchPhaseEvent`) have a deterministic
+ * input — passing an explicit value is only necessary when a test asserts on
+ * the document text or relies on a grammar-realistic serialisation.
+ */
+export interface FakeDocumentOptions<TAst extends AstNode, TDiagnostic> {
+   text?: string;
+   version?: number;
+   state?: DocumentState;
+   diagnostics?: TDiagnostic[];
+   /** Override the parserErrors / lexerErrors arrays returned from `parseResult`. */
+   parseResult?: Partial<LangiumDocument<TAst>['parseResult']>;
+   /**
+    * Cross-reference list. Defaults to `[]`. Loosely typed because a full
+    * Langium `Reference` is not constructible in a unit test, so tests
+    * exercising CST / reference paths pass the minimal shape they need.
+    */
+   references?: readonly unknown[];
+   /**
+    * Full `textDocument` override for tests that need a real `TextDocument` —
+    * the LSP position API (`positionAt` / `offsetAt`), which the minimal
+    * default lacks. Defaults to a `{ uri, version, getText }` shell.
+    */
+   textDocument?: LangiumDocument<TAst>['textDocument'];
+}
+
+/**
+ * Serialise `root` for the fake document's default text. AST fixtures routinely
+ * carry `$container` back-references (child → parent → child), so a plain
+ * `JSON.stringify` throws on the cycle; fall back to a minimal, deterministic
+ * `$type` marker in that case. The default text is only for fingerprint / dedup
+ * determinism — tests that assert on document text pass an explicit `text`.
+ */
+function stringifyFakeRoot(root: unknown): string {
+   try {
+      return JSON.stringify(root);
+   } catch {
+      return JSON.stringify({ $type: (root as { $type?: unknown } | undefined)?.$type });
+   }
+}
+
+/**
+ * Build a {@link LangiumDocument} shell suitable for stub services trees in
+ * unit tests. The returned document satisfies the structural shape Langium
+ * production code reads from — `uri`, `parseResult`, `textDocument`,
+ * `diagnostics`, `state` — without spinning up a real grammar.
+ *
+ * Default state is {@link DocumentState.Validated} so callers exercising the
+ * post-build read path (`getDocument` → assert AST) work without explicit
+ * staging. Override via `options.state` for tests that gate on earlier
+ * phases.
+ */
+export function makeFakeDocument<TAst extends AstNode = AstNode, TDiagnostic = unknown>(
+   uri: string | URI,
+   root: TAst,
+   options: FakeDocumentOptions<TAst, TDiagnostic> = {}
+): LangiumDocument<TAst> {
+   const parsed = UriUtils.toUri(uri);
+   const text = options.text ?? stringifyFakeRoot(root);
+   const version = options.version ?? 1;
+   const document = {
+      uri: parsed,
+      parseResult: {
+         value: root,
+         parserErrors: [],
+         lexerErrors: [],
+         ...options.parseResult
+      },
+      textDocument: options.textDocument ?? {
+         uri: parsed.toString(),
+         version,
+         getText: () => text
+      },
+      diagnostics: (options.diagnostics ?? []) as never,
+      references: options.references ?? [],
+      state: options.state ?? DocumentState.Validated
+   } as unknown as LangiumDocument<TAst>;
+   // Wire the root → document back-reference the real LangiumDocumentFactory
+   // sets, so consumers that resolve a node's owning document (e.g. the
+   // transfer encoder deriving the encode context's URI) see the fake as
+   // attached rather than detached.
+   (root as { $document?: LangiumDocument<TAst> }).$document = document;
+   return document;
+}

package/src/testing/fake-reflection.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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 { AstReflection, TypeMetaData } from '@hydranium/langium';
+
+/** Per-property metadata a {@link makeFakeReflection} type map may declare. */
+export interface FakeReflectionProperty {
+   defaultValue?: unknown;
+   referenceType?: string;
+}
+
+/**
+ * Build a minimal {@link AstReflection} for serializer / encoder tests.
+ *
+ * Only `getTypeMetaData(type).properties[prop]` — with the optional
+ * `defaultValue` / `referenceType` the serialization utilities read — is
+ * populated; every other reflection member is absent, so an accidental new
+ * dependency throws loudly rather than silently returning `undefined`. Pass a
+ * `type -> property -> metadata` map.
+ *
+ * The single unavoidable cast (an object literal can't structurally satisfy the
+ * generated `AstReflection` interface) is encapsulated here so call sites stay
+ * cast-free — the reflection sibling of `makeFakeAstNode`.
+ */
+export function makeFakeReflection(types: Record<string, Record<string, FakeReflectionProperty>>): AstReflection {
+   return {
+      getTypeMetaData: (type: string): TypeMetaData =>
+         ({
+            name: type,
+            properties: types[type] ?? {}
+         }) as unknown as TypeMetaData
+   } as unknown as AstReflection;
+}

package/src/testing/index.ts

@@ -0,0 +1,45 @@
+/********************************************************************************
+ * 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` — the framework's BROWSER-NEUTRAL test-support
+ * surface: Langium-layer doubles for the shared-services slots, the harness that
+ * composes them into a services tree, the fake AST / document / reflection
+ * 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
+ * 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:
+ * the portable name is the short one.
+ */
+
+export * from './ast-snapshot.js';
+export * from './document-uri-policy-conformance.js';
+export * from './fake-description.js';
+export * from './fake-document.js';
+export * from './fake-reflection.js';
+export * from './langium-test-helpers.js';
+export * from './make-noop-language-services.js';
+export * from './make-noop-shared-services.js';
+export * from './make-test-services.js';
+export * from './make-test-tracer.js';
+export * from './parse-semantic-root.js';
+export * from './run-update-pipeline.js';
+export * from './stub-document-builder.js';
+export * from './stub-index-manager.js';
+export * from './stub-langium-documents.js';
+export * from './stub-model-service.js';
+export * from './stub-ast-document-manager.js';
+export * from './stub-project-manager.js';
+export * from './stub-self-save-registry.js';
+export * from './stub-service-registry.js';
+export * from './stub-hydranium-text-documents.js';
+export * from './stub-writable-file-system.js';

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

@@ -0,0 +1,26 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Re-exports of Langium's `langium/test` helpers, so that
+ * `@hydranium/core/testing` is one import location for both test patterns:
+ *
+ * - the stubs from this subpath (`makeTestServices`, the `Stub*` classes) —
+ *   when the unit under test is a framework production class and can be
+ *   exercised without a real Langium grammar, against a
+ *   `ServerSharedServices`-shaped tree that no parser drives;
+ * - the Langium helpers re-exported here (`parseHelper`, `expectCompletion`,
+ *   `expectError`, …) — when the unit under test needs the AST a real grammar
+ *   produces.
+ *
+ * The re-export is verbatim and uncurated: the source of truth for the helpers'
+ * contracts stays Langium upstream, so a rename there surfaces here rather than
+ * being absorbed by a hand-maintained list.
+ */
+export * from '@hydranium/langium/test';

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

@@ -0,0 +1,47 @@
+/********************************************************************************
+ * 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 { ServerLanguageServices } from '../langium/language-module.js';
+import { makeNoopSharedServices, type NoopSharedServicesOverrides } from './make-noop-shared-services.js';
+
+/**
+ * Overrides for {@link makeNoopLanguageServices}. `shared` flows into
+ * {@link makeNoopSharedServices} (so the shared tree gets its no-op defaults);
+ * every other key is a loosely-typed per-language slot group (`references`,
+ * `ast`, `serializer`, `integrity`, `updateRewrite`, `validation`, the
+ * language-level `workspace`, …) spread onto the result, so a test drops in the
+ * one or two service stubs the class under test reads without a per-slot cast.
+ */
+export interface NoopLanguageServicesOverrides {
+   /** Overrides for the `shared` sub-tree — forwarded to {@link makeNoopSharedServices}. */
+   shared?: NoopSharedServicesOverrides;
+   /** Any per-language slot the class under test reads. */
+   [slot: string]: unknown;
+}
+
+/**
+ * Build a {@link ServerLanguageServices} tree whose `shared` sub-tree carries
+ * the {@link makeNoopSharedServices} no-op defaults, leaving the per-language
+ * slots for the caller to fill through `overrides`.
+ *
+ * The single unavoidable cast — an assembled literal can't structurally satisfy
+ * the full `ServerLanguageServices` (it omits the Langium per-language surface a
+ * unit test doesn't touch) — is encapsulated here, so a test constructing a
+ * framework per-language service (`DefaultIntegrityService`,
+ * `DefaultAstExtensionService`, `DefaultScopeExtensionService`,
+ * `DefaultUpdateRewriteService`, …) stays cast-free. The per-language sibling of
+ * {@link makeNoopSharedServices}.
+ */
+export function makeNoopLanguageServices(overrides: NoopLanguageServicesOverrides = {}): ServerLanguageServices {
+   const { shared, ...rest } = overrides;
+   return {
+      shared: makeNoopSharedServices(shared),
+      ...rest
+   } as unknown as ServerLanguageServices;
+}

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

@@ -0,0 +1,78 @@
+/********************************************************************************
+ * 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, DefaultTracer, type Logger, NoopLogger, SystemClock, type Tracer } from '@hydranium/protocol';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+
+/**
+ * Overrides for {@link makeNoopSharedServices}. The three observability slots
+ * are typed (they are the boilerplate this helper exists to default);
+ * `workspace` and any other slot are loosely typed so a test can drop in a
+ * structurally-narrower stub (a `Pick` of `LangiumDocuments`, an inline
+ * `{ wsRelativePath }` `WorkspaceManager`, …) without a per-slot cast — the
+ * single boundary cast lives inside {@link makeNoopSharedServices}.
+ */
+export interface NoopSharedServicesOverrides {
+   /** Bound on the top-level `Clock` slot. Default: {@link SystemClock}. */
+   Clock?: Clock;
+   /**
+    * Bound on the top-level `Logger` slot AND wrapped by the default `Tracer`
+    * (pass a `makeCapturingLogger().logger` to see tracer-emitted lines too).
+    * Default: {@link NoopLogger}.
+    */
+   Logger?: Logger;
+   /** Bound on the top-level `Tracer` slot. Default: a `DefaultTracer` over `Logger` + `Clock`. */
+   Tracer?: Tracer;
+   /** Per-slot `workspace` overrides. Slots left out resolve to `undefined`. */
+   workspace?: Record<string, unknown>;
+   /** Any other minimal slot (`ServiceRegistry`, `AstReflection`, `additionalDocuments`, …). */
+   [slot: string]: unknown;
+}
+
+/**
+ * Build a {@link ServerSharedServicesMinimal} tree backed by no-op defaults for
+ * the observability slots every framework component reads (`Clock` / `Logger` /
+ * `Tracer`) plus an empty `additionalDocuments`, leaving every other slot for
+ * the caller to fill through `overrides`.
+ *
+ * The single unavoidable cast — an assembled literal can't structurally satisfy
+ * the full `ServerSharedServicesMinimal` (it omits the many Langium slots a unit
+ * test doesn't touch: `ServiceRegistry`, `AstNodeLocator`, `IndexManager`, …) —
+ * is encapsulated here so call sites stay cast-free and intention-revealing.
+ * It is the shared-services sibling of `makeFakeAstNode` / `makeFakeReflection`:
+ * a test that reads an unset slot gets `undefined` and should override it.
+ *
+ * `overrides` is loosely typed on purpose (see {@link NoopSharedServicesOverrides})
+ * so structurally-narrower stubs slot in without a per-slot cast. For a fully
+ * wired tree with real Langium-layer stubs (LangiumDocuments / DocumentBuilder /
+ * ModelService / …) use `makeTestServices` instead — this helper is the light
+ * option for services that read only a handful of slots.
+ *
+ * The return type defaults to {@link ServerSharedServicesMinimal}; a consumer
+ * whose constructor declares the fuller `ServerSharedServices` requests it via
+ * the type parameter (`makeNoopSharedServices<ServerSharedServices>(...)`) so
+ * the value is assignable without a call-site cast — the extra LSP-bound slots
+ * are still undefined and should be overridden if the code under test reads them.
+ */
+export function makeNoopSharedServices<T extends ServerSharedServicesMinimal = ServerSharedServicesMinimal>(
+   overrides: NoopSharedServicesOverrides = {}
+): T {
+   const { Clock: clock, Logger: logger, Tracer: tracer, workspace, additionalDocuments, ...restTop } = overrides;
+   const resolvedClock = clock ?? new SystemClock();
+   const resolvedLogger = logger ?? new NoopLogger();
+   const resolvedTracer = tracer ?? new DefaultTracer(resolvedLogger, resolvedClock);
+   return {
+      Clock: resolvedClock,
+      Logger: resolvedLogger,
+      Tracer: resolvedTracer,
+      additionalDocuments: additionalDocuments ?? {},
+      ...restTop,
+      workspace: { ...(workspace ?? {}) }
+   } as unknown as T;
+}