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

package/src/locale/server-locale.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { Tracer } from '@hydranium/protocol';
+import type { Locale, Tracer } from '@hydranium/protocol';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
 import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
 
@@ -25,8 +25,8 @@ export type ServerLocaleOptions = LogNameOptions;
  */
 export interface ServerLocale {
    /** The locale, or `undefined` when no init supplied one — the framework's English. */
-   readonly value: string | undefined;
-   accept(locale: string): void;
+   readonly value: Locale | undefined;
+   accept(locale: Locale): void;
 }
 
 /**
@@ -40,14 +40,14 @@ export interface ServerLocale {
  */
 export class DefaultServerLocale implements ServerLocale {
    protected readonly tracer: Tracer;
-   protected current: string | undefined;
+   protected current: Locale | undefined;
 
    constructor(services: ServerSharedServicesMinimal, options: ServerLocaleOptions = {}) {
       this.tracer = services.Tracer.for(options.logName ?? 'ServerLocale').trace('instantiated');
    }
 
    /** The locale, or `undefined` when no init supplied one — which means the framework's English. */
-   get value(): string | undefined {
+   get value(): Locale | undefined {
       return this.current;
    }
 
@@ -79,7 +79,7 @@ export class DefaultServerLocale implements ServerLocale {
     * threshold and therefore absent from exactly the log someone would be
     * reading.
     */
-   accept(locale: string): void {
+   accept(locale: Locale): void {
       this.current = locale;
       this.tracer.info(`rendering messages in locale '${locale}'`);
    }

package/src/lsp/completion/hydranium-completion-provider.ts

@@ -7,9 +7,16 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type AstNodeDescription, type ReferenceInfo, type Stream } from '@hydranium/langium';
+import { type AstNodeDescription, type LangiumDocument, type ReferenceInfo, type Stream } from '@hydranium/langium';
 import { DefaultCompletionProvider, type CompletionContext, type CompletionValueItem } from '@hydranium/langium/lsp';
-import type { CompletionItem, InsertReplaceEdit } from 'vscode-languageserver';
+import {
+   CompletionList,
+   type CancellationToken,
+   type CompletionItem,
+   type CompletionParams,
+   type InsertReplaceEdit,
+   type Position
+} from 'vscode-languageserver';
 import { type ReferenceCandidateProvider } from '../../langium/scope/reference-candidate-provider.js';
 import { type ServerLanguageServices } from '../../langium/language-module.js';
 
@@ -52,6 +59,14 @@ import { type ServerLanguageServices } from '../../langium/language-module.js';
  * elements. The provider owns that pipeline in one place, so the
  * text-editor dropdown and the protocol candidate picker stay in sync; this
  * class keeps only the LSP-specific {@link fillCompletionItem} upgrade.
+ *
+ * **A comment is not a completion site.** Langium's context builder reads the
+ * non-hidden token stream alone, so a cursor in a comment is indistinguishable
+ * from one in the whitespace between the tokens surrounding it: the grammar's
+ * follow-set goes out as keyword proposals, and none of them is filtered,
+ * because the characters the user typed belong to the hidden token and the
+ * prefix matched against is therefore empty. {@link isInsideComment} suppresses
+ * the request instead.
  */
 export class HydraniumCompletionProvider extends DefaultCompletionProvider {
    protected readonly candidateProvider: ReferenceCandidateProvider;
@@ -61,6 +76,71 @@ export class HydraniumCompletionProvider extends DefaultCompletionProvider {
       this.candidateProvider = services.references.CandidateProvider;
    }
 
+   /**
+    * Answer no proposals at all when the cursor is inside a comment.
+    *
+    * Suppressing the whole request is what makes the rule hold for every
+    * proposal kind at once. Filtering the built contexts instead has to catch
+    * each context kind the base builds separately, and a kind added upstream
+    * arrives unguarded.
+    *
+    * The list is marked incomplete so the client re-asks on the next keystroke
+    * and proposals resume the moment the cursor leaves the comment.
+    */
+   override async getCompletion(
+      document: LangiumDocument,
+      params: CompletionParams,
+      cancelToken?: CancellationToken
+   ): Promise<CompletionList | undefined> {
+      if (this.isInsideComment(document, params.position)) {
+         return CompletionList.create([], true);
+      }
+      return super.getCompletion(document, params, cancelToken);
+   }
+
+   /**
+    * Whether `position` falls in text a comment terminal claims.
+    *
+    * The two comment kinds part company at their far edge. A single-line
+    * comment runs to the line break, so a cursor at its end offset is still in
+    * prose and that offset counts as inside. A multi-line comment is
+    * terminated, so a cursor at its end offset has passed the terminator and is
+    * back in code. A cursor ON the opening delimiter is outside either way,
+    * that offset being a legal position for whatever token the comment
+    * displaced.
+    *
+    * The hidden token stream decides rather than the CST. A leaf lookup by
+    * offset misses the position a cursor reaches by typing prose into a
+    * trailing comment, because that comment ends AT the line break and
+    * whitespace is discarded before a CST node is built over it — so the
+    * lookup answers nothing exactly where proposals are least wanted.
+    *
+    * An adopter whose comment syntax carries completable content — a
+    * documentation tag naming a type — narrows this to return `false` over that
+    * region rather than replacing {@link getCompletion}.
+    */
+   protected isInsideComment(document: LangiumDocument, position: Position): boolean {
+      const text = document.textDocument.getText();
+      const offset = document.textDocument.offsetAt(position);
+      const multilineCommentRules = this.grammarConfig.multilineCommentRules;
+      for (const token of this.lexer.tokenize(text).hidden) {
+         if (token.startOffset >= offset) {
+            // Hidden tokens arrive in document order, so no later one reaches back over the cursor.
+            return false;
+         }
+         // `endOffset` is optional on the token type and the image is not, so
+         // the width comes from the image and needs no absent-value branch.
+         const endOffset = token.startOffset + token.image.length;
+         if (offset < endOffset) {
+            return true;
+         }
+         if (offset === endOffset && !multilineCommentRules.includes(token.tokenType.name)) {
+            return true;
+         }
+      }
+      return false;
+   }
+
    /**
     * Delegate cross-reference candidate gathering to the candidate provider
     * so the LSP completion dropdown applies the same filter / canonical

package/src/lsp/connection-features.ts

@@ -0,0 +1,67 @@
+/********************************************************************************
+ * 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 { LogMessageNotification, MessageType, type Features, type RemoteConsole } from 'vscode-languageserver';
+import { isClientGoneError } from '../util/connection-liveness.js';
+
+/**
+ * Add Hydranium's connection-liveness handling to a language-server
+ * connection's console. The upstream `RemoteConsole` catches every failed log
+ * notification and prints `Sending log message failed`, so every ordinary
+ * teardown reports a failure; this console drops only a failure that
+ * {@link isClientGoneError} recognises and re-raises any other as an
+ * unhandled rejection.
+ *
+ * Supply it where the connection is created. `createConnection` builds the
+ * console from these features, so a connection that already exists keeps the
+ * upstream console for its whole lifetime.
+ */
+export function withHydraniumLspFeatures<T extends Features>(features: T): T {
+   return {
+      ...features,
+      console: (Base: new () => RemoteConsole) =>
+         class extends Base {
+            override error(message: string): void {
+               this.sendLogMessage(MessageType.Error, message);
+            }
+
+            override warn(message: string): void {
+               this.sendLogMessage(MessageType.Warning, message);
+            }
+
+            override info(message: string): void {
+               this.sendLogMessage(MessageType.Info, message);
+            }
+
+            override log(message: string): void {
+               this.sendLogMessage(MessageType.Log, message);
+            }
+
+            override debug(message: string): void {
+               this.sendLogMessage(MessageType.Debug, message);
+            }
+
+            private sendLogMessage(type: MessageType, message: string): void {
+               try {
+                  void this.connection.sendNotification(LogMessageNotification.type, { type, message }).catch(error => {
+                     this.handleLogSendFailure(error);
+                  });
+               } catch (error) {
+                  this.handleLogSendFailure(error);
+               }
+            }
+
+            private handleLogSendFailure(error: unknown): void {
+               if (!isClientGoneError(error)) {
+                  void Promise.reject(error);
+               }
+            }
+         }
+   } as T;
+}

package/src/lsp/diagnostics-connection.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * 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 { Connection } from 'vscode-languageserver';
+import { isClientGoneError } from '../util/connection-liveness.js';
+
+const wrappedConnections = new WeakSet<object>();
+
+/**
+ * Protect Langium's fire-and-forget diagnostics publish from the expected
+ * failure caused by a peer disconnecting during teardown.
+ *
+ * A publish issued after the connection is disposed throws synchronously
+ * instead of rejecting, and Langium's publisher is a document-phase listener,
+ * so an unguarded throw fails the build that validated the document. The
+ * `try` answers that case with a resolved promise; a guard on the promise
+ * alone never sees it.
+ *
+ * Otherwise the original promise is returned unchanged. The detached catch is
+ * deliberate: it marks the original promise as observed, suppresses only the
+ * expected connection-liveness error, and rethrows unexpected failures so they
+ * stay visible as unhandled rejections, as an unguarded fire-and-forget send
+ * would leave them.
+ */
+export function guardDiagnosticsConnection(connection: Connection): void {
+   if (wrappedConnections.has(connection)) {
+      return;
+   }
+   wrappedConnections.add(connection);
+
+   const sendDiagnostics = connection.sendDiagnostics.bind(connection);
+   connection.sendDiagnostics = params => {
+      let result: Promise<void>;
+      try {
+         result = sendDiagnostics(params);
+      } catch (error: unknown) {
+         if (isClientGoneError(error)) {
+            return Promise.resolve();
+         }
+         throw error;
+      }
+      void result.catch(error => {
+         if (isClientGoneError(error)) {
+            return;
+         }
+         throw error;
+      });
+      return result;
+   };
+}

package/src/lsp/edit-requests-guard.ts

@@ -0,0 +1,152 @@
+/********************************************************************************
+ * Copyright (c) 2026 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';
+import { type LangiumSharedServices } from '@hydranium/langium/lsp';
+import {
+   type Connection,
+   type Disposable,
+   type HandlerResult,
+   LSPErrorCodes,
+   ResponseError,
+   type WorkspaceEdit
+} from 'vscode-languageserver';
+import { LANGUAGE_CLIENT_ID } from '../documents/client-ids.js';
+import { HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+
+const wrappedConnections = new WeakSet<object>();
+
+type Register<P, A extends unknown[], R, E> = (handler: (params: P, ...rest: A) => HandlerResult<R, E>) => Disposable;
+
+/**
+ * Refuse with `ContentModified` a request whose answer edits documents, when
+ * the editor of the request's document is behind the store as it arrives, or
+ * when a document the answer edits changed while it was computed, by another
+ * client, by a rebuild of a closed document or by its release, or its editor
+ * is then behind.
+ *
+ * The editor applies the edits by position to the text it holds, and sent the
+ * request's position in it, so an answer computed on other text rewrites the
+ * wrong characters. The check runs on the answer, since the documents a rename
+ * or code action edits are only known there, and on the connection, so an
+ * adopter's provider for these requests is covered. Edits that arrive by a
+ * resolve request, a file operation, `willSaveWaitUntil`, an inlay hint or a
+ * command's `workspace/applyEdit` are not.
+ *
+ * Read-only answers are not refused, since a refusal would blank them. An
+ * editor ahead of the store does not exist, as its changes reach the store
+ * before any request it sends after them.
+ */
+export function guardEditRequests(connection: Connection, services: LangiumSharedServices): void {
+   const store = services.workspace.TextDocuments;
+   if (wrappedConnections.has(connection) || !(store instanceof HydraniumTextDocuments)) {
+      return;
+   }
+   wrappedConnections.add(connection);
+   // A Hydranium store implies the Hydranium shared services.
+   const keyOf = (uri: URI | string): string =>
+      (services as LangiumSharedServices & ServerSharedServicesMinimal).workspace.DocumentUriPolicy.canonicalUri(uri);
+   const versions = (): ReadonlyMap<string, number> => new Map(store.all().map(document => [document.uri, document.version]));
+   // A closed document records no author per version, so a rebuild of it
+   // while an answer is computed is what refuses the answer. A release clears
+   // the authors, so a reopen would attribute another client's change to the
+   // editor, and refuses it as well.
+   const watching = new Set<{ readonly rebuilt: Set<string>; readonly released: Set<string> }>();
+   services.workspace.DocumentBuilder.onUpdate((changed, deleted) => {
+      if (watching.size === 0) {
+         return;
+      }
+      const keys = [...changed, ...deleted].map(keyOf);
+      for (const watched of watching) {
+         keys.forEach(key => watched.rebuilt.add(key));
+      }
+   });
+   store.onDidReleaseDocument(event => {
+      for (const watched of watching) {
+         watched.released.add(event.uri);
+      }
+   });
+   // The editor's own changes are not counted: it discards or re-filters an
+   // answer that predates them, and counting them would blank completion
+   // while the user types.
+   const changedByAnother = (uri: string, from: number | undefined, to: number): boolean => {
+      if (from === undefined) {
+         return true;
+      }
+      for (let version = from + 1; version <= to; version++) {
+         if (store.getAuthor(uri, version) !== LANGUAGE_CLIENT_ID) {
+            return true;
+         }
+      }
+      return false;
+   };
+   const refused = <E>(): ResponseError<E> =>
+      new ResponseError<E>(LSPErrorCodes.ContentModified, 'The editor does not hold the text the answer was computed on');
+   // The request's position is in the editor's text, which an answer
+   // computed on the store's would be applied past.
+   const behind = (uri: string): boolean => store.isLanguageClientBehind(uri, store.version(uri));
+   /** Watches the documents an answer may edit while it is computed; dispose it after. */
+   const watch = (): { changed(uris: Iterable<string>): boolean; dispose(): void } => {
+      const computedOn = versions();
+      const watched = { rebuilt: new Set<string>(), released: new Set<string>() };
+      watching.add(watched);
+      return {
+         changed: uris =>
+            [...new Set(uris)].some(uri => {
+               const document = store.get(uri);
+               const key = keyOf(uri);
+               const changed =
+                  watched.released.has(key) ||
+                  (document === undefined
+                     ? watched.rebuilt.has(key)
+                     : changedByAnother(uri, computedOn.get(document.uri), document.version));
+               return changed || behind(uri);
+            }),
+         dispose: () => watching.delete(watched)
+      };
+   };
+   const guard =
+      <P extends { readonly textDocument: { readonly uri: string } }, A extends unknown[], R, E>(
+         register: Register<P, A, R, E>,
+         edited: (result: R | null | undefined | void) => Iterable<string> = () => []
+      ): Register<P, A, R, E> =>
+      handler =>
+         register(async (params, ...rest) => {
+            const uri = params.textDocument.uri;
+            if (behind(uri)) {
+               return refused<E>();
+            }
+            const answer = watch();
+            try {
+               const result = await handler(params, ...rest);
+               return result instanceof ResponseError || !answer.changed([uri, ...edited(result)]) ? result : refused<E>();
+            } finally {
+               answer.dispose();
+            }
+         });
+
+   connection.onCompletion = guard(connection.onCompletion.bind(connection));
+   connection.onDocumentFormatting = guard(connection.onDocumentFormatting.bind(connection));
+   connection.onDocumentRangeFormatting = guard(connection.onDocumentRangeFormatting.bind(connection));
+   connection.onDocumentOnTypeFormatting = guard(connection.onDocumentOnTypeFormatting.bind(connection));
+   connection.onRenameRequest = guard(connection.onRenameRequest.bind(connection), editedUris);
+   connection.onCodeAction = guard(connection.onCodeAction.bind(connection), actions =>
+      (actions ?? []).flatMap(action => ('edit' in action && action.edit ? [...editedUris(action.edit)] : []))
+   );
+}
+
+function* editedUris(edit: WorkspaceEdit | null | undefined | void): Iterable<string> {
+   yield* Object.keys(edit?.changes ?? {});
+   for (const change of edit?.documentChanges ?? []) {
+      if ('textDocument' in change) {
+         yield change.textDocument.uri;
+      }
+   }
+}