@hydranium/core 1.0.0-next.155 → 1.0.0-next.158

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

@@ -12,7 +12,7 @@ import { defineMessage, type Tracer } from '@hydranium/protocol';
 import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
-import { serveVirtualDocument, serveVirtualNode } from './virtual-document.js';
+import { notFound } from './file-not-found.js';
 
 /**
  * A provider's spelling of "the document is not there", raised wherever a read
@@ -43,15 +43,6 @@ export const UNSUPPORTED_WRITE = defineMessage(
    'Cannot write {uri}: the scheme names no location on disk'
 );
 
-/**
- * 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.
- */
-function notFound(message: string, uri: URI): Error {
-   return Object.assign(new Error(message), { code: 'ENOENT', path: uri.fsPath });
-}
-
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
  *
@@ -165,10 +156,6 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
    }
 
    readFileSync(uri: URI): string {
-      const served = serveVirtualDocument(this.services, uri);
-      if (served !== undefined) {
-         return served;
-      }
       const content = this.files.get(normalize(uri));
       if (content === undefined) {
          throw notFound(NO_SUCH_FILE.format({ uri: uri.toString() }), uri);
@@ -189,11 +176,6 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
    }
 
    statSync(uri: URI): FileSystemNode {
-      // Virtual first, on the same terms as `readFileSync`.
-      const served = serveVirtualNode(this.services, uri);
-      if (served !== undefined) {
-         return served;
-      }
       const path = normalize(uri);
       if (this.files.has(path)) {
          return { isFile: true, isDirectory: false, uri };
@@ -209,9 +191,6 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
    }
 
    existsSync(uri: URI): boolean {
-      if (serveVirtualDocument(this.services, uri) !== undefined) {
-         return true;
-      }
       const path = normalize(uri);
       return this.files.has(path) || this.hasChildren(path);
    }
@@ -281,8 +260,8 @@ function normalize(uri: URI | string): string {
  * services context exactly where a Node host spreads `NodeFileSystem`.
  *
  * A host that needs to reach the provider afterwards — to seed or mutate it
- * mid-test — reads it back off `shared.workspace.FileSystemProvider`, since the
- * slot owns construction.
+ * mid-test — narrows `shared.workspace.FileSystemProvider.host` to this
+ * class, since the slot owns construction.
  */
 export function inMemoryFileSystem(options: InMemoryFileSystemOptions = {}): {
    fileSystemProvider: (services: unknown) => WritableFileSystemProvider;

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

@@ -125,13 +125,6 @@ export interface PersistentFileSystemOptions extends InMemoryFileSystemOptions {
  * restored as deleted, which is why the marker is NUL-wrapped and text a grammar
  * can parse is not.
  *
- * # A registered virtual document still wins
- *
- * `readFileSync` consults the virtual-document seam before the map, so a stdlib
- * contributed in code keeps answering for its URI whether or not the store holds
- * one. The store cannot shadow it, which is what keeps a rebuild that re-reads
- * that URI from losing the stdlib.
- *
  * # What it deliberately does not answer
  *
  * The store is scoped to the ORIGIN, not to the page: two pages on the same

package/src/langium/workspace/virtual-document.ts

@@ -8,14 +8,19 @@
  ********************************************************************************/
 
 import { type FileSystemNode, URI } from '@hydranium/langium';
+import { type Tracer } from '@hydranium/protocol';
+import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
+import { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from './in-memory-file-system-provider.js';
+import { notFound } from './file-not-found.js';
 
 /**
  * URI scheme for virtual documents — LangiumDocuments that have no backing
  * file on disk (a language's stdlib, library types, built-in definitions,
  * mirrors, generated views). Chosen so it cannot collide with on-disk `file:`
- * URIs, and so the framework's FileSystemProvider can recognise and serve them
- * on re-read (see {@link serveVirtualDocument}).
+ * URIs, and so the framework can serve them on re-read through its own
+ * provider for the scheme (see {@link VirtualFileSystemProvider}).
  */
 export const VIRTUAL_SCHEME = 'virtual';
 
@@ -72,41 +77,95 @@ export function isVirtualUri(uri: URI | string): boolean {
 }
 
 /**
- * Serve the text of a registered virtual document, or `undefined` when `uri`
- * is not virtual or no document is registered for it (so a FileSystemProvider
- * delegates to its real backing).
+ * The file system provider for the {@link VIRTUAL_SCHEME} scheme, registered by
+ * the framework in the shared `fileSystemProviders` group so every host serves
+ * `virtual:` whatever provider it binds for its own files.
  *
- * The framework's FileSystemProvider defaults consult this across their whole
- * read surface, so a virtual document survives a re-read:
- * `DocumentBuilder.update` / `LangiumDocumentFactory.update` re-read a changed
- * URI from the FileSystemProvider, and nothing on disk backs a virtual URI. The
- * text comes from the registered document — the original source for a
- * `fromString` document, or the serialized form retained by the framework's
- * `fromModel` (which fills in the text Langium leaves empty). No serializer is
- * consulted here; the text is already on the document.
+ * A virtual document has no backing outside the index, and a re-read still has
+ * to find it: `DocumentBuilder.update` and `LangiumDocumentFactory.update`
+ * re-read a changed URI from the provider, and the last close rebuilds a
+ * released document the provider says `exists`. So the text comes from the
+ * document `LangiumDocuments` holds — the original source for a `fromString`
+ * document, or the serialized form the framework's `fromModel` retains. An
+ * edited one answers with its edited text.
  *
- * **Every read method has to agree.** Serving only the text methods leaves one
+ * **Every read method agrees.** Serving only the text methods would leave one
  * provider answering "here is the content" and "nothing is there" about one
- * URI, which is a worse contract than answering neither: a caller cannot probe
- * before reading.
+ * URI, so a caller could not probe before reading. A registered document is
+ * always a FILE with no children: a workspace walk handed a directory would try
+ * to enumerate children it has none of.
+ *
+ * Read-only: a write is refused, since nothing backs the scheme.
  */
-export function serveVirtualDocument(services: ServerSharedServicesMinimal, uri: URI): string | undefined {
-   if (!isVirtualUri(uri)) {
-      return undefined;
+export class VirtualFileSystemProvider implements WritableFileSystemProvider {
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal,
+      options: LogNameOptions = {}
+   ) {
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
    }
-   const document = services.workspace.LangiumDocuments.getDocument(uri);
-   return document ? document.textDocument.getText() : undefined;
-}
 
-/**
- * The filesystem node a registered virtual document presents as, or `undefined`
- * on the same terms as {@link serveVirtualDocument}.
- *
- * Always a FILE: a virtual document is a leaf carrying text, and nothing is
- * addressable beneath it. Reporting it as a directory instead would put it in
- * front of a workspace walk that would then try to enumerate children it has
- * none of.
- */
-export function serveVirtualNode(services: ServerSharedServicesMinimal, uri: URI): FileSystemNode | undefined {
-   return serveVirtualDocument(services, uri) === undefined ? undefined : { isFile: true, isDirectory: false, uri };
+   async writeFile(uri: URI, _content: string): Promise<void> {
+      throw new Error(UNSUPPORTED_WRITE.format({ uri: uri.toString() }));
+   }
+
+   async readFile(uri: URI): Promise<string> {
+      return this.readFileSync(uri);
+   }
+
+   readFileSync(uri: URI): string {
+      const text = this.text(uri);
+      if (text === undefined) {
+         throw notFound(NO_SUCH_FILE.format({ uri: uri.toString() }), uri);
+      }
+      return text;
+   }
+
+   async readBinary(uri: URI): Promise<Uint8Array> {
+      return this.readBinarySync(uri);
+   }
+
+   readBinarySync(uri: URI): Uint8Array {
+      return new TextEncoder().encode(this.readFileSync(uri));
+   }
+
+   async stat(uri: URI): Promise<FileSystemNode> {
+      return this.statSync(uri);
+   }
+
+   statSync(uri: URI): FileSystemNode {
+      if (this.text(uri) === undefined) {
+         throw notFound(NO_SUCH_PATH.format({ uri: uri.toString() }), uri);
+      }
+      return { isFile: true, isDirectory: false, uri };
+   }
+
+   async exists(uri: URI): Promise<boolean> {
+      return this.existsSync(uri);
+   }
+
+   existsSync(uri: URI): boolean {
+      return this.text(uri) !== undefined;
+   }
+
+   async readDirectory(_uri: URI): Promise<FileSystemNode[]> {
+      return [];
+   }
+
+   readDirectorySync(_uri: URI): FileSystemNode[] {
+      return [];
+   }
+
+   /**
+    * Text of the document registered at `uri`, if there is one.
+    *
+    * `LangiumDocuments` is resolved per call, not in the constructor: it reaches
+    * this provider back through the document factory, so resolving it eagerly
+    * is a construction cycle.
+    */
+   protected text(uri: URI): string | undefined {
+      return this.services.workspace.LangiumDocuments.getDocument(uri)?.textDocument.getText();
+   }
 }

package/src/node/node-file-system-provider.ts

@@ -19,7 +19,6 @@ import { renameOverOpenReaders } from './rename-over-open-readers.js';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../langium/shared-services.js';
 import { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from '../langium/workspace/in-memory-file-system-provider.js';
-import { serveVirtualDocument, serveVirtualNode } from '../langium/workspace/virtual-document.js';
 
 /**
  * Node-based default {@link WritableFileSystemProvider}. Extends Langium's
@@ -29,17 +28,18 @@ import { serveVirtualDocument, serveVirtualNode } from '../langium/workspace/vir
  * {@link SelfSaveRegistry} bound at `services.workspace.SelfSaveRegistry` — so
  * consumers can suppress the `didChangeWatchedFiles` echo for their own writes.
  *
- * Its read surface answers for registered virtual documents and refuses to
- * derive a disk path from a URI that names no disk location — see
- * {@link servesFromDisk}, which is the one place that judgement is made. Every
- * method that derives an OS path is held to it, writes most of all: a read that
- * skipped it would only mis-report, while a write would CREATE a file at a path
- * the URI never named.
+ * Its read surface refuses to derive a disk path from a URI that names no disk
+ * location — see {@link servesFromDisk}, which is the one place that judgement
+ * is made. Every method that derives an OS path is held to it, writes most of
+ * all: a read that skipped it would only mis-report, while a write would CREATE
+ * a file at a path the URI never named. Behind the framework's
+ * `FileSystemProviderRegistry`, a `virtual:` URI goes to the framework's own
+ * provider for that scheme, not here.
  *
  * Server-only (`@hydranium/core/node`): pulls `node:fs`. The portable `.`
- * entry binds `DefaultEmptyFileSystemProvider` by default, so a Node host
- * must rebind this slot — through `context.fileSystemProvider` or directly — to
- * get real disk I/O.
+ * entry falls back to `DefaultEmptyFileSystemProvider`, so a Node host passes
+ * this one through `context.fileSystemProvider` (see {@link NodeFileSystem})
+ * to get real disk I/O.
  */
 export class DefaultFileSystemProvider extends NodeFileSystemProvider implements WritableFileSystemProvider {
    readonly selfSaveRegistry: SelfSaveRegistry;
@@ -76,23 +76,14 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
       return uri.scheme === 'file';
    }
 
-   // Each read resolves in the same order: a registered virtual document first
-   // (it has no `fsPath` backing), then disk for a path this provider can
-   // reach, then the filesystem's own "nothing here" answer — never a probe
+   // Each read answers from disk for a path this provider can reach, and
+   // otherwise with the filesystem's own "nothing here" — never a probe
    // against a path derived from a URI that names no disk location.
    override readFile(uri: URI): Promise<string> {
-      const served = serveVirtualDocument(this.services, uri);
-      if (served !== undefined) {
-         return Promise.resolve(served);
-      }
       return this.servesFromDisk(uri) ? super.readFile(uri) : Promise.reject(noSuchFile(uri));
    }
 
    override readFileSync(uri: URI): string {
-      const served = serveVirtualDocument(this.services, uri);
-      if (served !== undefined) {
-         return served;
-      }
       if (!this.servesFromDisk(uri)) {
          throw noSuchFile(uri);
       }
@@ -100,18 +91,10 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
    }
 
    override readBinary(uri: URI): Promise<Uint8Array> {
-      const served = serveVirtualDocument(this.services, uri);
-      if (served !== undefined) {
-         return Promise.resolve(encode(served));
-      }
       return this.servesFromDisk(uri) ? super.readBinary(uri) : Promise.reject(noSuchFile(uri));
    }
 
    override readBinarySync(uri: URI): Uint8Array {
-      const served = serveVirtualDocument(this.services, uri);
-      if (served !== undefined) {
-         return encode(served);
-      }
       if (!this.servesFromDisk(uri)) {
          throw noSuchFile(uri);
       }
@@ -119,18 +102,10 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
    }
 
    override stat(uri: URI): Promise<FileSystemNode> {
-      const served = serveVirtualNode(this.services, uri);
-      if (served !== undefined) {
-         return Promise.resolve(served);
-      }
       return this.servesFromDisk(uri) ? super.stat(uri) : Promise.reject(noSuchPath(uri));
    }
 
    override statSync(uri: URI): FileSystemNode {
-      const served = serveVirtualNode(this.services, uri);
-      if (served !== undefined) {
-         return served;
-      }
       if (!this.servesFromDisk(uri)) {
          throw noSuchPath(uri);
       }
@@ -140,16 +115,10 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
    // Delegating to `existsSync` would be shorter and would put a blocking stat
    // on the async path.
    override async exists(uri: URI): Promise<boolean> {
-      if (serveVirtualDocument(this.services, uri) !== undefined) {
-         return true;
-      }
       return this.servesFromDisk(uri) ? super.exists(uri) : false;
    }
 
    override existsSync(uri: URI): boolean {
-      if (serveVirtualDocument(this.services, uri) !== undefined) {
-         return true;
-      }
       return this.servesFromDisk(uri) ? super.existsSync(uri) : false;
    }
 
@@ -311,11 +280,6 @@ function unsupportedWrite(uri: URI): Error {
    return new Error(UNSUPPORTED_WRITE.format({ uri: uri.toString() }));
 }
 
-/** A virtual document's text as the bytes a binary read returns. */
-function encode(text: string): Uint8Array {
-   return new TextEncoder().encode(text);
-}
-
 /**
  * What a write has to know about the regular file at `path` before replacing
  * it: the permission bits to carry over, and how many names share its inode.