@reqlan/language 1.6.2 → 1.8.1

package/src/reqlan-definition-provider.ts

@@ -2,7 +2,7 @@
  * Go-to-definition for imports, file references, symbols, and embedded comment references.
  */
 import type { CstNode, FileSystemProvider, LangiumDocument, MaybePromise } from 'langium';
-import { AstUtils, CstUtils, GrammarUtils, URI } from 'langium';
+import { CstUtils, GrammarUtils, URI } from 'langium';
 import { DefaultDefinitionProvider, type GoToLink } from 'langium/lsp';
 import type { DefinitionParams, Position } from 'vscode-languageserver';
 import { LocationLink } from 'vscode-languageserver';
@@ -33,6 +33,7 @@ import {
     isInvalidFromImport,
     isLocalReference,
     isQualifiedReference,
+    isWildcardReference,
     type FileReference,
     type FileSymbolReference,
     type Import,
@@ -41,6 +42,7 @@ import {
 } from './generated/ast.js';
 import type { ReqlanServices } from './reqlan-module.js';
 import { pathResolveContextFromServices } from './reqlan-path-resolve.js';
+import { findWildcardReferenceAtPosition } from './reqlan-wildcard-resolve.js';
 
 export class ReqlanDefinitionProvider extends DefaultDefinitionProvider {
 
@@ -60,9 +62,20 @@ export class ReqlanDefinitionProvider extends DefaultDefinitionProvider {
     }
 
     override getDefinition(document: LangiumDocument, params: DefinitionParams): MaybePromise<LocationLink[] | undefined> {
+        // Fast path: when the cursor is on an idea token inside a bracket/wiki reference the
+        // answer is just the cached Langium ref target — no text scans, no file-system calls.
+        // Same-file and cross-file idea refs both take this path, so neither is slower than the other.
+        if (this.isIdeaReferencePosition(document, params.position)) {
+            return super.getDefinition(document, params);
+        }
         if (isMarkdownLinkLabelPosition(document, params.position)) {
             return undefined;
         }
+        // Wildcard refs open the activity-bar search pane via extension command (document link / middleware).
+        const offset = document.textDocument.offsetAt(params.position);
+        if (findWildcardReferenceAtPosition(document, offset)) {
+            return undefined;
+        }
         const commentPart = findCommentReferencePartAt(document, params.position);
         if (commentPart?.property === 'idea') {
             return this.createCommentIdeaReferenceLinks(document, commentPart.reference);
@@ -75,7 +88,11 @@ export class ReqlanDefinitionProvider extends DefaultDefinitionProvider {
             this.pathContext()
         );
         if (fileReference) {
-            if (fileReference.resolution === 'folder' || fileReference.resolution === 'missing') {
+            if (
+                fileReference.resolution === 'folder'
+                || fileReference.resolution === 'missing'
+                || fileReference.resolution === 'wildcard'
+            ) {
                 return undefined;
             }
             return [this.resolvedFileLinkToLocationLink(fileReference)];
@@ -95,6 +112,56 @@ export class ReqlanDefinitionProvider extends DefaultDefinitionProvider {
         return super.getDefinition(document, params);
     }
 
+    /**
+     * Returns true when the cursor sits on an idea/ideaset name token inside a bracket or
+     * wikilink reference (LocalReference or QualifiedReference) but NOT on the path/qualifier
+     * token that points to an import.  This lets us skip all text-scan pre-checks and jump
+     * straight to the cached Langium ref resolution.
+     */
+    private isIdeaReferencePosition(document: LangiumDocument, position: Position): boolean {
+        const root = document.parseResult.value.$cstNode;
+        if (!root) {
+            return false;
+        }
+        const offset = document.textDocument.offsetAt(position);
+        let current: CstNode | undefined = CstUtils.findLeafNodeAtOffset(root, offset);
+        while (current) {
+            const node = current.astNode;
+            if (isLocalReference(node)) {
+                // A local ref whose idea is already resolved → fast O(1) path.
+                // Unresolved ones still go through the normal flow so file-link checks can try.
+                return node.idea?.ref !== undefined;
+            }
+            if (isQualifiedReference(node)) {
+                const assignment = GrammarUtils.findAssignment(current);
+                if (!assignment) {
+                    current = current.container;
+                    continue;
+                }
+                // On the path/qualifier token → defer to import-path checks.
+                if (assignment.feature === 'path' || assignment.feature === 'qualifier') {
+                    return false;
+                }
+                // On the idea or ideaset token → O(1) cached ref lookup.
+                if (assignment.feature === 'idea' || assignment.feature === 'ideaset') {
+                    return node.idea?.ref !== undefined || node.ideaset?.ref !== undefined;
+                }
+                return false;
+            }
+            // FileReference / FileSymbolReference / Import / WildcardReference → not idea refs, stop.
+            if (
+                isFileReference(node)
+                || isFileSymbolReference(node)
+                || isImport(node)
+                || isWildcardReference(node)
+            ) {
+                return false;
+            }
+            current = current.container;
+        }
+        return false;
+    }
+
     protected override findLinks(source: CstNode): GoToLink[] {
         const fileLink = this.linkForFileReference(source) ?? this.linkForNamespaceImportReference(source);
         if (fileLink) {
@@ -229,24 +296,30 @@ export class ReqlanDefinitionProvider extends DefaultDefinitionProvider {
     }
 
     private findAnonymousImportPathLinkAtPosition(document: LangiumDocument, position: Position): GoToLink | undefined {
+        const root = document.parseResult.value.$cstNode;
+        if (!root) {
+            return undefined;
+        }
         const offset = document.textDocument.offsetAt(position);
-        for (const node of AstUtils.streamAst(document.parseResult.value)) {
-            if (!isQualifiedReference(node) || node.path?.ref) {
-                continue;
-            }
-            const pathNode = node.path?.$refNode ?? GrammarUtils.findNodeForProperty(node.$cstNode, 'path');
-            if (!pathNode || offset < pathNode.offset || offset >= pathNode.end) {
-                continue;
-            }
-            const resolved = resolveQualifiedReferencePathLink(node, this.documents, this.pathContext());
-            if (!resolved) {
-                continue;
-            }
-            const targetDocument = this.documents.getDocument(URI.parse(resolved.targetUri.split('#')[0]));
-            if (!targetDocument) {
-                continue;
+        // Walk up from the leaf node — O(depth) rather than O(all AST nodes).
+        let current: CstNode | undefined = CstUtils.findLeafNodeAtOffset(root, offset);
+        while (current) {
+            const node = current.astNode;
+            if (isQualifiedReference(node) && !node.path?.ref) {
+                const pathNode = node.path?.$refNode ?? GrammarUtils.findNodeForProperty(node.$cstNode, 'path');
+                if (pathNode && offset >= pathNode.offset && offset < pathNode.end) {
+                    const resolved = resolveQualifiedReferencePathLink(node, this.documents, this.pathContext());
+                    if (!resolved) {
+                        return undefined;
+                    }
+                    const targetDocument = this.documents.getDocument(URI.parse(resolved.targetUri.split('#')[0]));
+                    if (!targetDocument) {
+                        return undefined;
+                    }
+                    return resolvedFileLinkToGoToTarget(resolved, pathNode, targetDocument);
+                }
             }
-            return resolvedFileLinkToGoToTarget(resolved, pathNode, targetDocument);
+            current = current.container;
         }
         return undefined;
     }

package/src/reqlan-document-factory.ts

@@ -0,0 +1,75 @@
+/**
+ * Document factory that never lets a sync lex/parse throw escape into workspace init.
+ * Async path uses [ReqlanAsyncParser]: sync fast path by default, killable worker when escalated.
+ * rq:["../../../reqlan rq/language/parser_lexer.rq".parse_budget_timeout]
+ */
+import {
+    DefaultLangiumDocumentFactory,
+    type AstNode,
+    type LangiumDocument,
+    type LangiumSharedCoreServices,
+    type ParseResult,
+    type ParserOptions,
+    URI
+} from 'langium';
+import type { CancellationToken } from 'vscode-languageserver';
+import { CancellationToken as CancelToken } from 'vscode-languageserver';
+import { ReqlanAsyncParser } from './reqlan-async-parser.js';
+import {
+    createIncompleteParseResult,
+    type ReqlanParseResult
+} from './reqlan-parse-budget.js';
+
+export class ReqlanLangiumDocumentFactory extends DefaultLangiumDocumentFactory {
+    /** URIs that previously hit the parse budget — keep using a killable worker. */
+    private readonly workerEscalateUris = new Set<string>();
+
+    constructor(services: LangiumSharedCoreServices) {
+        super(services);
+    }
+
+    protected override parse<T extends AstNode>(
+        uri: URI,
+        text: string,
+        options?: ParserOptions
+    ): ParseResult<T> {
+        const services = this.serviceRegistry.getServices(uri);
+        try {
+            return services.parser.LangiumParser.parse(text, options);
+        } catch (error) {
+            return createIncompleteParseResult<T>(services.parser.LangiumParser, {
+                reason: 'failure',
+                cause: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+
+    protected override async parseAsync<T extends AstNode>(
+        uri: URI,
+        text: string,
+        cancellationToken: CancellationToken = CancelToken.None
+    ): Promise<ParseResult<T>> {
+        const services = this.serviceRegistry.getServices(uri);
+        const asyncParser = services.parser.AsyncParser;
+        const uriKey = uri.toString();
+        const forceWorker = this.workerEscalateUris.has(uriKey);
+
+        const result = asyncParser instanceof ReqlanAsyncParser
+            ? await asyncParser.parse<T>(text, cancellationToken, { forceWorker })
+            : await asyncParser.parse<T>(text, cancellationToken);
+
+        const reqlanResult = result as ReqlanParseResult<T>;
+        if (reqlanResult.reqlanIncomplete?.reason === 'timeout') {
+            this.workerEscalateUris.add(uriKey);
+        } else if (!reqlanResult.reqlanIncomplete) {
+            this.workerEscalateUris.delete(uriKey);
+        }
+
+        return result;
+    }
+
+    /** Test helper: expose incomplete marker after async parse. */
+    static isIncompleteDocument(document: LangiumDocument): boolean {
+        return Boolean((document.parseResult as ReqlanParseResult).reqlanIncomplete);
+    }
+}

package/src/reqlan-document-link-provider.ts

@@ -1,5 +1,6 @@
 /**
- * Clickable document links for file references and import paths.
+ * Clickable document links for idea references, file references, and import paths.
+ * Same-file and cross-file idea refs both get links so the editor underline is consistent.
  */
 import type { LangiumDocument } from 'langium';
 import type { DocumentLinkProvider } from 'langium/lsp';
@@ -7,6 +8,7 @@ import type { DocumentLink, DocumentLinkParams } from 'vscode-languageserver';
 import { DocumentLink as LspDocumentLink } from 'vscode-languageserver';
 import { collectFileLinks, resolvedFileLinkTargetUri } from './reqlan-file-link-resolver.js';
 import { folderReferenceCommandTarget } from './reqlan-reference-at-position.js';
+import { wildcardReferenceCommandTarget } from './reqlan-wildcard-resolve.js';
 import type { ReqlanServices } from './reqlan-module.js';
 import { pathResolveContextFromServices } from './reqlan-path-resolve.js';
 
@@ -35,6 +37,12 @@ export class ReqlanDocumentLinkProvider implements DocumentLinkProvider {
                     folderReferenceCommandTarget(link.targetUri)
                 )];
             }
+            if (link.resolution === 'wildcard' && link.wildcardArgs) {
+                return [LspDocumentLink.create(
+                    link.sourceRange,
+                    wildcardReferenceCommandTarget(link.wildcardArgs)
+                )];
+            }
             const target = resolvedFileLinkTargetUri(link);
             if (!target) {
                 return [];

package/src/reqlan-file-link-resolver.ts

@@ -1,7 +1,8 @@
 /**
- * Resolves file references and import paths to target URIs and editor ranges.
+ * Resolves file references, idea references, and import paths to target URIs and editor ranges.
+ * Document links use these so same-file and cross-file refs share the same underline/click affordance.
  */
-import type { CstNode, FileSystemProvider, LangiumDocument, LangiumDocuments, URI } from 'langium';
+import type { AstNode, CstNode, FileSystemProvider, LangiumDocument, LangiumDocuments, Reference, URI } from 'langium';
 import { AstUtils, CstUtils, GrammarUtils } from 'langium';
 import type { Range } from 'vscode-languageserver';
 import { resolveFileUri } from './reqlan-comment-resolver.js';
@@ -23,11 +24,14 @@ import {
     isLocalReference,
     isMarkdownLink,
     isQualifiedReference,
+    isWildcardReference,
     type FileReference,
     type FileSymbolReference,
     type Import,
+    type LocalReference,
     type MarkdownLink,
-    type QualifiedReference
+    type QualifiedReference,
+    type WildcardReference
 } from './generated/ast.js';
 import { parseMarkdownLink } from './reqlan-references.js';
 import { reqlanStringDelimiter } from './reqlan-quoted-strings.js';
@@ -35,8 +39,14 @@ import {
     isNamespaceImportOnlyReference,
     resolveNamespaceImportReferenceLink
 } from './reqlan-namespace-import-links.js';
+import {
+    resolveWildcardReferenceMatches,
+    wildcardArgsFromReference,
+    type WildcardMatch,
+    type WildcardReferenceArgs
+} from './reqlan-wildcard-resolve.js';
 
-export type ReferenceResolution = 'file' | 'folder' | 'missing';
+export type ReferenceResolution = 'file' | 'folder' | 'missing' | 'wildcard';
 
 export type FileLinkTargetIssue = 'empty' | 'parse-error';
 
@@ -47,6 +57,9 @@ export interface ResolvedFileLink {
     resolution?: ReferenceResolution;
     folderFiles?: string[];
     targetIssue?: FileLinkTargetIssue;
+    /** Present when resolution is `wildcard`. */
+    wildcardArgs?: WildcardReferenceArgs;
+    wildcardMatches?: WildcardMatch[];
 }
 
 function withFileSystem(
@@ -368,6 +381,80 @@ function fileStartRange(): Range {
     };
 }
 
+/**
+ * Document link for a resolved Langium cross-reference (same-file or imported idea/ideaset).
+ * Source range is the reference name; target is the declaration name (or whole node).
+ */
+export function resolveLinkedAstReferenceLink(reference: Reference<AstNode> | undefined): ResolvedFileLink | undefined {
+    const target = reference?.ref;
+    const sourceNode = reference?.$refNode;
+    if (!target || !sourceNode) {
+        return undefined;
+    }
+    const targetDocument = AstUtils.getDocument(target);
+    const nameNode = GrammarUtils.findNodeForProperty(target.$cstNode, 'name') ?? target.$cstNode;
+    if (!nameNode) {
+        return undefined;
+    }
+    return {
+        sourceRange: sourceNode.range,
+        targetUri: targetDocument.textDocument.uri,
+        targetRange: nameNode.range,
+        resolution: 'file'
+    };
+}
+
+/** Idea/ideaset name links inside bracket and qualified references (not namespace-file aliases). */
+export function resolveIdeaReferenceLinks(
+    reference: LocalReference | QualifiedReference
+): ResolvedFileLink[] {
+    if (isLocalReference(reference)) {
+        if (isNamespaceImportOnlyReference(reference)) {
+            return [];
+        }
+        const link = resolveLinkedAstReferenceLink(reference.idea);
+        return link ? [link] : [];
+    }
+    const links: ResolvedFileLink[] = [];
+    const ideasetLink = resolveLinkedAstReferenceLink(reference.ideaset);
+    if (ideasetLink) {
+        links.push(ideasetLink);
+    }
+    const ideaLink = resolveLinkedAstReferenceLink(reference.idea);
+    if (ideaLink) {
+        links.push(ideaLink);
+    }
+    return links;
+}
+
+export function resolveWildcardReferenceLink(
+    reference: WildcardReference,
+    documents: LangiumDocuments,
+    context?: PathResolveContext
+): ResolvedFileLink | undefined {
+    const pathNode = GrammarUtils.findNodeForProperty(reference.$cstNode, 'pathPattern');
+    const ideaNode = GrammarUtils.findNodeForProperty(reference.$cstNode, 'ideaPattern');
+    const sourceRange = reference.$cstNode?.range
+        ?? (pathNode && ideaNode
+            ? {
+                start: pathNode.range.start,
+                end: ideaNode.range.end
+            }
+            : pathNode?.range);
+    if (!sourceRange) {
+        return undefined;
+    }
+    const matches = resolveWildcardReferenceMatches(reference, documents, context);
+    const args = wildcardArgsFromReference(reference);
+    return {
+        sourceRange,
+        targetUri: AstUtils.getDocument(reference).uri.toString(),
+        resolution: 'wildcard',
+        wildcardArgs: args,
+        wildcardMatches: matches
+    };
+}
+
 export function collectFileLinks(
     document: LangiumDocument,
     documents: LangiumDocuments,
@@ -377,40 +464,49 @@ export function collectFileLinks(
     const pathContext = withFileSystem(fileSystem, context);
     const links: ResolvedFileLink[] = [];
     const linkedRanges: string[] = [];
+    const pushLink = (link: ResolvedFileLink): void => {
+        links.push(link);
+        linkedRanges.push(rangeKey(link.sourceRange));
+    };
     for (const node of AstUtils.streamAst(document.parseResult.value)) {
         if (isFileReference(node) || isFileSymbolReference(node)) {
             const link = resolveFileReferenceLink(node, documents, fileSystem, pathContext);
             if (link) {
-                links.push(link);
-                linkedRanges.push(rangeKey(link.sourceRange));
+                pushLink(link);
+            }
+        }
+        if (isWildcardReference(node)) {
+            const link = resolveWildcardReferenceLink(node, documents, pathContext);
+            if (link) {
+                pushLink(link);
             }
         }
         if ((isLocalReference(node) || isQualifiedReference(node)) && isNamespaceImportOnlyReference(node)) {
             const link = resolveNamespaceImportReferenceLink(node, documents, fileSystem, pathContext);
             if (link) {
-                links.push(link);
-                linkedRanges.push(rangeKey(link.sourceRange));
+                pushLink(link);
+            }
+        } else if (isLocalReference(node) || isQualifiedReference(node)) {
+            for (const link of resolveIdeaReferenceLinks(node)) {
+                pushLink(link);
             }
         }
         if (isImport(node)) {
             const link = resolveImportPathLink(node, documents, pathContext);
             if (link) {
-                links.push(link);
-                linkedRanges.push(rangeKey(link.sourceRange));
+                pushLink(link);
             }
         }
         if (isQualifiedReference(node) && node.path && !node.path.ref) {
             const link = resolveQualifiedReferencePathLink(node, documents, pathContext);
             if (link) {
-                links.push(link);
-                linkedRanges.push(rangeKey(link.sourceRange));
+                pushLink(link);
             }
         }
         if (isMarkdownLink(node)) {
             const link = resolveMarkdownLinkTargetLink(node, document, documents, fileSystem, pathContext);
             if (link) {
-                links.push(link);
-                linkedRanges.push(rangeKey(link.sourceRange));
+                pushLink(link);
             }
         }
     }
@@ -421,8 +517,7 @@ export function collectFileLinks(
         }
         const link = resolveEmbeddedFileReferenceLink(reference, document, documents, fileSystem, pathContext);
         if (link) {
-            links.push(link);
-            linkedRanges.push(key);
+            pushLink(link);
         }
     }
     return links;
@@ -440,7 +535,7 @@ function rangesOverlap(left: Range, right: Range): boolean {
 }
 
 export function resolvedFileLinkTargetUri(link: ResolvedFileLink): string | undefined {
-    if (link.resolution === 'folder' || link.resolution === 'missing') {
+    if (link.resolution === 'folder' || link.resolution === 'missing' || link.resolution === 'wildcard') {
         return undefined;
     }
     if (link.targetRange) {

package/src/reqlan-import-edits.ts

@@ -1,6 +1,8 @@
 /**
- * Shared WorkspaceEdit helpers for import insertion used by unresolved-reference quick fixes.
+ * Shared WorkspaceEdit helpers for import insertion used by unresolved-reference quick fixes
+ * and cross-file reference completion auto-import.
  * rq:["../../../reqlan rq/extension/language-support/features-imports.rq".import_error]
+ * rq:["../../../reqlan rq/extension/language-support/features-imports.rq".import_code_completion_auto_file_import]
  */
 import type { LangiumDocument, URI } from 'langium';
 import { UriUtils } from 'langium';

package/src/reqlan-inbound-reference-inlay-label.ts

@@ -28,43 +28,108 @@ export type ReferencedDeclaration = IdeaDeclaration | IdeaSet;
 
 const MAX_INLINE_NAMES = 3;
 
+/** Target key: `${documentUri}#${astNodePath}` — matches IndexManager reference descriptions. */
+export type InboundReferencerIndex = Map<string, InboundReferencer[]>;
+
 /**
- * Collect inbound idea referencers from the whole Langium workspace index
- * (every indexed `.rq` document), not only the declaration's file.
+ * Langium's IndexManager stores outbound refs per source document and scans every
+ * document for each `findAllReferences` call. Building the inverse once makes
+ * inlay hints O(workspace refs) instead of O(ideas × workspace refs).
+ * rq:["../../../reqlan rq/extension/syntax/features-syntax-highlighting.rq".inbound_inlay_index_performance]
  */
-export function collectInboundReferencers(
+type IndexManagerReferenceIndex = {
+    referenceIndex: Map<string, Array<{
+        sourceUri: { toString(): string };
+        sourcePath: string;
+        targetUri: { toString(): string };
+        targetPath: string;
+    }>>;
+};
+
+export function declarationInboundKey(
     services: ReqlanServices,
     declaration: ReferencedDeclaration
-): InboundReferencer[] {
+): string {
+    const document = AstUtils.getDocument(declaration);
+    const path = services.workspace.AstNodeLocator.getAstNodePath(declaration);
+    return `${document.uri.toString()}#${path}`;
+}
+
+/**
+ * Build inbound referencers for every idea/ideaset target in one pass.
+ */
+export function buildInboundReferencerIndex(services: ReqlanServices): InboundReferencerIndex {
     const documents = services.shared.workspace.LangiumDocuments;
     const locator = services.workspace.AstNodeLocator;
-    const referencers = new Map<string, InboundReferencer>();
-
-    // findReferences without documentUri walks IndexManager across the workspace.
-    for (const reference of services.references.References.findReferences(declaration, { includeDeclaration: false }).toArray()) {
-        const sourceDocument = documents.getDocument(reference.sourceUri);
-        if (!sourceDocument) {
-            continue;
-        }
-        const sourceNode = locator.getAstNode(sourceDocument.parseResult.value, reference.sourcePath);
-        if (!sourceNode) {
-            continue;
-        }
-        const referrer = enclosingReferrerDeclaration(sourceNode);
-        if (!referrer || isSameDeclaration(referrer, declaration)) {
-            continue;
-        }
-        const location = locationForReferrer(referrer);
-        if (!location) {
-            continue;
+    const indexManager = services.shared.workspace.IndexManager as unknown as IndexManagerReferenceIndex;
+    const buckets = new Map<string, Map<string, InboundReferencer>>();
+
+    for (const docRefs of indexManager.referenceIndex.values()) {
+        for (const reference of docRefs) {
+            const sourceDocument = documents.getDocument(reference.sourceUri as never);
+            if (!sourceDocument) {
+                continue;
+            }
+            const sourceNode = locator.getAstNode(sourceDocument.parseResult.value, reference.sourcePath);
+            if (!sourceNode) {
+                continue;
+            }
+            const referrer = enclosingReferrerDeclaration(sourceNode);
+            if (!referrer) {
+                continue;
+            }
+            const location = locationForReferrer(referrer);
+            if (!location) {
+                continue;
+            }
+            const targetKey = `${reference.targetUri.toString()}#${reference.targetPath}`;
+            const referrerDoc = AstUtils.getDocument(referrer).uri.toString();
+            const referrerPath = locator.getAstNodePath(referrer);
+            if (targetKey === `${referrerDoc}#${referrerPath}`) {
+                continue;
+            }
+            let byLocation = buckets.get(targetKey);
+            if (!byLocation) {
+                byLocation = new Map();
+                buckets.set(targetKey, byLocation);
+            }
+            byLocation.set(locationKey(location), {
+                name: referrer.name,
+                location
+            });
         }
-        referencers.set(locationKey(location), {
-            name: referrer.name,
-            location
-        });
     }
 
-    return [...referencers.values()].sort((left, right) => left.name.localeCompare(right.name));
+    const result: InboundReferencerIndex = new Map();
+    for (const [targetKey, byLocation] of buckets) {
+        result.set(
+            targetKey,
+            [...byLocation.values()].sort((left, right) => left.name.localeCompare(right.name))
+        );
+    }
+    return result;
+}
+
+export function lookupInboundReferencers(
+    index: InboundReferencerIndex,
+    services: ReqlanServices,
+    declaration: ReferencedDeclaration
+): InboundReferencer[] {
+    return index.get(declarationInboundKey(services, declaration)) ?? [];
+}
+
+/**
+ * Collect inbound idea referencers from the whole Langium workspace index
+ * (every indexed `.rq` document), not only the declaration's file.
+ *
+ * Prefer {@link buildInboundReferencerIndex} + {@link lookupInboundReferencers}
+ * when resolving many declarations (e.g. inlay hints).
+ */
+export function collectInboundReferencers(
+    services: ReqlanServices,
+    declaration: ReferencedDeclaration
+): InboundReferencer[] {
+    return lookupInboundReferencers(buildInboundReferencerIndex(services), services, declaration);
 }
 
 /** @deprecated Use {@link collectInboundReferencers} */
@@ -86,16 +151,6 @@ function enclosingReferrerDeclaration(node: AstNode): ReferencedDeclaration | un
     return undefined;
 }
 
-function isSameDeclaration(left: ReferencedDeclaration, right: ReferencedDeclaration): boolean {
-    if (left === right) {
-        return true;
-    }
-    if (left.name !== right.name) {
-        return false;
-    }
-    return AstUtils.getDocument(left).uri.toString() === AstUtils.getDocument(right).uri.toString();
-}
-
 function locationForReferrer(referrer: ReferencedDeclaration): Location | undefined {
     const nameNode = GrammarUtils.findNodeForProperty(referrer.$cstNode, 'name');
     if (!nameNode?.range) {