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

package/src/langium/keys/containment.ts

@@ -13,8 +13,9 @@
  *
  * **These live beside the key provider because the constraint is the key
  * provider's.** `NameBasedKeyProvider` keys a node the `NameProvider` gives no
- * name from its position, as `` `${$containerProperty}@${$containerIndex}` ``,
- * so a node appended with a bare `array.push` carries neither and
+ * name from its position, as `` `${$containerProperty}@${$containerIndex}` ``
+ * (`` `${$containerProperty}@` `` in a single-valued property), so a node
+ * appended with a bare `array.push` carries neither and
  * `getElementKey` answers `undefined` — the element has no key at all, and the
  * GLSP index cannot address it. Deleting from the middle of such a list must
  * renumber the survivors, or an id derived later in the same command names the

package/src/langium/keys/name-based-key-provider.ts

@@ -44,20 +44,25 @@ import { type NameProvider } from '../naming/name-provider.js';
  * `NameProvider` gives no name. For grammars with unnamed element types the
  * reorder / insert / delete stability above does NOT apply to those nodes:
  * their keys move when their index moves, so a mid-array insert or delete
- * renumbers every later sibling.
+ * renumbers every later sibling. A node held in a single-valued property has
+ * no `$containerIndex` and falls back to `` `${$containerProperty}@` ``; the
+ * trailing `@` keeps its key apart from a sibling named after the property.
  *
  * Two consequences for a caller creating such nodes programmatically
  * (a GLSP operation handler is the usual case):
  *
- * - A node appended with a bare `array.push` has no `$containerProperty` /
- *   `$containerIndex`, so `getElementKey` returns `undefined` and the node
- *   has no key at all. The containment plumbing has to be stamped.
+ * - A node appended with a bare `array.push`, or assigned to a single-valued
+ *   property without its `$containerProperty`, has no container position, so
+ *   `getElementKey` returns `undefined` and the node has no key at all. The
+ *   containment plumbing has to be stamped.
  * - After a removal, surviving siblings need their `$containerIndex`
  *   renumbered, or a key derived afterwards addresses the wrong node.
  *
- * {@link appendChild} and {@link removeChildren} discharge both, and ship
- * beside this provider because the constraint is this provider's rather than
- * any caller's.
+ * {@link appendChild} and {@link removeChildren} discharge both for arrays,
+ * and ship beside this provider because the constraint is this provider's
+ * rather than any caller's. A single-valued property needs no helper: build
+ * the node with its `$container` and `$containerProperty`, which
+ * `buildAstNode` accepts.
  *
  * Adopters that need insert / delete stability for unnamed types should
  * give those types a name in the grammar, or bind a key provider whose
@@ -137,14 +142,21 @@ export class NameBasedKeyProvider implements ElementKeyProvider {
    }
 
    /**
-    * Fallback segment for unnamed intermediate ancestors —
-    * `containerProperty@containerIndex`. Returns `undefined` when the
-    * node has no container position, which short-circuits the walk.
+    * Segment for a node the `NameProvider` gives no name —
+    * `containerProperty@containerIndex`, or `containerProperty@` when the
+    * container holds no array in that property, attached or not. Returns
+    * `undefined` when the node has no container position: the node itself
+    * then has no key, and an ancestor's level is left out of the key.
     */
    protected unidentifiedSegment(node: AstNode): string | undefined {
-      if (node.$containerProperty === undefined || node.$containerIndex === undefined) {
+      const property = node.$containerProperty;
+      if (property === undefined) {
          return undefined;
       }
-      return `${node.$containerProperty}@${node.$containerIndex}`;
+      if (node.$containerIndex !== undefined) {
+         return `${property}@${node.$containerIndex}`;
+      }
+      // An array member without its index stays keyless rather than share `property@` with its siblings.
+      return Array.isArray((node.$container as Record<string, unknown> | undefined)?.[property]) ? undefined : `${property}@`;
    }
 }

package/src/langium/language-module.ts

@@ -28,11 +28,19 @@ import { DefaultReferenceBuilder, type ReferenceBuilder } from './scope/referenc
 import { type ScopeExtensionContribution } from './scope/scope-extension-contribution.js';
 import { DefaultScopeExtensionService, type ScopeExtensionService } from './scope/scope-extension-service.js';
 import { type Serializer } from './serialization/serializer.js';
+import { type TriviaContribution } from './trivia/trivia-contribution.js';
+import { type TriviaService, DefaultTriviaService } from './trivia/trivia-service.js';
+import { CommentPreserverContribution } from './trivia/comment-preserver.js';
+import { DocumentEndingPreserverContribution } from './trivia/document-ending-preserver.js';
 import { type UpdateRewriteContribution } from './update-rewrite/update-rewrite-contribution.js';
 import { DefaultUpdateRewriteService, type UpdateRewriteService } from './update-rewrite/update-rewrite-service.js';
 import { HydraniumDocumentValidator } from './validation/document-validator.js';
 import { type ValidationCheckContribution } from './validation/validation-contribution.js';
-import { ValidationContributionCollector } from './validation/validation-contribution-collector.js';
+import {
+   DefaultValidationContributionCollector,
+   type ValidationContributionCollector
+} from './validation/validation-contribution-collector.js';
+import { HydraniumAstNodeLocator } from './workspace/ast-node-locator.js';
 import { type ServerModuleContext, type ServerSharedServices } from './module.js';
 
 /**
@@ -149,12 +157,12 @@ export interface ServerAddedServices {
    serializer: {
       /**
        * Typed home for grammar-specific round-trip serialisers.
-       * `ModelService.serialize` resolves it via
+       * `DefaultModelService.serialize` resolves it via
        * `services.ServiceRegistry.getServices(uri).serializer.Serializer`, so
        * multi-grammar workspaces route to the right serializer per file. The
        * framework default throws a clear "no Serializer registered" error;
        * adopters bind their own per-language subclass to enable
-       * `ModelService.update` / `ModelService.save`.
+       * a client session's `update` / `save`.
        */
       Serializer: Serializer;
    };
@@ -181,10 +189,33 @@ export interface ServerAddedServices {
        */
       rules: Record<string, IntegrityRuleContribution>;
    };
+   trivia: {
+      /**
+       * Runs the registered trivia preservers around a write, so what a
+       * document carries that its model does not — its comments, the whitespace
+       * it ended with — survives being re-serialized from that model.
+       *
+       * A separate group from {@link Serializer} because a preserver needs the
+       * document being overwritten, which a serializer is never given:
+       * `serializeAst` could reach one through its model, but
+       * `serializeTransfer` receives a plain wire object with no document at
+       * all, so folding this in would carry trivia on one write path and
+       * silently not on the other.
+       */
+      TriviaService: TriviaService;
+      /**
+       * Declarative {@link TriviaContribution} group. Distinct sub-keys
+       * accumulate across framework + adopter modules via Langium's deep-merge;
+       * binding one the framework already uses REPLACES it. The framework ships
+       * a sub-key per preserver, so an adopter replacing `comments` keeps
+       * `documentEnding` and whatever else ships beside it.
+       */
+      preservers: Record<string, TriviaContribution>;
+   };
    updateRewrite: {
       /**
        * Per-language runner for transfer-model rewrites applied on the
-       * structured write path of `ModelService.update` / `save`, before
+       * structured write path of a client session's `update` / `save`, before
        * serialisation. The RPC-update-stage sibling of the
        * {@link IntegrityService} / {@link AstExtensionService} registries.
        * Framework default is a no-op (zero rewrites registered) — adopters
@@ -219,7 +250,7 @@ export interface ServerAddedServices {
       ValidationContributionCollector: ValidationContributionCollector;
       /**
        * Declarative {@link ValidationCheckContribution} group. Each sub-key
-       * binds a contribution; the {@link ValidationContributionCollector}
+       * binds a contribution; the {@link DefaultValidationContributionCollector}
        * iterates this group at construction and calls each contribution's
        * `registerValidationChecks(registry)`, where `registry` is a thin
        * adapter over Langium's `ValidationRegistry`. The framework binds
@@ -236,12 +267,12 @@ export interface ServerAddedServices {
 class UnboundSerializer implements Serializer {
    serializeAst(_model: AstNode): string {
       throw new Error(
-         'No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before calling ModelService.update / ModelService.save.'
+         "No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before writing through a client session's update or save."
       );
    }
    serializeTransfer(_model: TransferElement): string {
       throw new Error(
-         'No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before calling ModelService.update / ModelService.save.'
+         "No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before writing through a client session's update or save."
       );
    }
 }
@@ -325,7 +356,8 @@ export function createServerLanguageModule(
          CommentProvider: services => new HydraniumCommentProvider(services)
       },
       workspace: {
-         AstNodeDescriptionProvider: services => new HydraniumAstNodeDescriptionProvider(services)
+         AstNodeDescriptionProvider: services => new HydraniumAstNodeDescriptionProvider(services),
+         AstNodeLocator: () => new HydraniumAstNodeLocator()
       },
       ast: {
          AstExtensionService: services => new DefaultAstExtensionService(services),
@@ -334,6 +366,17 @@ export function createServerLanguageModule(
       serializer: {
          Serializer: () => new UnboundSerializer()
       },
+      // Bound with a sub-key per preserver so an adopter can replace one and
+      // keep the other. Adopters MUST avoid these two keys for their own
+      // contributions unless replacement is what they mean — Langium's
+      // deep-merge is last-wins on same-key leaves.
+      trivia: {
+         TriviaService: services => new DefaultTriviaService(services),
+         preservers: {
+            comments: services => new CommentPreserverContribution(services),
+            documentEnding: () => new DocumentEndingPreserverContribution()
+         }
+      },
       // The per-URI serialise / re-parse path only fires when a rule mutates,
       // so the no-op default is safe even before adopters bind a real
       // serializer / parser.
@@ -353,7 +396,7 @@ export function createServerLanguageModule(
          // option values rebinds the slot with its own `new
          // HydraniumDocumentValidator(services, { … })`.
          DocumentValidator: services => new HydraniumDocumentValidator(services),
-         ValidationContributionCollector: services => new ValidationContributionCollector(services),
+         ValidationContributionCollector: services => new DefaultValidationContributionCollector(services),
          checks: {
             // Flags name-bearing nodes whose name value contains the
             // configured name separator, so qualified names can never collide