@hydranium/core 1.0.0-next.31 → 1.0.0-next.315

package/src/langium/integration-services.ts

@@ -18,8 +18,7 @@ import {
 } from '@hydranium/langium/lsp';
 import { DEFAULT_EAGER_SERVICES, bootstrapLangiumLanguages } from './bootstrap.js';
 import { createServerLanguageModule } from './language-module.js';
-import { createServerSharedModule, type ServerModuleContext } from './module.js';
-import type { ServerSharedServicesMinimal } from './shared-services.js';
+import { createServerSharedModule, type ServerModuleContext, type ServerSharedServices } from './module.js';
 
 /**
  * Options accepted by {@link createIntegrationServices}. Wraps the
@@ -40,7 +39,7 @@ import type { ServerSharedServicesMinimal } from './shared-services.js';
  */
 export interface IntegrationServicesOptions<
    TContext extends ServerModuleContext,
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TShared extends LangiumSharedServices & ServerSharedServices,
    TLanguage extends LangiumServices
 > {
    /**
@@ -69,17 +68,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.). */
@@ -104,7 +103,7 @@ export interface IntegrationServicesOptions<
        *
        * Both differences are the point, and neither is served by
        * {@link extra}. Most framework shared services are constructed with
-       * no options (`ModelService: services => new ModelService(services)`),
+       * 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`,
@@ -159,6 +158,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>>>;
    };
 
    /**
@@ -179,11 +195,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
@@ -209,19 +223,21 @@ export interface IntegrationServicesOptions<
  * differs only in its grammar-generated module.
  */
 export interface AdditionalLanguageModules<
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TShared extends LangiumSharedServices & ServerSharedServices,
    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>>>;
 }
 
 /**
@@ -243,7 +259,7 @@ export interface AdditionalLanguageModules<
  */
 export function createIntegrationServices<
    TContext extends ServerModuleContext,
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TShared extends LangiumSharedServices & ServerSharedServices,
    TLanguage extends LangiumServices
 >(
    options: IntegrationServicesOptions<TContext, TShared, TLanguage>
@@ -283,19 +299,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,23 @@ 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. A server's first write, whichever language
+ *    makes it, is logged at `info`, naming the file and the `syncMode` option.
+ * - `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 +78,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;