@hydranium/core 1.0.0-next.94 → 1.0.0-next.96

package/src/langium/language-module.ts

@@ -28,6 +28,10 @@ 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';
@@ -181,6 +185,29 @@ 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
@@ -334,6 +361,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.

package/src/langium/model-service/model-service.ts

@@ -134,6 +134,10 @@ export interface ModelServiceOptions extends LogNameOptions {
 }
 
 /**
+ * The seam every non-LSP head talks to: the data server, the GLSP head and an
+ * adopter's own services reach documents through this slot rather than through
+ * the workspace stores.
+ *
  * In-process facade over the framework's document plumbing
  * (`HydraniumTextDocuments`, `LangiumDocuments`,
  * `DocumentBuilder`, `WritableFileSystemProvider`). Owns the
@@ -192,24 +196,6 @@ export interface ModelServiceOptions extends LogNameOptions {
  * by URI happens here so consumers can subscribe per-document without
  * implementing the URI gate at each callsite.
  *
- * **Generic parameters.**
- * - `TAst` — the AST root type each consumer expects on the returned
- *   {@link AstDocument}. Constrained to {@link AstNode}.
- * - `TDiagnostic` — the AST-layer diagnostic: whatever the build left on
- *   `LangiumDocument.diagnostics`, carried through on the returned
- *   {@link AstDocument}. Defaults to {@link AstDiagnostic}.
- *   **Not the `TransferEncoder`'s parameter of the same name**, which is
- *   that encoder's OUTPUT and so names the wire shape. This one names its
- *   input, and an adopter binds the two to different types.
- * - `TTransfer` — transfer-model root accepted by `update` / `save`
- *   args. Constrained to {@link TransferElement}. Defaults to the
- *   structural base.
- */
-/**
- * The seam every non-LSP head talks to: the data server, the GLSP head and an
- * adopter's own services reach documents through this slot rather than through
- * the workspace stores.
- *
  * **Two families, and the distinction matters more than the names suggest.**
  * `waitFor*` is a pure wait — it never triggers a build, so a caller waiting on
  * a document no build has touched waits until something else builds it.
@@ -232,6 +218,19 @@ export interface ModelServiceOptions extends LogNameOptions {
  * direction is the safe one: the alternative permits stale reads silently. A
  * member taking a phase as a PARAMETER cannot judge statically and so returns
  * `TDiagnostic`, leaving the choice to the caller.
+ *
+ * **Generic parameters.**
+ * - `TAst` — the AST root type each consumer expects on the returned
+ *   {@link AstDocument}. Constrained to {@link AstNode}.
+ * - `TDiagnostic` — the AST-layer diagnostic: whatever the build left on
+ *   `LangiumDocument.diagnostics`, carried through on the returned
+ *   {@link AstDocument}. Defaults to {@link AstDiagnostic}.
+ *   **Not the `TransferEncoder`'s parameter of the same name**, which is
+ *   that encoder's OUTPUT and so names the wire shape. This one names its
+ *   input, and an adopter binds the two to different types.
+ * - `TTransfer` — transfer-model root accepted by `update` / `save`
+ *   args. Constrained to {@link TransferElement}. Defaults to the
+ *   structural base.
  */
 export interface ModelService<
    TAst extends AstNode,
@@ -1175,7 +1174,47 @@ export class DefaultModelService<
          return model;
       }
       const rewritten = await this.rewriteModel(uri, model, cancelToken);
-      return this.serialize(uri, rewritten);
+      const target = UriUtils.toUri(uri);
+      const trivia = this.services.ServiceRegistry?.getServices(target)?.trivia?.TriviaService;
+      // Extracted BEFORE serializing, so it reads the document the write is
+      // about to replace rather than whatever a concurrent build left behind.
+      let document = this.services.workspace.LangiumDocuments.getDocument(target);
+      if (trivia !== undefined && document === undefined) {
+         const source = await this.textToTakeTriviaFrom(uri, target);
+         if (source !== undefined) {
+            document = this.services.workspace.LangiumDocumentFactory.fromString(source, target);
+         }
+      }
+      const extracted = trivia !== undefined && document !== undefined ? trivia.extract(document) : undefined;
+      const serialized = await this.serialize(uri, rewritten);
+      return extracted === undefined ? serialized : trivia!.apply(serialized, extracted, target);
+   }
+
+   /**
+    * The text a write into an unloaded document should take its trivia from —
+    * the open editor's if one holds it, the file's otherwise, and `undefined`
+    * when neither can supply it.
+    *
+    * **A read that fails answers `undefined` rather than throwing.** `getDocument`
+    * is a store read, so an ordinary create answers nothing here and must still
+    * write; letting a permission error or a path that turned into a directory
+    * escape would fail the user's write instead, having found nothing to preserve
+    * in a file the write is about to replace anyway. Losing the comments is
+    * recoverable, and traced; losing the write is neither.
+    */
+   protected async textToTakeTriviaFrom(uri: string, target: URI): Promise<string | undefined> {
+      const open = this.services.workspace.TextDocuments.get(uri)?.getText();
+      if (open !== undefined) {
+         return open;
+      }
+      const fileSystem = this.services.workspace.FileSystemProvider;
+      try {
+         return (await fileSystem.exists(target)) ? await fileSystem.readFile(target) : undefined;
+      } catch (err: unknown) {
+         const detail = err instanceof Error ? err.message : String(err);
+         this.tracer.withUri(uri).debug(`Could not read the file to take trivia from; writing as emitted. ${detail}`);
+         return undefined;
+      }
    }
 
    /**

package/src/langium/residency/cst-residency-service.ts

@@ -185,8 +185,10 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
 }
 
 /**
- * Residency policy that reclaims memory by shedding the concrete syntax tree
- * (CST) of closed documents while keeping their AST resident. Each build refreshes
+ * Keeps a document's CST available to the readers that need one, shedding it
+ * for documents that have gone idle and re-grafting on demand.
+ *
+ * Each build refreshes
  * the idle window of the documents in its batch; when a closed, sheddable
  * document's window elapses, every AST node's `$cstNode` and every reference's
  * `$refNode` are nulled, and the CST root, `Range`s and `Position`s become
@@ -231,10 +233,6 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
  * `NameProvider.getNameNode` chokepoint, the comment provider, and
  * `HydraniumLangiumDocuments.getOrCreateDocument`.
  */
-/**
- * Keeps a document's CST available to the readers that need one, shedding it
- * for documents that have gone idle and re-grafting on demand.
- */
 export interface CstResidencyService {
    /**
     * Ensure `document` has a CST, re-parsing its retained text if it was shed.

package/src/langium/serialization/abstract-serializer.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { isPromiseLike, type MaybePromise, type Tracer, type TransferElement } from '@hydranium/protocol';
+import { type MaybePromise, type Tracer, type TransferElement } from '@hydranium/protocol';
 import { type AstNode, type AstReflection, type GenericAstNode, isAstNode } from '@hydranium/langium';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumLanguageServices } from '../language-module.js';
@@ -66,16 +66,6 @@ export interface AbstractSerializerOptions extends LogNameOptions {
     * the extra property carries a value.
     */
    readonly referenceWrapperTypes?: ReadonlyMap<string, string>;
-   /**
-    * Whether {@link AbstractSerializer.serializeAst} trims trailing whitespace
-    * from the final output (leading whitespace is always trimmed). Defaults to
-    * `true` — the conventional "no trailing blank lines" document shape. Set to
-    * `false` for grammars whose values may legitimately END the document with
-    * blank lines that must survive a round-trip — e.g. a multi-line block-scalar
-    * property (see `YamlSerializerOptions.blockScalarProperties`),
-    * where a trailing-trim would silently eat user-typed blank lines.
-    */
-   readonly trimTrailingWhitespace?: boolean;
 }
 
 /**
@@ -139,29 +129,20 @@ export abstract class AbstractSerializer<
     * Entry point for AST-shape inputs. Typically the grammar root, but any
     * AST node works — the walker is recursive and shape-agnostic.
     *
-    * Preserves the sync fast path: when every subclass override and every
-    * adopter hook is sync, the return is a bare `string` (no Promise
-    * allocation, no microtask). The async branch fires only if at least one
-    * recursive `serializeNode` call resolved to a Promise.
+    * **Emits the model and nothing else — do not trim here.** Trailing
+    * whitespace belongs to the author, and a write path holding the prior
+    * document restores it from there; trimming at this end deletes it before
+    * that restore sees it. A serializer has no prior document to consult, so it
+    * cannot tell a deliberate blank line from an accidental one.
+    *
+    * **Nothing trims what a subclass emits**, at either end. Emitting leading
+    * whitespace therefore puts it in the file, where no write path removes it.
+    *
+    * Returns whatever `serializeNode` returns, so a fully sync subclass keeps a
+    * bare `string` with no promise allocation.
     */
    serializeAst(model: TAst): MaybePromise<string> {
-      const result = this.serializeNode(model, 0);
-      if (isPromiseLike(result)) {
-         return result.then(text => this.trimSerialized(text));
-      }
-      return this.trimSerialized(result);
-   }
-
-   /**
-    * Trim the final serialized output. Leading whitespace is always removed;
-    * trailing whitespace is removed unless {@link AbstractSerializerOptions.trimTrailingWhitespace}
-    * is `false` (which preserves document-ending blank lines, e.g. inside a block scalar).
-    */
-   protected trimSerialized(text: string | undefined): string {
-      if (text === undefined) {
-         return '';
-      }
-      return this.options.trimTrailingWhitespace === false ? text.trimStart() : text.trim();
+      return this.serializeNode(model, 0);
    }
 
    /**