@hydranium/core 1.0.0-next.39 → 1.0.0-next.391

package/src/langium/scope/hydranium-scope-provider.ts

@@ -24,11 +24,12 @@ import {
    type AstNodeLocator,
    AstUtils,
    DefaultScopeProvider,
+   type LocalSymbols,
    MapScope,
+   MultiMapScope,
    type ReferenceInfo,
    type Scope,
    type ScopeOptions,
-   StreamScope,
    type URI,
    UriUtils,
    WorkspaceCache,
@@ -39,8 +40,10 @@ import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumLanguageServices } from '../language-module.js';
 import { type NameProvider } from '../naming/name-provider.js';
 import { type HydraniumDocumentRegistry } from '../workspace/langium-documents.js';
-import { type ScopeExtensionService } from './scope-extension-service.js';
-import { isTieredDescription } from './scoped-ast-node-description.js';
+import { builtLocalSymbols } from './built-local-symbols.js';
+import { FallbackScope } from './fallback-scope.js';
+import { type ScopeExtensionDescriptions, type ScopeExtensionService } from './scope-extension-service.js';
+import { type TieredAstNodeDescription, isTieredDescription } from './scoped-ast-node-description.js';
 
 /**
  * Construction-time options for {@link HydraniumScopeProvider}. Extends
@@ -95,7 +98,7 @@ export interface ScopeContext {
 /**
  * Per-language scope provider that owns the full scope chain in ONE
  * class. Bridges the protocol-layer {@link ReferenceContext} to
- * Langium's {@link ReferenceInfo}, layers per-context scope-extension
+ * Langium's {@link ReferenceInfo}, layers scope-extension
  * contributions ({@link ScopeExtensionService}) at their declared tier,
  * and composes the cached project-tier chain (own-project → dependency
  * → universal) on top of Langium's unfiltered global index.
@@ -103,16 +106,16 @@ export interface ScopeContext {
  * ## Scope chain (high → low, inner shadows outer)
  *
  * ```
- *   document-local (Langium precomputed)        [DefaultScopeProvider.getScope]
- *     extension:local                           [layerLocalExtension, per-context]
+ *   document-local (Langium precomputed)        [getScope, CACHED per build in localScope]
+ *     extension:local                           [layerLocalExtension, CACHED per descriptions]
  *       own-project → dependency → universal-index   [createGlobalScope default, CACHED per ${project}::${refType}]
- *         extension:universal                   [layerUniversalExtension, per-context, outermost]
+ *         extension:universal                   [layerUniversalExtension, CACHED per descriptions, outermost]
  * ```
  *
- * Implementation: Langium's `getScope` layers document-local on top of
- * whatever `getGlobalScope` returns. The framework owns `getGlobalScope`
- * and uses it to assemble everything *below* document-local, with the
- * adopter-overridable {@link createGlobalScope} in the middle.
+ * Implementation: {@link getScope} layers document-local on top of
+ * whatever `getGlobalScope` returns, as Langium's does. The framework owns
+ * `getGlobalScope` and uses it to assemble everything *below* document-local,
+ * with the adopter-overridable {@link createGlobalScope} in the middle.
  *
  * ## Adopter override surface
  *
@@ -132,7 +135,8 @@ export interface ScopeContext {
  * - **{@link createScopeForNodes}** — inherited from Langium and re-keyed by
  *   the framework to bare own-names, so it is the helper a `getScope`
  *   override uses to resolve a dotted member reference against a container
- *   the reference chain cannot reach.
+ *   the reference chain cannot reach. Override {@link createNodeScope} to
+ *   change the scope it builds.
  *
  * **Do NOT override `getGlobalScope` itself** — that is the framework's
  * extension-assembly seam. Overriding it would hide the scope-extension
@@ -161,6 +165,24 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * the workspace-global `DocumentBuilder.onUpdate`.
     */
    protected readonly scopeCache: WorkspaceCache<string, Scope>;
+   /**
+    * Each container's local scope per reference type, keyed by the local
+    * symbols it was built from. A build replaces a document's local symbols
+    * when it recomputes them, so a rebuilt document never reads a stale entry.
+    */
+   protected readonly localScopes = new WeakMap<LocalSymbols, Map<AstNode, Map<string, Scope>>>();
+   /**
+    * {@link createScopeForNodes}' scope per list of nodes, keyed by the local
+    * symbols of the document the nodes belong to, which a rebuild of that
+    * document replaces.
+    */
+   protected readonly nodeScopes = new WeakMap<LocalSymbols, WeakMap<readonly AstNode[], Scope>>();
+   /**
+    * The scope of each scope extension's descriptions of one tier, keyed by
+    * the array: an extension with a cache key answers every reference of that
+    * key with the same one.
+    */
+   protected readonly extensionScopes = new WeakMap<readonly TieredAstNodeDescription[], Scope>();
    protected readonly tracer: Tracer;
    /**
     * Narrows the inherited Langium {@link NameProvider} field to the framework's
@@ -183,19 +205,115 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
       this.tracer = services.shared.Tracer.for(options.logName ?? 'ScopeProvider').trace('instantiated');
    }
 
+   /**
+    * Drop every cached scope — the framework's project-tier chain and the
+    * inherited global scope it is filtered from.
+    *
+    * **Called from outside the class**, by the build pipeline once the batch is
+    * re-indexed. The caches' own eviction does not cover this:
+    * `DocumentBuilder.onUpdate` fires after the build has taken every changed
+    * document's symbols out of the index and before it puts them back, so a
+    * scope built in that gap denies those symbols exist and every document the
+    * same build links afterwards resolves against it.
+    *
+    * Both go together because the second is derived from the first: clearing
+    * only {@link scopeCache} refills it from a stale `globalScopeCache`, and
+    * clearing only `globalScopeCache` leaves the filtered copy standing.
+    */
+   clearScopeCaches(): void {
+      this.scopeCache.clear();
+      this.globalScopeCache.clear();
+   }
+
+   /**
+    * Langium's, with each container's local scope built once per build through
+    * {@link localScope} rather than once per reference. Linking a document then
+    * costs its references plus its declarations, not their product.
+    */
+   override getScope(context: ReferenceInfo): Scope {
+      const referenceType = this.reflection.getReferenceType(context);
+      const localSymbols = this.localSymbolsOf(context.container);
+      let result = this.getGlobalScope(referenceType, context);
+      if (localSymbols === undefined) {
+         return result;
+      }
+      const containers: AstNode[] = [];
+      for (let container: AstNode | undefined = context.container; container; container = container.$container) {
+         if (localSymbols.has(container)) {
+            containers.push(container);
+         }
+      }
+      // Outermost first, so the innermost container's symbols shadow the rest.
+      for (let i = containers.length - 1; i >= 0; i--) {
+         result = new FallbackScope(this.localScope(localSymbols, containers[i], referenceType), result);
+      }
+      return result;
+   }
+
+   /**
+    * The local symbols of the build that `node`'s root came from: the
+    * document's while they are set for that root, else the ones the build
+    * pipeline recorded for it when its document computed scopes. A rebuild
+    * clears the document's, then keys them by the new root's nodes.
+    */
+   protected localSymbolsOf(node: AstNode): LocalSymbols | undefined {
+      const root = AstUtils.findRootNode(node);
+      const document = AstUtils.getDocument(root);
+      const recorded = builtLocalSymbols.get(root);
+      if (recorded === undefined || (document.parseResult.value === root && document.localSymbols !== undefined)) {
+         return document.localSymbols;
+      }
+      return recorded;
+   }
+
+   /**
+    * The symbols `container` declares that a `referenceType` reference can
+    * reach, through {@link createScope}, built once per `localSymbols`.
+    */
+   protected localScope(localSymbols: LocalSymbols, container: AstNode, referenceType: string): Scope {
+      let byContainer = this.localScopes.get(localSymbols);
+      if (byContainer === undefined) {
+         byContainer = new Map();
+         this.localScopes.set(localSymbols, byContainer);
+      }
+      let byType = byContainer.get(container);
+      if (byType === undefined) {
+         byType = new Map();
+         byContainer.set(container, byType);
+      }
+      let scope = byType.get(referenceType);
+      if (scope === undefined) {
+         scope = this.createScope(
+            localSymbols.getStream(container).filter(description => this.reflection.isSubtype(description.type, referenceType))
+         );
+         byType.set(referenceType, scope);
+      }
+      return scope;
+   }
+
+   /**
+    * Keyed by name, where Langium's walks every element on each lookup. Every
+    * description of a name is kept and the first answers, as in Langium's;
+    * `getAllElements` lists them in order, but with a description following
+    * the first of its name.
+    */
+   protected override createScope(elements: Iterable<AstNodeDescription>, outerScope?: Scope, options?: ScopeOptions): Scope {
+      return new MultiMapScope(elements, outerScope, options);
+   }
+
    /**
     * Framework-owned assembly seam. **Adopters do NOT override this** —
     * override {@link createGlobalScope} instead. This method layers the
     * scope-extension tiers around the adopter-overridable global scope.
     *
-    * Langium's `DefaultScopeProvider.getScope` then layers document-local
-    * on top of this result, yielding the full chain documented on the
-    * class.
+    * {@link getScope} then layers document-local on top of this result,
+    * yielding the full chain documented on the class.
     */
    protected override getGlobalScope(referenceType: string, context: ReferenceInfo): Scope {
       const projectChain = this.createGlobalScope(referenceType, context);
-      const withUniversal = this.layerUniversalExtension(referenceType, context, projectChain);
-      return this.layerLocalExtension(referenceType, context, withUniversal);
+      const extensions = this.scopeExtensionService.getDescriptions(referenceType, context.container);
+      const withUniversal = this.layerUniversalExtension(extensions, projectChain, referenceType, context);
+      return this.layerLocalExtension(extensions, withUniversal, referenceType, context);
    }
 
    /**
@@ -230,22 +348,66 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
-    * Layer scope-extension `local`-tier descriptions on top of `inner`.
-    * Returns `inner` unchanged when no extension contributes for the
-    * reference type (zero-cost common path).
+    * Layer each scope extension's `local`-tier descriptions on top of `inner`,
+    * an earlier extension's above a later one's, through {@link extensionScope}.
+    * Returns `inner` unchanged when there are none.
     */
-   protected layerLocalExtension(referenceType: string, context: ReferenceInfo, inner: Scope): Scope {
-      return this.scopeExtensionService.getLocalExtensionScope(referenceType, context.container, inner);
+   protected layerLocalExtension(
+      extensions: readonly ScopeExtensionDescriptions[],
+      inner: Scope,
+      _referenceType: string,
+      _context: ReferenceInfo
+   ): Scope {
+      return (
+         this.chainExtensionScopes(
+            extensions.map(extension => extension.local),
+            inner
+         ) ?? inner
+      );
+   }
+
+   /**
+    * Layer each scope extension's `universal`-tier descriptions below `inner`,
+    * which shadows them, an earlier extension's above a later one's, through
+    * {@link extensionScope}. Returns `inner` unchanged when there are none.
+    */
+   protected layerUniversalExtension(
+      extensions: readonly ScopeExtensionDescriptions[],
+      inner: Scope,
+      _referenceType: string,
+      _context: ReferenceInfo
+   ): Scope {
+      const below = this.chainExtensionScopes(extensions.map(extension => extension.universal));
+      return below ? new FallbackScope(inner, below) : inner;
+   }
+
+   /**
+    * Chain the scope of each non-empty array above `outer`, an earlier array's
+    * above a later one's; `undefined` when there is neither.
+    */
+   protected chainExtensionScopes(tiers: ReadonlyArray<readonly TieredAstNodeDescription[]>, outer?: Scope): Scope | undefined {
+      let result = outer;
+      for (let i = tiers.length - 1; i >= 0; i--) {
+         if (tiers[i].length > 0) {
+            const scope = this.extensionScope(tiers[i]);
+            result = result ? new FallbackScope(scope, result) : scope;
+         }
+      }
+      return result;
    }
 
    /**
-    * Layer scope-extension `universal`-tier descriptions BELOW `inner`
-    * (extensions appear last in the chain, shadowed by inner). Returns
-    * `inner` unchanged when no extension contributes for the reference
-    * type.
+    * The scope of one extension's descriptions of one tier, through
+    * {@link createScope}, built once per array and shared by every reference
+    * it answers, so an override of `createScope` sees no reference context.
     */
-   protected layerUniversalExtension(referenceType: string, context: ReferenceInfo, inner: Scope): Scope {
-      return this.scopeExtensionService.getUniversalExtensionScope(referenceType, context.container, inner);
+   protected extensionScope(descriptions: readonly TieredAstNodeDescription[]): Scope {
+      let scope = this.extensionScopes.get(descriptions);
+      if (scope === undefined) {
+         scope = this.createScope(descriptions);
+         this.extensionScopes.set(descriptions, scope);
+      }
+      return scope;
    }
 
    /**
@@ -286,7 +448,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * closure).
     *
     * Contrast {@link getGlobalScope}, which applies the framework's
-    * tier filter to this set, and `getScope` (Langium default), which
+    * tier filter to this set, and {@link getScope}, which
     * additionally merges in the local scope.
     */
    protected getAllElementsGlobalScope(referenceType: string, context: ReferenceInfo): Scope {
@@ -344,11 +506,11 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * Includes own-project `'public'`-tier descriptions when
     * {@link HydraniumScopeProviderOptions.includeOwnProjectPublic} is set
     * (routed to the own-project bucket by {@link bucketFor}). Returns a
-    * {@link StreamScope} (not {@link MapScope}) so same-name siblings are
+    * {@link MultiMapScope} (not {@link MapScope}) so same-name siblings are
     * preserved rather than collapsed.
     */
    protected createOwnProjectScope(context: ScopeContext): Scope {
-      return new StreamScope(stream(context.ownProjectEntries));
+      return new MultiMapScope(context.ownProjectEntries);
    }
 
    /**
@@ -357,7 +519,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * (own-project canonical filter applied by {@link bucketFor}).
     */
    protected createDependencyScope(context: ScopeContext): Scope {
-      return new StreamScope(stream(context.dependencyEntries));
+      return new MultiMapScope(context.dependencyEntries);
    }
 
    /**
@@ -369,13 +531,13 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
-    * Chain three tier sub-scopes inner-first. The `outerScope` argument
-    * of {@link StreamScope} is consulted only when the inner stream has
-    * no match, so a more specific tier shadows a less specific one of
-    * the same name.
+    * Chain three tier sub-scopes inner-first through {@link FallbackScope},
+    * which consults an outer tier only when the inner one has no match, so a
+    * more specific tier shadows a less specific one of the same name, and each
+    * tier keeps its own lookup.
     */
    protected chainScopes(ownScope: Scope, dependencyScope: Scope, universalScope: Scope): Scope {
-      return new StreamScope(ownScope.getAllElements(), new StreamScope(dependencyScope.getAllElements(), universalScope));
+      return new FallbackScope(ownScope, new FallbackScope(dependencyScope, universalScope));
    }
 
    /**
@@ -442,9 +604,51 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
+    * Langium's, with the scope cached: a member scope is asked for once per
+    * reference, and building it each time makes linking cost references times
+    * members.
+    *
+    * - Cached: the scope for a list of a built document's nodes, passed with
+    *   no `outerScope` or `options`, built once through {@link createNodeScope}.
+    * - Dropped: when that document's local symbols are replaced; a build that
+    *   leaves its nodes in place keeps it.
+    * - Any other list gets a scope per call.
+    *
+    * Override {@link createNodeScope} to change the scope; an override of this
+    * method keeps the cache only by calling `super`. The list must hold nodes
+    * of one document, which it is keyed by; a list changed in place between
+    * builds is answered as it was.
+    */
+   protected override createScopeForNodes(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): Scope {
+      if (!Array.isArray(elements) || elements.length === 0 || outerScope !== undefined || options !== undefined) {
+         return this.createNodeScope(elements, outerScope, options);
+      }
+      const nodes: readonly AstNode[] = elements;
+      const root = AstUtils.findRootNode(nodes[0]);
+      const localSymbols = root.$document?.parseResult.value === root ? root.$document.localSymbols : undefined;
+      if (localSymbols === undefined) {
+         return this.createNodeScope(nodes);
+      }
+      let byList = this.nodeScopes.get(localSymbols);
+      if (byList === undefined) {
+         byList = new WeakMap();
+         this.nodeScopes.set(localSymbols, byList);
+      }
+      let scope = byList.get(nodes);
+      if (scope === undefined) {
+         scope = this.createNodeScope(nodes);
+         byList.set(nodes, scope);
+      }
+      return scope;
+   }
+
+   /**
+    * The scope {@link createScopeForNodes} answers with, keyed by name.
+    *
     * Keys the scope by {@link NameProvider.getOwnName} instead of Langium's
-    * `getName`. Same correction `HydraniumScopeComputation.addLocalSymbol`
-    * makes to the local-symbols pass, for the same reason: `getName` defaults
+    * `getName`. Same correction
+    * `HydraniumScopeComputation.addLocalSymbolByOwnName` makes to the
+    * local-symbols pass, for the same reason: `getName` defaults
     * to the project-qualified form here, so the base would key a member scope
     * by the fully qualified `Container.member` while the reference text after
     * the dot is the bare `member` — and nothing reports the mismatch, because
@@ -454,7 +658,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * reference to a member the container does not have must fail rather than
     * fall through to a same-named member on an unrelated type.
     */
-   protected override createScopeForNodes(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): Scope {
+   protected createNodeScope(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): Scope {
       const descriptions = stream(elements)
          .map(node => {
             const name = this.nameProvider.getOwnName(node);
@@ -463,7 +667,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
             return name ? this.descriptions.createDescription(node, name, AstUtils.getDocument(node)) : undefined;
          })
          .nonNullable();
-      return new StreamScope(descriptions, outerScope, options);
+      return new MultiMapScope(descriptions, outerScope, options);
    }
 
    /**

package/src/langium/scope/index.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 export * from './ast-node-description-provider.js';
+export * from './fallback-scope.js';
 export * from './reference-builder.js';
 export * from './reference-candidate-provider.js';
 export * from './hydranium-scope-computation.js';

package/src/langium/scope/reference-candidate-provider.ts

@@ -102,9 +102,9 @@ export interface ResolvedCandidate {
 export interface ReferenceCandidateProvider {
    /**
     * UI-facing entry point: returns the candidate scope's elements as
-    * {@link ReferenceCandidate}s.
+    * {@link ReferenceCandidate}s. Accepts what {@link getCandidateScope} does.
     */
-   find(ctx: ReferenceContext): ReferenceCandidate[];
+   find(ctx: ReferenceContext | ReferenceInfo): ReferenceCandidate[];
 
    /**
     * Build a ranked + deduped scope for candidate selection at the
@@ -195,14 +195,15 @@ export class DefaultReferenceCandidateProvider implements ReferenceCandidateProv
     * 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.
+    * The mirror of `DefaultReferenceBuilder.nameProviderFor`, and the same
+    * fallback reasoning: an unroutable target has no better answer than the
+    * source's.
     */
    protected nameProviderFor(target: AstNode): NameProvider {
       return this.services.shared.ServiceRegistry?.getServicesFor(target)?.references.NameProvider ?? this.nameProvider;
    }
 
-   find(ctx: ReferenceContext): ReferenceCandidate[] {
+   find(ctx: ReferenceContext | ReferenceInfo): ReferenceCandidate[] {
       const scope = this.getCandidateScope(ctx);
       return scope.elementScope
          .getAllElements()