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

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

@@ -0,0 +1,55 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type LangiumDocument } from '@hydranium/langium';
+import { type TriviaContribution, type TriviaRegistry } from './trivia-contribution.js';
+import { type TriviaPreserver } from './trivia-preserver.js';
+
+/**
+ * Carries the whitespace a document ended with across a write.
+ *
+ * **Normalising this to one final newline rewrites files nobody asked to
+ * 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.
+ *
+ * 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.
+ */
+export class DocumentEndingPreserver implements TriviaPreserver<string> {
+   readonly id = 'document-ending';
+   readonly label = 'Document 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;
+   }
+
+   /**
+    * **Override for a grammar whose CONTENT can end in whitespace** — a
+    * block-scalar property as the document's last value, say. The trim cannot
+    * 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.
+    */
+   apply(serialized: string, trivia: string): string {
+      return serialized.trimEnd() + trivia;
+   }
+}
+
+/** Registers {@link DocumentEndingPreserver}; bound at `trivia.preservers.documentEnding`. */
+export class DocumentEndingPreserverContribution implements TriviaContribution {
+   registerTriviaPreservers(registry: TriviaRegistry): void {
+      registry.register(new DocumentEndingPreserver());
+   }
+}

package/src/langium/trivia/index.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+export * from './comment-preserver.js';
+export * from './document-ending-preserver.js';
+export * from './trivia-contribution.js';
+export * from './trivia-preserver.js';
+export * from './trivia-service.js';

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

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type Disposable } from 'vscode-languageserver';
+import { type TriviaPreserver } from './trivia-preserver.js';
+
+/**
+ * Registry handed to a {@link TriviaContribution}. Implemented by the trivia
+ * service; a contribution receives it and registers one or many preservers.
+ * Doubles as the low-level imperative API for the rare runtime-dynamic case.
+ */
+export interface TriviaRegistry {
+   register(preserver: TriviaPreserver): Disposable;
+}
+
+/**
+ * Declarative registration of trivia preservers. Bound under the module's
+ * `trivia.preservers` contribution group; the trivia service reads its own
+ * group at construction and calls this method, handing itself in as the
+ * registry.
+ *
+ * The framework binds one sub-key per preserver it ships rather than one for
+ * all of them, so an adopter replacing `comments` — a grammar identifying its
+ * nodes by something no name property holds — keeps the rest. Langium's
+ * deep-merge is last-wins on same-key leaves, so binding a sub-key REPLACES the
+ * framework's contribution under it rather than adding to it.
+ *
+ * The domain-qualified method name lets one cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface TriviaContribution {
+   registerTriviaPreservers(registry: TriviaRegistry): void;
+}

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

@@ -0,0 +1,54 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type LangiumDocument, type URI } from '@hydranium/langium';
+import { type RegistryItem } from '../../util/registry.js';
+
+/**
+ * One kind of trivia — what a document carries that its model does not, so a
+ * write that re-serializes from the model would otherwise lose it.
+ *
+ * **Two phases, because there is a suspension point between them.** The write
+ * path extracts, awaits the serializer, then applies; and the preserver is a
+ * per-language singleton, so two concurrent writes would clobber each other if
+ * it held the extracted value itself. `T` therefore travels through the caller.
+ *
+ * Declared with METHODS rather than arrow properties: an implementation
+ * narrowing `T` stays assignable only under method-parameter bivariance, which
+ * arrow properties lose.
+ */
+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.
+    */
+   extract(document: LangiumDocument): T;
+
+   /**
+    * Put `trivia` back into `serialized`, returning the text the NEXT preserver
+    * sees — the chain is a fold, so an implementation must derive its positions
+    * from the text it is handed rather than from the document it extracted from.
+    */
+   apply(serialized: string, trivia: T, uri: URI): string;
+}
+
+/**
+ * One preserver's output, kept beside the preserver that produced it.
+ *
+ * Pairing them is what lets the chain stay agnostic: it never learns what a
+ * payload IS, only which preserver knows how to apply it, so a preserver can
+ * use whatever shape suits it without the service naming that shape.
+ */
+export interface ExtractedTrivia {
+   readonly preserver: TriviaPreserver;
+   readonly trivia: unknown;
+}
+
+/** Everything the registered preservers took off one document, in the order they ran. */
+export type DocumentTrivia = readonly ExtractedTrivia[];

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

@@ -0,0 +1,99 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type Tracer } from '@hydranium/protocol';
+import { type LangiumDocument, type URI } from '@hydranium/langium';
+import { type Disposable } from 'vscode-languageserver';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { Registry } from '../../util/registry.js';
+import { type TriviaRegistry } from './trivia-contribution.js';
+import { type DocumentTrivia, type TriviaPreserver } from './trivia-preserver.js';
+
+/**
+ * Public contract for the per-language trivia runner. Extends the
+ * {@link TriviaRegistry} contributions register through with the entry points
+ * the write paths call around serialization.
+ *
+ * Adopter overrides go through {@link DefaultTriviaService}; the interface keeps
+ * the public API stable while the registry stays `protected` on the class.
+ */
+export interface TriviaService extends TriviaRegistry {
+   /** Remove a preserver by id. Returns `true` if one was removed. */
+   unregister(id: string): boolean;
+
+   /**
+    * Run every registered preserver's `extract` over `document`, in priority
+    * order, while it still holds the text the write is about to replace.
+    */
+   extract(document: LangiumDocument): DocumentTrivia;
+
+   /**
+    * Fold `serialized` through every extracted entry, handing each preserver
+    * back its own payload, and return the text to write.
+    */
+   apply(serialized: string, trivia: DocumentTrivia, uri: URI): string;
+}
+
+/** Construction options for {@link DefaultTriviaService}. */
+export type TriviaServiceOptions = LogNameOptions;
+
+/**
+ * Default {@link TriviaService}: an ordered registry of preservers, run around
+ * the serializer on every structured write.
+ *
+ * **An empty registry is a no-op**, which is how preservation is switched off —
+ * there is no enabled flag, and a preserver that is not registered costs
+ * nothing rather than being asked and declining.
+ *
+ * **Per-language service.** Comment terminals come from the grammar, so this
+ * cannot be shared; `ModelService` resolves it via
+ * `ServiceRegistry.getServices(uri)` so a multi-grammar workspace routes each
+ * write to the right preservers.
+ */
+export class DefaultTriviaService implements TriviaService {
+   /** Registry of preservers, keyed by id, iterated in priority order. */
+   protected readonly preservers = new Registry<TriviaPreserver>();
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: HydraniumLanguageServices,
+      options: TriviaServiceOptions = {}
+   ) {
+      this.tracer = services.shared.Tracer.for(options.logName ?? 'Trivia').trace('instantiated');
+
+      // Optional chaining tolerates incomplete test stubs; production wiring
+      // always provides the slot via `createServerLanguageModule`.
+      const contributions = services.trivia?.preservers ?? {};
+      for (const contribution of Object.values(contributions)) {
+         contribution.registerTriviaPreservers(this);
+      }
+   }
+
+   register(preserver: TriviaPreserver): Disposable {
+      return this.preservers.register(preserver);
+   }
+
+   unregister(id: string): boolean {
+      return this.preservers.unregister(id);
+   }
+
+   extract(document: LangiumDocument): DocumentTrivia {
+      return this.preservers.all().map(preserver => ({ preserver, trivia: preserver.extract(document) }));
+   }
+
+   /**
+    * Fold, not map: each preserver sees what the ones before it produced, so a
+    * pair that touch the same region resolve by priority rather than by
+    * whichever happened to register first.
+    */
+   apply(serialized: string, trivia: DocumentTrivia, uri: URI): string {
+      return trivia.reduce((text, entry) => entry.preserver.apply(text, entry.trivia, uri), serialized);
+   }
+}

package/src/testing/node/scratch-workspace.ts

@@ -21,8 +21,8 @@
  * committed sample workspace can **rewrite the sample files**, after which
  * every later run asserts against already-repaired input: a suite that passes
  * while testing nothing. The same applies to a fixture built in place, which
- * additionally loses its explanatory comments, because the write-back goes
- * through the serializer.
+ * additionally comes back in the serializer's layout, because the write-back
+ * goes through it.
  *
  * The second reason is cleanup. Hand-rolled `mkdtempSync` without a matching
  * `rmSync` leaks a directory per test run into the OS temp dir, which nobody