@hydranium/core 1.0.0-next.11 → 1.0.0-next.112

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

@@ -11,11 +11,12 @@ import {
    type CanonicalUri,
    type CloseModelArgs,
    ConflictError,
+   isSnapshotVersion,
+   defineMessage,
    Logger,
    type MaybeObservableValue,
    type MaybePromise,
    ObservableValue,
-   type TransferDiagnostic,
    type TransferElement,
    type OpenModelArgs,
    type Tracer,
@@ -23,6 +24,7 @@ import {
    type TransferUpdateArgs
 } from '@hydranium/protocol';
 import { type AstNode, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
 import { ReentrantWriteLockError, isInsideWriteLock } from '../workspace/write-lock-scope.js';
 import { type CancellationToken, type Disposable } from 'vscode-languageserver';
@@ -34,6 +36,23 @@ import { labelPhaseListener } from '../document-builder/labeled-phase-listener.j
 import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
 import { type ServerSharedServices } from '../module.js';
 
+/**
+ * The undo-stack entry for a server-authored write pushed to the editor.
+ *
+ * **A user-facing LABEL, not a log string**, which is easy to miss because it
+ * travels as an options field rather than as a message: LSP specifies
+ * `ApplyWorkspaceEditParams.label` as "presented in the user interface for
+ * example on an undo stack to undo the workspace edit". So a user who edits
+ * through a form or drags a diagram node reads this in their editor's undo menu
+ * — which is why it is rendered like any other message the server sends rather
+ * than left as the English literal it was.
+ *
+ * Parameterless deliberately. The obvious improvement is to name the document,
+ * and it is the wrong one: an undo menu is already grouped under the file, so
+ * the URI would be noise in the one place it is redundant.
+ */
+export const MODEL_UPDATE_EDIT = defineMessage('hydranium/core/model-update-edit', 'Update Model');
+
 /** Max time {@link ModelService.settleSave} waits for the build to settle and the sync chain to drain. */
 const SAVE_SETTLE_TIMEOUT_MS = 10_000;
 
@@ -115,6 +134,10 @@ export interface ModelServiceOptions extends LogNameOptions {
 }
 
 /**
+ * The seam every non-LSP head talks to: the data server, the GLSP head and an
+ * adopter's own services reach documents through this slot rather than through
+ * the workspace stores.
+ *
  * In-process facade over the framework's document plumbing
  * (`HydraniumTextDocuments`, `LangiumDocuments`,
  * `DocumentBuilder`, `WritableFileSystemProvider`). Owns the
@@ -173,18 +196,89 @@ export interface ModelServiceOptions extends LogNameOptions {
  * by URI happens here so consumers can subscribe per-document without
  * implementing the URI gate at each callsite.
  *
+ * **Two families, and the distinction matters more than the names suggest.**
+ * `waitFor*` is a pure wait — it never triggers a build, so a caller waiting on
+ * a document no build has touched waits until something else builds it.
+ * `ensureDocumentState` and the phase shorthands over it *dispatch*: warm
+ * documents are awaited, cold ones are built.
+ *
+ * **Diagnostics are typed `never` below `Validated`.** Validation is the last
+ * phase, so at any earlier landmark the array either is not yet computed or
+ * still holds the previous build's, and reading it would take stale results
+ * for fresh ones. A caller that needs diagnostics asks for {@link validated}.
+ *
+ * What the `never` buys, exactly: reading a field off an element is a compile
+ * error, and nothing can be appended. It does NOT stop a caller assigning an
+ * element to a typed variable, because `never` is assignable to everything — so
+ * this is a guard against reaching for diagnostics by accident, not a seal
+ * against doing it deliberately.
+ *
+ * The waits resolve at or ABOVE their target, so an already-validated document
+ * does carry usable diagnostics and the `never` over-forbids there. That
+ * direction is the safe one: the alternative permits stale reads silently. A
+ * member taking a phase as a PARAMETER cannot judge statically and so returns
+ * `TDiagnostic`, leaving the choice to the caller.
+ *
  * **Generic parameters.**
  * - `TAst` — the AST root type each consumer expects on the returned
  *   {@link AstDocument}. Constrained to {@link AstNode}.
- * - `TDiagnostic` — wire diagnostic shape used by the injected
- *   `TransferEncoder`. Defaults to {@link TransferDiagnostic}.
+ * - `TDiagnostic` — the AST-layer diagnostic: whatever the build left on
+ *   `LangiumDocument.diagnostics`, carried through on the returned
+ *   {@link AstDocument}. Defaults to {@link AstDiagnostic}.
+ *   **Not the `TransferEncoder`'s parameter of the same name**, which is
+ *   that encoder's OUTPUT and so names the wire shape. This one names its
+ *   input, and an adopter binds the two to different types.
  * - `TTransfer` — transfer-model root accepted by `update` / `save`
  *   args. Constrained to {@link TransferElement}. Defaults to the
  *   structural base.
  */
-export class ModelService<
+export interface ModelService<
+   TAst extends AstNode,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
+   TTransfer extends TransferElement = TransferElement
+> {
+   /**
+    * Resolves once the workspace has been initialised and its first build has
+    * completed — the gate every read should wait behind, since a document
+    * queried before it may be unbuilt and reach no phase.
+    *
+    * A property rather than a method, matching `ProjectManager.ready` and
+    * Langium's `WorkspaceManager.ready`. An implementation needing a stricter
+    * gate supplies a Promise that awaits its own concern as well.
+    */
+   readonly ready: Promise<void>;
+
+   // Pure waits — never trigger a build.
+   waitForDocumentState(uri: string, state: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   waitForBuilderState(state: DocumentState, cancelToken?: CancellationToken): Promise<void>;
+
+   // Wait if warm, build if cold.
+   ensureDocumentState(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   rebuild(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   open(args: OpenModelArgs): Promise<Disposable>;
+   close(args: CloseModelArgs): Promise<void>;
+   isOpen(uri: string): boolean;
+   snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined;
+   getDocument(uri: string): LangiumDocument | undefined;
+
+   onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onModelSaved(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+}
+
+export class DefaultModelService<
    TAst extends AstNode,
-   TDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    /**
     * Structured payload accepted by `update` / `save`. Constrained to
     * {@link TransferElement} — the minimal `{ readonly $type: string }`
@@ -195,7 +289,7 @@ export class ModelService<
     * integrity service) that pass AST roots remain compatible.
     */
    TTransfer extends TransferElement = TransferElement
-> {
+> implements ModelService<TAst, TDiagnostic, TTransfer> {
    protected readonly tracer: Tracer;
    /**
     * The single document-identity seam (`services.workspace.DocumentUriPolicy`),
@@ -329,8 +423,12 @@ export class ModelService<
     * {@link waitForDocumentState} for the common "wait until content is stable"
     * case (e.g. settling a save). Pure wait — does not trigger a build.
     */
-   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      return this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken);
+   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
+      return (await this.waitForDocumentStateCanonical(
+         this.uriPolicy.canonicalUri(uri),
+         IntegrityService.SettledState,
+         cancelToken
+      )) as AstDocument<TAst, never>;
    }
 
    /**
@@ -484,11 +582,19 @@ export class ModelService<
     *
     * Phase invariants encoded in the return type:
     * - `parsed` / `linked` / `settled` / `indexed` return
-    *   `AstDocument<TAst, never>` — diagnostics array is empty by phase
-    *   contract.
+    *   `AstDocument<TAst, never>` — no diagnostics have been computed at
+    *   those phases.
     * - `validated` returns `AstDocument<TAst, TDiagnostic>` — diagnostics
     *   are populated.
     *
+    * **The `never` is enforced, not merely declared.** The wait underneath
+    * resolves at or ABOVE the requested state, so a document something else
+    * already carried past `Validated` would otherwise come back from
+    * `settled()` carrying a full diagnostics array typed `never`; these four
+    * strip it. An empty array here therefore means "this read does not report
+    * diagnostics", never "this document is clean" — call {@link validated}
+    * when the answer has to mean the second.
+    *
     * `settled` is the integrity-overlay name for "all integrity rules
     * have fired"; it maps to {@link IntegrityService.SettledState} (which
     * equals `DocumentState.IndexedReferences`), but the dedicated method
@@ -496,19 +602,19 @@ export class ModelService<
     * ever moves.
     */
    async parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken));
    }
 
    async linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.Linked, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.Linked, cancelToken));
    }
 
    async settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken));
    }
 
    async indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken));
    }
 
    async validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
@@ -596,22 +702,44 @@ export class ModelService<
       const run = async <T>(stage: string, fn: () => MaybePromise<T>): Promise<T> => (session ? session.scope(stage, fn) : fn());
       // Open WITH the new text so a cold URI (no open editor, no file on disk) is
       // created from the payload rather than read from the filesystem — `update`
-      // is an upsert. For an already-open document `open` refreshes content (the
-      // text is ignored on that branch), so existing-document behaviour is
-      // unchanged. `version` is intentionally NOT forwarded to `open`: a cold
-      // create stays at its initial version, so a based-on-`version` update of a
-      // not-yet-existing document still trips the conflict gate below.
+      // is an upsert. For an already-open document `open` only attaches the
+      // client (the text is ignored on that branch), and the actual update is
+      // `AstDocumentManager.update`'s. `version` is intentionally NOT
+      // forwarded to `open`, so a cold create stays at its initial version
+      // rather than adopting a number the caller chose.
+      //
+      // The gate reads the version and decides BEFORE the open, and both halves
+      // of that matter.
+      //
+      // Reading first, because for a document no client holds open the open
+      // assigns the shared version from the INCOMING text, so a version read
+      // afterwards has already absorbed the caller's own write. Gating on it
+      // rejects every modifying write to a closed document, comparing the
+      // caller's `basedOn` against a number the caller itself produced — and a
+      // serialised round-trip that is not byte-identical to the stored text is
+      // enough to trigger that. Reading first keeps both cases the gate exists
+      // for: an unknown URI answers 0, so a based-on-version update of a
+      // not-yet-existing document still trips it, and a genuine conflict still
+      // trips it, another writer having advanced the sequence past the version
+      // the caller read.
+      //
+      // Deciding first, because the open is a mutation and `update` is an
+      // upsert: for a cold URI it installs the payload in the shared text store
+      // and records a hold for the writing client. Throwing after it hands the
+      // caller its rejection while the server keeps the refused text — and the
+      // hold outlives the call, because a client whose write failed has no
+      // reason to close a document it never asked to open. Serialisation is
+      // held back too; it is the adopter's code and need not be side-effect
+      // free.
+      const currentVersion = this.services.workspace.TextDocuments.version(uri);
+      if (isSnapshotVersion(args.basedOn) && currentVersion !== args.basedOn) {
+         // Distinct from the post-build "superseded" debug line below: this is a
+         // based-on-stale rejection (the write never applies), not two writes racing.
+         this.tracer.debug(`Conflict on ${uri}: based-on v${args.basedOn} stale, server at v${currentVersion}`);
+         throw new ConflictError(uri, args.basedOn, currentVersion);
+      }
       const text = await run('serialize', () => this.modelToText(uri, args.model, cancelToken));
       await run('open', () => this.open({ uri, clientId: args.clientId, text }));
-      if (args.baseVersion !== undefined) {
-         const current = this.services.workspace.TextDocuments.version(uri);
-         if (current !== args.baseVersion) {
-            // Distinct from the post-build "superseded" debug line below: this is a
-            // based-on-stale rejection (the write never applies), not two writes racing.
-            this.tracer.debug(`Conflict on ${uri}: based-on v${args.baseVersion} stale, server at v${current}`);
-            throw new ConflictError(uri, args.baseVersion, current);
-         }
-      }
       const appliedVersion = await run('apply', () => this.services.workspace.AstDocumentManager.update(uri, text, args.clientId));
       // Dispatch through the public `rebuild` (which re-canonicalizes the already-
       // canonical `uri` once, idempotently) rather than `rebuildCanonical`, so an
@@ -733,6 +861,31 @@ export class ModelService<
       return this.services.workspace.AstDocumentManager.isOpen(uri);
    }
 
+   /**
+    * Snapshot of `uri` as it stands RIGHT NOW — the synchronous sibling of the
+    * phase reads, which all wait. `undefined` when no document is registered.
+    *
+    * **This is what a writer wants, and {@link getDocument} is not.** The
+    * envelope's `version` is copied by value at projection time, so it cannot
+    * move afterwards; a version read off the live document at write time is
+    * whatever the server is at *now*, which is the number an optimistic gate is
+    * about to compare it against.
+    *
+    * Diagnostics only from a document that has reached `Validated`, and an
+    * empty array otherwise. Unlike the phase reads this one names no phase, so
+    * the state it finds is the only thing that can say whether the array
+    * describes the content being handed back or whatever an earlier build left.
+    * A caller that needs them unconditionally waits, via {@link validated}.
+    */
+   snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined {
+      const document = this.getDocument(uri);
+      if (!document) {
+         return undefined;
+      }
+      const envelope = AstDocument.from<TAst, TDiagnostic>(document);
+      return document.state >= DocumentState.Validated ? envelope : this.withoutDiagnostics(envelope);
+   }
+
    /**
     * The built {@link LangiumDocument} for `uri`, looked up by canonical identity —
     * the synchronous, phase-agnostic sibling of {@link ensureDocumentState} /
@@ -741,6 +894,13 @@ export class ModelService<
     * into `LangiumDocuments` directly: a symlinked / `..` / case-divergent URI
     * still resolves to the one document the build keys by its real path. Returns
     * `undefined` if no document is registered for `uri`.
+    *
+    * **Live, so do not take a based-on version off it.** `textDocument` is the
+    * store's own object rather than a copy, so `.version` read here answers for
+    * the moment of the READ, not the moment of the earlier content — pass it to
+    * a write and the server compares its current version against itself, the
+    * gate passes unconditionally, and a concurrent edit is overwritten with
+    * nothing logged. Use {@link snapshot} for that, or a phase read.
     */
    getDocument(uri: string): LangiumDocument | undefined {
       return this.services.workspace.AstDocumentManager.getDocument(uri);
@@ -834,17 +994,17 @@ export class ModelService<
     *
     * The signal is "a known client other than the language client authored this
     * version **and** the URI was in the last build's changed set
-    * (`isDirectChange`)". A framework-internal rebuild reports no author
+    * (`isTriggeringEdit`)". A framework-internal rebuild reports no author
     * (`getAuthor` → `undefined`), so it fails `hasKnownAuthor` without comparing
     * against a sentinel. This is NOT redundant with content/registration — it
     * distinguishes "client edited" from "framework rebuilt", which neither the
-    * shadow nor `isDirectChange` alone can.
+    * shadow nor `isTriggeringEdit` alone can.
     */
    protected isNonLanguageClientEdit(document: LangiumDocument): boolean {
       const documents = this.services.workspace.AstDocumentManager;
       const author = documents.getAuthor(document);
       const hasKnownAuthor = !!author && author !== LANGUAGE_CLIENT_ID;
-      return hasKnownAuthor && documents.isDirectChange(document.textDocument.uri);
+      return hasKnownAuthor && documents.isTriggeringEdit(document.textDocument.uri);
    }
 
    /**
@@ -878,13 +1038,26 @@ export class ModelService<
       this.syncChains.set(uri, chain);
    }
 
+   /**
+    * The undo-stack label for a server-authored write, in the locale the server
+    * was handed at init.
+    *
+    * One method rather than the literal at each `applyEdit`, because the two
+    * call sites are the same edit — a push and its full-replace retry — and an
+    * undo menu showing two different words for one operation would read as two
+    * operations.
+    */
+   protected editLabel(): string {
+      return this.services.MessageRenderer.renderMessage(MODEL_UPDATE_EDIT);
+   }
+
    protected async drainSyncQueue(uri: string): Promise<void> {
       const uriLogger = this.tracer.withUri(uri);
       while (this.pendingSync.has(uri)) {
          const text = this.pendingSync.get(uri)!;
          this.pendingSync.delete(uri);
          try {
-            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
             if (result?.applied === false && !this.pendingSync.has(uri)) {
                // The push is addressed at the client's LAST DECLARED VERSION, so a
                // rejection normally means the client's buffer moved while the
@@ -905,7 +1078,7 @@ export class ModelService<
                // queued — best-effort, since a settle arriving later simply pushes
                // after this and still wins.
                uriLogger.warn(`Language client rejected applyEdit at its declared version — re-pushing a full replace`);
-               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
                if (result?.applied === false) {
                   uriLogger.warn(`Language client rejected the full-replace retry too — client content is stale`);
                }
@@ -1013,7 +1186,47 @@ export class ModelService<
          return model;
       }
       const rewritten = await this.rewriteModel(uri, model, cancelToken);
-      return this.serialize(uri, rewritten);
+      const target = UriUtils.toUri(uri);
+      const trivia = this.services.ServiceRegistry?.getServices(target)?.trivia?.TriviaService;
+      // Extracted BEFORE serializing, so it reads the document the write is
+      // about to replace rather than whatever a concurrent build left behind.
+      let document = this.services.workspace.LangiumDocuments.getDocument(target);
+      if (trivia !== undefined && document === undefined) {
+         const source = await this.textToTakeTriviaFrom(uri, target);
+         if (source !== undefined) {
+            document = this.services.workspace.LangiumDocumentFactory.fromString(source, target);
+         }
+      }
+      const extracted = trivia !== undefined && document !== undefined ? trivia.extract(document) : undefined;
+      const serialized = await this.serialize(uri, rewritten);
+      return extracted === undefined ? serialized : trivia!.apply(serialized, extracted, target);
+   }
+
+   /**
+    * The text a write into an unloaded document should take its trivia from —
+    * the open editor's if one holds it, the file's otherwise, and `undefined`
+    * when neither can supply it.
+    *
+    * **A read that fails answers `undefined` rather than throwing.** `getDocument`
+    * is a store read, so an ordinary create answers nothing here and must still
+    * write; letting a permission error or a path that turned into a directory
+    * escape would fail the user's write instead, having found nothing to preserve
+    * in a file the write is about to replace anyway. Losing the comments is
+    * recoverable, and traced; losing the write is neither.
+    */
+   protected async textToTakeTriviaFrom(uri: string, target: URI): Promise<string | undefined> {
+      const open = this.services.workspace.TextDocuments.get(uri)?.getText();
+      if (open !== undefined) {
+         return open;
+      }
+      const fileSystem = this.services.workspace.FileSystemProvider;
+      try {
+         return (await fileSystem.exists(target)) ? await fileSystem.readFile(target) : undefined;
+      } catch (err: unknown) {
+         const detail = err instanceof Error ? err.message : String(err);
+         this.tracer.withUri(uri).debug(`Could not read the file to take trivia from; writing as emitted. ${detail}`);
+         return undefined;
+      }
    }
 
    /**
@@ -1048,4 +1261,23 @@ export class ModelService<
          ? AstDocument.from<TAst, TDiagnostic>(document)
          : AstDocument.create<TAst, TDiagnostic>(uri.toString(), 0, undefined as unknown as TAst, []);
    }
+
+   /**
+    * The same envelope with no diagnostics, for a read that names a phase below
+    * `Validated`.
+    *
+    * Langium fills `LangiumDocument.diagnostics` from inside `validateDocument`
+    * and from nowhere else, so below that phase the array holds whatever an
+    * EARLIER build left — a verdict about text the document may no longer have.
+    * The wait underneath resolves at or above the phase asked for, so a document
+    * something else carried past `Validated` would otherwise hand a full array
+    * back from `parsed()`.
+    *
+    * A copy rather than a clear: the envelope is freshly built here, but
+    * {@link toAstDocument} is overridable and an adopter's version may return
+    * one it also keeps.
+    */
+   protected withoutDiagnostics(document: AstDocument<TAst, TDiagnostic>): AstDocument<TAst, never> {
+      return { ...document, diagnostics: [] };
+   }
 }