@hydranium/core 1.0.0-next.10

package/lib/langium/language-module.d.ts

@@ -0,0 +1,281 @@
+/********************************************************************************
+ * 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 AstNode, type LangiumCoreServices, type Module } from '@hydranium/langium';
+import { type LangiumServices, type PartialLangiumServices } from '@hydranium/langium/lsp';
+import { type AstExtensionContribution } from './ast-extension/ast-extension-contribution.js';
+import { type AstExtensionService } from './ast-extension/ast-extension-service.js';
+import { type IntegrityRuleContribution } from './integrity/integrity-contribution.js';
+import { type IntegrityService } from './integrity/integrity-service.js';
+import { type ElementKeyProvider } from './keys/element-key-provider.js';
+import { type LabelProvider } from './labeling/label-provider.js';
+import { type NameProvider } from './naming/name-provider.js';
+import { HydraniumAstNodeDescriptionProvider } from './scope/ast-node-description-provider.js';
+import { type ReferenceCandidateProvider } from './scope/reference-candidate-provider.js';
+import { HydraniumScopeComputation } from './scope/hydranium-scope-computation.js';
+import { HydraniumScopeProvider } from './scope/hydranium-scope-provider.js';
+import { type ReferenceBuilder } from './scope/reference-builder.js';
+import { type ScopeExtensionContribution } from './scope/scope-extension-contribution.js';
+import { type ScopeExtensionService } from './scope/scope-extension-service.js';
+import { type Serializer } from './serialization/serializer.js';
+import { type UpdateRewriteContribution } from './update-rewrite/update-rewrite-contribution.js';
+import { type UpdateRewriteService } from './update-rewrite/update-rewrite-service.js';
+import { type ValidationCheckContribution } from './validation/validation-contribution.js';
+import { ValidationContributionCollector } from './validation/validation-contribution-collector.js';
+import { type ServerModuleContext, type ServerSharedServices } from './module.js';
+/**
+ * Language-level slots contributed by `@hydranium/core`. Bound by
+ * {@link createServerLanguageModule}; consumer modules layered after
+ * it can override any slot (later-wins, same composition idiom as the
+ * shared-module side).
+ *
+ * Only contains slots every protocol head shares. LSP-textual-specific
+ * bindings (e.g. `lsp.CompletionProvider`) belong to
+ * `@hydranium/core/lsp`; GLSP-, data-, and other-head-specific
+ * bindings live in their respective head packages.
+ */
+export interface ServerAddedServices {
+    references: {
+        ScopeComputation: HydraniumScopeComputation;
+        ScopeProvider: HydraniumScopeProvider;
+        /**
+         * Cross-reference candidate provider — owns the candidate-side
+         * completion pipeline (filter / dedupe / sort / build wire DTO).
+         * Adopters subclass {@link DefaultReferenceCandidateProvider}
+         * to override grammar-specific filters or label/value shaping.
+         * Default binding registers
+         * {@link DefaultReferenceCandidateProvider}.
+         */
+        CandidateProvider: ReferenceCandidateProvider;
+        /**
+         * The naming axis — names that change on rename. A re-typed extension
+         * of Langium's `references.NameProvider` slot, bound by default to a
+         * {@link DefaultNameProvider} exposing the framework's three
+         * qualification levels ({@link NameProvider.getOwnName} /
+         * {@link NameProvider.getDocumentQualifiedName} /
+         * {@link NameProvider.getProjectQualifiedName}). Langium's linker and
+         * scope read `getName` through this slot, which defaults to
+         * `getProjectQualifiedName` (workspace-unique). Override to customise
+         * naming; identity that must survive a rename belongs to
+         * {@link ElementKeyProvider} instead.
+         */
+        NameProvider: NameProvider;
+        /**
+         * The identity axis — stable identifiers that do NOT change on rename
+         * (GModel ids, UI selection persistence). Exposes
+         * {@link ElementKeyProvider.getElementKey} plus the hooks of the
+         * resolving walk. A framework-only slot kept separate from
+         * {@link NameProvider} so an adopter customises one axis without
+         * disturbing the other.
+         */
+        ElementKeyProvider: ElementKeyProvider;
+        /**
+         * Labeling service — the UI axis (human-readable display strings),
+         * sibling to {@link NameProvider} (the identifier axis). Read by the
+         * candidate provider for completion labels and by adopter GModel
+         * factories for diagram text. Default binding registers
+         * {@link DefaultLabelProvider} (reads `labelProperties: ['name']`).
+         */
+        LabelProvider: LabelProvider;
+        /**
+         * Reference-construction service — turns (target, source) into the
+         * `$refText` an author would type / a Langium `Reference`. The
+         * construction dual of `ScopeProvider` / `CandidateProvider`
+         * (which resolve references); reads names from {@link NameProvider} and
+         * visibility from `ProjectManager`. Default binding registers
+         * {@link DefaultReferenceBuilder}; adopters override
+         * {@link DefaultReferenceBuilder.encodeRefText} for `$refText` escaping.
+         */
+        ReferenceBuilder: ReferenceBuilder;
+        /**
+         * Per-language dynamic scope contributions — extra resolvable
+         * descriptions layered on top of the scope `getScope` computes. Read
+         * by {@link HydraniumScopeProvider.getScope}; lives here alongside the
+         * other scope-resolution services. The service reads its
+         * `scopes` contribution group at construction.
+         */
+        ScopeExtensionService: ScopeExtensionService;
+        /**
+         * Declarative {@link ScopeExtensionContribution} group. Each sub-key
+         * binds a contribution; the {@link ScopeExtensionService} iterates this
+         * group at construction and calls each contribution's
+         * `registerScopeExtensions(registry)`. Distinct sub-keys accumulate
+         * across framework + adopter modules via Langium's deep-merge.
+         * Same-keyed entries last-wins; the framework binds its own
+         * contributions under a `framework` sub-key — adopters MUST avoid
+         * that literal key.
+         */
+        scopes: Record<string, ScopeExtensionContribution>;
+    };
+    workspace: {
+        AstNodeDescriptionProvider: HydraniumAstNodeDescriptionProvider;
+    };
+    ast: {
+        /**
+         * Per-language build-phase AST enrichment (computed / synthetic
+         * properties). Driven by the shared `BuildPipelineIntegration`
+         * via `extendDocument`. The service reads its `extensions`
+         * contribution group at construction.
+         *
+         * Lives in a purpose-named `ast` group rather than under `workspace`
+         * (which holds Langium lifecycle concerns: WorkspaceManager,
+         * DocumentBuilder, FileSystemProvider, AstNodeDescriptionProvider).
+         * Matches the convention set by `references.ScopeExtensionService`
+         * and `integrity.IntegrityService` — each registry lives in a group
+         * named for its purpose.
+         */
+        AstExtensionService: AstExtensionService;
+        /**
+         * Declarative {@link AstExtensionContribution} group. Each sub-key
+         * binds a contribution; the {@link AstExtensionService} iterates this
+         * group at construction and calls each contribution's
+         * `registerAstExtensions(registry)`. Distinct sub-keys accumulate
+         * across framework + adopter modules via Langium's deep-merge.
+         */
+        extensions: Record<string, AstExtensionContribution>;
+    };
+    serializer: {
+        /**
+         * Typed home for grammar-specific round-trip serialisers.
+         * `ModelService.serialize` resolves it via
+         * `services.ServiceRegistry.getServices(uri).serializer.Serializer`, so
+         * multi-grammar workspaces route to the right serializer per file. The
+         * framework default throws a clear "no Serializer registered" error;
+         * adopters bind their own per-language subclass to enable
+         * `ModelService.update` / `ModelService.save`.
+         */
+        Serializer: Serializer;
+    };
+    integrity: {
+        /**
+         * Build-phase AST-integrity rule runner for this language. Framework
+         * default is a no-op (zero rules registered) — adopters declare
+         * their rules via {@link IntegrityRuleContribution}s under
+         * `rules`, or via an `IntegrityService` subclass for
+         * grammar-typed access (`IntegrityService<MyRoot>` is covariant in
+         * `TRoot`, so the narrower subclass assigns to the
+         * `IntegrityService<AstNode>` slot without a cast). The service
+         * reads its `rules` contribution group at construction.
+         * Driven by the shared `BuildPipelineIntegration`, which routes
+         * each document to its own language's instance.
+         */
+        IntegrityService: IntegrityService<AstNode>;
+        /**
+         * Declarative {@link IntegrityRuleContribution} group. Each sub-key
+         * binds a contribution; the {@link IntegrityService} iterates this
+         * group at construction and calls each contribution's
+         * `registerIntegrityRules(registry)`. Distinct sub-keys accumulate
+         * across framework + adopter modules via Langium's deep-merge.
+         */
+        rules: Record<string, IntegrityRuleContribution>;
+    };
+    updateRewrite: {
+        /**
+         * Per-language runner for transfer-model rewrites applied on the
+         * structured write path of `ModelService.update` / `save`, before
+         * serialisation. The RPC-update-stage sibling of the
+         * {@link IntegrityService} / {@link AstExtensionService} registries.
+         * Framework default is a no-op (zero rewrites registered) — adopters
+         * declare theirs via {@link UpdateRewriteContribution}s under
+         * `rewrites`. Resolved per-URI by `ModelService`, so
+         * multi-grammar workspaces route each write to the right rewrite set.
+         */
+        UpdateRewriteService: UpdateRewriteService;
+        /**
+         * Declarative {@link UpdateRewriteContribution} group. Each sub-key binds
+         * a contribution; the {@link UpdateRewriteService} iterates this group at
+         * construction and calls each contribution's
+         * `registerUpdateRewrites(registry)`. Distinct sub-keys accumulate across
+         * framework + adopter modules via Langium's deep-merge.
+         *
+         * The framework ships no member by default — notably
+         * `NormalizeEmptyStringsContribution` is opt-in (it encodes a
+         * grammar-specific "`''` means unset" assumption), registered by the
+         * adopter under a named sub-key only when its form transport emits `''`.
+         */
+        rewrites: Record<string, UpdateRewriteContribution>;
+    };
+    validation: {
+        /**
+         * Per-language eager service that wires
+         * {@link ValidationCheckContribution}s under `checks` into
+         * Langium's `ValidationRegistry` at construction time. Constructed
+         * on first per-language services access (typically forced by
+         * `BuildPipelineIntegration`'s per-language routing helper
+         * touching this slot before the first `Validated`-phase fire).
+         */
+        ValidationContributionCollector: ValidationContributionCollector;
+        /**
+         * Declarative {@link ValidationCheckContribution} group. Each sub-key
+         * binds a contribution; the {@link ValidationContributionCollector}
+         * iterates this group at construction and calls each contribution's
+         * `registerValidationChecks(registry)`, where `registry` is a thin
+         * adapter over Langium's `ValidationRegistry`. The framework binds
+         * its own {@link NameSeparatorCheckContribution} under `framework`;
+         * adopters bind their own contributions under named sub-keys. Two
+         * contributions registering a check for the same node type both
+         * fire — Langium's `ValidationRegistry` stores entries in a MultiMap.
+         */
+        checks: Record<string, ValidationCheckContribution>;
+    };
+}
+/**
+ * Minimum per-language services tree every framework-bound class accepts
+ * via its `services` constructor parameter.
+ *
+ * Langium's `LangiumCoreServices` (the LSP-free core surface) with two
+ * framework refinements: `.shared` narrowed to {@link ServerSharedServices},
+ * and the framework's own per-language additions
+ * ({@link ServerAddedServices}). Bound classes therefore read framework
+ * per-language slots like `this.services.ast.AstExtensionService` and
+ * `this.services.references.NameProvider.getDocumentQualifiedName`
+ * without a per-callsite cast.
+ *
+ * The only thing this type omits versus {@link ServerLanguageServices} is the
+ * LSP-enabled `LangiumServices` surface — so use this narrower type when the
+ * bound class does not consume LSP slots (the framework's own services are
+ * NOT LSP slots and belong here).
+ *
+ * Adopters declaring per-language services trees should extend this, and
+ * intersect their own narrower `shared`, so the framework's
+ * `(services, options)` constructor surface accepts their service shape
+ * without manual `.shared` casts.
+ */
+export type HydraniumLanguageServices = LangiumCoreServices & ServerAddedServices & {
+    shared: ServerSharedServices;
+};
+/**
+ * Full language-service surface contributed by `createServerLanguageModule`.
+ *
+ * Extends {@link HydraniumLanguageServices} with the LSP-enabled
+ * `LangiumServices` surface. The narrowed `.shared: ServerSharedServices` flows through from
+ * `HydraniumLanguageServices` so framework-bound classes constructed at
+ * the binding site (e.g. `services => new HydraniumScopeProvider(services)`)
+ * see the framework-extended shared tree without a cast.
+ *
+ * Adopters whose per-language type intersects `LangiumServices &
+ * ServerAddedServices & ...` must add `& { shared: <YourSharedServices> }`
+ * so the type is assignable to `ServerLanguageServices` and the
+ * framework's bound-class constructors accept it. An adopter does this
+ * via a `/* override *\/ shared: <YourSharedServices>` declaration on its
+ * per-language added-services interface.
+ */
+export type ServerLanguageServices = LangiumServices & ServerAddedServices & {
+    shared: ServerSharedServices;
+};
+/**
+ * `@hydranium/core`'s default language module. Provides the head-neutral
+ * bindings declared by {@link ServerAddedServices}; each protocol head
+ * package layers its own language module after this one, as does the
+ * adopter's.
+ *
+ * Order matters — `createServerLanguageModule` provides framework
+ * defaults; later modules override (later-wins).
+ */
+export declare function createServerLanguageModule(_context: ServerModuleContext): Module<ServerLanguageServices, PartialLangiumServices & ServerAddedServices>;
+//# sourceMappingURL=language-module.d.ts.map

package/lib/langium/language-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-module.d.ts","sourceRoot":"","sources":["../../src/langium/language-module.ts"],"names":[],"mappings":"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"}

package/lib/langium/language-module.js

@@ -0,0 +1,103 @@
+/********************************************************************************
+ * 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 { DefaultAstExtensionService } from './ast-extension/ast-extension-service.js';
+import { HydraniumCommentProvider } from './documentation/comment-provider.js';
+import { DefaultIntegrityService } from './integrity/integrity-service.js';
+import { DefaultElementKeyProvider } from './keys/default-element-key-provider.js';
+import { DefaultLabelProvider } from './labeling/label-provider.js';
+import { DefaultNameProvider } from './naming/name-provider.js';
+import { NameSeparatorCheckContribution } from './naming/name-separator-validation.js';
+import { HydraniumAstNodeDescriptionProvider } from './scope/ast-node-description-provider.js';
+import { DefaultReferenceCandidateProvider } from './scope/reference-candidate-provider.js';
+import { HydraniumScopeComputation } from './scope/hydranium-scope-computation.js';
+import { HydraniumScopeProvider } from './scope/hydranium-scope-provider.js';
+import { DefaultReferenceBuilder } from './scope/reference-builder.js';
+import { DefaultScopeExtensionService } from './scope/scope-extension-service.js';
+import { DefaultUpdateRewriteService } from './update-rewrite/update-rewrite-service.js';
+import { HydraniumDocumentValidator } from './validation/document-validator.js';
+import { ValidationContributionCollector } from './validation/validation-contribution-collector.js';
+/** Framework default — throws when either serializer entry point is invoked without an adopter binding. */
+class UnboundSerializer {
+    serializeAst(_model) {
+        throw new Error('No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before calling ModelService.update / ModelService.save.');
+    }
+    serializeTransfer(_model) {
+        throw new Error('No Serializer registered at services.serializer.Serializer — bind a Serializer<TAst, TTransfer> in your per-language module before calling ModelService.update / ModelService.save.');
+    }
+}
+/**
+ * `@hydranium/core`'s default language module. Provides the head-neutral
+ * bindings declared by {@link ServerAddedServices}; each protocol head
+ * package layers its own language module after this one, as does the
+ * adopter's.
+ *
+ * Order matters — `createServerLanguageModule` provides framework
+ * defaults; later modules override (later-wins).
+ */
+export function createServerLanguageModule(_context) {
+    return {
+        references: {
+            ScopeComputation: services => new HydraniumScopeComputation(services),
+            ScopeProvider: services => new HydraniumScopeProvider(services),
+            CandidateProvider: services => new DefaultReferenceCandidateProvider(services),
+            NameProvider: services => new DefaultNameProvider(services),
+            ElementKeyProvider: services => new DefaultElementKeyProvider(services),
+            LabelProvider: services => new DefaultLabelProvider(services),
+            ReferenceBuilder: services => new DefaultReferenceBuilder(services),
+            ScopeExtensionService: services => new DefaultScopeExtensionService(services),
+            scopes: {}
+        },
+        documentation: {
+            // Read-side CST rehydration for hover/completion docs — a shed
+            // target's preceding comment is resolved from its `$cstNode`, which
+            // this provider restores on demand.
+            CommentProvider: services => new HydraniumCommentProvider(services)
+        },
+        workspace: {
+            AstNodeDescriptionProvider: services => new HydraniumAstNodeDescriptionProvider(services)
+        },
+        ast: {
+            AstExtensionService: services => new DefaultAstExtensionService(services),
+            extensions: {}
+        },
+        serializer: {
+            Serializer: () => new UnboundSerializer()
+        },
+        // 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.
+        integrity: {
+            IntegrityService: services => new DefaultIntegrityService(services),
+            rules: {}
+        },
+        updateRewrite: {
+            UpdateRewriteService: services => new DefaultUpdateRewriteService(services),
+            rewrites: {}
+        },
+        validation: {
+            // The framework validator on Langium's stock slot: it is what makes
+            // `element`/`property` (the field a form client attaches an error to),
+            // the `$synthetic` node skip and the virtual-document skip real.
+            // Left at framework defaults on purpose — an adopter wanting other
+            // option values rebinds the slot with its own `new
+            // HydraniumDocumentValidator(services, { … })`.
+            DocumentValidator: services => new HydraniumDocumentValidator(services),
+            ValidationContributionCollector: services => new ValidationContributionCollector(services),
+            checks: {
+                // Flags name-bearing nodes whose name value contains the
+                // configured name separator, so qualified names can never collide
+                // with literal names. Adopters MUST avoid the `framework` sub-key
+                // for their own contributions — Langium's deep-merge is last-wins
+                // on same-key leaves, so replacing it drops this check.
+                framework: services => new NameSeparatorCheckContribution(services)
+            }
+        }
+    };
+}
+//# sourceMappingURL=language-module.js.map

package/lib/langium/language-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-module.js","sourceRoot":"","sources":["../../src/langium/language-module.ts"],"names":[],"mappings":"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"}

package/lib/langium/language-types.d.ts

@@ -0,0 +1,85 @@
+/********************************************************************************
+ * 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 Grammar, type LanguageMetaData } from '@hydranium/langium';
+/**
+ * The two slots {@link buildLanguageTypeIndex} reads off a registered language.
+ * Narrowed to exactly this rather than taking `LangiumCoreServices` so the
+ * index is testable against a grammar plus an id, and so the signature states
+ * what it actually touches. A real service tree satisfies it structurally.
+ */
+export interface TypedLanguage {
+    readonly Grammar: Grammar;
+    readonly LanguageMetaData: LanguageMetaData;
+}
+/**
+ * Which registered language can produce a given AST `$type`.
+ *
+ * **Why this exists.** Langium routes languages by file extension, so a request
+ * that names no document — an element id, or a synthetic node addressing a
+ * directory URI during a create-element flow — has no URI to route by. What it
+ * does carry is an AST type. The obvious resolver, `AstReflection`, cannot help:
+ * Langium declares it in `LangiumGeneratedSharedCoreServices`, i.e. ONE
+ * reflection per project covering every grammar, with no language attribution.
+ * `Grammar`, on the other hand, is a per-language service — so the attribution
+ * is recoverable from the grammars themselves.
+ *
+ * Build it once (grammar walks are not cheap) and query per request; the
+ * registered set is fixed after bootstrap.
+ */
+export interface LanguageTypeIndex<TLanguage extends TypedLanguage = TypedLanguage> {
+    /**
+     * Languages whose grammar can produce `type`, in registration order.
+     * Empty when no grammar produces it; more than one when several do (types
+     * reached through a shared imported grammar), which is the caller's signal
+     * that the type alone does not identify a language.
+     */
+    languagesFor(type: string): readonly TLanguage[];
+    /** Every AST `$type` the language with this id can produce. */
+    typesOf(languageId: string): ReadonlySet<string>;
+}
+/**
+ * The AST `$type`s a grammar can actually produce — the types of the parser
+ * rules a document of the language can reach, plus the types assigned by
+ * `{infer X}` / `{X}` actions inside those rules.
+ *
+ * **Produced, not mentioned.** A grammar that only cross-references a type
+ * carries that type in its serialised grammar without any rule producing it —
+ * a document of that language can never contain such a node. Collecting
+ * mentions instead would report every language that merely links to a type,
+ * which for a grammar pair that cross-references is most of them.
+ *
+ * Three rule kinds are skipped because none yields an AST node type:
+ * - **fragments** (`fragment Foo: …`), which splice their assignments into the
+ *   calling rule's object. `langium-cli` generates no type for them, so
+ *   counting the rule name would invent types the `AstReflection` has never
+ *   heard of — and a fragment shared through an imported grammar would be
+ *   attributed to every language that imports it.
+ * - **data-type rules** (`QualifiedName returns string: …`), which produce a
+ *   primitive value rather than a node.
+ * - **rules returning a declared literal-union type** — the
+ *   `type OpKind = '=' | '!='; OpKind returns OpKind: '=' | '!=';` idiom.
+ *   `langium-cli` emits these as TypeScript string-union aliases, never as
+ *   reflected node types, so counting them made `assertReflectionCoversLanguages`
+ *   warn on every boot of any grammar using the idiom, and put phantom entries
+ *   in this index for types no document can ever contain. Such a rule's
+ *   `dataType` is NOT set — the return type is a declared union, not a
+ *   primitive — so the data-type skip does not catch it, and
+ *   {@link isLiteralOnlyType} decides it instead.
+ *
+ * A declared type that unions AST node types (`type Expr = Binary | Unary`) is
+ * deliberately still counted: `langium-cli` reflects those, so dropping them
+ * would hide real coverage gaps rather than false ones.
+ */
+export declare function collectProducibleTypes(grammar: Grammar | undefined): Set<string>;
+/**
+ * Build a {@link LanguageTypeIndex} over the registered languages. Pure over
+ * its input so it unit-tests against hand-built grammars without a boot.
+ */
+export declare function buildLanguageTypeIndex<TLanguage extends TypedLanguage>(languages: readonly TLanguage[]): LanguageTypeIndex<TLanguage>;
+//# sourceMappingURL=language-types.d.ts.map

package/lib/langium/language-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-types.d.ts","sourceRoot":"","sources":["../../src/langium/language-types.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAwB,KAAK,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE/F;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;CAC9C;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB,CAAC,SAAS,SAAS,aAAa,GAAG,aAAa;IAC/E;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE,CAAC;IACjD,+DAA+D;IAC/D,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;CACnD;AA4ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,CA8BhF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,SAAS,aAAa,EAAE,SAAS,EAAE,SAAS,SAAS,EAAE,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAqBrI"}

package/lib/langium/language-types.js

@@ -0,0 +1,173 @@
+/********************************************************************************
+ * 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 { AstUtils, GrammarAST } from '@hydranium/langium';
+/**
+ * Parser rules a document of this language can actually reach — the entry rule
+ * and everything transitively rule-called from it, fragments included (they are
+ * traversed for their own calls even though they contribute no type).
+ *
+ * **Reachability, not mere presence.** Langium grammar imports pull the
+ * imported grammar's rules into the importing grammar wholesale, so a grammar
+ * that imports another purely for a cross-reference target ends up
+ * *containing* all of that grammar's rules — including rules no document of
+ * the importing language can hold. Walking from the entry rule is what
+ * separates "this grammar mentions the rule" from "a document of this
+ * language can contain such a node".
+ *
+ * Cross-references are deliberately NOT followed: a `[Target:ID]` assignment
+ * names a link target, not containment.
+ *
+ * Falls back to every parser rule when the grammar declares no entry rule —
+ * a grammar fragment used only through imports, where reachability is
+ * undefined and over-reporting is safer than reporting nothing.
+ */
+function reachableParserRules(grammar) {
+    const parserRules = (grammar?.rules ?? []).filter(GrammarAST.isParserRule);
+    const entry = parserRules.find(rule => rule.entry);
+    if (!entry) {
+        return parserRules;
+    }
+    const visited = new Set();
+    const queue = [entry];
+    while (queue.length > 0) {
+        const rule = queue.pop();
+        if (visited.has(rule)) {
+            continue;
+        }
+        visited.add(rule);
+        for (const node of AstUtils.streamAllContents(rule)) {
+            // A rule call inside a cross-reference is the link's token, not
+            // containment — `streamAllContents` would otherwise walk into it.
+            if (GrammarAST.isRuleCall(node) && !GrammarAST.isCrossReference(node.$container)) {
+                const called = node.rule.ref;
+                if (called && GrammarAST.isParserRule(called)) {
+                    queue.push(called);
+                }
+            }
+        }
+    }
+    return [...visited];
+}
+/**
+ * Whether a declared grammar `type` resolves to literals and primitives only —
+ * `type OpKind = '=' | '!='` — as opposed to unioning AST node types.
+ *
+ * Decided on the leaves: every `SimpleType` in the definition tree carries
+ * exactly one of `stringType` (a keyword literal), `primitiveType`, or
+ * `typeRef` (a reference to another grammar type). A single `typeRef` anywhere
+ * means the type can denote a node, so it is not literal-only.
+ *
+ * Returns `false` when the definition has no `SimpleType` leaf at all, so a
+ * shape this decision does not recognise leaves the rule counted rather than
+ * silently dropped.
+ */
+function isLiteralOnlyType(declared) {
+    let sawLeaf = false;
+    for (const node of [declared.type, ...AstUtils.streamAllContents(declared.type)]) {
+        if (GrammarAST.isSimpleType(node)) {
+            if (node.typeRef) {
+                return false;
+            }
+            sawLeaf = true;
+        }
+    }
+    return sawLeaf;
+}
+/**
+ * The AST `$type`s a grammar can actually produce — the types of the parser
+ * rules a document of the language can reach, plus the types assigned by
+ * `{infer X}` / `{X}` actions inside those rules.
+ *
+ * **Produced, not mentioned.** A grammar that only cross-references a type
+ * carries that type in its serialised grammar without any rule producing it —
+ * a document of that language can never contain such a node. Collecting
+ * mentions instead would report every language that merely links to a type,
+ * which for a grammar pair that cross-references is most of them.
+ *
+ * Three rule kinds are skipped because none yields an AST node type:
+ * - **fragments** (`fragment Foo: …`), which splice their assignments into the
+ *   calling rule's object. `langium-cli` generates no type for them, so
+ *   counting the rule name would invent types the `AstReflection` has never
+ *   heard of — and a fragment shared through an imported grammar would be
+ *   attributed to every language that imports it.
+ * - **data-type rules** (`QualifiedName returns string: …`), which produce a
+ *   primitive value rather than a node.
+ * - **rules returning a declared literal-union type** — the
+ *   `type OpKind = '=' | '!='; OpKind returns OpKind: '=' | '!=';` idiom.
+ *   `langium-cli` emits these as TypeScript string-union aliases, never as
+ *   reflected node types, so counting them made `assertReflectionCoversLanguages`
+ *   warn on every boot of any grammar using the idiom, and put phantom entries
+ *   in this index for types no document can ever contain. Such a rule's
+ *   `dataType` is NOT set — the return type is a declared union, not a
+ *   primitive — so the data-type skip does not catch it, and
+ *   {@link isLiteralOnlyType} decides it instead.
+ *
+ * A declared type that unions AST node types (`type Expr = Binary | Unary`) is
+ * deliberately still counted: `langium-cli` reflects those, so dropping them
+ * would hide real coverage gaps rather than false ones.
+ */
+export function collectProducibleTypes(grammar) {
+    const types = new Set();
+    // A real language always binds `Grammar` (Langium requires it in
+    // `LangiumGeneratedCoreServices`, and `assertCoreSlotsBound` fails the boot
+    // without it). Tolerated here anyway so a routing lookup degrades to "this
+    // language produces nothing" rather than throwing a TypeError mid-request.
+    for (const rule of reachableParserRules(grammar)) {
+        if (rule.fragment || rule.dataType !== undefined) {
+            continue;
+        }
+        const returnedType = rule.returnType?.ref;
+        if (returnedType && GrammarAST.isType(returnedType) && isLiteralOnlyType(returnedType)) {
+            continue;
+        }
+        // A parser rule's type: an explicit `returns X`, an `infer X`, else the
+        // rule name (Langium's default inferred type).
+        const declared = rule.returnType?.ref?.name ?? rule.inferredType?.name ?? rule.name;
+        types.add(declared);
+        // Actions rewrite the current object's type mid-rule, so they produce
+        // types no rule signature mentions.
+        for (const node of AstUtils.streamAllContents(rule)) {
+            if (GrammarAST.isAction(node)) {
+                const actionType = node.inferredType?.name ?? node.type?.ref?.name;
+                if (actionType) {
+                    types.add(actionType);
+                }
+            }
+        }
+    }
+    return types;
+}
+/**
+ * Build a {@link LanguageTypeIndex} over the registered languages. Pure over
+ * its input so it unit-tests against hand-built grammars without a boot.
+ */
+export function buildLanguageTypeIndex(languages) {
+    const byType = new Map();
+    const byLanguage = new Map();
+    for (const language of languages) {
+        const types = collectProducibleTypes(language.Grammar);
+        byLanguage.set(language.LanguageMetaData.languageId, types);
+        for (const type of types) {
+            const owners = byType.get(type);
+            if (owners) {
+                owners.push(language);
+            }
+            else {
+                byType.set(type, [language]);
+            }
+        }
+    }
+    const none = [];
+    const empty = new Set();
+    return {
+        languagesFor: type => byType.get(type) ?? none,
+        typesOf: languageId => byLanguage.get(languageId) ?? empty
+    };
+}
+//# sourceMappingURL=language-types.js.map