@hydranium/core 1.0.0-next.10

package/lib/langium/scope/reference-candidate-provider.js

@@ -0,0 +1,185 @@
+/********************************************************************************
+ * 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, stream, StreamScope } from '@hydranium/langium';
+import { dedupeTierSiblingsStream } from './tier-specificity.js';
+/**
+ * Default implementation of {@link ReferenceCandidateProvider}.
+ * Reads scope from a {@link HydraniumScopeProvider} and applies the
+ * standard filter / dedupe / sort / build pipeline.
+ *
+ * Pipeline (in {@link getCandidateScope}):
+ * 1. Enrich reference info via {@link scopedReferenceInfo} (adds
+ *    `document` + `projectId`).
+ * 2. Collect descriptions from the outer scope via
+ *    `scopeProvider.getScope(referenceInfo)`.
+ * 3. Filter via {@link filterCandidate} (framework default is a no-op;
+ *    adopters add grammar-specific predicates).
+ * 4. Collapse tier-siblings to the canonical tier via
+ *    {@link applyCanonicalFilter}.
+ * 5. Dedupe by `description.name` and sort by
+ *    `scopeProvider.sortText`.
+ * 6. Wrap in a {@link StreamScope}.
+ *
+ * The {@link find} method then maps each description through
+ * {@link buildCandidate} to produce the wire DTO.
+ *
+ * Adopter override points:
+ * - {@link scopedReferenceInfo} — extend `ScopedReferenceInfo` with
+ *   richer source context.
+ * - {@link filterCandidate} — grammar-specific candidate filters.
+ * - {@link buildCandidate} — label / value separation for adopters
+ *   whose UI surface needs a different display string from the
+ *   persisted reference id. Default reads
+ *   {@link LabelProvider.getLabel}, falling back to the
+ *   description's bare name.
+ */
+export class DefaultReferenceCandidateProvider {
+    services;
+    scopeProvider;
+    labelProvider;
+    /**
+     * This language's own `NameProvider`, held for subclasses naming something
+     * in the SOURCE document (the reference's own container, its owner). The
+     * default candidate build uses {@link labelProvider} for labels, not this.
+     *
+     * For a CANDIDATE's node use {@link nameProviderFor} instead — a candidate
+     * scope legitimately spans documents in other languages.
+     */
+    nameProvider;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.scopeProvider = services.references.ScopeProvider;
+        this.labelProvider = services.references.LabelProvider;
+        this.nameProvider = services.references.NameProvider;
+        this.tracer = services.shared.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    /**
+     * The `NameProvider` of the language that owns `target`'s document,
+     * falling back to this language's when `target` routes nowhere.
+     *
+     * **A candidate's name is a fact about the candidate.** Which properties
+     * carry it and how segments join are per-language (`nameProperties`,
+     * `nameSeparator`), and a candidate scope spans every document a reference
+     * could resolve to — including other grammars', since cross-language
+     * references resolve through the global index. A subclass filter that
+     * compares `description.name` against a name derived with THIS language's
+     * provider therefore compares two different spellings of the same element
+     * and never matches: a self-reference filter silently stops excluding, and
+     * the element offers itself as its own target.
+     *
+     * The mirror of `ReferenceBuilder.nameProviderFor`, and the same fallback
+     * reasoning: an unroutable target has no better answer than the source's.
+     */
+    nameProviderFor(target) {
+        return this.services.shared.ServiceRegistry?.getServicesFor(target)?.references.NameProvider ?? this.nameProvider;
+    }
+    find(ctx) {
+        const scope = this.getCandidateScope(ctx);
+        return scope.elementScope
+            .getAllElements()
+            .map(description => this.buildCandidate(description, scope))
+            .toArray();
+    }
+    getCandidateScope(ctx) {
+        const referenceInfo = 'reference' in ctx ? this.scopedReferenceInfo(ctx) : this.scopedReferenceInfo(this.scopeProvider.referenceContextToInfo(ctx));
+        const filtered = this.scopeProvider
+            .getScope(referenceInfo)
+            .getAllElements()
+            .filter(description => this.filterCandidate(description, referenceInfo));
+        const filteredDescriptions = this.applyCanonicalFilter(filtered)
+            .distinct(description => description.name)
+            .toArray()
+            .sort((left, right) => this.scopeProvider.sortText(left).localeCompare(this.scopeProvider.sortText(right)));
+        const elementScope = new StreamScope(stream(filteredDescriptions));
+        return { elementScope, source: referenceInfo };
+    }
+    resolveCandidate(ref) {
+        const node = this.scopeProvider.resolveReference(ref);
+        if (!node) {
+            return undefined;
+        }
+        return { candidate: this.buildResolvedCandidate(node, ref.value), node };
+    }
+    /**
+     * Canonical filter — collapse the multiple descriptions a single node
+     * emits across visibility tiers (multi-tier emission) down to the
+     * most-specific tier-sibling per node, so a user sees one candidate
+     * per node. Applied unconditionally in the candidate pipeline; adopters
+     * needing the raw multi-tier set (debugging UIs, model-introspection
+     * tooling) override to return the input unchanged.
+     */
+    applyCanonicalFilter(candidates) {
+        return dedupeTierSiblingsStream(candidates);
+    }
+    /**
+     * Enrich a Langium {@link ReferenceInfo} with the source document
+     * and the source's project id. Project id resolution uses the
+     * framework's `ProjectManager` bound at
+     * `services.shared.workspace.ProjectManager`. Adopters with a
+     * different project-ownership model (e.g. a custom project manager)
+     * override to read their own manager.
+     */
+    scopedReferenceInfo(referenceInfo) {
+        const document = AstUtils.getDocument(referenceInfo.container);
+        const projectId = this.services.shared.workspace.ProjectManager.getProject(document.uri)?.id;
+        return { ...referenceInfo, document, projectId };
+    }
+    /**
+     * Per-description filter applied during {@link getCandidateScope}.
+     * The framework default is a no-op pass-through that suppresses
+     * nothing — tier-sibling collapsing is owned by
+     * {@link applyCanonicalFilter} downstream. Adopters override with
+     * grammar-specific predicates.
+     */
+    filterCandidate(_description, _reference) {
+        return true;
+    }
+    /**
+     * Build a {@link ReferenceCandidate} from an AST description
+     * in the context of the surrounding candidate scope. Override hook
+     * for adopters whose UI surface needs a different label / value
+     * separation — a human-readable display string shown to the user
+     * while the bare id is what gets persisted.
+     *
+     * Default behaviour: reads {@link LabelProvider.getLabel} from the
+     * description's node and uses it as `label`, falling back to
+     * `description.name` when there is no own label. Adopters with a
+     * meaningful `labelProperties` get the display label in candidates
+     * "for free" without overriding this method.
+     */
+    buildCandidate(description, _scope) {
+        const label = description.node ? (this.labelProvider.getLabel(description.node) ?? description.name) : description.name;
+        return {
+            uri: description.documentUri.toString(),
+            type: description.type,
+            label,
+            value: description.name
+        };
+    }
+    /**
+     * Build a {@link ReferenceCandidate} for a resolved target node and the
+     * value that resolved it. The node-based counterpart to
+     * {@link buildCandidate} (which starts from a description in a list): the
+     * resolve path holds the written `value` and the matched node, so `value`
+     * is the request's value and `label` is the node's display name when it
+     * differs. Adopters override alongside {@link buildCandidate} when they
+     * shape labels specially.
+     */
+    buildResolvedCandidate(node, value) {
+        const label = this.labelProvider.getLabel(node) ?? value;
+        return {
+            uri: AstUtils.getDocument(node).uri.toString(),
+            type: node.$type,
+            label,
+            value
+        };
+    }
+}
+//# sourceMappingURL=reference-candidate-provider.js.map

package/lib/langium/scope/reference-candidate-provider.js.map

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

package/lib/langium/scope/scope-extension-contribution.d.ts

@@ -0,0 +1,32 @@
+/********************************************************************************
+ * 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 Disposable } from 'vscode-languageserver';
+import { type ScopeExtension } from './scope-extension-service.js';
+/**
+ * Registry handed to a {@link ScopeExtensionContribution}. Implemented by the
+ * scope-extension service; a contribution receives it and registers one or
+ * many scope extensions (extra resolvable descriptions layered on top of the
+ * `getScope` result). Doubles as the low-level imperative API.
+ */
+export interface ScopeExtensionRegistry {
+    register(extension: ScopeExtension): Disposable;
+}
+/**
+ * Declarative registration of scope extensions. Bound under the module's
+ * `references.scopes` contribution group; the scope-extension service reads
+ * its own group at construction and calls this method, handing itself in as
+ * the registry.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface ScopeExtensionContribution {
+    registerScopeExtensions(registry: ScopeExtensionRegistry): void;
+}
+//# sourceMappingURL=scope-extension-contribution.d.ts.map

package/lib/langium/scope/scope-extension-contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-extension-contribution.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/scope-extension-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACpC,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,UAAU,CAAC;CAClD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,0BAA0B;IACxC,uBAAuB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAClE"}

package/lib/langium/scope/scope-extension-contribution.js

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=scope-extension-contribution.js.map

package/lib/langium/scope/scope-extension-contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-extension-contribution.js","sourceRoot":"","sources":["../../../src/langium/scope/scope-extension-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}

package/lib/langium/scope/scope-extension-service.d.ts

@@ -0,0 +1,149 @@
+/********************************************************************************
+ * 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 LangiumDocument, type Scope } from '@hydranium/langium';
+import { type Disposable } from 'vscode-languageserver';
+import { type Tracer } from '@hydranium/protocol';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { Registry, type RegistryItem } from '../../util/registry.js';
+import { type ScopeExtensionRegistry } from './scope-extension-contribution.js';
+import { type TieredAstNodeDescription } from './scoped-ast-node-description.js';
+/**
+ * Acceptor passed to {@link ScopeExtension.addDescriptions}. Mirrors the
+ * `ValidationAcceptor` pattern: a single parameter that hides both the
+ * description factory and the result accumulator.
+ *
+ * Scope extensions are **query-time, per-context contributors** rebuilt on
+ * every `getScope` call from the live reference context. Only two visibility
+ * tiers are coherent for such contributors:
+ * - `local(...)` — document-only symbol; layered above the project chain
+ *   but below document-local. Most extension-scope descriptions.
+ * - `universal(...)` — visible everywhere unconditionally; layered at the
+ *   bottom of the chain (synthetic / stdlib content).
+ *
+ * **Why no `project` / `public` tiers**: `public` ("visible from dependent
+ * projects") is undeliverable from a per-context contributor — a
+ * contribution made while resolving a reference in document D is never
+ * indexed, so a dependent project's query never sees it. Genuine
+ * cross-project synthetic symbols go through the AST-extension / export
+ * path (which IS indexed + tiered). `project` collapses into `local` —
+ * since the extension is already scoped to this one query, "project
+ * visibility" adds no real visibility over `local`. Use `createOwnProjectScope`
+ * / `createDependencyScope` hooks on `HydraniumScopeProvider` for genuine
+ * tier-weaving needs.
+ */
+export interface ScopeDescriptionAcceptor {
+    local(options: {
+        node: AstNode;
+        name: string;
+        document: LangiumDocument;
+    }): void;
+    universal(options: {
+        node: AstNode;
+        name: string;
+        document: LangiumDocument;
+    }): void;
+    /**
+     * Push a pre-built {@link TieredAstNodeDescription} directly — use when
+     * descriptions are constructed ahead of time, to avoid per-query
+     * allocation. The pushed description's `tier` must be `'local'` or
+     * `'universal'`; a description of any other tier is silently dropped,
+     * because the per-tier query methods only return descriptions matching
+     * the tier they were asked for.
+     */
+    push(description: TieredAstNodeDescription): void;
+}
+/**
+ * A registration that contributes additional descriptions to the scope
+ * computed by `getScope` for specific reference types. Contributed descriptions
+ * layer at their declared tier (local above the project chain but below
+ * document-local; universal at the bottom).
+ */
+export interface ScopeExtension extends RegistryItem {
+    /** Reference types this extension applies to, as `$type` strings. */
+    readonly referenceTypes: string[];
+    /**
+     * Contribute scope descriptions for the given context via `accept`.
+     * If the extension does not apply, call nothing.
+     *
+     * Sync-only by Langium contract: invoked from `ScopeProvider.getScope`,
+     * which Langium defines as synchronous. Adopters needing async work must
+     * build the data up-front and hand a sync acceptor here.
+     */
+    addDescriptions(context: AstNode, referenceType: string, document: LangiumDocument, accept: ScopeDescriptionAcceptor): void;
+}
+/**
+ * Public contract for the per-language scope-extension service. Extends
+ * the {@link ScopeExtensionRegistry} (the imperative `register` surface
+ * contributions use) with the per-tier query methods called cross-class
+ * from `HydraniumScopeProvider`'s `layerLocalExtension` /
+ * `layerUniversalExtension` helpers, which layer scope-extension
+ * contributions around the cached project chain.
+ *
+ * Adopter overrides go through {@link DefaultScopeExtensionService}; the
+ * interface keeps the public API stable while internals
+ * (`collectExtensionDescriptions` walk) stay `protected` on the default
+ * class.
+ */
+export interface ScopeExtensionService extends ScopeExtensionRegistry {
+    /**
+     * Layer this language's `local`-tier scope-extension descriptions on
+     * top of `outerScope` for the given reference type. Returns
+     * `outerScope` unchanged when no extension contributes a `local`-tier
+     * description for the type (zero-cost common path).
+     */
+    getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
+    /**
+     * Layer this language's `universal`-tier scope-extension descriptions
+     * BELOW `outerScope` for the given reference type. Returns `outerScope`
+     * unchanged when no extension contributes a `universal`-tier
+     * description for the type.
+     */
+    getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
+}
+export type ScopeExtensionServiceOptions = LogNameOptions;
+/**
+ * Default {@link ScopeExtensionService} implementation. Per-language
+ * registry for dynamic scope contributions: extra resolvable descriptions
+ * layered at their declared tier within the scope `getScope` computes for
+ * specific reference types. Split out of `DefaultAstExtensionService` so
+ * the build-phase AST enrichment concern (which mutates nodes) is
+ * separate from the query-time scope-resolution concern (which only reads).
+ *
+ * Lives in the per-language `references` group alongside `ScopeProvider`,
+ * which consumes the per-tier query methods ({@link getLocalExtensionScope}
+ * / {@link getUniversalExtensionScope}). Designed as a base class; adopters
+ * extend it and call `register` in their constructor.
+ */
+export declare class DefaultScopeExtensionService implements ScopeExtensionService {
+    protected readonly services: ServerLanguageServices;
+    protected readonly scopeExtensions: Registry<ScopeExtension>;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerLanguageServices, options?: ScopeExtensionServiceOptions);
+    /**
+     * Register a single scope extension. Doubles as the imperative low-level
+     * API and as the {@link ScopeExtensionRegistry} entry point that
+     * `ScopeExtensionContribution.registerScopeExtensions` hands to
+     * contributions. Throws on duplicate id.
+     */
+    register(extension: ScopeExtension): Disposable;
+    getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
+    getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
+    /**
+     * Walk this language's registered scope extensions matching
+     * `referenceType` and collect descriptions of the requested `tier`.
+     * `push`-ed descriptions of other tiers are silently dropped here —
+     * the per-tier query methods only return descriptions matching their
+     * tier. (`local` and `universal` are the only acceptor entry points;
+     * `push` is the escape hatch for pre-built descriptions and is the
+     * only path that could carry other tiers.)
+     */
+    protected collectExtensionDescriptions(referenceType: string, context: AstNode, tier: 'local' | 'universal'): TieredAstNodeDescription[];
+}
+//# sourceMappingURL=scope-extension-service.d.ts.map

package/lib/langium/scope/scope-extension-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-extension-service.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/scope-extension-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAY,KAAK,eAAe,EAAY,KAAK,KAAK,EAAuB,MAAM,oBAAoB,CAAC;AAC7H,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,wBAAwB;IACtC,KAAK,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE,GAAG,IAAI,CAAC;IACjF,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE,GAAG,IAAI,CAAC;IACrF;;;;;;;OAOG;IACH,IAAI,CAAC,WAAW,EAAE,wBAAwB,GAAG,IAAI,CAAC;CACpD;AAcD;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,YAAY;IACjD,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAClC;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC9H;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAsB,SAAQ,sBAAsB;IAClE;;;;;OAKG;IACH,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,CAAC;IAC1F;;;;;OAKG;IACH,0BAA0B,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK,CAAC;CAChG;AAED,MAAM,MAAM,4BAA4B,GAAG,cAAc,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,qBAAa,4BAA6B,YAAW,qBAAqB;IAKpE,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB;IAJtD,SAAS,CAAC,QAAQ,CAAC,eAAe,2BAAkC;IACpE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,sBAAsB,EACnD,OAAO,GAAE,4BAAiC;IAc7C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,UAAU;IAI/C,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK;IAQzF,0BAA0B,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,GAAG,KAAK;IAQ7F;;;;;;;;OAQG;IACH,SAAS,CAAC,4BAA4B,CACnC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,GAAG,WAAW,GAC3B,wBAAwB,EAAE;CAa/B"}

package/lib/langium/scope/scope-extension-service.js

@@ -0,0 +1,94 @@
+/********************************************************************************
+ * 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, MapScope, StreamScope, stream } from '@hydranium/langium';
+import { Registry } from '../../util/registry.js';
+/** Build a {@link ScopeDescriptionAcceptor} that synthesises typed descriptions via `descriptions` and accumulates them into `into`. */
+function createScopeDescriptionAcceptor(into, descriptions) {
+    return {
+        local: options => into.push(descriptions.createLocal(options)),
+        universal: options => into.push(descriptions.createUniversal(options)),
+        push: description => into.push(description)
+    };
+}
+/**
+ * Default {@link ScopeExtensionService} implementation. Per-language
+ * registry for dynamic scope contributions: extra resolvable descriptions
+ * layered at their declared tier within the scope `getScope` computes for
+ * specific reference types. Split out of `DefaultAstExtensionService` so
+ * the build-phase AST enrichment concern (which mutates nodes) is
+ * separate from the query-time scope-resolution concern (which only reads).
+ *
+ * Lives in the per-language `references` group alongside `ScopeProvider`,
+ * which consumes the per-tier query methods ({@link getLocalExtensionScope}
+ * / {@link getUniversalExtensionScope}). Designed as a base class; adopters
+ * extend it and call `register` in their constructor.
+ */
+export class DefaultScopeExtensionService {
+    services;
+    scopeExtensions = new Registry();
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'ScopeExtension').trace('instantiated');
+        // Read the language's ScopeExtensionContribution group and let each
+        // contribution register one or many scope extensions through this service.
+        // Optional chaining tolerates incomplete test stubs; production
+        // wiring always provides the slot via `createServerLanguageModule`.
+        const contributions = services.references?.scopes ?? {};
+        for (const contribution of Object.values(contributions)) {
+            contribution.registerScopeExtensions(this);
+        }
+    }
+    /**
+     * Register a single scope extension. Doubles as the imperative low-level
+     * API and as the {@link ScopeExtensionRegistry} entry point that
+     * `ScopeExtensionContribution.registerScopeExtensions` hands to
+     * contributions. Throws on duplicate id.
+     */
+    register(extension) {
+        return this.scopeExtensions.register(extension);
+    }
+    getLocalExtensionScope(referenceType, context, outerScope) {
+        const local = this.collectExtensionDescriptions(referenceType, context, 'local');
+        if (local.length === 0) {
+            return outerScope;
+        }
+        return new StreamScope(stream(local), outerScope);
+    }
+    getUniversalExtensionScope(referenceType, context, outerScope) {
+        const universal = this.collectExtensionDescriptions(referenceType, context, 'universal');
+        if (universal.length === 0) {
+            return outerScope;
+        }
+        return new StreamScope(outerScope.getAllElements(), new MapScope(universal));
+    }
+    /**
+     * Walk this language's registered scope extensions matching
+     * `referenceType` and collect descriptions of the requested `tier`.
+     * `push`-ed descriptions of other tiers are silently dropped here —
+     * the per-tier query methods only return descriptions matching their
+     * tier. (`local` and `universal` are the only acceptor entry points;
+     * `push` is the escape hatch for pre-built descriptions and is the
+     * only path that could carry other tiers.)
+     */
+    collectExtensionDescriptions(referenceType, context, tier) {
+        const extensionsForType = this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+        if (extensionsForType.length === 0) {
+            return [];
+        }
+        const document = AstUtils.getDocument(context);
+        const collected = [];
+        const accept = createScopeDescriptionAcceptor(collected, this.services.workspace.AstNodeDescriptionProvider);
+        for (const extension of extensionsForType) {
+            extension.addDescriptions(context, referenceType, document, accept);
+        }
+        return collected.filter(description => description.tier === tier);
+    }
+}
+//# sourceMappingURL=scope-extension-service.js.map

package/lib/langium/scope/scope-extension-service.js.map

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