@hydranium/core 1.0.0-next.10

package/src/testing/stub-ast-document-manager.ts

@@ -0,0 +1,224 @@
+/********************************************************************************
+ * 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 AstNode, type LangiumDocument, UriUtils } from '@hydranium/langium';
+import { Disposable } from 'vscode-languageserver';
+import {
+   type AstDocument,
+   type AstDocumentManager,
+   type AstDocumentUpdatedEvent,
+   type WritableFileSystemProvider
+} from '../documents/ast-document-manager.js';
+import type { CloseModelArgs, OpenModelArgs } from '@hydranium/protocol';
+import type { StubHydraniumTextDocuments } from './stub-hydranium-text-documents.js';
+import type { StubLangiumDocuments } from './stub-langium-documents.js';
+
+/**
+ * Minimal stub of {@link AstDocumentManager} for use in test
+ * harnesses. Implements just the methods the framework's
+ * `ModelService` calls (`open` / `close` / `update` / `save` /
+ * `isOpen` / `getDocument`); `onSave` / `onClientClosed` forward to the
+ * underlying stub text-document manager, `onUpdate` is driven explicitly
+ * through {@link StubAstDocumentManager.emitUpdate} because the stub tree runs
+ * no build phases to emit from, and the remaining read helpers
+ * (`isDirectChange`, `getAuthor`, `readFile`) throw if invoked — tests that
+ * need them should wire a richer stub or use the real
+ * {@link AstDocumentManager}.
+ *
+ * Open state is tracked per URI as the set of holding client ids, so a
+ * document stays open until its last client closes. The stub forwards
+ * content-change / save notifications to the supplied
+ * {@link StubHydraniumTextDocuments} so assertions on its `changes` /
+ * `saves` arrays see the same traffic the real manager would produce.
+ *
+ * # Stub-vs-real surface
+ *
+ * Picks the methods the stub claims to implement from
+ * {@link AstDocumentManager} — the compiler enforces each signature
+ * stays aligned with the real class. Methods that throw `notSupported`
+ * are still picked so signature drift on them produces a compile
+ * error rather than silent divergence.
+ */
+export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic = unknown> extends Pick<
+   AstDocumentManager<TAst, TDiagnostic>,
+   | 'open'
+   | 'close'
+   | 'isOpen'
+   | 'update'
+   | 'save'
+   | 'onUpdate'
+   | 'onSave'
+   | 'onClientClosed'
+   | 'getAuthor'
+   | 'getDocument'
+   | 'isDirectChange'
+   | 'readFile'
+> {
+   readonly openClients: Map<string, Set<string>>;
+
+   /**
+    * Deliver an update event to every live {@link StubAstDocumentManager.onUpdate}
+    * subscriber for `uri`. Returns how many listeners received it.
+    *
+    * **This exists because `onUpdate` cannot fire on its own, and that is a
+    * trap without a driver.** The real manager emits from a
+    * `DocumentBuilder.onDocumentPhase(Validated)` hook; a `makeTestServices`
+    * tree has a stub builder that runs no phases, so a subscription made
+    * through the stub would never be called. A test written as
+    * `onUpdate(uri, …); await tick(); expect(events).toHaveLength(0)` therefore
+    * passes for the wrong reason — the listener was never wired to anything —
+    * and reads as coverage of a suppression path it never reached. Driving the
+    * event explicitly is what lets such a test first prove delivery works, so
+    * the negative assertion means something.
+    *
+    * **The return value is the point, not a convenience.** `0` says no
+    * subscriber for that URI was registered, which is the state a negative
+    * assertion cannot distinguish from correct suppression. Assert it is
+    * non-zero before believing an empty event list.
+    *
+    * Two alternatives were rejected. Making `onUpdate` THROW would fence the
+    * hazard at zero API cost, but this harness ships (`files: ["lib", "src"]`)
+    * and an adopter subclass or test that subscribes and legitimately ignores
+    * the event would start failing on a stub it never asked to fire. Wiring the
+    * stub to the text-document store's change notifications — the way `onSave`
+    * is wired — would make it fire on its own, which moves the pass reason of
+    * every existing suite on a `makeTestServices` tree and asserts a phase
+    * semantics (`Validated`, with the real manager's author lookup and
+    * `changed`/`deleted`/`rebuilt` classification) that no stub tree has.
+    */
+   emitUpdate(uri: string, event: AstDocumentUpdatedEvent<TAst, TDiagnostic>): number;
+
+   /**
+    * How many live {@link StubAstDocumentManager.onUpdate} subscribers `uri`
+    * has, or the total across every URI when called with no argument.
+    *
+    * Read from outside — it is what a test asserts to show a subscription was
+    * actually established, and what makes {@link emitUpdate}'s `0` legible.
+    */
+   updateSubscriptions(uri?: string): number;
+}
+
+export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic = unknown>(
+   textDocuments: StubHydraniumTextDocuments,
+   fileSystem: Pick<WritableFileSystemProvider, 'writeFile'>,
+   documents?: StubLangiumDocuments<TAst, TDiagnostic>
+): StubAstDocumentManager<TAst, TDiagnostic> {
+   const openClients = new Map<string, Set<string>>();
+   // Keyed by the URI as given, not canonicalized: the stub has no URI policy,
+   // and `getDocument` below looks documents up by their given URI for the same
+   // reason, so both halves agree on identity.
+   const updateListeners = new Map<string, Set<(event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void>>();
+   const notSupported = (method: string): never => {
+      throw new Error(`StubAstDocumentManager.${method} is not implemented; wire the real AstDocumentManager if your test needs it.`);
+   };
+   const close = async (args: CloseModelArgs): Promise<void> => {
+      const clients = openClients.get(args.uri);
+      clients?.delete(args.clientId);
+      if (clients && clients.size === 0) {
+         openClients.delete(args.uri);
+      }
+   };
+   return {
+      openClients,
+      async open(args: OpenModelArgs): Promise<Disposable> {
+         const clients = openClients.get(args.uri) ?? new Set<string>();
+         clients.add(args.clientId);
+         openClients.set(args.uri, clients);
+         // The real `open` materialises the synced document (from the payload
+         // text or the filesystem); mirror that so a subsequent `update` finds
+         // an open document to apply its content change to.
+         if (!textDocuments.get(args.uri)) {
+            textDocuments.seedOpen(args.uri, args.text ?? '', args.clientId);
+         }
+         return Disposable.create(() => close({ uri: args.uri, clientId: args.clientId }));
+      },
+      close,
+      isOpen(uri: string): boolean {
+         return openClients.has(uri);
+      },
+      async update(uri: string, text: string, clientId: string): Promise<number> {
+         // Mirrors the real manager: the store assigns the shared version
+         // (step iff the content changed) — no fabricated version numbers.
+         return textDocuments.applyContentChange(uri, text, clientId);
+      },
+      async save(uri: string, clientId: string): Promise<void> {
+         const text = textDocuments.get(uri)?.getText() ?? '';
+         await fileSystem.writeFile(UriUtils.toUri(uri), text);
+         textDocuments.notifyDidSaveTextDocument({ textDocument: { uri }, text }, clientId);
+      },
+      // Registers the listener but never calls it by itself — the real manager
+      // emits from a `DocumentBuilder.onDocumentPhase(Validated)` hook and the
+      // stub tree runs no phases. `emitUpdate` is the only thing that fires it;
+      // see its declaration for why that is a driver rather than a throw or an
+      // autonomous wiring.
+      onUpdate(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable {
+         const listeners = updateListeners.get(uri) ?? new Set<(event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void>();
+         listeners.add(listener);
+         updateListeners.set(uri, listeners);
+         return Disposable.create(() => {
+            listeners.delete(listener);
+            if (listeners.size === 0) {
+               updateListeners.delete(uri);
+            }
+         });
+      },
+      emitUpdate(uri: string, event: AstDocumentUpdatedEvent<TAst, TDiagnostic>): number {
+         // Snapshot before iterating: a listener that disposes itself on first
+         // delivery would otherwise mutate the set mid-iteration.
+         const listeners = [...(updateListeners.get(uri) ?? [])];
+         for (const listener of listeners) {
+            listener(event);
+         }
+         return listeners.length;
+      },
+      updateSubscriptions(uri?: string): number {
+         if (uri !== undefined) {
+            return updateListeners.get(uri)?.size ?? 0;
+         }
+         let total = 0;
+         for (const listeners of updateListeners.values()) {
+            total += listeners.size;
+         }
+         return total;
+      },
+      onSave(uri: string, listener: (event: { document: AstDocument<TAst, TDiagnostic>; sourceClientId: string }) => void): Disposable {
+         return textDocuments.onDidSave(event => {
+            if (event.document.uri !== uri) {
+               return;
+            }
+            listener({
+               document: { uri, version: textDocuments.version(uri), root: undefined as unknown as TAst, diagnostics: [] as TDiagnostic[] },
+               sourceClientId: event.clientId
+            });
+         });
+      },
+      onClientClosed(uri: string, clientId: string, listener: () => void): Disposable {
+         return textDocuments.onDidClose(event => {
+            if (event.clientId === clientId && event.document.uri === uri) {
+               listener();
+            }
+         });
+      },
+      getAuthor(): string {
+         return notSupported('getAuthor');
+      },
+      // Canonicalizing document gateway. The stub has no canonicalizer, so it looks
+      // the document up in the seeded `StubLangiumDocuments` by its given URI (tests
+      // that need real symlink canonicalization wire the real AstDocumentManager).
+      getDocument(uri: string): LangiumDocument | undefined {
+         return documents?.getDocument(UriUtils.toUri(uri));
+      },
+      isDirectChange(): boolean {
+         return notSupported('isDirectChange');
+      },
+      async readFile(uri: string): Promise<string> {
+         return notSupported(`readFile(${uri})`);
+      }
+   };
+}

package/src/testing/stub-document-builder.ts

@@ -0,0 +1,242 @@
+/********************************************************************************
+ * 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 DocumentBuilder,
+   type DocumentPhaseListener,
+   type DocumentState,
+   type DocumentUpdateListener,
+   type LangiumDocument,
+   type URI
+} from '@hydranium/langium';
+import { type CancellationToken, Disposable } from 'vscode-languageserver';
+
+/** Recorded call to a stubbed {@link DocumentBuilder} method. */
+export interface RecordedBuilderCall<TArgs extends unknown[]> {
+   readonly args: TArgs;
+}
+
+/**
+ * Handle over one held {@link StubDocumentBuilder.waitUntil} call.
+ *
+ * **Consumption is observable on purpose**: a handle whose `resolve()` silently
+ * did nothing would let "the gate released the wait" and "the subject never
+ * reached the wait" produce identical, green runs.
+ */
+export interface StubWaitUntilGate {
+   /**
+    * Release the held call.
+    *
+    * **Throws if no `waitUntil` ever took this gate**, and drops the gate from
+    * the queue on the way out — an unconsumed gate is FIFO-handed to the next
+    * `waitUntil`, which may belong to an unrelated later test, where it parks a
+    * call nobody meant to hold.
+    */
+   resolve(): void;
+   /** Whether a {@link StubDocumentBuilder.waitUntil} call has taken this gate. */
+   readonly consumed: boolean;
+}
+
+/**
+ * Stub for Langium's {@link DocumentBuilder}. Implements the slice production
+ * code reads from on the framework's test paths (`update` / `waitUntil` /
+ * `onDocumentPhase` / `onUpdate`) plus test-only helpers:
+ *
+ * - {@link firePhase} — synchronously dispatch the registered phase
+ *   listener(s) for a document, simulating a build completing.
+ * - {@link fireOnUpdate} — invoke `onUpdate` subscribers with synthetic
+ *   changed / deleted URI lists, simulating Langium's update fan-out.
+ * - {@link gateNextWaitUntil} — defer the next {@link waitUntil} resolution
+ *   until the returned `resolve()` is called, simulating a long-running
+ *   build that lets a caller observe the in-flight state.
+ *
+ * Recorded `updateCalls` / `waitUntilCalls` allow assertions on the
+ * arguments the consumer passed.
+ *
+ * # Stub-vs-real surface
+ *
+ * Picks the methods the framework reads from {@link DocumentBuilder} on
+ * the slot path — the compiler enforces those signatures stay aligned.
+ * `update`, `onDocumentPhase`, `onUpdate`, and `waitUntil` carry stubbed
+ * implementations; `build`, `onBuildPhase`, and `resetToState` are
+ * implemented as loud-failing `notSupported` throwers so production code
+ * that goes through the cast at the bind site (i.e. accesses methods the
+ * stub claims but doesn't meaningfully implement) fails with a clear
+ * message instead of "undefined is not a function".
+ */
+export interface StubDocumentBuilder extends Pick<
+   DocumentBuilder,
+   'update' | 'onDocumentPhase' | 'onUpdate' | 'build' | 'onBuildPhase' | 'resetToState'
+> {
+   /**
+    * Single-overload stub of {@link DocumentBuilder.waitUntil}. Real has
+    * two overloads (`(state, cancelToken?): Promise<void>` and
+    * `(state, uri?, cancelToken?): Promise<URI | undefined>`) that can't
+    * be expressed as a single object-literal method type, so the stub
+    * declares only the more general second form. Tests pass cancelToken
+    * by name if needed (the stub ignores it).
+    */
+   waitUntil(state: DocumentState, uri?: URI): Promise<URI | undefined>;
+   readonly updateCalls: ReadonlyArray<RecordedBuilderCall<[URI[], URI[]]>>;
+   readonly waitUntilCalls: ReadonlyArray<RecordedBuilderCall<[DocumentState, URI | undefined]>>;
+   /**
+    * Synchronously fire the phase listener(s) registered for `state` with
+    * `document`. `cancelToken` defaults to a non-cancelled token; pass a
+    * cancelled token to simulate a build preempted by a concurrent write
+    * lock.
+    */
+   firePhase(state: DocumentState, document: LangiumDocument, cancelToken?: CancellationToken): void;
+   /** Synchronously fire every registered `onUpdate` listener. */
+   fireOnUpdate(changed: URI[], deleted: URI[]): void;
+   /**
+    * Hold the next {@link waitUntil} call. The returned handle releases it;
+    * the call's return value resolves on the next tick after `resolve` runs.
+    */
+   gateNextWaitUntil(): StubWaitUntilGate;
+   /** Drop recorded state and gates. Useful for `beforeEach`-style resets. */
+   reset(): void;
+}
+
+/**
+ * Re-raise a listener's asynchronous failure instead of discarding it.
+ *
+ * These dispatchers are synchronous, so a listener's promise cannot be awaited
+ * and `void` on it drops the rejection entirely — a phase listener that fails
+ * asynchronously leaves the test green while the code under test threw. Raising
+ * it as an uncaught exception is the only channel a `void`-returning dispatcher
+ * has, and is what every runner already reports. A test that legitimately
+ * expects a listener to reject must assert on it directly rather than firing a
+ * phase and ignoring the result.
+ */
+function reraise(result: unknown): void {
+   void Promise.resolve(result).catch((error: unknown) => {
+      queueMicrotask(() => {
+         throw error;
+      });
+   });
+}
+
+/**
+ * Build a {@link StubDocumentBuilder}. The stub is grammar-free and never
+ * actually parses; the `update` method only records its args. Tests that
+ * want to observe rebuilt state should `set` the new root on the document
+ * registry and then call `firePhase` to trigger the framework's post-build
+ * read path.
+ */
+export function makeStubDocumentBuilder(): StubDocumentBuilder {
+   const phaseListeners = new Map<DocumentState, DocumentPhaseListener[]>();
+   const onUpdateListeners: DocumentUpdateListener[] = [];
+   const gates: Array<{ take(release: () => void): void }> = [];
+   const updateCalls: RecordedBuilderCall<[URI[], URI[]]>[] = [];
+   const waitUntilCalls: RecordedBuilderCall<[DocumentState, URI | undefined]>[] = [];
+
+   const notSupported = (method: string): never => {
+      throw new Error(`StubDocumentBuilder.${method} is not implemented; wire a real DocumentBuilder if your test needs it.`);
+   };
+   const stub: StubDocumentBuilder = {
+      get updateCalls() {
+         return updateCalls;
+      },
+      get waitUntilCalls() {
+         return waitUntilCalls;
+      },
+      async update(changed: URI[], deleted: URI[]) {
+         updateCalls.push({ args: [changed, deleted] });
+      },
+      async waitUntil(state: DocumentState, uri?: URI) {
+         waitUntilCalls.push({ args: [state, uri] });
+         const gate = gates.shift();
+         if (gate) {
+            await new Promise<void>(resolve => gate.take(resolve));
+         }
+         return uri;
+      },
+      onDocumentPhase(state: DocumentState, listener: DocumentPhaseListener) {
+         const list = phaseListeners.get(state) ?? [];
+         list.push(listener);
+         phaseListeners.set(state, list);
+         return Disposable.create(() => {
+            const idx = list.indexOf(listener);
+            if (idx >= 0) {
+               list.splice(idx, 1);
+            }
+         });
+      },
+      onUpdate(listener: DocumentUpdateListener) {
+         onUpdateListeners.push(listener);
+         return Disposable.create(() => {
+            const idx = onUpdateListeners.indexOf(listener);
+            if (idx >= 0) {
+               onUpdateListeners.splice(idx, 1);
+            }
+         });
+      },
+      firePhase(state: DocumentState, document: LangiumDocument, cancelToken?: CancellationToken) {
+         const token =
+            cancelToken ??
+            ({
+               isCancellationRequested: false,
+               onCancellationRequested: () => Disposable.create(() => undefined)
+            } as CancellationToken);
+         const listeners = phaseListeners.get(state) ?? [];
+         for (const listener of listeners) {
+            reraise(listener(document, token));
+         }
+      },
+      fireOnUpdate(changed: URI[], deleted: URI[]) {
+         for (const listener of onUpdateListeners.slice()) {
+            reraise(listener(changed, deleted));
+         }
+      },
+      gateNextWaitUntil(): StubWaitUntilGate {
+         let release: (() => void) | undefined;
+         const entry = {
+            take(resolve: () => void): void {
+               release = resolve;
+            }
+         };
+         gates.push(entry);
+         return {
+            get consumed(): boolean {
+               return release !== undefined;
+            },
+            resolve(): void {
+               if (!release) {
+                  const queued = gates.indexOf(entry);
+                  if (queued >= 0) {
+                     gates.splice(queued, 1);
+                  }
+                  throw new Error(
+                     'StubDocumentBuilder: gateNextWaitUntil().resolve() ran before any waitUntil took the gate. ' +
+                        'Nothing was held, so releasing it proves nothing — wait until `waitUntilCalls` records the call first.'
+                  );
+               }
+               release();
+            }
+         };
+      },
+      build() {
+         return notSupported('build');
+      },
+      onBuildPhase() {
+         return notSupported('onBuildPhase');
+      },
+      resetToState() {
+         return notSupported('resetToState');
+      },
+      reset() {
+         phaseListeners.clear();
+         onUpdateListeners.length = 0;
+         gates.length = 0;
+         updateCalls.length = 0;
+         waitUntilCalls.length = 0;
+      }
+   };
+   return stub;
+}