@hydranium/core 1.0.0-next.22 → 1.0.0-next.220

package/src/langium/language-module.ts

@@ -28,11 +28,18 @@ 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 { type ServerModuleContext, type ServerSharedServices } from './module.js';
 
 /**
@@ -154,7 +161,7 @@ export interface ServerAddedServices {
        * 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 +188,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 +249,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 +266,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."
       );
    }
 }
@@ -334,6 +364,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 +394,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