@hydranium/core 1.0.0-next.23 → 1.0.0-next.232

package/src/langium/document-builder/index.ts

@@ -8,5 +8,6 @@
  ********************************************************************************/
 
 export * from './build-pipeline-integration.js';
+export * from './build-session.js';
 export * from './document-builder.js';
 export * from './labeled-phase-listener.js';

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,
@@ -69,17 +69,17 @@ export interface IntegrationServicesOptions<
       /**
        * Module emitted by `langium-cli` (grammar metadata, AST reflection).
        *
-       * `AstReflection` is a SINGLE shared slot, so in a multi-grammar
-       * composition this must be the *combined* generated shared module of
-       * ONE `langium-cli` run over all grammars (one `langium-config.json`
-       * with several entry grammars). Two independently generated language
-       * packages each bind this one slot and the last one wins, leaving the
-       * other grammar's types unknown to reflection — `isSubtype` answers
-       * false, `getTypeMetaData` is empty, and indexing, reference routing
-       * and the transfer encoder all silently miss those types.
+       * `AstReflection` is a single shared slot, so in a multi-grammar
+       * composition this must cover every grammar: either the combined
+       * generated shared module of one `langium-cli` run over all grammars,
+       * or a module binding `AstReflection` to a `CompositeAstReflection`
+       * over each separately generated package's reflection. Spreading two
+       * packages' generated shared modules instead keeps only the last one's
+       * reflection — `isSubtype` answers false for the other grammar's types,
+       * `getTypeMetaData` is empty, and indexing, reference routing and the
+       * transfer encoder all silently miss them.
        * {@link bootstrapLangiumLanguages} throws when a language's types are
-       * wholly absent and warns on a partial gap, because the types cannot
-       * express "these modules came from one generator run".
+       * wholly absent and warns on a partial gap.
        */
       generated: Module<TShared, PartialLangiumSharedServices>;
       /** Adopter's override module (workspace manager, file-system provider, integrity rules, etc.). */
@@ -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>>>;
    };
 
    /**
@@ -154,11 +196,9 @@ export interface IntegrationServicesOptions<
     * language's, so a second grammar that reuses the same service
     * overrides only supplies its own `generated` module.
     *
-    * Every grammar composed here must come from ONE `langium-cli` run —
-    * see the `generated` note on {@link IntegrationServicesOptions.sharedModules}.
-    * The shared `AstReflection` slot cannot hold two independently
-    * generated reflections, so separately generated language packages are
-    * detected at bootstrap rather than supported.
+    * The primary `generated` shared module must reflect every grammar
+    * composed here — see the `generated` note on
+    * {@link IntegrationServicesOptions.sharedModules}.
     *
     * Multi-grammar adopters should also rebind `lsp.configurationRoot`
     * (it defaults to the first registered language's id) and, if they
@@ -188,15 +228,17 @@ export interface AdditionalLanguageModules<
    TLanguage extends LangiumServices
 > {
    /**
-    * Module emitted by `langium-cli` for this grammar — from the SAME run
-    * that produced the primary language's modules and the shared
-    * `generated` module, not a separately generated language package.
+    * Module emitted by `langium-cli` for this grammar. The shared
+    * `generated` module must reflect its types, either from the same run or
+    * through a `CompositeAstReflection`.
     */
    generated: Module<TLanguage, PartialLangiumServices>;
    /** Adopter overrides for this language. Defaults to the primary language's. */
    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 +289,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 +300,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-rule.ts

@@ -49,14 +49,22 @@ export namespace IntegrityPhase {
 }
 
 /**
- * Controls how integrity corrections are persisted for *closed* files. The
- * mode does not reach open files: their corrected text is delivered by the
- * model service's settled-state sync, whatever the mode says.
+ * Controls how integrity corrections are persisted for files no editor holds.
+ * The mode does not reach a file open in the language client: the correction
+ * is delivered to the editor, which shows it as an unsaved change.
  *
- * - `silent`: write to disk immediately; no editor involvement.
- * - `editor`: open the file dirty via `applyEdit`. If the user closes without
- *    saving, the correction is suppressed until the file changes or the
- *    workspace reloads.
+ * - `silent`: write to disk immediately; no editor involvement. For a file
+ *    held only through the data or GLSP head, only while disk still holds the
+ *    text the correction was computed from and the text store still holds the
+ *    correction. Otherwise — the holder has unsaved edits, disk changed behind
+ *    the server, or disk cannot be read — the correction waits in the text
+ *    store for the next save.
+ * - `editor`: leave disk alone and stage the correction; the next open of the
+ *    file takes it over the disk text, and an editor shows it as an unsaved
+ *    change. Until then no editor sees it. A file held only through the data
+ *    or GLSP head is not staged: the correction stays in the text store, and
+ *    since those heads mark only their own edits unsaved, nothing shows that
+ *    store and disk differ until a save or the last close.
  */
 export type IntegritySyncMode = 'silent' | 'editor';
 
@@ -69,7 +77,7 @@ export type IntegritySyncMode = 'silent' | 'editor';
  * bucket. Lower runs first; ties break by registration order.
  */
 export interface IntegrityRule<T extends AstNode = AstNode> extends RegistryItem {
-   /** Which AST node type this rule applies to. */
+   /** Which AST node type this rule applies to, subtypes included. */
    readonly nodeType: string;
    /** At which document state this rule should run. Be aware that extension properties may not be available in all phases. */
    readonly phase: IntegrityPhase;