@hydranium/core 1.0.0-next.283 → 1.0.0-next.285

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/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;
 }