@hydranium/core 1.0.0-next.10

package/lib/langium/bootstrap.d.ts

@@ -0,0 +1,224 @@
+/********************************************************************************
+ * 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 LangiumServices, type LangiumSharedServices } from '@hydranium/langium/lsp';
+import type { ServerSharedServicesMinimal } from './shared-services.js';
+/**
+ * Verify that the slots `@hydranium/core` is responsible for
+ * binding are populated after composition. Throws an error with a
+ * teaching message naming the missing slot and the most likely cause.
+ *
+ * Invoked from {@link bootstrapLangium}; consumers don't normally call
+ * this directly. Exported so framework integration tests can pin the
+ * error-message contract.
+ *
+ * Why a runtime check on top of TypeScript: in practice the consumer
+ * pattern `inject(...) as MyServices` widens away the composition shape
+ * — a missing module compiles but produces a half-bound services tree.
+ * The first failure surfaces deep inside Langium with a stack pointing
+ * at an unrelated slot. This assertion fails fast at bootstrap with a
+ * message that points at the actual cause and the fix.
+ */
+export declare function assertCoreSlotsBound(shared: LangiumSharedServices, language: LangiumServices): void;
+/**
+ * Environment variable that opts into the strict-binding diagnostic. Set
+ * to `1` / `true` / `yes` / `on` to enable; unset (the default) skips the
+ * check entirely. Off by default because it is a development aid, not a
+ * production gate.
+ */
+export declare const STRICT_BINDINGS_ENV = "HYDRANIUM_STRICT_BINDINGS";
+/**
+ * Opt-in diagnostic (gated by {@link STRICT_BINDINGS_ENV}): warn when a
+ * framework slot is bound to a value that does NOT extend the framework
+ * base class for that slot. Langium DI is structural, so such a binding
+ * compiles and runs but silently drops the framework behaviour the base
+ * carries (e.g. a `ScopeComputation` not extending
+ * {@link HydraniumScopeComputation} loses tier-aware export). Warns, never
+ * throws — safe to leave enabled in a dev/test run; a no-op unless the env
+ * var is set.
+ *
+ * Invoked from {@link bootstrapLangium} after {@link assertCoreSlotsBound}.
+ * Exported so framework integration tests can pin the warning contract.
+ */
+export declare function warnOnUnexpectedBindings(shared: LangiumSharedServices, language: LangiumServices): void;
+/**
+ * Default eager-construction list for {@link bootstrapLangium}. Contains
+ * the framework services whose constructors attach to the build pipeline —
+ * either as a direct `documentBuilder` listener or as a
+ * `BuildPhasePassService` pass — and which therefore must be instantiated
+ * before the first build cycle:
+ *
+ * - **`workspace.ProjectManager`** — subscribes to
+ *   `documentBuilder.onUpdate` to track descriptor file changes.
+ * - **`workspace.BuildPipelineIntegration`** — registers the
+ *   `documentBuilder.onBuildPhase` / `onDocumentPhase` listeners that
+ *   dispatch every build-phase pass and drive AST enrichment, and
+ *   registers the framework integrity passes itself. The per-language
+ *   feature services it routes to (`ast.AstExtensionService` +
+ *   `integrity.IntegrityService`, plus `references.ScopeExtensionService`
+ *   read by the scope provider) hold the registries and the logic but own
+ *   no listeners, so they need not be eager: each language's services
+ *   construct lazily when the orchestrator (or scope provider) first
+ *   reaches them, and their constructors register that language's rules /
+ *   extensions just-in-time.
+ * - **`profilers.LangiumProfiler`** — self-registers a `Validated`
+ *   BuildPhasePass that flushes the aggregated parse/link/validate profile
+ *   once per build. No production cost (the profiler is trace-gated), but
+ *   the pass must be registered up front.
+ * - **`workspace.CstResidencyService`** — self-registers a `Validated`
+ *   BuildPhasePass that sheds the CST of closed documents. The framework
+ *   default strategy is `always-keep`, so the pass runs but sheds nothing
+ *   until an adopter configures a shedding strategy.
+ *
+ * Consumers with no additional eager targets can omit the third argument
+ * to {@link bootstrapLangium} — the parameter default is this exact set.
+ * Adopters needing extra eager targets spread this constant into their own
+ * array and append their accessors.
+ */
+export declare const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServicesMinimal) => unknown>;
+/**
+ * After `inject(...)` returns, services are constructed lazily on first
+ * access. Some framework services attach to the build pipeline in their
+ * constructors — a `documentBuilder.onUpdate` / `onDocumentPhase` /
+ * `onBuildPhase` listener, or a build-phase pass — and that attachment
+ * has to happen **before** the first build runs, so those services must
+ * be constructed eagerly during bootstrap.
+ *
+ * Defaults to {@link DEFAULT_EAGER_SERVICES} when no list is supplied,
+ * which covers every framework service that needs it. Consumers with
+ * additional eager targets spread the default into their own list.
+ * Accessors are invoked in array order and their return values are
+ * discarded.
+ *
+ * Bootstrap responsibilities, in order:
+ *  1. Hand the shared services to `shared.ServiceRegistry` if it accepts
+ *     them after construction, so Langium's declared-languageId lookup
+ *     rung works however the adopter's registry binding was built.
+ *  2. {@link assertDistinctFileRouting} — before registration, because
+ *     `register` resolves a routing collision by last-wins and afterwards
+ *     the evidence is gone.
+ *  3. Register `language` against `shared.ServiceRegistry`, the
+ *     required final step of any Langium DI bootstrap. Done before slot
+ *     validation so subclassed registries (typed-accessor extensions)
+ *     populate any side state before validation walks construct services
+ *     that read from the registry.
+ *  4. {@link assertCoreSlotsBound} — fail fast if the consumer's
+ *     `inject(...)` composition is missing a `@hydranium/core` module. May
+ *     trigger lazy service construction as side effect of walking the
+ *     slots; that construction expects a populated `ServiceRegistry`,
+ *     hence the order.
+ *  5. {@link warnOnUnexpectedBindings} — opt-in (gated by
+ *     {@link STRICT_BINDINGS_ENV}); warns when a framework slot is bound
+ *     to a non-subclass of its framework base. No-op unless the env is set.
+ *  6. {@link assertReflectionCoversLanguages} — catch a clobbered shared
+ *     `AstReflection` before it starts silently answering `isSubtype`
+ *     false for a registered language's types. Skipped here, since a lone
+ *     language has no sibling that could clobber it.
+ *  7. Invoke eager-construction accessors in array order.
+ *
+ * Multi-grammar adopters use {@link bootstrapLangiumLanguages}, which
+ * registers every language before validating slots or constructing the
+ * eager set.
+ */
+export declare function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(shared: TShared, language: TLang, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
+    shared: TShared;
+    language: TLang;
+};
+/**
+ * Multi-language form of {@link bootstrapLangium}: bootstraps several
+ * languages that share ONE shared-services tier, as a multi-grammar adopter
+ * needs when its grammars cross-reference each other through the shared
+ * index.
+ *
+ * Same responsibilities as the single-language form, but the phase
+ * ORDER across languages is what makes this a distinct function rather
+ * than a loop the caller could write:
+ *
+ *  1. **Every** language is registered against `shared.ServiceRegistry`
+ *     first. Slot validation and eager construction both build services
+ *     that read the registry — a per-language
+ *     register-then-validate-then-eager loop would run them while later
+ *     languages were still missing, so a shared service that walks
+ *     `ServiceRegistry.all` (or resolves by extension) would see a
+ *     half-populated registry and cache the wrong answer.
+ *  2. `assertCoreSlotsBound` / `warnOnUnexpectedBindings` per language —
+ *     each language composes its own module chain, so each is checked.
+ *  3. Eager accessors run **once**, after all registrations. They take
+ *     the shared tier, and the framework's eager set is shared-tier only
+ *     (`ProjectManager`, `BuildPipelineIntegration`, `LangiumProfiler`,
+ *     `CstResidencyService`) — `BuildPipelineIntegration` in particular
+ *     routes per document URI to each language's `IntegrityService` /
+ *     `AstExtensionService`, so it must be constructed knowing all of
+ *     them. Running the set per language would attach its
+ *     `documentBuilder` listeners N times and enforce each phase N times.
+ *
+ * Throws when `languages` is empty: a shared tier with no registered
+ * language never validates its slots, which silently defers a
+ * composition error to the first build.
+ */
+export declare function bootstrapLangiumLanguages<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(shared: TShared, languages: ReadonlyArray<TLang>, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
+    shared: TShared;
+    languages: ReadonlyArray<TLang>;
+};
+/**
+ * Fail fast when two registered languages claim the same routing key — a file
+ * extension, a whole file name, or a language id.
+ *
+ * **Why this is an error and not a warning.** Langium's `ServiceRegistry.register`
+ * resolves a collision by last-wins and reports it with a raw `console.warn`.
+ * That warning goes to the process console, outside the framework `Logger`, so
+ * it never reaches the LSP output channel an adopter reads — and the result is
+ * that every file of the losing language is parsed, scoped and validated by the
+ * WRONG grammar. There is no configuration under which that is intended, and
+ * the symptom (mass validation errors in files that look fine) points nowhere
+ * near the cause.
+ *
+ * A duplicate `languageId` is worse still: the id keys `languageIdMap`, so the
+ * losing language becomes unreachable by every lookup path at once, including
+ * the declared-id rung and `getServicesById`.
+ *
+ * Runs before registration, since afterwards the collision has already been
+ * resolved and the evidence is gone.
+ */
+export declare function assertDistinctFileRouting(languages: ReadonlyArray<LangiumServices>): void;
+/**
+ * Fail fast when the shared `AstReflection` does not know a registered
+ * language's types.
+ *
+ * **The composition mistake this catches.** `AstReflection` lives in Langium's
+ * `LangiumGeneratedSharedCoreServices` — ONE slot for the whole project. A
+ * single `langium-cli` run over several grammars emits one combined reflection
+ * covering all of them, which is fine. But composing two *separately generated*
+ * language packages means composing two `…GeneratedSharedModule`s, each binding
+ * that one slot: last-wins, and the loser's types vanish from the reflection.
+ * Nothing errors. Instead `isSubtype` silently answers `false` for those types,
+ * which quietly breaks `IndexManager.allElements(type)` and `getElementByName`
+ * (so reference routing finds nothing), `getTypeMetaData` (so the encoder's
+ * `'grammar'` mode emits nothing), and Langium's own linking.
+ *
+ * The check is per language, on the types its grammar can produce, and costs
+ * one grammar walk per language at boot; a single-language composition, which
+ * nothing can clobber, is skipped entirely. It cannot repair the situation — a
+ * reflection that spans independently generated grammars is a real design piece
+ * (a composite reflection dispatching per owning language) and is not attempted
+ * here; the point is to turn a silent runtime misbehaviour into a boot failure
+ * that names the language and the mistake.
+ *
+ * **Two severities, because a clobber is not always total.** Throwing only when
+ * NONE of a language's types are known misses the realistic case: two grammars
+ * that share an imported base overlap heavily, so a reflection covering only
+ * one of them still recognises most of the other's types and a
+ * none-are-known test passes while the language's DISTINCTIVE types are
+ * absent. So any non-empty gap now warns (naming the missing types), and the
+ * throw is reserved for the unambiguous all-missing case. The warning can also
+ * fire benignly — a generator folding an unused rule away leaves a type the
+ * reflection never had — which is why partial coverage warns rather than
+ * throwing.
+ */
+export declare function assertReflectionCoversLanguages(shared: LangiumSharedServices, languages: ReadonlyArray<LangiumServices>): void;
+//# sourceMappingURL=bootstrap.d.ts.map

package/lib/langium/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/langium/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AA+GxE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAanG;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAmF/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAiBvG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,2BAA2B,KAAK,OAAO,CAKpG,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,qBAAqB,GAAG,2BAA2B,EAAE,KAAK,SAAS,eAAe,EAChI,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,KAAK,EACf,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,CAGtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACtC,OAAO,SAAS,qBAAqB,GAAG,2BAA2B,EACnE,KAAK,SAAS,eAAe,EAE7B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CAAE,CAiCtD;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CA+BzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,qBAAqB,EAAE,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CAiC9H"}