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

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

@@ -9,27 +9,21 @@
 
 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 AstDiagnostic } from '../langium/validation/document-validator.js';
+import { AstDocument, type AstDocumentManager, type UpdateAttribution } from '../documents/ast-document-manager.js';
+import { type WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
+import { UNKNOWN_CLIENT_ID } from '../documents/client-ids.js';
+import { DefaultModelLedger, type ModelLedger } from '../documents/model-ledger.js';
+import { type CloseModelArgs, type 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}.
+ * Minimal stub of {@link AstDocumentManager} for use in test harnesses,
+ * implementing what the model service and client sessions call. `getAuthor`
+ * throws if invoked, and `attributeUpdate` reports every update as its
+ * author's change; tests that need either 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
@@ -45,75 +39,31 @@ import type { StubLangiumDocuments } from './stub-langium-documents.js';
  * 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<
+export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> extends Pick<
    AstDocumentManager<TAst, TDiagnostic>,
    | 'open'
    | 'close'
    | 'isOpen'
    | 'update'
    | 'save'
-   | 'onUpdate'
-   | 'onSave'
-   | 'onClientClosed'
+   | 'delete'
+   | 'isDeleting'
+   | 'attributeDeletion'
    | 'getAuthor'
    | 'getDocument'
-   | 'isDirectChange'
-   | 'readFile'
+   | 'toAstDocument'
+   | 'attributeUpdate'
 > {
    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>(
+export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
    textDocuments: StubHydraniumTextDocuments,
    fileSystem: Pick<WritableFileSystemProvider, 'writeFile'>,
-   documents?: StubLangiumDocuments<TAst, TDiagnostic>
+   documents?: StubLangiumDocuments<TAst, TDiagnostic>,
+   ledger: ModelLedger = new DefaultModelLedger()
 ): 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.`);
    };
@@ -131,10 +81,13 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic = u
          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.
+         // text or the filesystem), or attaches the client to the one that is
+         // there; mirror both so a subsequent `update` finds the document open
+         // for this client.
          if (!textDocuments.get(args.uri)) {
             textDocuments.seedOpen(args.uri, args.text ?? '', args.clientId);
+         } else {
+            textDocuments.attachClient(args.uri, args.clientId);
          }
          return Disposable.create(() => close({ uri: args.uri, clientId: args.clientId }));
       },
@@ -147,78 +100,44 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic = u
          // (step iff the content changed) — no fabricated version numbers.
          return textDocuments.applyContentChange(uri, text, clientId);
       },
-      async save(uri: string, clientId: string): Promise<void> {
+      async save(uri: string, clientId: string): Promise<number> {
          const text = textDocuments.get(uri)?.getText() ?? '';
+         const version = textDocuments.version(uri);
          await fileSystem.writeFile(UriUtils.toUri(uri), text);
          textDocuments.notifyDidSaveTextDocument({ textDocument: { uri }, text }, clientId);
+         return version;
       },
-      // 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);
-            }
-         });
+      delete(): Promise<void> {
+         return notSupported('delete');
       },
-      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;
+      // The stub deletes nothing, so no delete is ever under way.
+      isDeleting(): boolean {
+         return false;
       },
-      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();
-            }
-         });
+      attributeDeletion(): string {
+         return UNKNOWN_CLIENT_ID;
       },
       getAuthor(): string {
          return notSupported('getAuthor');
       },
+      // Reports every event as a change by the version's author: the stub
+      // tree runs no builds, so there is no delivery to tell a rebuild by. A
+      // test of the rebuilt branch replaces this method or uses the real
+      // manager.
+      attributeUpdate(document: LangiumDocument): UpdateAttribution {
+         const author = textDocuments.getAuthor(document.textDocument.uri, document.textDocument.version) ?? UNKNOWN_CLIENT_ID;
+         return { reason: 'changed', sourceClientId: author, causedBy: author };
+      },
       // 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})`);
+      toAstDocument(document: LangiumDocument): AstDocument<TAst, TDiagnostic> {
+         const uri = document.textDocument.uri;
+         const root = document.parseResult.value as TAst;
+         return AstDocument.create<TAst, TDiagnostic>(uri, ledger.versionOf(root), root, document.diagnostics as TDiagnostic[] | undefined);
       }
    };
 }

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

@@ -9,13 +9,17 @@
 
 import {
    type DocumentBuilder,
+   type DocumentBuildListener,
    type DocumentPhaseListener,
    type DocumentState,
    type DocumentUpdateListener,
+   isOperationCancelled,
    type LangiumDocument,
-   type URI
+   type URI,
+   type WorkspaceLock
 } from '@hydranium/langium';
 import { type CancellationToken, Disposable } from 'vscode-languageserver';
+import { type BuildEndedEvent, HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
 
 /** Recorded call to a stubbed {@link DocumentBuilder} method. */
 export interface RecordedBuilderCall<TArgs extends unknown[]> {
@@ -45,8 +49,7 @@ export interface StubWaitUntilGate {
 
 /**
  * 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:
+ * code reads on the framework's test paths, plus test-only helpers:
  *
  * - {@link firePhase} — synchronously dispatch the registered phase
  *   listener(s) for a document, simulating a build completing.
@@ -64,16 +67,17 @@ export interface StubWaitUntilGate {
  * 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
+ * implementations, and `scheduleUpdate` calls `update` in one lock write per
+ * call (see {@link makeStubDocumentBuilder}); `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'
-> {
+export interface StubDocumentBuilder
+   extends
+      Pick<DocumentBuilder, 'update' | 'onDocumentPhase' | 'onUpdate' | 'build' | 'onBuildPhase' | 'resetToState' | 'updateBuildOptions'>,
+      Pick<HydraniumDocumentBuilder, 'onDocumentPhaseDelivered' | 'scheduleUpdate' | 'finalBuildState' | 'onBuildEnded'> {
    /**
     * Single-overload stub of {@link DocumentBuilder.waitUntil}. Real has
     * two overloads (`(state, cancelToken?): Promise<void>` and
@@ -87,13 +91,29 @@ export interface StubDocumentBuilder extends Pick<
    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.
+    * `document`, then, unless a listener was cancelled, the
+    * `onDocumentPhaseDelivered` listeners. `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;
+   /**
+    * Synchronously fire the BUILD-phase listener(s) for `state` with the whole
+    * batch. The per-build counterpart of {@link firePhase}: a subject that
+    * reports once per build rather than once per document subscribes here, and
+    * a stub that only fired {@link firePhase} would leave it silent while
+    * looking wired.
+    */
+   fireBuildPhase(state: DocumentState, built: LangiumDocument[], cancelToken?: CancellationToken): void;
+   /**
+    * Synchronously fire every {@link HydraniumDocumentBuilder.onBuildEnded}
+    * listener with `event`. As in the real builder, one that throws does not
+    * stop the others; the real builder logs the error, and this stub, having
+    * no logger, rethrows the first one once all have run.
+    */
+   fireBuildEnded(event: BuildEndedEvent): 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.
@@ -128,10 +148,18 @@ function reraise(result: unknown): void {
  * 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.
+ *
+ * `workspaceLock` is the lock `scheduleUpdate` writes under, without the real
+ * builder's sharing: pass the services tree's own, so a caller's lock ordering
+ * and reentrancy behave as against the real builder. Without one,
+ * `scheduleUpdate` records the update unlocked.
  */
-export function makeStubDocumentBuilder(): StubDocumentBuilder {
+export function makeStubDocumentBuilder(workspaceLock?: WorkspaceLock): StubDocumentBuilder {
    const phaseListeners = new Map<DocumentState, DocumentPhaseListener[]>();
+   const deliveredListeners = new Map<DocumentState, Array<(document: LangiumDocument, version: number) => void>>();
+   const buildPhaseListeners = new Map<DocumentState, DocumentBuildListener[]>();
    const onUpdateListeners: DocumentUpdateListener[] = [];
+   const buildEndedListeners: Array<(event: BuildEndedEvent) => void> = [];
    const gates: Array<{ take(release: () => void): void }> = [];
    const updateCalls: RecordedBuilderCall<[URI[], URI[]]>[] = [];
    const waitUntilCalls: RecordedBuilderCall<[DocumentState, URI | undefined]>[] = [];
@@ -140,6 +168,11 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
       throw new Error(`StubDocumentBuilder.${method} is not implemented; wire a real DocumentBuilder if your test needs it.`);
    };
    const stub: StubDocumentBuilder = {
+      // Langium's own default, so a session write waits for `Validated` here
+      // as it does against the real builder.
+      updateBuildOptions: { validation: { categories: ['built-in', 'fast'] } },
+      // The real rule, read off this stub's options, so the two cannot drift.
+      finalBuildState: () => HydraniumDocumentBuilder.prototype.finalBuildState.call(stub),
       get updateCalls() {
          return updateCalls;
       },
@@ -149,6 +182,9 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
       async update(changed: URI[], deleted: URI[]) {
          updateCalls.push({ args: [changed, deleted] });
       },
+      scheduleUpdate(changed: URI[], deleted: URI[]) {
+         return workspaceLock ? workspaceLock.write(() => stub.update(changed, deleted)) : stub.update(changed, deleted);
+      },
       async waitUntil(state: DocumentState, uri?: URI) {
          waitUntilCalls.push({ args: [state, uri] });
          const gate = gates.shift();
@@ -185,15 +221,95 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
                onCancellationRequested: () => Disposable.create(() => undefined)
             } as CancellationToken);
          const listeners = phaseListeners.get(state) ?? [];
+         const delivered = deliveredListeners.get(state) ?? [];
+         // Taken before the listeners, as the real builder does: one of them
+         // may stand in for a write that moves the version on. Read only when
+         // someone is told, since many fakes carry no text document.
+         const version = delivered.length > 0 ? document.textDocument.version : 0;
+         // As the real builder: a listener reached on a cancelled token, or
+         // throwing OperationCancelled, counts as cancelled and withholds the
+         // delivered listeners.
+         let cancelledListeners = 0;
          for (const listener of listeners) {
-            reraise(listener(document, token));
+            if (token.isCancellationRequested) {
+               cancelledListeners++;
+               continue;
+            }
+            try {
+               reraise(listener(document, token));
+            } catch (err: unknown) {
+               if (!isOperationCancelled(err)) {
+                  throw err;
+               }
+               cancelledListeners++;
+            }
+         }
+         if (cancelledListeners === 0) {
+            for (const listener of delivered) {
+               listener(document, version);
+            }
          }
       },
+      onDocumentPhaseDelivered(state: DocumentState, listener: (document: LangiumDocument, version: number) => void) {
+         const list = deliveredListeners.get(state) ?? [];
+         list.push(listener);
+         deliveredListeners.set(state, list);
+         return Disposable.create(() => {
+            const idx = list.indexOf(listener);
+            if (idx >= 0) {
+               list.splice(idx, 1);
+            }
+         });
+      },
       fireOnUpdate(changed: URI[], deleted: URI[]) {
          for (const listener of onUpdateListeners.slice()) {
             reraise(listener(changed, deleted));
          }
       },
+      onBuildEnded(listener: (event: BuildEndedEvent) => void) {
+         buildEndedListeners.push(listener);
+         return Disposable.create(() => {
+            const idx = buildEndedListeners.indexOf(listener);
+            if (idx >= 0) {
+               buildEndedListeners.splice(idx, 1);
+            }
+         });
+      },
+      fireBuildEnded(event: BuildEndedEvent) {
+         const failures: unknown[] = [];
+         for (const listener of buildEndedListeners.slice()) {
+            try {
+               listener(event);
+            } catch (error: unknown) {
+               failures.push(error);
+            }
+         }
+         if (failures.length > 0) {
+            throw failures[0];
+         }
+      },
+      onBuildPhase(state: DocumentState, listener: DocumentBuildListener) {
+         const list = buildPhaseListeners.get(state) ?? [];
+         list.push(listener);
+         buildPhaseListeners.set(state, list);
+         return Disposable.create(() => {
+            const idx = list.indexOf(listener);
+            if (idx >= 0) {
+               list.splice(idx, 1);
+            }
+         });
+      },
+      fireBuildPhase(state: DocumentState, built: LangiumDocument[], cancelToken?: CancellationToken) {
+         const token =
+            cancelToken ??
+            ({
+               isCancellationRequested: false,
+               onCancellationRequested: () => Disposable.create(() => undefined)
+            } as CancellationToken);
+         for (const listener of buildPhaseListeners.get(state) ?? []) {
+            reraise(listener(built, token));
+         }
+      },
       gateNextWaitUntil(): StubWaitUntilGate {
          let release: (() => void) | undefined;
          const entry = {
@@ -224,15 +340,14 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
       build() {
          return notSupported('build');
       },
-      onBuildPhase() {
-         return notSupported('onBuildPhase');
-      },
       resetToState() {
          return notSupported('resetToState');
       },
       reset() {
          phaseListeners.clear();
+         deliveredListeners.clear();
          onUpdateListeners.length = 0;
+         buildEndedListeners.length = 0;
          gates.length = 0;
          updateCalls.length = 0;
          waitUntilCalls.length = 0;