@hydranium/core 1.0.0-next.19 → 1.0.0-next.192

package/src/langium/workspace/file-not-found.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * 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 URI } from '@hydranium/langium';
+
+// Not re-exported from the workspace barrel: the framework's providers share
+// it, and it is no API of theirs.
+
+/**
+ * A missing-file error shaped as a Node file system raises it, with code
+ * `ENOENT` and the path: callers tell a missing file from any other failure by
+ * those two fields, whichever provider is bound. The last close relies on it to
+ * tell a document gone meanwhile from any other failed rebuild.
+ */
+export function notFound(message: string, uri: URI): Error {
+   return Object.assign(new Error(message), { code: 'ENOENT', path: uri.fsPath });
+}

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

@@ -9,18 +9,18 @@
 
 import { type Tracer } from '@hydranium/protocol';
 import { EmptyFileSystemProvider } from '@hydranium/langium';
-import type { URI } from '@hydranium/langium';
+import type { FileSystemNode, URI } from '@hydranium/langium';
 import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.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`
- * lives in `@hydranium/core/node` (it pulls `node:fs`).
+ * Empty-filesystem {@link WritableFileSystemProvider}. For browser / test / CLI
+ * hosts that don't have a real filesystem. All writes 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 {
    protected readonly tracer: Tracer;
@@ -37,16 +37,153 @@ 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` 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 readFileSync(uri?: URI): string {
-      const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
-      return served !== undefined ? served : super.readFileSync();
+   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;
+}
+
+/** 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` and `mtimeMs` are always present and forward to the scheme's
+ * provider. Where that provider lacks one, `realpath` returns the URI unchanged
+ * and `mtimeMs` returns `undefined`: the answers `RealpathDocumentUriPolicy`
+ * and the self-save filter 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 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;
+   }
+
+   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);
+   }
+
+   readDirectorySync(uri: URI): FileSystemNode[] {
+      return this.providerFor(uri).readDirectorySync(uri);
    }
 }

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

@@ -12,9 +12,17 @@ import {
    AstUtils,
    DefaultLangiumDocumentFactory,
    type LangiumDocument,
+   type Mutable,
    type ParseResult,
    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 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. */
@@ -49,6 +57,49 @@ interface WithSerializer {
  * node identity is preserved.
  */
 export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFactory {
+   /**
+    * Narrows the inherited Langium `ServiceRegistry` field to the framework's
+    * {@link ExtendedServiceRegistry}, so the by-id lookup below needs no
+    * per-callsite cast. The framework's shared module binds that class.
+    */
+   declare protected readonly serviceRegistry: ExtendedServiceRegistry;
+
+   /** Resolved per call: the sync service reaches the registry, which is built with this factory. */
+   protected readonly versionSyncService: () => VersionSyncService;
+   protected readonly modelLedger: () => ModelLedger;
+
+   constructor(services: ServerSharedServicesMinimal) {
+      super(services);
+      this.versionSyncService = () => services.workspace.VersionSyncService;
+      this.modelLedger = () => services.workspace.ModelLedger;
+   }
+
+   /**
+    * Parse `text` for `uri` under the grammar `languageId` names, instead of
+    * the one `uri` routes to.
+    *
+    * For a URI that routes to no grammar at all: a directory, or any other URI
+    * that names no file and so carries no extension. Langium's ladder ends at
+    * the extension, so it reports `no services for the extension ''` from
+    * inside the parse — naming neither the URI nor the caller that could have
+    * said which grammar it meant.
+    *
+    * The caller supplies the language because nothing else can. A URI with no
+    * extension carries no routing signal, and choosing on its behalf would be a
+    * guess the moment a second grammar is registered — which is why this takes
+    * the id rather than falling back to a sole registered language.
+    *
+    * @throws when `languageId` names no registered grammar.
+    */
+   fromStringInLanguage<T extends AstNode = AstNode>(text: string, uri: URI, languageId: string): LangiumDocument<T> {
+      const services = this.serviceRegistry.getServicesById(languageId);
+      if (!services) {
+         throw new Error(`No grammar is registered for the language id '${languageId}' (parsing ${uri.toString()}).`);
+      }
+      const parseResult: ParseResult<T> = services.parser.LangiumParser.parse<T>(text);
+      return this.createLangiumDocument<T>(parseResult, uri, undefined, text);
+   }
+
    override fromModel<T extends AstNode = AstNode>(model: T, uri: URI): LangiumDocument<T> {
       // Make the code-built AST as structurally complete as a parsed one — the
       // parser links containers, `fromModel` does not. In place (identity kept).
@@ -61,6 +112,72 @@ export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFacto
       return this.createLangiumDocument<T>(parseResult, uri, undefined, text);
    }
 
+   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();
+      this.versionSyncService().modelProduced(document, { version: this.versionOfParsedText(uri, parsed, textDocument?.version ?? 0) });
+      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>> {
+      const stored = this.textDocuments?.get(document.uri.toString())?.version;
+      const updated = await super.update(document, 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;
+   }
+
+   /**
+    * `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;
+   }
+
    /**
     * Serialize `model` via the per-language serializer, or `undefined` if none
     * is bound, it fails, or it is async — `fromModel` is synchronous, so an

package/src/langium/workspace/hydranium-workspace-lock.ts

@@ -7,10 +7,31 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { type Clock, type Tracer } from '@hydranium/protocol';
 import { DefaultWorkspaceLock, type MaybePromise } from '@hydranium/langium';
-import { type CancellationToken } from 'vscode-languageserver-protocol';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver-protocol';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { runInWriteLockScope } from './write-lock-scope.js';
 
+/** Constructor options for {@link HydraniumWorkspaceLock}. */
+export interface HydraniumWorkspaceLockOptions extends LogNameOptions {
+   /**
+    * How long a write may keep running after a later write cancelled it before
+    * the lock logs an error. Every write and read waits behind it meanwhile, so
+    * one that never ends stops the server. Defaults to 10 s; `0` turns the
+    * check off.
+    */
+   readonly stalledWriteWarnMs?: number;
+}
+
+const DEFAULT_STALLED_WRITE_WARN_MS = 10_000;
+
+/** The write action a {@link HydraniumWorkspaceLock} is running, with the timer its cancellation started. */
+export interface RunningWrite {
+   stallTimer?: Disposable;
+}
+
 /**
  * Langium's {@link DefaultWorkspaceLock} with the write action marked as a
  * write-lock scope, so anything it reaches can be asked whether the lock is
@@ -29,7 +50,70 @@ import { runInWriteLockScope } from './write-lock-scope.js';
  * would turn ordinary read-then-write sequences into false positives.
  */
 export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
+   /** Backs {@link writeCancellations}. */
+   protected cancelledWriteCount = 0;
+   protected readonly clock: Clock;
+   protected readonly tracer: Tracer;
+   protected readonly stalledWriteWarnMs: number;
+   protected runningWrite?: RunningWrite;
+
+   constructor(services: Pick<ServerSharedServicesMinimal, 'Clock' | 'Tracer'>, options: HydraniumWorkspaceLockOptions = {}) {
+      super();
+      this.clock = services.Clock;
+      this.tracer = services.Tracer.for(options.logName ?? 'WorkspaceLock');
+      this.stalledWriteWarnMs = options.stalledWriteWarnMs ?? DEFAULT_STALLED_WRITE_WARN_MS;
+   }
+
+   /**
+    * How many calls have cancelled the lock's latest write: every `write`,
+    * which cancels the write before it, and every `cancelWrite`. A caller that
+    * reads this right after queuing a write, and reads the same number later,
+    * holds a write nothing has cancelled, whether it is still queued or
+    * already running. Its token answers that only once the write runs, since
+    * a queued write has not been handed it yet.
+    */
+   get writeCancellations(): number {
+      return this.cancelledWriteCount;
+   }
+
    override write(action: (token: CancellationToken) => MaybePromise<void>): Promise<void> {
-      return super.write(token => runInWriteLockScope(() => action(token)));
+      return super.write(token => runInWriteLockScope(() => this.runWrite(action, token)));
+   }
+
+   /** Run `action` as {@link runningWrite}, so a cancellation while it runs can time it. */
+   protected async runWrite(action: (token: CancellationToken) => MaybePromise<void>, token: CancellationToken): Promise<void> {
+      const running: RunningWrite = {};
+      this.runningWrite = running;
+      try {
+         await action(token);
+      } finally {
+         running.stallTimer?.dispose();
+         if (this.runningWrite === running) {
+            this.runningWrite = undefined;
+         }
+      }
+   }
+
+   /**
+    * Counted here rather than in {@link write}, because Langium's `write` cancels
+    * through this method too. A write running when this is called has been
+    * cancelled, by this call or an earlier one, so its timer starts here.
+    */
+   override cancelWrite(): void {
+      this.cancelledWriteCount++;
+      const running = this.runningWrite;
+      if (running && !running.stallTimer && this.stalledWriteWarnMs > 0) {
+         running.stallTimer = this.clock.setTimer(() => this.reportStalledWrite(), this.stalledWriteWarnMs);
+      }
+      super.cancelWrite();
+   }
+
+   protected reportStalledWrite(): void {
+      this.tracer.error(
+         `A write is still running ${this.stalledWriteWarnMs} ms after it was cancelled, and every write and read waits behind it. ` +
+            'Likely causes: a model-service write or rebuild from inside a build in a host with no write-lock scope tracker, ' +
+            'which waits for the build it runs in, or a write action that ignores its cancellation token. ' +
+            'See https://github.com/eclipse-emfcloud/hydranium/issues/245.'
+      );
    }
 }