@hydranium/core 1.0.0-next.39 → 1.0.0-next.391

package/src/langium/workspace/file-system-provider.ts

@@ -9,17 +9,94 @@
 
 import { type Tracer } from '@hydranium/protocol';
 import { EmptyFileSystemProvider } from '@hydranium/langium';
-import type { URI } from '@hydranium/langium';
-import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import type { FileSystemNode, FileSystemProvider, URI } from '@hydranium/langium';
+import { type SelfSaveRegistry } from './self-save-registry.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
-import { serveVirtualDocument } from './virtual-document.js';
 
 /**
- * Empty-filesystem default {@link WritableFileSystemProvider}. For
- * in-memory / browser / test / CLI hosts that don't have a real filesystem.
- * All writes are no-ops. This is the portable `.`-entry default; the
- * Node-backed `DefaultFileSystemProvider`
+ * File-system provider extension that supports writes. Langium's standard
+ * {@link FileSystemProvider} is read-only; `AstDocumentManager` needs to persist
+ * saves, so consumers wire in a provider that implements this superset.
+ *
+ * Implementations may optionally hold a reference to a
+ * {@link SelfSaveRegistry} so they can record their own write mtimes and
+ * help downstream file-watchers suppress echo events for those writes.
+ * The framework's `DefaultFileSystemProvider` reads it from
+ * `services.workspace.SelfSaveRegistry`; alternative implementations can do
+ * the same or leave the field unset.
+ */
+export interface WritableFileSystemProvider extends FileSystemProvider {
+   writeFile(uri: URI, content: string): Promise<void>;
+   /**
+    * Remove the file at `uri`: the name the URI gives, never the file a
+    * symlink there points at, leaving a parent directory it empties in place.
+    * A no-op when nothing is there; a directory is refused.
+    */
+   deleteFile(uri: URI): Promise<void>;
+   /**
+    * Last-modified time (ms) of the file at `uri`, or `undefined` if it can't
+    * be determined (missing file, or a provider with no disk — in-memory /
+    * browser). Optional: the only consumer is self-save echo suppression
+    * (`didChangeWatchedFiles`), which simply lets a change through when the
+    * mtime is unavailable. Distinct from Langium's `stat` (whose
+    * `FileSystemNode` carries no mtime). Keeping disk access on the provider
+    * seam is what lets the LSP update handler avoid a direct `node:fs` import.
+    */
+   mtimeMs?(uri: URI): Promise<number | undefined>;
+   /**
+    * Resolve `uri` to its real on-disk identity (symlinks collapsed, `..`/`.`
+    * walked, case-folded on case-insensitive filesystems), or `undefined` *iff
+    * the filesystem knows the path is absent*. The single source of the
+    * "nothing loadable here" signal `RealpathDocumentUriPolicy` turns into
+    * the synthetic-placeholder branch of `getOrCreateDocument`.
+    *
+    * Contract for implementers:
+    * - A `file:`-backed provider returns the resolved URI when the file exists,
+    *   and `undefined` when it cannot resolve the path (missing / unreadable).
+    * - A non-`file:` URI (or any URI the provider cannot stat) passes through
+    *   **unchanged** — it is treated as present, never reported absent.
+    * - A provider with no disk to check (in-memory / browser / empty) simply
+    *   omits this method; the framework's `FileSystemProviderRegistry` then
+    *   returns the URI unchanged, and `RealpathDocumentUriPolicy` answers as
+    *   the syntactic `DefaultDocumentUriPolicy` does.
+    *
+    * Synchronous (a `realpath` is a kernel-cached syscall) and optional — the
+    * only consumers are the document-identity policy's `canonicalUri`/`loadUri`.
+    * Keeping the syscall on the provider seam is what lets the policy stay
+    * browser-neutral (no `node:fs` import).
+    */
+   realpath?(uri: URI): URI | undefined;
+   /**
+    * The path `uri` names with every link followed, a link to nothing
+    * included, so that `RealpathDocumentUriPolicy.canonicalUri` keys a file
+    * reached through a link the same before it exists and once it does.
+    * Where {@link realpath} resolves, the same answer; otherwise what is
+    * missing joined as spelled under the real path of what exists. Optional,
+    * as `realpath` is: without it an absent path keys by its syntactic form.
+    */
+   resolveLinks?(uri: URI): URI;
+   /**
+    * Whether a file is at `uri`, where a miss counts only once it has lasted:
+    * on a disk where replacing a file can hide its name for a moment, a single
+    * {@link exists} cannot tell that from a deletion. Ask this before acting on
+    * a miss as a deletion; a caller expecting a miss, such as a create, asks
+    * {@link exists}, since here a real miss costs the whole wait.
+    *
+    * Optional: a provider whose misses are always final omits it, and a caller
+    * takes the answer of {@link exists} as settled.
+    */
+   existsSettled?(uri: URI): Promise<boolean>;
+   /** Registry the provider records its own writes against. Optional — providers without watcher integration may omit. */
+   readonly selfSaveRegistry?: SelfSaveRegistry;
+}
+
+/**
+ * Empty-filesystem {@link WritableFileSystemProvider}. For browser / test / CLI
+ * hosts that don't have a real filesystem. All writes and deletes are no-ops.
+ * On the portable `.` entry it is the
+ * {@link FileSystemProviderRegistry.host} when `context.fileSystemProvider`
+ * gives no writable provider; the Node-backed `DefaultFileSystemProvider`
  * lives in `@hydranium/core/node` (it pulls `node:fs`).
  */
 export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider implements WritableFileSystemProvider {
@@ -37,16 +114,181 @@ export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider impl
       // no-op
    }
 
-   // Serve virtual documents from the registered document (there is no disk to
-   // read); delegate everything else to the empty base (which throws). The
-   // base declares these param-less, so the param is optional here.
-   override readFile(uri?: URI): Promise<string> {
-      const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
-      return served !== undefined ? Promise.resolve(served) : super.readFile();
+   async deleteFile(_uri: URI): Promise<void> {
+      // no-op
+   }
+
+   // `async` so the base's refusal becomes a rejection: it throws
+   // SYNCHRONOUSLY from a method declared to return a promise, and a
+   // synchronous throw escapes the promise chain — `.catch()` never attaches
+   // and `Promise.all` dies while its argument array is still being built, so
+   // a caller reading several URIs cannot handle the miss it asked about. The
+   // base declares `readFile` and `readBinary` param-less, so the param is
+   // optional there.
+   override async readFile(_uri?: URI): Promise<string> {
+      return super.readFile();
+   }
+
+   override async readBinary(_uri?: URI): Promise<Uint8Array> {
+      return super.readBinary();
+   }
+
+   override async stat(uri: URI): Promise<FileSystemNode> {
+      return super.stat(uri);
+   }
+}
+
+/**
+ * The provider bound on `workspace.FileSystemProvider`: it dispatches each call
+ * by the URI's scheme to the provider registered for it in the shared
+ * `fileSystemProviders` group, and to the {@link host} for any scheme without
+ * one.
+ *
+ * So one provider answers for each scheme, and a host's provider needs to know
+ * only its own: the framework registers `virtual:` there, and an adopter adds a
+ * scheme by contributing to the group. The host takes every unclaimed scheme
+ * rather than `file:` alone, which keeps an in-memory workspace under `memory:`
+ * or any other scheme on the host's provider.
+ *
+ * `THost` types the host, so an adopter whose own provider has more members
+ * than the base declares the slot as `FileSystemProviderRegistry<MyProvider>`,
+ * binds a {@link DefaultFileSystemProviderRegistry} with that host, and reads
+ * those members through `services.workspace.FileSystemProvider.host`.
+ */
+export interface FileSystemProviderRegistry<
+   THost extends WritableFileSystemProvider = WritableFileSystemProvider
+> extends WritableFileSystemProvider {
+   /** The provider for every scheme no entry of `fileSystemProviders` claims. */
+   readonly host: THost;
+   /** The provider that answers for `uri`. */
+   providerFor(uri: URI): WritableFileSystemProvider;
+}
+
+/** Whether `provider` dispatches by scheme, as the provider bound on `workspace.FileSystemProvider` does. */
+export function isFileSystemProviderRegistry(provider: WritableFileSystemProvider): provider is FileSystemProviderRegistry {
+   return 'providerFor' in provider && typeof provider.providerFor === 'function';
+}
+
+/** Options for {@link DefaultFileSystemProviderRegistry}. */
+export interface FileSystemProviderRegistryOptions<
+   THost extends WritableFileSystemProvider = WritableFileSystemProvider
+> extends LogNameOptions {
+   /**
+    * The provider for every scheme no entry of `fileSystemProviders` claims.
+    * The framework passes the provider `context.fileSystemProvider` returns,
+    * or a {@link DefaultEmptyFileSystemProvider} when that is not writable.
+    */
+   host: THost;
+}
+
+/**
+ * The framework's {@link FileSystemProviderRegistry}.
+ *
+ * A directory is listed by the provider of its own scheme, so a workspace
+ * root's tree comes from that provider alone.
+ *
+ * `realpath`, `resolveLinks`, `mtimeMs` and `existsSettled` are always present
+ * and forward to the scheme's provider. Where that provider lacks one,
+ * `realpath` and `resolveLinks` return the URI unchanged, `mtimeMs` returns
+ * `undefined` and `existsSettled` answers as `exists`: the answers their
+ * callers already give a provider without them.
+ */
+export class DefaultFileSystemProviderRegistry<
+   THost extends WritableFileSystemProvider = WritableFileSystemProvider
+> implements FileSystemProviderRegistry<THost> {
+   readonly host: THost;
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal & { fileSystemProviders: Record<string, WritableFileSystemProvider> },
+      options: FileSystemProviderRegistryOptions<THost>
+   ) {
+      this.host = options.host;
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   /**
+    * The group is read per call, not in the constructor, so a registered
+    * provider is built on first use and may read slots that reach back to this
+    * one. Only an OWN key of the group counts: the DI container resolves any
+    * key found on the prototype chain, so a scheme such as `constructor` would
+    * otherwise dispatch to a function.
+    */
+   providerFor(uri: URI): WritableFileSystemProvider {
+      const providers = this.services.fileSystemProviders;
+      return Object.hasOwn(providers, uri.scheme) ? providers[uri.scheme] : this.host;
+   }
+
+   // The async methods are `async` so a provider that throws synchronously from
+   // one still rejects, for the reason `DefaultEmptyFileSystemProvider` gives.
+   async writeFile(uri: URI, content: string): Promise<void> {
+      return this.providerFor(uri).writeFile(uri, content);
+   }
+
+   async deleteFile(uri: URI): Promise<void> {
+      return this.providerFor(uri).deleteFile(uri);
+   }
+
+   async mtimeMs(uri: URI): Promise<number | undefined> {
+      return this.providerFor(uri).mtimeMs?.(uri);
+   }
+
+   realpath(uri: URI): URI | undefined {
+      const provider = this.providerFor(uri);
+      return provider.realpath ? provider.realpath(uri) : uri;
+   }
+
+   resolveLinks(uri: URI): URI {
+      const provider = this.providerFor(uri);
+      if (provider.resolveLinks) {
+         return provider.resolveLinks(uri);
+      }
+      // A provider with `realpath` alone still keys a present path by it.
+      return provider.realpath?.(uri) ?? uri;
+   }
+
+   async existsSettled(uri: URI): Promise<boolean> {
+      const provider = this.providerFor(uri);
+      return provider.existsSettled ? provider.existsSettled(uri) : provider.exists(uri);
+   }
+
+   async stat(uri: URI): Promise<FileSystemNode> {
+      return this.providerFor(uri).stat(uri);
+   }
+
+   statSync(uri: URI): FileSystemNode {
+      return this.providerFor(uri).statSync(uri);
+   }
+
+   async exists(uri: URI): Promise<boolean> {
+      return this.providerFor(uri).exists(uri);
+   }
+
+   existsSync(uri: URI): boolean {
+      return this.providerFor(uri).existsSync(uri);
+   }
+
+   async readBinary(uri: URI): Promise<Uint8Array> {
+      return this.providerFor(uri).readBinary(uri);
+   }
+
+   readBinarySync(uri: URI): Uint8Array {
+      return this.providerFor(uri).readBinarySync(uri);
+   }
+
+   async readFile(uri: URI): Promise<string> {
+      return this.providerFor(uri).readFile(uri);
+   }
+
+   readFileSync(uri: URI): string {
+      return this.providerFor(uri).readFileSync(uri);
+   }
+
+   async readDirectory(uri: URI): Promise<FileSystemNode[]> {
+      return this.providerFor(uri).readDirectory(uri);
    }
 
-   override readFileSync(uri?: URI): string {
-      const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
-      return served !== undefined ? served : super.readFileSync();
+   readDirectorySync(uri: URI): FileSystemNode[] {
+      return this.providerFor(uri).readDirectorySync(uri);
    }
 }

package/src/langium/workspace/hydranium-langium-document-factory.ts

@@ -9,13 +9,29 @@
 
 import {
    type AstNode,
+   type AstReflection,
    AstUtils,
    DefaultLangiumDocumentFactory,
+   DocumentState,
+   isAstNode,
+   isMultiReference,
    type LangiumDocument,
+   type Linker,
+   type MultiReference,
+   type Mutable,
    type ParseResult,
+   type Reference,
+   type ReferenceInfo,
    type URI
 } from '@hydranium/langium';
+import { type CancellationToken } from 'vscode-languageserver-protocol';
+import { type TextDocument } from 'vscode-languageserver-textdocument';
+import { STALE_VERSION } from '@hydranium/protocol';
+import { type ModelLedger } from '../../documents/model-ledger.js';
+import { type CstResidencyService } from '../residency/cst-residency-service.js';
+import { type VersionSyncService } from '../../documents/version-sync-service.js';
 import { type ExtendedServiceRegistry } from '../service-registry.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type Serializer } from '../serialization/serializer.js';
 
 /** Structural view of the per-language serializer slot on the resolved services. */
@@ -36,10 +52,18 @@ interface WithSerializer {
  * scope descriptions pointing at them, stay valid. A `fromString` document
  * already carries its source, so only `fromModel` needs help.
  *
+ * The first build grafts the CST of that text onto the model, as for a shed
+ * document, which gives every reference the `$refNode` the reference index
+ * needs. A model that does not pair node for node with its serialized text is
+ * re-parsed instead, and its nodes are replaced: from its file, or from the
+ * text it holds when no file is at its URI, since reading the URI would throw.
+ * While the document is open, the store's text wins.
+ *
  * Degrades to Langium's text-less `fromModel` when no serializer is bound for
- * the URI's language (the serializer throws or is absent) — the document still
- * works; only a re-read of it would yield empty text, which never happens for a
- * build-once virtual document.
+ * the URI's language (the serializer throws or is absent). Its first build
+ * re-reads it from the store or its file, replacing its nodes, as Langium
+ * does. With neither, it keeps its nodes but gets no CST, so its references
+ * stay out of the reference index and it is not relinked.
  *
  * Also links the model's container properties (`$container` /
  * `$containerProperty` / `$containerIndex`), which Langium's parser sets via
@@ -57,6 +81,24 @@ export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFacto
     */
    declare protected readonly serviceRegistry: ExtendedServiceRegistry;
 
+   /** A thunk: a version-sync service whose constructor reads this factory would otherwise be a cycle. */
+   protected readonly versionSyncService: () => VersionSyncService;
+   /** A thunk: a ledger whose constructor reads this factory would otherwise be a cycle. */
+   protected readonly modelLedger: () => ModelLedger;
+   /** A thunk: the residency service resolves `LangiumDocuments`, which is built with this factory. */
+   protected readonly cstResidency: () => CstResidencyService;
+   /** The code-built documents, which are re-read from the text they hold when no file is at their URI. */
+   protected readonly codeBuiltDocuments = new WeakSet<LangiumDocument>();
+   protected readonly astReflection: AstReflection;
+
+   constructor(services: ServerSharedServicesMinimal) {
+      super(services);
+      this.astReflection = services.AstReflection;
+      this.versionSyncService = () => services.workspace.VersionSyncService;
+      this.modelLedger = () => services.workspace.ModelLedger;
+      this.cstResidency = () => services.workspace.CstResidencyService;
+   }
+
    /**
     * Parse `text` for `uri` under the grammar `languageId` names, instead of
     * the one `uri` routes to.
@@ -87,12 +129,205 @@ export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFacto
       // Make the code-built AST as structurally complete as a parsed one — the
       // parser links containers, `fromModel` does not. In place (identity kept).
       AstUtils.linkContentToContainer(model, { deep: true });
+      // The parser fills in the defaults a model built in code may leave out.
+      // Filled before serializing, since a serializer may read them, and
+      // without them the model does not pair with the parse of its text.
+      for (const node of AstUtils.streamAst(model)) {
+         AstUtils.assignMandatoryProperties(this.astReflection, node);
+      }
       const text = this.serializeModel(model, uri);
       if (text === undefined) {
          return super.fromModel(model, uri);
       }
       const parseResult: ParseResult<T> = { value: model, parserErrors: [], lexerErrors: [] };
-      return this.createLangiumDocument<T>(parseResult, uri, undefined, text);
+      const document = this.createLangiumDocument<T>(parseResult, uri, undefined, text);
+      this.codeBuiltDocuments.add(document);
+      const linker = this.serviceRegistry.getServices(uri).references.Linker;
+      document.references = AstUtils.streamAst(model)
+         .flatMap(node => AstUtils.streamReferences(node))
+         .toArray()
+         .flatMap(info => this.rebuildReference(linker, info) ?? []);
+      return document;
+   }
+
+   /**
+    * Replace a code-set reference with one the linker built, holding the same
+    * target. A relink resets and the reference index reads only such
+    * references, and only those listed in `document.references`. The first
+    * build unlinks them before its link phase, which resolves and indexes them.
+    * The target is kept in the field Langium's references hold it in, so a
+    * linker whose references have no such field resolves it on first read.
+    * `undefined` when the reference has no slot to go back in.
+    */
+   protected rebuildReference(
+      linker: Linker,
+      { reference, container, property, index }: ReferenceInfo
+   ): Reference | MultiReference | undefined {
+      const owner: unknown = Reflect.get(container, property);
+      if (index !== undefined && !Array.isArray(owner)) {
+         return undefined;
+      }
+      let rebuilt: Reference | MultiReference;
+      if (isMultiReference(reference)) {
+         // Read through the field, as `items` would resolve a linker-built reference.
+         const items = '_items' in reference ? reference._items : reference.items;
+         const multi = linker.buildMultiReference(container, property, reference.$refNode, reference.$refText);
+         if ('_items' in multi) {
+            multi._items = Array.isArray(items) ? [...items] : undefined;
+         }
+         rebuilt = multi;
+      } else {
+         const target = '_ref' in reference ? reference._ref : reference.ref;
+         const single = linker.buildReference(container, property, reference.$refNode, reference.$refText);
+         if ('_ref' in single) {
+            single._ref = isAstNode(target) ? target : undefined;
+         }
+         rebuilt = single;
+      }
+      if (Array.isArray(owner) && index !== undefined) {
+         owner[index] = rebuilt;
+      } else {
+         Reflect.set(container, property, rebuilt);
+      }
+      return rebuilt;
+   }
+
+   protected override createLangiumDocument<T extends AstNode = AstNode>(
+      parseResult: ParseResult<T>,
+      uri: URI,
+      textDocument?: TextDocument,
+      text?: string
+   ): LangiumDocument<T> {
+      const document = super.createLangiumDocument(parseResult, uri, textDocument, text);
+      // Without `textDocument` Langium creates one at version 0 on first read,
+      // which needs a language for `uri` that a folder URI does not have.
+      const parsed = parseResult.value.$cstNode?.root.fullText ?? text ?? textDocument?.getText();
+      const version = this.versionOfParsedText(uri, parsed, textDocument?.version ?? 0);
+      // A `fromModel` root has no CST to hold its serialized text. Recorded, it
+      // is the text a build grafts a CST from, keeping the model's nodes.
+      this.versionSyncService().modelProduced(document, { version, text: parseResult.value.$cstNode ? undefined : text });
+      return document;
+   }
+
+   /**
+    * The version is read before the parse, for the same reason as in
+    * {@link update}: the text document is the store's, which an edit updates
+    * in place while the parse runs.
+    */
+   protected override async createAsync<T extends AstNode = AstNode>(
+      uri: URI,
+      content: string | TextDocument,
+      cancelToken: CancellationToken
+   ): Promise<LangiumDocument<T>> {
+      const version = typeof content === 'string' ? undefined : content.version;
+      const document = await super.createAsync<T>(uri, content, cancelToken);
+      if (version !== undefined) {
+         this.versionSyncService().modelProduced(document, { version });
+      }
+      return document;
+   }
+
+   /**
+    * The store's version is read before Langium's `update`, which reads the
+    * store's text before its first await: read after, it can belong to an
+    * edit that arrived while the parse ran.
+    *
+    * Reconciled with the store here rather than in a `Parsed` listener, which
+    * a cancel skips, leaving the root on the version of its earlier text.
+    */
+   override async update<T extends AstNode = AstNode>(
+      document: Mutable<LangiumDocument<T>>,
+      cancellationToken: CancellationToken
+   ): Promise<LangiumDocument<T>> {
+      // Langium keeps the AST when the CST's text equals the new text, but a
+      // shed document has no CST and would get new AST nodes, leaving its
+      // dependents on the old ones. Grafted only when the new text is the text
+      // the AST was parsed from, so an edit on disk or in the store is still
+      // re-parsed. Not `isCstShed`: the builder has already reset the document
+      // to `Changed`. A refused or diverged graft re-parses, and a build after
+      // this one relinks the dependents: this build has prepared its
+      // documents, and a reset now would drop their build state.
+      const root = document.parseResult.value;
+      const parsedFrom = root.$cstNode === undefined ? this.modelLedger().textOf(root) : undefined;
+      const codeBuilt = await this.codeBuiltSource(document);
+      if (parsedFrom !== undefined) {
+         const text =
+            codeBuilt?.text ??
+            this.textDocuments?.get(document.uri.toString())?.getText() ??
+            (await this.fileSystemProvider.readFile(document.uri));
+         if (text === parsedFrom) {
+            this.cstResidency().rehydrate(document);
+            if (root.$cstNode === undefined) {
+               this.versionSyncService().rebuildWhileCurrent(document);
+            }
+         }
+      }
+      const stored = codeBuilt === undefined ? this.textDocuments?.get(document.uri.toString())?.version : codeBuilt.version;
+      const updated =
+         codeBuilt === undefined
+            ? await super.update(document, cancellationToken)
+            : await this.reparse(document, codeBuilt.text, cancellationToken);
+      const version =
+         stored ??
+         this.versionOfParsedText(
+            updated.uri,
+            this.modelLedger().textOf(updated.parseResult.value) ?? updated.textDocument.getText(),
+            updated.textDocument.version
+         );
+      this.versionSyncService().modelProduced(updated, { version });
+      return updated;
+   }
+
+   /**
+    * The text a code-built document is read from when no file is at its URI:
+    * the store's while it is open, else the text it holds, serialized at
+    * creation or last read, as `VirtualFileSystemProvider` serves it.
+    * `undefined` for any other document, which is read as Langium reads it.
+    * The store's version is read with its text, since an edit can land
+    * before the caller resumes. Held text has no version.
+    */
+   protected async codeBuiltSource(document: LangiumDocument): Promise<{ text: string; version: number | undefined } | undefined> {
+      if (!this.codeBuiltDocuments.has(document) || (await this.fileSystemProvider.exists(document.uri))) {
+         return undefined;
+      }
+      const open = this.textDocuments?.get(document.uri.toString());
+      return open === undefined
+         ? { text: document.textDocument.getText(), version: undefined }
+         : { text: open.getText(), version: open.version };
+   }
+
+   /**
+    * Langium's `update` with `text` in place of the text it reads from the
+    * store or the URI. Mirrors `DefaultLangiumDocumentFactory.update` of
+    * Langium 4.3.1, so a Langium upgrade has to compare the two. From
+    * Langium 4.4, an override of `getUpdatedText` replaces it.
+    */
+   protected async reparse<T extends AstNode = AstNode>(
+      document: Mutable<LangiumDocument<T>>,
+      text: string,
+      cancellationToken: CancellationToken
+   ): Promise<LangiumDocument<T>> {
+      const textDocument = this.textDocuments?.get(document.uri.toString());
+      Object.defineProperty(
+         document,
+         'textDocument',
+         textDocument ? { value: textDocument } : { get: this.createTextDocumentGetter(document.uri, text) }
+      );
+      if (document.parseResult.value.$cstNode?.root.fullText !== text) {
+         document.parseResult = await this.parseAsync<T>(document.uri, text, cancellationToken);
+         (document.parseResult.value as Mutable<AstNode>).$document = document;
+      }
+      document.state = DocumentState.Parsed;
+      return document;
+   }
+
+   /**
+    * `version`, or {@link STALE_VERSION} when the store holds `uri` open with
+    * other text than `parsed`: text read from the file while an open landed.
+    */
+   protected versionOfParsedText(uri: URI, parsed: string | undefined, version: number): number {
+      const open = this.textDocuments?.get(uri.toString());
+      return open !== undefined && parsed !== undefined && open.getText() !== parsed ? STALE_VERSION : version;
    }
 
    /**