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

package/src/langium/naming/name-provider.ts

@@ -221,6 +221,11 @@ export interface NameProvider extends LangiumNameProvider {
     * walk traverses through the document root: if the root has its own
     * name, that name IS part of the qualified form. Adopters who want a
     * different boundary override this method.
+    *
+    * May answer as of its first read since the last build: the default
+    * memoises per built node, so a name changed in memory after that read
+    * reads as the old one until its document rebuilds. A node in no document
+    * is named afresh on every call.
     */
    getDocumentQualifiedName(node?: AstNode): string | undefined;
 
@@ -236,6 +241,10 @@ export interface NameProvider extends LangiumNameProvider {
     * string) or no project owns the URI — in those cases project-
     * qualified equals document-qualified, and
     * `HydraniumScopeComputation` skips the multi-tier emit.
+    *
+    * The default memoises it as it does {@link getDocumentQualifiedName}, and
+    * for a node in no document answers the document-qualified name: there is
+    * no project to prefix.
     */
    getProjectQualifiedName(node?: AstNode): string | undefined;
 
@@ -326,6 +335,9 @@ export class DefaultNameProvider implements NameProvider {
     * document's lifetime. Evicted automatically when Langium rebuilds
     * the document.
     *
+    * So a built node renamed in memory reads its old name until the rebuild,
+    * as {@link NameProvider.getDocumentQualifiedName} warns.
+    *
     * Only cached when the computed result is a defined string — `undefined`
     * results re-evaluate on each call (cheap path: `getOwnName` returns
     * undefined for unnamed nodes, no chain walk needed).
@@ -334,7 +346,9 @@ export class DefaultNameProvider implements NameProvider {
    /**
     * Per-document memo for {@link getProjectQualifiedName} results.
     * Sibling of {@link documentQualifiedNameCache}; covers the additional
-    * project-reference-name lookup the project-qualified variant performs.
+    * project-reference-name lookup the project-qualified variant performs,
+    * and goes stale on an in-memory rename the same way, as
+    * {@link NameProvider.getDocumentQualifiedName} warns.
     *
     * **Project-rename caveat.** If `Project.referenceName` mutates without
     * a corresponding document rebuild, cached entries become stale. Adopters

package/src/langium/trivia/document-ending-preserver.ts

@@ -18,20 +18,31 @@ import { type TriviaPreserver } from './trivia-preserver.js';
  * restyle.** A document may legitimately end in blank lines, or deliberately in
  * none, and a write that changed one field is not the place to decide it should
  * not. A serializer cannot make the call either — it has no prior file to
- * consult — which is why the decision lives on the write path.
+ * consult — which is why the decision lives on the write path. Only a blank
+ * document, created or existing, has no ending to keep and takes
+ * {@link defaultEnding}.
  *
  * Line terminators are matched to the body the serializer emits, which is the
  * one thing here that cannot be preserved: keeping them verbatim leaves a
- * rewritten CRLF document with its only CRLFs at the very end.
+ * rewritten CRLF document with its only CRLFs at the very end. A body with no
+ * line break has none to match, so its ending stays as the file had it.
  */
 export class DocumentEndingPreserver implements TriviaPreserver<string> {
+   /** Default {@link defaultEnding}. */
+   static readonly DEFAULT_ENDING = '\n';
+
    readonly id = 'document-ending';
    readonly label = 'Document Ending';
 
+   /** The ending of a blank document, which a created one is: it has none of its own to keep. */
+   protected readonly defaultEnding: string = DocumentEndingPreserver.DEFAULT_ENDING;
+
    extract(document: LangiumDocument): string {
       const source = document.textDocument.getText();
-      const ending = source.slice(source.trimEnd().length);
-      return ending.includes('\r') ? ending.replace(/\r\n/g, '\n') : ending;
+      if (source.trim().length === 0) {
+         return this.defaultEnding;
+      }
+      return source.slice(source.trimEnd().length);
    }
 
    /**
@@ -40,10 +51,15 @@ export class DocumentEndingPreserver implements TriviaPreserver<string> {
     * tell a blank line the serializer emitted as part of a value from one that
     * is merely the end of the file, so it removes both and restores the ending
     * the old document had. A document whose final value just gained trailing
-    * blank lines therefore loses them.
+    * blank lines therefore loses them. An override also takes over matching the
+    * ending's line terminators to the body's.
     */
    apply(serialized: string, trivia: string): string {
-      return serialized.trimEnd() + trivia;
+      const body = serialized.trimEnd();
+      // The body's first line break, since a value may hold the other kind; with none
+      // there is no terminator to match, so the ending stays as extracted.
+      const terminator = /\r?\n/.exec(body)?.[0];
+      return body + (terminator === undefined ? trivia : trivia.replace(/\r?\n/g, terminator));
    }
 }
 

package/src/langium/trivia/trivia-preserver.ts

@@ -26,7 +26,9 @@ import { type RegistryItem } from '../../util/registry.js';
 export interface TriviaPreserver<T = unknown> extends RegistryItem {
    /**
     * Take this preserver's trivia off `document`, while it still holds the text
-    * the write is about to replace.
+    * the write is about to replace. For a document being created, or one the
+    * store holds no text for, `document` is parsed from empty text, so its root
+    * may carry parser errors; a preserver answers its default for it.
     */
    extract(document: LangiumDocument): T;
 

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

@@ -257,17 +257,18 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
     * Warn when a seeded additional document's URI matches no registered
     * language.
     *
-    * Such a document is added to the workspace and indexed, but every
-    * per-language service is resolved per URI — so scope computation, naming,
-    * validation and serialisation all fail to route to it, and it contributes
-    * nothing to the scopes it was written to populate. Nothing else reports
-    * this: the document exists, so no lookup errors, it is simply inert.
+    * Every per-language service is resolved per URI, so the workspace cannot
+    * load such a document: adding it throws, and the startup build fails
+    * with an error naming only the extension, not the document. This
+    * line names the document and the fix first.
     *
-    * The usual cause is a `virtualUri` with no file extension:
-    * `virtualUri(contributor)` yields `virtual:<contributor>`, and routing has
-    * nothing to match on — there is no extension, and a virtual document is
-    * never open in `TextDocuments`, so the declared-languageId rung cannot
-    * serve it either. The convention is to end the URI with a registered
+    * The usual cause is a `fromModel` or `fromStringInLanguage` document
+    * under a `virtualUri` with no file extension: `virtualUri(contributor)`
+    * yields `virtual:<contributor>`, and routing has nothing to match on —
+    * there is no extension, and a virtual document is never open in
+    * `TextDocuments`, so the declared-languageId rung cannot serve it either.
+    * A `fromString` document under such a URI never gets here: its parse
+    * throws first. The convention is to end the URI with a registered
     * extension by passing it as the last segment,
     * `virtualUri(contributor, 'name.<ext>')`.
     */
@@ -277,9 +278,8 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       }
       const extensions = this.languageRegistry.all.flatMap(language => language.LanguageMetaData.fileExtensions);
       this.tracer.warn(
-         `Additional document '${document.uri.toString()}' matches no registered language, so every per-language ` +
-            'service (scope computation, naming, validation, serialization) will fail to route to it and it will ' +
-            `contribute nothing to scopes. End its URI with a registered file extension (${extensions.join(', ')}); ` +
+         `Additional document '${document.uri.toString()}' matches no registered language, so the workspace ` +
+            `cannot load it and the startup build fails. End its URI with a registered file extension (${extensions.join(', ')}); ` +
             'for a virtual document that means passing it as the last segment, `virtualUri(contributor, "name.<ext>")`.'
       );
    }

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

@@ -45,12 +45,12 @@ export const VIRTUAL_SCHEME = 'virtual';
  * `virtual:<contributor>`, which has no extension and so matches no registered
  * language — a trap. Every per-language service is resolved per URI, and a
  * virtual document is never open in `TextDocuments`, so the declared-languageId
- * lookup rung cannot serve it either: the document is indexed but inert,
- * contributing nothing to the scopes it was written to populate, with no error
- * anywhere. Pass the extension as the last segment,
- * `virtualUri(contributor, 'name.<ext>')`. `HydraniumWorkspaceManager` warns
- * when a seeded additional document fails to route, which is where this
- * usually surfaces.
+ * lookup rung cannot serve it either, and the startup build fails. A
+ * `fromString` document throws while parsing; a `fromModel` or
+ * `fromStringInLanguage` document is built, and throws as it is added to the
+ * workspace, after `HydraniumWorkspaceManager` warns that it matches no
+ * language. Pass the extension as the last segment,
+ * `virtualUri(contributor, 'name.<ext>')`.
  *
  * # Relationship to the `$synthetic` node marker
  *

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

@@ -155,7 +155,9 @@ export interface LspServerConnection extends Harness {
     * Seam: the server-side `Connection`, NOT yet attached to a server. The caller
     * composes the services tree onto it (`createXxxServices({ connection })`) and
     * calls `startLanguageServer(services.shared)`, which wires the LSP handlers
-    * and calls `connection.listen()`.
+    * and calls `connection.listen()`; a caller recording only applied edits
+    * skips `startLanguageServer` but still calls `listen()`, as
+    * {@link makeLspServerConnection} says.
     */
    readonly serverConnection: Connection;
    /** Seam: the raw client connection over the in-memory wire; escape hatch for unwrapped requests. */
@@ -333,6 +335,10 @@ function makeCountingStreamPair(): {
  * (it owns the `createServices` callback + `startLanguageServer` + `buildWorkspace`);
  * use this primitive directly when the CALLER must own the tree — e.g. to attach
  * additional protocol heads (data-server, GLSP) onto the same `shared` services.
+ *
+ * To record only {@link LspServerConnection.appliedEdits}, skip
+ * `startLanguageServer`, call `serverConnection.listen()`, and open through
+ * `TextDocuments.notifyDidOpenTextDocument`.
  */
 export function makeLspServerConnection(): LspServerConnection {
    const pair = makeCountingStreamPair();

package/src/testing/run-update-pipeline.ts

@@ -9,7 +9,9 @@
 
 /**
  * Driver for the structured-write transform chain — the rewrite registry plus
- * the serializer — run the way a session's `update` runs it.
+ * the serializer — answering the bare serializer output, without the trivia
+ * and `ModelService` overrides a session's write applies: call
+ * `ModelService.modelToText` with a canonical URI for that text.
  *
  * # Why a driver and not a documented recipe
  *
@@ -91,7 +93,7 @@ export interface UpdatePipelineResult<TTransfer extends TransferElement = Transf
     * surface but it makes the precise assertion unavailable.
     */
    readonly rewritten: TTransfer;
-   /** The serialized text, which is what a session's `update` applies to the store. */
+   /** The serializer's text, without the trivia a session's `update` carries over. */
    readonly text: string;
 }