@hydranium/core 1.0.0-next.10

package/lib/langium/scope/reference-builder.d.ts

@@ -0,0 +1,125 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { type AstNode, type Reference } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { type NameProvider } from '../naming/name-provider.js';
+/**
+ * Reference-construction service — turns a (target, source) pair into the
+ * `$refText` an author would type, or a full Langium {@link Reference}.
+ *
+ * Split off {@link NameProvider} because reference *construction* is more than
+ * naming: it composes a name *tier* (own / document- / project-qualified) with
+ * **project visibility policy** (`ProjectManager.isVisible` / `getProjectForNode`)
+ * and adopter-specific `$refText` encoding. The visibility coupling is a
+ * different dependency axis from "what is this node's name", so it lives here
+ * — the construction dual of the resolution-side candidate / scope providers.
+ *
+ * Reads names from {@link NameProvider}; resolves project ownership +
+ * visibility from the shared `ProjectManager`. Adopters override
+ * `encodeRefText` for grammar-specific `$refText` escaping.
+ */
+export interface ReferenceBuilder {
+    /**
+     * The **reference name** targeting `target` from `source`'s context. Picks
+     * document-qualified or project-qualified form based on whether source
+     * and target share a project (via `ProjectManager`), gates cross-project
+     * references through `ProjectManager.isVisible`, and passes the result
+     * through {@link DefaultReferenceBuilder.encodeRefText} for adopter-specific
+     * character escaping.
+     *
+     * Returns `undefined` when no reference can be formed: target is
+     * undefined, target has no nameable form, or cross-project visibility
+     * forbids the reference.
+     *
+     * Source-aware sibling of {@link NameProvider.getProjectQualifiedName} /
+     * {@link NameProvider.getDocumentQualifiedName}: callers pass the containing
+     * node and get back the form that the source-text writer would type.
+     *
+     * A reference name is **not a fourth qualification level** — it is a policy
+     * *over* the levels (document-qualified within a project, project-qualified
+     * across one) plus escaping.
+     */
+    getReferenceName(target?: AstNode, source?: AstNode): string | undefined;
+    /**
+     * Reference shape constructor for an own-scope (bare) reference.
+     * Returns `undefined` when {@link NameProvider.getOwnName} returns
+     * `undefined` — surfaces real "node has no name" failures synchronously
+     * instead of producing an invalid `$refText: ''` that fails at link time
+     * with lost context.
+     */
+    toOwnReference<T extends AstNode>(target: T | undefined): Reference<T> | undefined;
+    /** Document-qualified sibling of {@link toOwnReference}. */
+    toDocumentReference<T extends AstNode>(target: T | undefined): Reference<T> | undefined;
+    /** Project-qualified sibling of {@link toOwnReference}. */
+    toProjectReference<T extends AstNode>(target: T | undefined): Reference<T> | undefined;
+    /**
+     * Visibility-aware reference constructor — uses {@link getReferenceName}
+     * to pick document- vs project-qualified form based on the source /
+     * target relationship and to gate forbidden cross-project references.
+     * Returns `undefined` when no reference can be formed.
+     */
+    toReference<T extends AstNode>(target: T | undefined, source?: AstNode): Reference<T> | undefined;
+}
+/**
+ * Default {@link ReferenceBuilder}. Reads names from the bound
+ * {@link NameProvider} and project ownership / visibility from the shared
+ * `ProjectManager`. Each `to*Reference` constructor is virtual and routes its
+ * `$refText` through {@link encodeRefText}, so an adopter that needs
+ * grammar-specific escaping overrides that one hook and every constructor
+ * (plus {@link getReferenceName}) picks it up.
+ */
+export declare class DefaultReferenceBuilder implements ReferenceBuilder {
+    protected readonly services: HydraniumLanguageServices;
+    protected readonly nameProvider: NameProvider;
+    protected readonly tracer: Tracer;
+    constructor(services: HydraniumLanguageServices, options?: LogNameOptions);
+    /**
+     * Override hook for adopter-specific `$refText` encoding (escape rules,
+     * delimiter handling, etc.). Default: identity — the qualified name
+     * goes into `$refText` unchanged.
+     *
+     * Deliberately the SOURCE language's concern, unlike name derivation
+     * below: escaping makes the text safe to write into the source document's
+     * syntax, so it follows the grammar doing the writing.
+     */
+    protected encodeRefText(name: string): string;
+    /**
+     * The `NameProvider` of the language that owns `target`'s document.
+     *
+     * **Name derivation follows the TARGET, not the source.** A name is a fact
+     * about the element being named — which properties carry it, how segments
+     * are joined — and both are per-language (`nameProperties`,
+     * `nameSeparator`). Deriving a cross-grammar target's name with the source
+     * language's provider yields `undefined` or an unmatchable `$refText`
+     * whenever the two differ, and the result is a permanently dangling
+     * reference with no diagnostic: the text is written, it just never
+     * resolves.
+     *
+     * Falls back to the source's provider when the target's document is
+     * unroutable — a synthetic node with no document, a URI matching no
+     * registered language, or a services tree with no registry at all (the
+     * minimal trees unit tests build). That is the best available guess, not a
+     * decision.
+     *
+     * Mirrored by `DefaultReferenceCandidateProvider.nameProviderFor` for the
+     * candidate side; both go through `ServiceRegistry.getServicesFor`, which
+     * owns the node-to-document step and the abstain-instead-of-throw.
+     */
+    protected nameProviderFor(target: AstNode): NameProvider;
+    /** Resolve the project id owning `node`, or `undefined` if outside any project. */
+    protected getProjectIdFor(node?: AstNode): string | undefined;
+    getReferenceName(target?: AstNode, source?: AstNode): string | undefined;
+    toOwnReference<T extends AstNode>(target: T | undefined): Reference<T> | undefined;
+    toDocumentReference<T extends AstNode>(target: T | undefined): Reference<T> | undefined;
+    toProjectReference<T extends AstNode>(target: T | undefined): Reference<T> | undefined;
+    toReference<T extends AstNode>(target: T | undefined, source?: AstNode): Reference<T> | undefined;
+}
+//# sourceMappingURL=reference-builder.d.ts.map

package/lib/langium/scope/reference-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-builder.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/reference-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAEzE;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEnF,4DAA4D;IAC5D,mBAAmB,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAExF,2DAA2D;IAC3D,kBAAkB,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEvF;;;;;OAKG;IACH,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;CACpG;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,YAAW,gBAAgB;IAK1D,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB;IAJzD,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,yBAAyB,EACtD,OAAO,GAAE,cAAmB;IAM/B;;;;;;;;OAQG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI7C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY;IAIxD,mFAAmF;IACnF,SAAS,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAI7D,gBAAgB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAqBxE,cAAc,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;IAQlF,mBAAmB,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;IAQvF,kBAAkB,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;IAQtF,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;CAOnG"}

package/lib/langium/scope/reference-builder.js

@@ -0,0 +1,115 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Default {@link ReferenceBuilder}. Reads names from the bound
+ * {@link NameProvider} and project ownership / visibility from the shared
+ * `ProjectManager`. Each `to*Reference` constructor is virtual and routes its
+ * `$refText` through {@link encodeRefText}, so an adopter that needs
+ * grammar-specific escaping overrides that one hook and every constructor
+ * (plus {@link getReferenceName}) picks it up.
+ */
+export class DefaultReferenceBuilder {
+    services;
+    nameProvider;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.nameProvider = services.references.NameProvider;
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'ReferenceBuilder').trace('instantiated');
+    }
+    /**
+     * Override hook for adopter-specific `$refText` encoding (escape rules,
+     * delimiter handling, etc.). Default: identity — the qualified name
+     * goes into `$refText` unchanged.
+     *
+     * Deliberately the SOURCE language's concern, unlike name derivation
+     * below: escaping makes the text safe to write into the source document's
+     * syntax, so it follows the grammar doing the writing.
+     */
+    encodeRefText(name) {
+        return name;
+    }
+    /**
+     * The `NameProvider` of the language that owns `target`'s document.
+     *
+     * **Name derivation follows the TARGET, not the source.** A name is a fact
+     * about the element being named — which properties carry it, how segments
+     * are joined — and both are per-language (`nameProperties`,
+     * `nameSeparator`). Deriving a cross-grammar target's name with the source
+     * language's provider yields `undefined` or an unmatchable `$refText`
+     * whenever the two differ, and the result is a permanently dangling
+     * reference with no diagnostic: the text is written, it just never
+     * resolves.
+     *
+     * Falls back to the source's provider when the target's document is
+     * unroutable — a synthetic node with no document, a URI matching no
+     * registered language, or a services tree with no registry at all (the
+     * minimal trees unit tests build). That is the best available guess, not a
+     * decision.
+     *
+     * Mirrored by `DefaultReferenceCandidateProvider.nameProviderFor` for the
+     * candidate side; both go through `ServiceRegistry.getServicesFor`, which
+     * owns the node-to-document step and the abstain-instead-of-throw.
+     */
+    nameProviderFor(target) {
+        return this.services.shared.ServiceRegistry?.getServicesFor(target)?.references.NameProvider ?? this.nameProvider;
+    }
+    /** Resolve the project id owning `node`, or `undefined` if outside any project. */
+    getProjectIdFor(node) {
+        return node ? this.services.shared.workspace.ProjectManager.getProjectForNode(node)?.id : undefined;
+    }
+    getReferenceName(target, source) {
+        if (!target) {
+            return undefined;
+        }
+        const sourceProjectId = this.getProjectIdFor(source);
+        const targetProjectId = this.getProjectIdFor(target);
+        if (sourceProjectId && targetProjectId) {
+            const projectManager = this.services.shared.workspace.ProjectManager;
+            // selfVisible: a project references its own elements.
+            if (!projectManager.isVisible(sourceProjectId, targetProjectId, true)) {
+                return undefined;
+            }
+        }
+        const nameProvider = this.nameProviderFor(target);
+        const name = sourceProjectId && sourceProjectId === targetProjectId
+            ? nameProvider.getDocumentQualifiedName(target)
+            : nameProvider.getProjectQualifiedName(target);
+        return name ? this.encodeRefText(name) : undefined;
+    }
+    toOwnReference(target) {
+        if (!target) {
+            return undefined;
+        }
+        const name = this.nameProviderFor(target).getOwnName(target);
+        return name ? { ref: target, $refText: this.encodeRefText(name) } : undefined;
+    }
+    toDocumentReference(target) {
+        if (!target) {
+            return undefined;
+        }
+        const name = this.nameProviderFor(target).getDocumentQualifiedName(target);
+        return name ? { ref: target, $refText: this.encodeRefText(name) } : undefined;
+    }
+    toProjectReference(target) {
+        if (!target) {
+            return undefined;
+        }
+        const name = this.nameProviderFor(target).getProjectQualifiedName(target);
+        return name ? { ref: target, $refText: this.encodeRefText(name) } : undefined;
+    }
+    toReference(target, source) {
+        if (!target) {
+            return undefined;
+        }
+        const refText = this.getReferenceName(target, source);
+        return refText ? { ref: target, $refText: refText } : undefined;
+    }
+}
+//# sourceMappingURL=reference-builder.js.map

package/lib/langium/scope/reference-builder.js.map

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

package/lib/langium/scope/reference-candidate-provider.d.ts

@@ -0,0 +1,228 @@
+/********************************************************************************
+ * 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 Tracer, type ReferenceCandidate, type ReferenceContext, type ReferenceRequest } from '@hydranium/protocol';
+import { type AstNode, type AstNodeDescription, type LangiumDocument, type ReferenceInfo, type Scope, type Stream } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { type LabelProvider } from '../labeling/label-provider.js';
+import { type NameProvider } from '../naming/name-provider.js';
+import { type HydraniumScopeProvider } from './hydranium-scope-provider.js';
+/**
+ * Reference info enriched with the source document and the source's
+ * project id (when the framework's `ProjectManager` resolves one
+ * for the document's URI). Returned by
+ * {@link DefaultReferenceCandidateProvider.scopedReferenceInfo};
+ * consumed by {@link DefaultReferenceCandidateProvider.filterCandidate}
+ * so grammar-specific filters know which project is asking.
+ * Adopters that carry richer source context (e.g. a data-model id)
+ * extend this with additional fields.
+ */
+export interface ScopedReferenceInfo extends ReferenceInfo {
+    /** The document declaring the source container. */
+    document: LangiumDocument;
+    /**
+     * The project id of {@link document}'s owning project, or `undefined`
+     * when no `ProjectManager` resolves a project for the document's URI
+     * (e.g. a standalone file, or framework binding without a project
+     * manager).
+     */
+    projectId: string | undefined;
+}
+/**
+ * Result of {@link ReferenceCandidateProvider.getCandidateScope}:
+ * the filtered + sorted scope plus the enriched source reference info
+ * that produced it. Consumers read `elementScope.getAllElements()` for
+ * ranked items and `source` for context-aware downstream filtering.
+ *
+ * Generic over the `source` shape so adopters that extend
+ * {@link ScopedReferenceInfo} with richer context can return a
+ * `CandidateScope<TheirShape>` from their `scopedReferenceInfo`
+ * override without re-declaring the result interface.
+ */
+export interface CandidateScope<TSource extends ScopedReferenceInfo = ScopedReferenceInfo> {
+    /** Ranked + deduped descriptions, filtered through {@link DefaultReferenceCandidateProvider.filterCandidate}. */
+    elementScope: Scope;
+    /** Source reference info used to compute the scope. */
+    source: TSource;
+}
+/**
+ * Resolution result handed back by
+ * {@link ReferenceCandidateProvider.resolveCandidate}: the built
+ * {@link ReferenceCandidate} for the matched target plus the resolved AST
+ * node. In-process only (the `node` never crosses the wire) — the
+ * data-server layer encodes the node into the wire `ReferenceTarget`.
+ */
+export interface ResolvedCandidate {
+    /** Candidate descriptor (uri / type / label / value) for the resolved target. */
+    candidate: ReferenceCandidate;
+    /** The resolved AST node, for the data-server layer to encode as a transfer subtree. */
+    node: AstNode;
+}
+/**
+ * Reference candidate provider — owns the UI-facing completion pipeline
+ * that turns a Langium scope into {@link ReferenceCandidate} DTOs for
+ * command-palettes, drop-target action providers, completion popups, and
+ * over-the-wire RPC consumers.
+ *
+ * Splits the four-stage pipeline (enrich source info → filter → dedupe
+ * + sort → build DTO) cleanly off the scope provider, leaving
+ * {@link HydraniumScopeProvider} focused on scope construction and
+ * reference resolution. Dependency direction: candidate provider →
+ * scope provider (uses `getScope`, `referenceContextToInfo`,
+ * `sortText`, `resolveReference`); scope provider never depends on the
+ * candidate provider, so the two services stay cycle-free.
+ *
+ * Adopters subclass one or the other based on which axis they want to
+ * customise: source resolution / scope composition lives on
+ * `HydraniumScopeProvider`; filter / display-name shaping lives on
+ * {@link DefaultReferenceCandidateProvider}.
+ */
+export interface ReferenceCandidateProvider {
+    /**
+     * UI-facing entry point: returns the candidate scope's elements as
+     * {@link ReferenceCandidate}s.
+     */
+    find(ctx: ReferenceContext): ReferenceCandidate[];
+    /**
+     * Build a ranked + deduped scope for candidate selection at the
+     * given reference context. Accepts either a Langium
+     * {@link ReferenceInfo} (for in-process callers that already have
+     * one) or a protocol-layer {@link ReferenceContext} (for callers
+     * wiring up from over-the-wire / synthetic contexts).
+     */
+    getCandidateScope(ctx: ReferenceContext | ReferenceInfo): CandidateScope;
+    /**
+     * Resolve a concrete {@link ReferenceRequest} to its target, returning
+     * the built candidate plus the resolved node, or `undefined` when the
+     * reference does not resolve. Uses the scope provider's resolution
+     * scope (tier-siblings preserved, so a value resolves whether written
+     * short or qualified), distinct from the collapsed candidate scope
+     * {@link getCandidateScope} builds for listing.
+     */
+    resolveCandidate(ref: ReferenceRequest): ResolvedCandidate | undefined;
+}
+/**
+ * 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 declare class DefaultReferenceCandidateProvider implements ReferenceCandidateProvider {
+    protected readonly services: ServerLanguageServices;
+    protected readonly scopeProvider: HydraniumScopeProvider;
+    protected readonly labelProvider: 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.
+     */
+    protected readonly nameProvider: NameProvider;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerLanguageServices, options?: LogNameOptions);
+    /**
+     * 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.
+     */
+    protected nameProviderFor(target: AstNode): NameProvider;
+    find(ctx: ReferenceContext): ReferenceCandidate[];
+    getCandidateScope(ctx: ReferenceContext | ReferenceInfo): CandidateScope;
+    resolveCandidate(ref: ReferenceRequest): ResolvedCandidate | undefined;
+    /**
+     * 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.
+     */
+    protected applyCanonicalFilter<T extends AstNodeDescription>(candidates: Stream<T>): Stream<T>;
+    /**
+     * 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.
+     */
+    protected scopedReferenceInfo(referenceInfo: ReferenceInfo): ScopedReferenceInfo;
+    /**
+     * 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.
+     */
+    protected filterCandidate(_description: AstNodeDescription, _reference: ScopedReferenceInfo): boolean;
+    /**
+     * 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.
+     */
+    protected buildCandidate(description: AstNodeDescription, _scope: CandidateScope): ReferenceCandidate;
+    /**
+     * 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.
+     */
+    protected buildResolvedCandidate(node: AstNode, value: string): ReferenceCandidate;
+}
+//# sourceMappingURL=reference-candidate-provider.d.ts.map

package/lib/langium/scope/reference-candidate-provider.d.ts.map

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