@hydranium/core 1.0.0-next.11 → 1.0.0-next.111

package/src/langium/integration-services.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { inject, type Module } from '@hydranium/langium';
+import { type DeepPartial, inject, type Module } from '@hydranium/langium';
 import {
    createDefaultModule,
    createDefaultSharedModule,
@@ -98,6 +98,31 @@ export interface IntegrationServicesOptions<
        * it is silently inert.
        */
       extra?: ReadonlyArray<Module<TShared, PartialLangiumSharedServices>>;
+      /**
+       * Shared modules composed LAST — after `adopter` — and partial over
+       * `TShared` rather than over Langium's shared services.
+       *
+       * Both differences are the point, and neither is served by
+       * {@link extra}. Most framework shared services are constructed with
+       * no options (`ModelService: services => new DefaultModelService(services)`),
+       * so rebinding the slot is the only way to boot one configured
+       * differently; a caller that needs that is usually a test, and the slot
+       * it needs is as often a framework ADDITION (`Clock`, `Tracer`,
+       * `ProjectManager`) as a Langium one. `extra` can express neither: it
+       * is typed `DeepPartial<LangiumSharedServices>`, and it loses to
+       * `adopter` on every slot the adopter binds.
+       *
+       * Kept separate rather than widening `extra` because `extra` is the
+       * protocol-head tier, and a head must NOT outrank the adopter. Widening
+       * it also does not typecheck — `Module<I, T>` puts `T` in factory
+       * return position, so a head module declaring Langium slot types stops
+       * being assignable once `T` becomes `DeepPartial<TShared>`.
+       *
+       * Composing last means an override wins over everything, including the
+       * adopter. That is what makes it usable for the slots an adopter binds
+       * itself, and why production code should not reach for it.
+       */
+      overrides?: ReadonlyArray<Module<TShared, DeepPartial<TShared>>>;
    };
 
    /**
@@ -134,6 +159,23 @@ export interface IntegrationServicesOptions<
        * still win over heads.
        */
       extra?: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
+      /**
+       * Modules composed LAST, after `adopter`, and partial over `TLanguage`
+       * rather than over Langium's per-language services. The language-tier
+       * twin of {@link IntegrationServicesOptions.sharedModules}'s
+       * `overrides`, and both differences carry the same weight they do
+       * there.
+       *
+       * A per-language framework service is constructed by the framework's
+       * own module with no options
+       * (`IntegrityService: services => new DefaultIntegrityService(services)`),
+       * so booting one configured differently means rebinding the slot.
+       * {@link extra} serves neither half of that: it composes BEFORE
+       * `adopter` and so loses every slot the adopter binds, and it is typed
+       * `PartialLangiumServices`, which cannot express a framework ADDITION
+       * like `IntegrityService` or `AstExtensionService` at all.
+       */
+      overrides?: ReadonlyArray<Module<TLanguage, DeepPartial<TLanguage>>>;
    };
 
    /**
@@ -197,6 +239,8 @@ export interface AdditionalLanguageModules<
    adopter?: (shared: TShared) => Module<TLanguage, PartialLangiumServices>;
    /** Protocol-head modules for this language. Defaults to the primary language's. */
    extra?: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
+   /** Last-composed overrides for this language. Defaults to the primary language's. */
+   overrides?: ReadonlyArray<Module<TLanguage, DeepPartial<TLanguage>>>;
 }
 
 /**
@@ -247,7 +291,9 @@ export function createIntegrationServices<
       sharedModules.generated,
       sharedModule,
       ...(sharedModules.extra ?? []),
-      sharedModules.adopter
+      sharedModules.adopter,
+      // Last, so an override outranks the adopter too — see `overrides`.
+      ...((sharedModules.overrides ?? []) as ReadonlyArray<Module<TShared, PartialLangiumSharedServices>>)
    ) as unknown as TShared;
 
    // Each language gets its OWN `createDefaultModule({ shared })` — the
@@ -256,19 +302,34 @@ export function createIntegrationServices<
    const composeLanguage = (
       generated: Module<TLanguage, PartialLangiumServices>,
       adopter: (shared: TShared) => Module<TLanguage, PartialLangiumServices>,
-      extra: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>
+      extra: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>,
+      overrides: ReadonlyArray<Module<TLanguage, DeepPartial<TLanguage>>>
    ): TLanguage => {
       const defaultLanguageModule = createDefaultModule({ shared }) as unknown as Module<TLanguage, PartialLangiumServices>;
       const serverLanguageModule = createServerLanguageModule(context) as unknown as Module<TLanguage, PartialLangiumServices>;
-      return inject(defaultLanguageModule, generated, serverLanguageModule, ...extra, adopter(shared)) as unknown as TLanguage;
+      return inject(
+         defaultLanguageModule,
+         generated,
+         serverLanguageModule,
+         ...extra,
+         adopter(shared),
+         // Last, so an override outranks the adopter too — see `overrides`.
+         ...(overrides as ReadonlyArray<Module<TLanguage, PartialLangiumServices>>)
+      ) as unknown as TLanguage;
    };
 
    const primaryExtra = (languageModules.extra ?? []) as ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
-   const language = composeLanguage(languageModules.generated, languageModules.adopter, primaryExtra);
+   const primaryOverrides = languageModules.overrides ?? [];
+   const language = composeLanguage(languageModules.generated, languageModules.adopter, primaryExtra, primaryOverrides);
    const languages = [
       language,
       ...additionalLanguages.map(additional =>
-         composeLanguage(additional.generated, additional.adopter ?? languageModules.adopter, additional.extra ?? primaryExtra)
+         composeLanguage(
+            additional.generated,
+            additional.adopter ?? languageModules.adopter,
+            additional.extra ?? primaryExtra,
+            additional.overrides ?? primaryOverrides
+         )
       )
    ];
 

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

@@ -17,6 +17,7 @@ import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumTextDocuments } from '../../documents/hydranium-text-documents.js';
 import { Registry } from '../../util/registry.js';
 import { type ServerLanguageServices } from '../language-module.js';
+import { isVirtualUri } from '../workspace/virtual-document.js';
 import { type IntegrityRuleRegistry } from './integrity-contribution.js';
 import { IntegrityPhase, type IntegrityRule, type IntegritySyncMode } from './integrity-rule.js';
 
@@ -75,6 +76,11 @@ export namespace IntegrityService {
     * at `DocumentState.Validated` and delivered separately via `publishDiagnostics`
     * or the `onModelUpdated` event.
     *
+    * The AST is what this guarantees, not the text. For a closed document whose
+    * repair was STAGED rather than written (`'editor'` sync mode),
+    * `textDocument` still mirrors disk — read the repair off the AST, or from
+    * the staged content the next open consumes.
+    *
     * Invariant: integrity rules only register at Parsed or Linked, so the build
     * is guaranteed post-integrity once it advances past `onBuildPhase(Linked)`
     * into `IndexedReferences`. {@link IntegrityService.register} enforces this at
@@ -310,24 +316,119 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          return;
       }
       const root = document.parseResult.value as TRoot;
-      const newText = await this.services.serializer.Serializer.serializeAst(root);
+      // Extracted while `document` still holds the text being replaced — the
+      // resync that follows overwrites it with `newText`. Absent on a test
+      // stub that binds no trivia group; `createServerLanguageModule` always
+      // provides it, and an empty registry is already the no-op.
+      const trivia = this.services.trivia?.TriviaService;
+      const extracted = trivia?.extract(document);
+      const serialized = await this.services.serializer.Serializer.serializeAst(root);
+      const newText =
+         extracted === undefined ? serialized : trivia!.apply(serialized, extracted, UriUtils.toUri(document.textDocument.uri));
 
       const oldText = document.textDocument.getText();
       if (oldText === newText) {
          return;
       }
 
+      const version = document.textDocument.version;
+      // Commit into the store's own document when the URI is open there, rather
+      // than into whichever text-document object this build is holding. The two
+      // are the same on the LSP path and are NOT when the document was built for
+      // an already-open URI through `fromString`: repairing only the build's copy
+      // leaves the store — the server's authority on what an open document says —
+      // on the unrepaired text, and the reconciling re-parse then redefines
+      // `textDocument` onto the store's object and discards the repair with it.
+      //
+      // Compared against the CST's own text, not against `document.textDocument`.
+      // That object IS the store's on the LSP path, so asking it whether the
+      // store still agrees compares the store with itself and can only ever say
+      // yes — the guard would be vacuous exactly where an editor race can happen.
+      // The CST's `fullText` is the text that actually produced this AST, which
+      // is the only thing a repair derived from it is valid against. A document
+      // with no CST (built from a model rather than parsed) has no better answer
+      // than the text it is carrying.
+      const parsedFrom = document.parseResult.value.$cstNode?.root.fullText ?? oldText;
+      const commit = this.textDocuments.commitRepair(document.textDocument.uri, parsedFrom, newText);
+      if (commit.status === 'stale') {
+         // An edit landed after the parse this repair came from, so the repair
+         // describes text the store has already replaced. Abandon it rather than
+         // persist or stage it: that edit drives a build of its own, which
+         // re-runs these rules against what the document actually says.
+         //
+         // Abandoning the WRITE is only half of it. The build carries on to its
+         // settled phase with whatever AST is registered, and every settled
+         // consumer reads that AST rather than the store — so leaving the rule's
+         // mutation in place would answer questions about this document from a
+         // parse of text nobody has. Reconciling discards it by re-reading the
+         // store, which is what the document now has to agree with.
+         await this.reconcileDocument(document, cancelToken);
+         return;
+      }
+
       // Keep the same version so HydraniumTextDocuments doesn't reject subsequent client edits.
       // Use manager.update so the `instanceof FullTextDocument` gate in the bare
       // `TextDocument.update` doesn't trip on adopter-custom text-document types.
-      const textDocument = this.textDocuments.update(document.textDocument, [{ text: newText }], document.textDocument.version);
+      const textDocument =
+         commit.status === 'committed' ? commit.document : this.textDocuments.update(document.textDocument, [{ text: newText }], version);
 
       await this.syncCorrections(textDocument);
 
+      await this.reconcileDocument(document, cancelToken);
+
+      // Re-version against the REPAIRED text, after either branch. The repair is
+      // a content change the store has not seen: whatever reconciliation ran
+      // during the re-parse saw the text on disk, which in `'editor'` sync mode
+      // is the PRE-repair text. Leave the sequence describing that and the next
+      // open hashes the repair, finds a mismatch and steps the version again, so
+      // every based-on version taken from this build is stale before it is used.
+      // Falls back to the pre-re-parse number for a URI the store never tracked,
+      // where there is no sequence to advance; an OPEN document answers
+      // `undefined` and keeps the store's own version, which is not this
+      // method's to move.
+      //
+      // Deliberately NOT gated on cancellation, unlike the entry to this method:
+      // `syncCorrections` has already written or staged the repair by now, so a
+      // preempted build that skipped this would leave the sequence describing
+      // text that is no longer there.
+      //
+      // Gated on the document being closed, because the fallback restores a
+      // number this method captured off whatever object it started with — and
+      // for a separately created document that is its own seeded numbering, not
+      // the store's. Applying it to the store's document (which the re-parse has
+      // by then made `textDocument`) would roll the shared version backwards.
+      // The store's own answer for an open document is `undefined` either way.
+      if (!this.textDocuments.isOpen(document.textDocument.uri)) {
+         const reconciled = this.textDocuments.reconcileExternalContent(document.textDocument.uri, newText) ?? version;
+         if (document.textDocument.version !== reconciled) {
+            this.textDocuments.update(document.textDocument, [], reconciled);
+         }
+      }
+   }
+
+   /**
+    * Bring `document` back into agreement with the text it is supposed to
+    * describe, after a rule has mutated its AST.
+    *
+    * Used for a correction that was applied and for one that was abandoned,
+    * because the document is left inconsistent either way: applied, the text
+    * moved under the CST; abandoned, the AST carries a mutation the text never
+    * had. Both are the same question — re-read and re-derive — and the phase is
+    * what decides how far that has to go.
+    */
+   protected async reconcileDocument(document: LangiumDocument, cancelToken?: CancellationToken): Promise<void> {
       if (document.state <= DocumentState.Parsed) {
          // Parsed-phase correction: re-parse only. The build pipeline still runs
          // IndexedContent → ComputedScopes → Linked → … on the fresh AST afterwards,
          // so the document reconciles naturally with no extra work here.
+         //
+         // Except for a closed document whose repair did not reach disk — `'editor'`
+         // sync mode stages it instead of writing it — where the re-parse is SKIPPED:
+         // Langium's factory gates the parse on the CST's `fullText`, which still
+         // equals the disk text the same call re-reads and redefines `textDocument`
+         // over. So `document.textDocument` is NOT post-integrity for such a
+         // document — it mirrors disk, and the AST is the only place the repair is
+         // legible, until an open consumes the staging.
          await this.documentBuilder.reparse(document, cancelToken);
       } else {
          // Linked-phase (or later) correction. The rule mutated the AST in place but
@@ -364,6 +465,19 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          return;
       }
 
+      // A virtual document has no disk backing, so neither persisting nor
+      // staging applies: there is no file to write and no editor that could open
+      // one. `URI.fsPath` yields a path for any scheme, so handing this to the
+      // provider would address `<cwd>/<contributor>/<name>` — an unrelated
+      // location a disk-backed provider refuses outright, turning a repair that
+      // was never persistable into a build failure. The correction is already on
+      // the AST and in the text store, which is the whole of where a virtual
+      // document lives, so there is nothing further to propagate.
+      if (isVirtualUri(document.uri)) {
+         this.tracer.with(document.uri).debug('Virtual document: correction kept in memory, nothing to persist');
+         return;
+      }
+
       // Closed files, silent mode: write to disk directly.
       if (this.syncMode === 'silent') {
          // Async write so the integrity pass does not block the event loop on a slow filesystem.

package/src/langium/keys/containment.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Containment-array maintenance for callers that build or delete AST nodes
+ * programmatically — a GLSP operation handler being the usual one.
+ *
+ * **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
+ * `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
+ * wrong node. Shipping the constraint's statement without the code that
+ * discharges it leaves every adopter in that position re-deriving thirty lines
+ * from prose, and both failures are silent.
+ *
+ * The population is narrower than "anyone creating elements from a diagram": it
+ * takes a grammar with UNNAMED element types, programmatic creation or deletion
+ * of them, and this key provider. A grammar whose diagram elements are all
+ * named never reaches it, and the two ways out are named on the provider —
+ * give the type a name, or bind a provider whose fallback is content-derived.
+ *
+ * **Free functions, and deliberately not a step on the AST builder.** Building a
+ * node detached and appending it later is legitimate, so a containment step
+ * cannot be mandatory; and an optional fluent step could not check the index
+ * against the array unless it were handed the array, at which point it is these
+ * signatures with more ceremony. `AstNodeInit` already accepts the three fields
+ * for a caller who has them, which is the case these cover: it is the INDEX that
+ * cannot be known without reading the array.
+ */
+
+import type { AstNode } from '@hydranium/langium';
+import type { Mutable } from '@hydranium/protocol';
+
+/**
+ * Append `child` to `children`, stamping the Langium containment plumbing
+ * (`$container`, `$containerProperty`, `$containerIndex`) so a positional key
+ * can address it.
+ *
+ * `property` and `children` are separate parameters rather than one property
+ * name the function dereferences: the array is what the index is derived from,
+ * so taking it directly is what makes the two agree by construction instead of
+ * by a lookup that a typo could point elsewhere.
+ *
+ * @returns `child`, so a caller can append and use it in one expression.
+ */
+export function appendChild<TChild extends AstNode>(container: AstNode, property: string, children: TChild[], child: TChild): TChild {
+   const mutable = child as Mutable<TChild>;
+   mutable.$container = container;
+   mutable.$containerProperty = property;
+   mutable.$containerIndex = children.length;
+   children.push(child);
+   return child;
+}
+
+/**
+ * Remove every entry of `children` that is in `toRemove`, then renumber the
+ * survivors' `$containerIndex`.
+ *
+ * Mutates `children` in place rather than returning a new array, because the
+ * caller's array IS the AST's containment list — replacing the reference would
+ * leave the parent pointing at the old one.
+ *
+ * @returns how many entries were removed, so a caller can tell a no-op delete
+ * from one that changed the model without comparing lengths itself.
+ */
+export function removeChildren<TChild extends AstNode>(children: TChild[], toRemove: ReadonlySet<TChild>): number {
+   if (toRemove.size === 0) {
+      return 0;
+   }
+   const survivors = children.filter(child => !toRemove.has(child));
+   const removed = children.length - survivors.length;
+   children.length = 0;
+   for (const [index, child] of survivors.entries()) {
+      (child as Mutable<TChild>).$containerIndex = index;
+      children.push(child);
+   }
+   return removed;
+}

package/src/langium/keys/index.ts

@@ -7,6 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './containment.js';
 export * from './element-key-provider.js';
 export * from './name-based-key-provider.js';
 export * from './positional-key-provider.js';

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

@@ -55,6 +55,10 @@ import { type NameProvider } from '../naming/name-provider.js';
  * - 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.
+ *
  * Adopters that need insert / delete stability for unnamed types should
  * give those types a name in the grammar, or bind a key provider whose
  * fallback is content-derived rather than positional.

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.