@hydranium/core 1.0.0-next.10

package/src/langium/scope/scope-extension-service.ts

@@ -0,0 +1,207 @@
+/********************************************************************************
+ * 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, AstUtils, type LangiumDocument, MapScope, type Scope, StreamScope, stream } 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 HydraniumAstNodeDescriptionProvider } from './ast-node-description-provider.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;
+}
+
+/** Build a {@link ScopeDescriptionAcceptor} that synthesises typed descriptions via `descriptions` and accumulates them into `into`. */
+function createScopeDescriptionAcceptor(
+   into: TieredAstNodeDescription[],
+   descriptions: HydraniumAstNodeDescriptionProvider
+): ScopeDescriptionAcceptor {
+   return {
+      local: options => into.push(descriptions.createLocal(options)),
+      universal: options => into.push(descriptions.createUniversal(options)),
+      push: description => into.push(description)
+   };
+}
+
+/**
+ * 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 class DefaultScopeExtensionService implements ScopeExtensionService {
+   protected readonly scopeExtensions = new Registry<ScopeExtension>();
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerLanguageServices,
+      options: ScopeExtensionServiceOptions = {}
+   ) {
+      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: ScopeExtension): Disposable {
+      return this.scopeExtensions.register(extension);
+   }
+
+   getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope {
+      const local = this.collectExtensionDescriptions(referenceType, context, 'local');
+      if (local.length === 0) {
+         return outerScope;
+      }
+      return new StreamScope(stream(local), outerScope);
+   }
+
+   getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope {
+      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.)
+    */
+   protected collectExtensionDescriptions(
+      referenceType: string,
+      context: AstNode,
+      tier: 'local' | 'universal'
+   ): TieredAstNodeDescription[] {
+      const extensionsForType = this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+      if (extensionsForType.length === 0) {
+         return [];
+      }
+      const document = AstUtils.getDocument(context);
+      const collected: TieredAstNodeDescription[] = [];
+      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);
+   }
+}

package/src/langium/scope/scoped-ast-node-description.ts

@@ -0,0 +1,174 @@
+/********************************************************************************
+ * 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 { AstNodeDescription } from '@hydranium/langium';
+
+/**
+ * Visibility tier of a {@link TieredAstNodeDescription} — the static
+ * metadata declaring intended visibility class for each description.
+ *
+ * Tier is orthogonal to "scope" (the source-conditioned, tier-aware
+ * projection of the global index at a query site, built by the scope
+ * providers via filter rules over tiers). Tier is a per-description
+ * label; scope is a per-query result.
+ *
+ * Four values:
+ * - `'local'` — document-only (not in the global index; lives in
+ *   Langium's precomputed per-document scope).
+ * - `'project'` — visible inside the owning project only (equality
+ *   check against the source's project id).
+ * - `'public'` — visible from dependent projects only (own-project
+ *   canonical filter + dependency-closure membership). The
+ *   project-qualified public-tier sibling of a multi-tier emission.
+ * - `'universal'` — visible everywhere unconditionally. Synthetic /
+ *   library / stdlib content with no project ownership.
+ */
+export type DescriptionTier = 'local' | 'project' | 'public' | 'universal';
+
+/**
+ * A description that carries its visibility tier (and optional owning
+ * project id) as typed fields. The framework's filter rules read these
+ * fields directly to build per-query scopes without rediscovering
+ * visibility via URI lookup on the hot path.
+ *
+ * The framework's `HydraniumScopeProvider.bucketFor`
+ * reads `tier` directly when present and falls back to the URI-based
+ * lookup for untagged descriptions, so adoption is incremental.
+ */
+export interface TieredAstNodeDescription extends AstNodeDescription {
+   readonly tier: DescriptionTier;
+   /**
+    * Owning project id. Semantics vary by tier:
+    *
+    * - **`tier: 'project'`** — REQUIRED. Identifies the project that
+    *   owns this description; visible iff `description.projectId ===
+    *   sourceProjectId` (equality, not closure membership). Cross-
+    *   project access via the `'public'`-tier sibling.
+    *
+    * - **`tier: 'public'`** — REQUIRED. Identifies the owning project of
+    *   a multi-tier emission's public-tier sibling. The filter hides
+    *   this description from queries originating inside its home
+    *   project (the `'project'` sibling under a shorter name is the
+    *   canonical entry there); visible from other projects iff
+    *   `description.projectId` is in the source's dependency closure.
+    *
+    * - **`tier: 'universal'`** — FORBIDDEN. Universal descriptions have
+    *   no owning project; visible everywhere unconditionally.
+    *
+    * - **`tier: 'local'`** — always absent. Local symbols don't pass
+    *   through the project filter, so the field would be unused.
+    *
+    * Set this via the matching `HydraniumAstNodeDescriptionProvider`
+    * factory method rather than constructing descriptions by hand — each
+    * method enforces the correct shape at the type level.
+    */
+   readonly projectId?: string;
+}
+
+/**
+ * Structural typeguard — true iff `description.tier` is set to a string.
+ *
+ * **Runtime value vs compile-time narrowing.** After the framework's
+ * `HydraniumAstNodeDescriptionProvider.createDescription` override always
+ * emits a `tier` field (defaulting to `'local'`), every description
+ * produced inside the framework is already a `TieredAstNodeDescription`
+ * at runtime — the predicate returns true for them unconditionally. The
+ * load-bearing value of this function today is **TypeScript narrowing**:
+ * it lifts an `AstNodeDescription` to `TieredAstNodeDescription` so call
+ * sites that need to read `.tier` / `.projectId` don't have to cast.
+ *
+ * The runtime check is still required for descriptions that originate
+ * outside the framework — third-party Langium services, fixtures, raw
+ * `IndexManager.allElements` consumers — where the field may be absent.
+ */
+export function isTieredDescription(description: AstNodeDescription): description is TieredAstNodeDescription {
+   return typeof (description as TieredAstNodeDescription).tier === 'string';
+}
+
+/**
+ * True iff `description` is a {@link TieredAstNodeDescription} with
+ * `tier === 'local'`. Use to filter / narrow at call sites that switch
+ * on tier; equivalent to `isTieredDescription(d) && d.tier === 'local'`
+ * with the type narrowing baked in.
+ */
+export function isLocalTier(description: AstNodeDescription): description is TieredAstNodeDescription & { readonly tier: 'local' } {
+   return isTieredDescription(description) && description.tier === 'local';
+}
+
+/**
+ * True iff `description` is a {@link TieredAstNodeDescription} with
+ * `tier === 'project'`. Narrows `projectId` to non-nullable `string` —
+ * matches the design contract that project-tier descriptions always
+ * carry an owning project id.
+ */
+export function isProjectTier(
+   description: AstNodeDescription
+): description is TieredAstNodeDescription & { readonly tier: 'project'; readonly projectId: string } {
+   return isTieredDescription(description) && description.tier === 'project';
+}
+
+/**
+ * True iff `description` is the public-tier sibling of a multi-tier
+ * emission — a {@link TieredAstNodeDescription} with `tier === 'public'`.
+ *
+ * `'public'` descriptions ALWAYS carry a `projectId` by construction
+ * (the typed factory `createPublic` requires it). The framework's
+ * `HydraniumScopeProvider.bucketFor` suppresses
+ * a `'public'` description inside its owning project (so the shorter-
+ * name `'project'`-tier sibling is the canonical entry there) and
+ * shows it to dependent projects in the source's visibility closure.
+ *
+ * Use this typeguard at sites that iterate `IndexManager.allElements()`
+ * and want to count each AST node exactly once — skip the public half
+ * because the project-tier sibling already represents the node.
+ */
+export function isPublicTier(
+   description: AstNodeDescription
+): description is TieredAstNodeDescription & { readonly tier: 'public'; readonly projectId: string } {
+   return isTieredDescription(description) && description.tier === 'public';
+}
+
+/**
+ * True iff `description` is `tier === 'universal'` — synthetic /
+ * library / stdlib content with no project ownership, visible
+ * everywhere unconditionally.
+ *
+ * Universal descriptions never carry `projectId` (forbidden by the
+ * factory `createUniversal`); the narrowed type omits the field.
+ */
+export function isUniversalTier(description: AstNodeDescription): description is TieredAstNodeDescription & { readonly tier: 'universal' } {
+   return isTieredDescription(description) && description.tier === 'universal';
+}
+
+/**
+ * Relational variant of {@link isPublicTier} — true iff the description
+ * is a `'public'`-tier entry whose owning project is the given `projectId`.
+ * Distinct from {@link isPublicTier} (which matches any public-tier
+ * description, regardless of home).
+ *
+ * Used at adopter sites that pick the canonical entry for a given
+ * source project: when iterating descriptions reachable from a source
+ * URI's project, the public-tier sibling belonging to that
+ * same project is redundant (the project-tier sibling under a shorter
+ * name is already in scope) and should be hidden from completion /
+ * linking. The framework's
+ * `HydraniumScopeProvider.bucketFor` uses this
+ * predicate to enforce the own-project canonical filter on the typed scope path.
+ *
+ * `projectId` accepts `string | undefined` for adopter-call-site
+ * ergonomics: when the source has no resolvable project (standalone
+ * document, no ProjectManager binding), the predicate returns `false`
+ * for every description without forcing every caller to guard.
+ */
+export function isPublicFor(
+   description: AstNodeDescription,
+   projectId: string | undefined
+): description is TieredAstNodeDescription & { readonly tier: 'public'; readonly projectId: string } {
+   return projectId !== undefined && isPublicTier(description) && description.projectId === projectId;
+}

package/src/langium/scope/tier-specificity.ts

@@ -0,0 +1,89 @@
+/********************************************************************************
+ * 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 AstNodeDescription, type Stream, stream } from '@hydranium/langium';
+import { isTieredDescription } from './scoped-ast-node-description.js';
+
+/**
+ * Tier-sibling primitives — the building blocks for the "canonical
+ * filter" that collapses the multiple descriptions a single AST node
+ * emits across visibility tiers (multi-tier emission) down to the one
+ * most-specific tier-sibling per node.
+ *
+ * Multi-tier emission means one node is exported under several
+ * {@link AstNodeDescription}s — e.g. a `'project'`-tier short name and a
+ * `'public'`-tier project-qualified name for the same node. Those
+ * descriptions are *tier siblings*: same node, different tier. In a
+ * resolution scope both may legitimately appear (so a reference resolves
+ * by either form); in a completion dropdown only the canonical
+ * (most-specific) sibling should be shown so the user sees one entry per
+ * node.
+ */
+
+/**
+ * True if two descriptions refer to the same AST node, regardless of
+ * tier. Prefers node identity when both carry a live `node`; otherwise
+ * falls back to the stable document-URI + path key.
+ */
+export function areTierSiblings(left: AstNodeDescription, right: AstNodeDescription): boolean {
+   if (left.node !== undefined && left.node === right.node) {
+      return true;
+   }
+   return left.documentUri.toString() === right.documentUri.toString() && left.path === right.path;
+}
+
+/**
+ * Compare two descriptions by tier specificity. Returns a negative
+ * number if `left` is more specific (should win), positive if `right`
+ * is, `0` if equally specific. More specific = narrower visibility:
+ * `local` < `project` < `public` < `universal`. Untiered descriptions
+ * rank least specific so a tiered sibling always wins.
+ */
+export function compareTierSpecificity(left: AstNodeDescription, right: AstNodeDescription): number {
+   return tierRank(left) - tierRank(right);
+}
+
+function tierRank(description: AstNodeDescription): number {
+   if (!isTieredDescription(description)) {
+      return Number.POSITIVE_INFINITY;
+   }
+   switch (description.tier) {
+      case 'local':
+         return 0;
+      case 'project':
+         return 1;
+      case 'public':
+         return 2;
+      case 'universal':
+         return 3;
+   }
+}
+
+function nodeKey(description: AstNodeDescription): string {
+   return `${description.documentUri.toString()}#${description.path}`;
+}
+
+/**
+ * Canonical filter: group descriptions by AST node and keep the
+ * most tier-specific sibling per group (see
+ * {@link compareTierSpecificity}). Input order is otherwise preserved —
+ * the first-seen sibling holds each group's slot and is only replaced by
+ * a strictly more specific one, so a stable upstream order stays stable.
+ */
+export function dedupeTierSiblingsStream<T extends AstNodeDescription>(descriptions: Stream<T>): Stream<T> {
+   const byNode = new Map<string, T>();
+   for (const description of descriptions) {
+      const key = nodeKey(description);
+      const existing = byNode.get(key);
+      if (existing === undefined || compareTierSpecificity(description, existing) < 0) {
+         byNode.set(key, description);
+      }
+   }
+   return stream(byNode.values());
+}