@hydranium/core 1.0.0-next.284 → 1.0.0-next.287

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

@@ -67,6 +67,15 @@ export interface WritableFileSystemProvider extends FileSystemProvider {
     * 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
@@ -173,10 +182,11 @@ export interface FileSystemProviderRegistryOptions<
  * A directory is listed by the provider of its own scheme, so a workspace
  * root's tree comes from that provider alone.
  *
- * `realpath`, `mtimeMs` and `existsSettled` are always present and forward to
- * the scheme's provider. Where that provider lacks one, `realpath` returns the
- * URI unchanged, `mtimeMs` returns `undefined` and `existsSettled` answers as
- * `exists`: the answers their callers already give a provider without them.
+ * `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
@@ -223,6 +233,15 @@ export class DefaultFileSystemProviderRegistry<
       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);

package/src/lsp/hydranium-document-update-handler.ts

@@ -63,13 +63,15 @@ export interface HydraniumDocumentUpdateHandlerOptions {
    readonly bypassNonLanguageClientChanges?: boolean;
    /**
     * Longest an editor's save waits on the server, in milliseconds, at each of
-    * its two steps: the `willSaveWaitUntil` answer waits for the server's disk
-    * writes of the document already queued, and server writes queued after the
-    * answer wait for the editor's `didSave`. Either wait that runs out is
-    * logged, and the editor's write and the server's can then land in either
-    * order. Default `1000`: VS Code gives up on an answer after about 1.5 s,
-    * and switches the listener off for the session once four answers, over
-    * all documents, timed out or failed.
+    * its two steps: the `willSaveWaitUntil` answer waits for the language
+    * client's answer to the push of the server's text and for the server's
+    * disk writes of the document already queued, and server writes queued
+    * after the answer wait for the editor's `didSave`. Either wait that runs
+    * out is logged, and the editor can then save without the server's text,
+    * or its write and the server's land in either order. Default `1000`: VS
+    * Code gives up on an answer after about 1.5 s, and switches the listener
+    * off for the session once four answers, over all documents, timed out or
+    * failed.
     */
    readonly willSaveGateMs?: number;
 }
@@ -96,10 +98,11 @@ export interface HydraniumDocumentUpdateHandlerOptions {
  *     runs, so a subclass that formats build logs can tag its line with the
  *     event that caused the build without per-adopter wiring to capture it.
  *  4. **Editor save gate** ({@link willSaveDocumentWaitUntil}) — the editor
- *     writes the file itself, so the server's disk writes of that document
- *     are ordered around it: the editor's save waits for the ones already
- *     queued, and the ones queued during its save wait for its `didSave`.
- *     Both waits are capped by
+ *     writes the file itself, so its save waits for the language client to
+ *     answer the push of the server's newer text, and the server's disk
+ *     writes of that document are ordered around it: the editor's save waits
+ *     for the ones already queued, and the ones queued during its save wait
+ *     for its `didSave`. The answer and the hold are each capped by
  *     {@link HydraniumDocumentUpdateHandlerOptions.willSaveGateMs}.
  *
  * What the build keeps after a document's last close is not dispatched here:
@@ -257,23 +260,27 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
    }
 
    /**
-    * Answer an editor's `willSaveWaitUntil` with no edits once the server's
-    * disk writes of the document already queued have landed, or after
-    * {@link willSaveGateMs}, whichever is first. From the moment the queue
-    * reaches this save, disk tasks of the document queued behind it wait for
-    * the editor's `didSave`, reported through
+    * Answer an editor's `willSaveWaitUntil` with no edits once
+    * {@link settleBeforeSave} has resolved and then the server's disk writes
+    * of the document already queued have landed, or after
+    * {@link willSaveGateMs} for both together, whichever is first. From the
+    * moment the queue reaches this save, disk tasks of the document queued
+    * behind it wait for the editor's `didSave`, reported through
     * `HydraniumTextDocuments.onDidSaveInLanguageClient`, or for
     * {@link willSaveGateMs} more.
     *
     * The hold is a disk task that waits only for that signal or its timer:
     * waiting on a build, a save or anything else queued for the document would
-    * wedge its queue. Resolves in every case, since a failed request counts
-    * against the listener in VS Code; Langium drops the request's cancellation,
-    * so an abandoned request still runs to the cap. A hold that runs out is
-    * logged at debug only: an editor skips `didSave` for a save it cancels or
-    * that changed nothing.
+    * wedge its queue, so the settle runs before it is queued. Past the cap the
+    * hold is queued while the settle still runs, so a write that build queues,
+    * such as an integrity repair, waits behind the hold. A settle that fails is
+    * logged and the save goes on. Resolves in every case, since a
+    * failed request counts against the listener in VS Code; Langium drops the
+    * request's cancellation, so an abandoned request still runs to the cap. A
+    * hold that runs out is logged at debug only: an editor skips `didSave` for
+    * a save it cancels or that changed nothing.
     */
-   willSaveDocumentWaitUntil(event: TextDocumentWillSaveEvent<TextDocument>): Promise<TextEdit[]> {
+   async willSaveDocumentWaitUntil(event: TextDocumentWillSaveEvent<TextDocument>): Promise<TextEdit[]> {
       const uri = event.document.uri;
       this.editorSaves.get(uri)?.();
       const hold = new Deferred();
@@ -284,32 +291,83 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
          hold.resolve();
       };
       this.editorSaves.set(uri, release);
-      return new Promise<TextEdit[]>(resolve => {
-         const clock = this.services.Clock;
-         const cap = clock.setTimer(() => {
+      const clock = this.services.Clock;
+      const answer = new Deferred<TextEdit[]>();
+      let settling = true;
+      const cap = clock.setTimer(() => {
+         if (settling) {
+            // A push unanswered past the cap is the stale-save case, and server
+            // writes queued ahead of the hold race the save; a build past the
+            // cap alone is routine on a large model.
+            if (this.services.model.ModelService.isLanguageClientPushPending(uri)) {
+               this.logger.warn(
+                  `willSaveWaitUntil for ${uri} answered after ${this.willSaveGateMs} ms with the language client's answer to a push of it still pending; the editor may save text older than the server's.`
+               );
+            } else if (!this.services.workspace.FileSystemTaskQueue.isIdle(uri)) {
+               this.logger.warn(
+                  `willSaveWaitUntil for ${uri} answered after ${this.willSaveGateMs} ms with its settle still pending and server writes of it queued; the editor's save may race them.`
+               );
+            } else {
+               this.logger.debug(
+                  `willSaveWaitUntil for ${uri} answered after ${this.willSaveGateMs} ms with its settle still pending, on its build or on a push a settle already timed out on.`
+               );
+            }
+         } else {
             this.logger.warn(
                `willSaveWaitUntil for ${uri} answered after ${this.willSaveGateMs} ms with server writes of it still queued; the editor's save may race them.`
             );
-            resolve([]);
-         }, this.willSaveGateMs);
+         }
+         answer.resolve([]);
+      }, this.willSaveGateMs);
+      // Caught on the settle itself, since a race that the cap has won drops a
+      // later rejection without a trace.
+      const settled = (async (): Promise<void> => {
          try {
-            void this.services.workspace.FileSystemTaskQueue.enqueue(uri, async () => {
-               cap.dispose();
-               resolve([]);
-               if ((await clock.raceTimer(hold.promise, this.willSaveGateMs)) === TIMED_OUT) {
-                  this.logger.debug(
-                     `No didSave for ${uri} within ${this.willSaveGateMs} ms; server writes of it no longer wait for the editor's save.`
-                  );
-                  release();
-               }
-            });
-         } catch (err) {
-            cap.dispose();
-            this.logger.error(`willSaveWaitUntil for ${uri} answered without waiting. ${describeErrorWithStack(err)}`);
-            release();
-            resolve([]);
+            await this.settleBeforeSave(uri);
+         } catch (err: unknown) {
+            this.logger.error(`The settle before an editor save of ${uri} failed. ${describeErrorWithStack(err)}`);
          }
-      });
+      })();
+      await Promise.race([settled, answer.promise]);
+      settling = false;
+      try {
+         void this.services.workspace.FileSystemTaskQueue.enqueue(uri, async () => {
+            cap.dispose();
+            answer.resolve([]);
+            if ((await clock.raceTimer(hold.promise, this.willSaveGateMs)) === TIMED_OUT) {
+               this.logger.debug(
+                  `No didSave for ${uri} within ${this.willSaveGateMs} ms; server writes of it no longer wait for the editor's save.`
+               );
+               release();
+            }
+         });
+      } catch (err: unknown) {
+         cap.dispose();
+         this.logger.error(`willSaveWaitUntil for ${uri} answered without waiting for server writes. ${describeErrorWithStack(err)}`);
+         release();
+         answer.resolve([]);
+      }
+      return answer.promise;
+   }
+
+   /**
+    * What an editor's save of `uri` waits for before it joins the document's
+    * disk queue: the language client's answer to the push of the server's
+    * newer text, applied or refused and logged
+    * (`ModelService.settleLanguageClient`). The editor saves its own buffer,
+    * so without it the editor can save text older than the server's. The
+    * settle waits for a build of the document's latest text, so a change of it
+    * still debounced is flushed first, along with every other debounced
+    * change. Runs outside the disk queue, under the save's cap; an override
+    * must not wait on a disk task of the document, which past the cap queues
+    * behind the save's hold.
+    */
+   protected async settleBeforeSave(uri: string): Promise<void> {
+      const key = URI.parse(uri).toString();
+      if (this.pendingChanged.has(key) || this.pendingDeleted.has(key)) {
+         this.flushPending();
+      }
+      await this.services.model.ModelService.settleLanguageClient(uri);
    }
 
    /**

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

@@ -11,8 +11,9 @@ import { type Tracer } from '@hydranium/protocol';
 import { type FileSystemNode, URI, UriUtils } from '@hydranium/langium';
 import { NodeFileSystemProvider } from '@hydranium/langium/node';
 import { randomUUID } from 'node:crypto';
-import { realpathSync } from 'node:fs';
+import { readlinkSync, realpathSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
 import { type WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
 import { isFileNotFound } from '../langium/workspace/file-not-found.js';
 import { type SelfSaveRegistry } from '../langium/workspace/self-save-registry.js';
@@ -314,6 +315,40 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
          return undefined;
       }
    }
+
+   /**
+    * The path `uri` names with every link followed, a link to nothing
+    * included, so a file reached through a link keys the same before it
+    * exists and once it does. What is missing is joined as spelled under the
+    * real path of what exists. A non-`file:` URI passes through unchanged.
+    */
+   resolveLinks(uri: URI): URI {
+      return uri.scheme === 'file' ? URI.file(followLinks(uri.fsPath)) : uri;
+   }
+}
+
+/** `path` with its links followed; see `DefaultFileSystemProvider.resolveLinks`. */
+function followLinks(path: string, hops = 0): string {
+   try {
+      return realpathSync(path);
+   } catch {
+      // Absent somewhere along the way.
+   }
+   // A link to nothing is followed to what it names; a chain is bounded as
+   // the kernel bounds one.
+   if (hops < 40) {
+      let target: string | undefined;
+      try {
+         target = readlinkSync(path);
+      } catch {
+         // Not a link, or not there.
+      }
+      if (target !== undefined) {
+         return followLinks(resolve(dirname(path), target), hops + 1);
+      }
+   }
+   const parent = dirname(path);
+   return parent === path ? path : join(followLinks(parent, hops), basename(path));
 }
 
 /** The "no content here" rejection, for a URI naming no readable file. */

package/src/testing/node/applied-edit-capture.ts

@@ -23,7 +23,7 @@ import type { AppliedEdit, NextAppliedEditOptions } from './lsp-server-connectio
 export interface AppliedEditCapture {
    readonly appliedEdits: ReadonlyArray<AppliedEdit>;
    nextAppliedEdit(uri: string, timeoutMsOrOptions?: number | NextAppliedEditOptions): Promise<AppliedEdit>;
-   setApplyEditHandler(handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult): void;
+   setApplyEditHandler(handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult | Promise<ApplyWorkspaceEditResult>): void;
    dispose(): void;
 }
 
@@ -37,7 +37,9 @@ export interface AppliedEditCapture {
 export function captureAppliedEdits(client: ProtocolConnection, defaultTimeoutMs: number): AppliedEditCapture {
    const appliedEdits: AppliedEdit[] = [];
    const waiters: Array<(edit: AppliedEdit) => boolean> = [];
-   let handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult = () => ({ applied: true });
+   let handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult | Promise<ApplyWorkspaceEditResult> = () => ({
+      applied: true
+   });
    const subscription = client.onRequest(ApplyWorkspaceEditRequest.type, (params: ApplyWorkspaceEditParams) => {
       const edit: AppliedEdit = { params, uris: editedUris(params.edit), text: insertedText(params.edit) };
       // Record before the handler runs, so a handler that rejects the edit or
@@ -92,7 +94,7 @@ export function captureAppliedEdits(client: ProtocolConnection, defaultTimeoutMs
          });
       },
 
-      setApplyEditHandler(next: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult): void {
+      setApplyEditHandler(next: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult | Promise<ApplyWorkspaceEditResult>): void {
          handler = next;
       },
 

package/src/testing/node/lsp-server-connection.ts

@@ -281,8 +281,9 @@ export interface LspServerConnection extends Harness {
     *
     * Throwing from the handler surfaces to the server as an RPC failure, which
     * is the other branch (`applyEditToLanguageClient` invalidates and rethrows).
+    * A handler returning a promise holds the answer until it settles.
     */
-   setApplyEditHandler(handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult): void;
+   setApplyEditHandler(handler: (params: ApplyWorkspaceEditParams) => ApplyWorkspaceEditResult | Promise<ApplyWorkspaceEditResult>): void;
 
    /**
     * Release every resource: the diagnostics and applyEdit subscriptions, the