@hydranium/core 1.0.0-next.135 → 1.0.0-next.140

package/src/langium/model-service/model-service.ts

@@ -87,9 +87,11 @@ export interface ModelServiceOptions extends LogNameOptions {
     * {@link ReentrantWriteLockError} rather than hanging, wherever a host
     * installs a write-lock scope tracker (`@hydranium/core/node` does at entry
     * load; see {@link isInsideWriteLock}). Setting `false` is the escape hatch
-    * for an adopter whose reentrant shape is unavoidable — nothing acquires the
-    * lock then, so there is nothing to be reentrant about; prefer it over
-    * unserialised builds only in that case.
+    * for an adopter whose reentrant shape is unavoidable: the facade's own
+    * build then takes no lock, so it cannot cancel the holder it runs inside.
+    * The wait after it can still hang there, because a document no build will
+    * carry is re-queued through the lock, and that re-queue waits for the
+    * holder to end. Prefer `false` over serialised builds only in that case.
     *
     * Accepts a {@link MaybeObservableValue} so it can be bound to a setting and
     * flipped without a restart.
@@ -134,15 +136,15 @@ export interface ModelServiceOptions extends LogNameOptions {
  * **Read-latest supersession**
  *
  * A session's default `update` and `save` use Langium's per-URI
- * `DocumentBuilder.waitUntil` to wait for the integrity-settled landmark
- * ({@link IntegrityService.SettledState}), then read the post-build state. Concurrent
- * in-process callers on the same URI all see the latest post-build
- * snapshot — none deadlock waiting for a specific version's settled
- * event. Adopters wanting strict version-matched semantics (resolve
- * with vN's snapshot specifically, log "vN superseded by vM at vN+1")
- * override `DefaultClientSession.updateDocument` to attach a phase-listener
- * with explicit version checks; the framework default doesn't need it for
- * safety.
+ * `DocumentBuilder.waitUntil` to wait for `Validated` (the integrity-settled
+ * landmark {@link IntegrityService.SettledState} when rebuilds do not
+ * validate), then read the post-build state. Concurrent in-process callers
+ * on the same URI all see the latest post-build snapshot — none deadlock
+ * waiting for a specific version's settled event. Adopters wanting strict
+ * version-matched semantics (resolve with vN's snapshot specifically, log
+ * "vN superseded by vM at vN+1") override
+ * `DefaultClientSession.updateDocument` to attach a phase-listener with
+ * explicit version checks; the framework default doesn't need it for safety.
  *
  * **Returns AST snapshots, not wire envelopes**
  *
@@ -546,8 +548,8 @@ export class DefaultModelService<
          // writing back through this facade — would cancel its own enclosing
          // build and then likely stall in the phase wait below. The check is
          // gated on `serializeBuilds` deliberately, because acquiring the lock IS
-         // the hazard: with serialisation off there is nothing to be reentrant
-         // about, which makes the existing opt-out the guard's opt-out too.
+         // the hazard: with serialisation off the build takes no lock, which
+         // makes the existing opt-out the guard's opt-out too.
          // Detection needs async-context propagation, so it is inert until a host
          // installs a tracker (`@hydranium/core/node` does) — see
          // `isInsideWriteLock`.
@@ -976,9 +978,8 @@ export class DefaultModelService<
     * `HydraniumTextDocuments` — single listener registration shared with
     * any direct `HydraniumTextDocuments.onUpdate` subscriber, so the same
     * underlying `DocumentBuilder.onDocumentPhase` listener serves both
-    * call paths. `sourceClientId` is resolved from the multi-client
-    * author history; reason discrimination follows the manager's own
-    * `lastUpdate` snapshot (see `AstDocumentManager.onUpdate`).
+    * call paths. The event's reason, source and cause are
+    * {@link AstDocumentManager.attributeUpdate}'s.
     */
    onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable {
       return this.services.workspace.AstDocumentManager.onUpdate(uri, listener as never);

package/src/langium/workspace/write-lock-scope.ts

@@ -72,8 +72,9 @@ export function isInsideWriteLock(): boolean {
  * Named rather than a bare `Error` because the remedy is specific and worth
  * pointing at: either move the write out of the build (integrity rules that
  * persist repairs should write through `FileSystemProvider.writeFile`, which
- * takes no lock), or set `ModelServiceOptions.serializeBuilds: false` to accept
- * unserialised builds in exchange for the reentrancy.
+ * takes no lock), or set `ModelServiceOptions.serializeBuilds: false`, which
+ * keeps the facade's build from cancelling the holder but not its wait from
+ * stalling on a document that needs a re-queue.
  */
 export class ReentrantWriteLockError extends Error {
    constructor(readonly uri: string) {

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

@@ -14,8 +14,10 @@ import {
    AstDocument,
    type AstDocumentManager,
    type AstDocumentUpdatedEvent,
+   type UpdateAttribution,
    type WritableFileSystemProvider
 } from '../documents/ast-document-manager.js';
+import { UNKNOWN_CLIENT_ID } from '../documents/client-ids.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';
@@ -48,7 +50,17 @@ import type { StubLangiumDocuments } from './stub-langium-documents.js';
  */
 export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic> extends Pick<
    AstDocumentManager<TAst, TDiagnostic>,
-   'open' | 'close' | 'isOpen' | 'update' | 'save' | 'onUpdate' | 'onSave' | 'onClientClosed' | 'getAuthor' | 'getDocument'
+   | 'open'
+   | 'close'
+   | 'isOpen'
+   | 'update'
+   | 'save'
+   | 'onUpdate'
+   | 'onSave'
+   | 'onClientClosed'
+   | 'getAuthor'
+   | 'getDocument'
+   | 'attributeUpdate'
 > {
    readonly openClients: Map<string, Set<string>>;
 
@@ -201,6 +213,14 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic ext
       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).

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

@@ -17,6 +17,7 @@ import {
    type URI
 } from '@hydranium/langium';
 import { type CancellationToken, Disposable } from 'vscode-languageserver';
+import { type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
 
 /** Recorded call to a stubbed {@link DocumentBuilder} method. */
 export interface RecordedBuilderCall<TArgs extends unknown[]> {
@@ -46,8 +47,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.
@@ -71,10 +71,10 @@ export interface StubWaitUntilGate {
  * 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'> {
    /**
     * Single-overload stub of {@link DocumentBuilder.waitUntil}. Real has
     * two overloads (`(state, cancelToken?): Promise<void>` and
@@ -88,9 +88,10 @@ 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 `cancelToken` is 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. */
@@ -140,6 +141,7 @@ function reraise(result: unknown): void {
  */
 export function makeStubDocumentBuilder(): 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 gates: Array<{ take(release: () => void): void }> = [];
@@ -150,6 +152,9 @@ 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'] } },
       get updateCalls() {
          return updateCalls;
       },
@@ -195,9 +200,30 @@ 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;
          for (const listener of listeners) {
             reraise(listener(document, token));
          }
+         if (!token.isCancellationRequested) {
+            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()) {
@@ -261,6 +287,7 @@ export function makeStubDocumentBuilder(): StubDocumentBuilder {
       },
       reset() {
          phaseListeners.clear();
+         deliveredListeners.clear();
          onUpdateListeners.length = 0;
          gates.length = 0;
          updateCalls.length = 0;