@hydranium/core 1.0.0-next.39 → 1.0.0-next.391

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.). */
@@ -196,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
@@ -226,13 +223,13 @@ 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. */
@@ -262,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>

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,13 +78,18 @@ 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;
    /**
     * Apply the rule. Returns `true` if the AST was mutated.
     *
+    * The build does not call it for a document whose parse lacks some of its
+    * text, see `hasSkippedText`, unless an override of `isStructurallyBroken`
+    * says otherwise, since a repair is written back by serializing the AST. A
+    * direct call of `IntegrityService.enforceIntegrity` has no such check.
+    *
     * Mirrors Langium's `ValidationCheck` shape (`MaybePromise<void>`) so a
     * rule that must consult an external system can return a promise without
     * forcing every sync rule to pay a microtask tick per node. The