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

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

@@ -8,7 +8,15 @@
  ********************************************************************************/
 
 import { type Tracer } from '@hydranium/protocol';
-import { type AstNode, type AstNodeDescription, DefaultAstNodeDescriptionProvider, type LangiumDocument } from '@hydranium/langium';
+import {
+   type AstNode,
+   AstUtils,
+   CstUtils,
+   DefaultAstNodeDescriptionProvider,
+   type DocumentSegment,
+   type LangiumDocument,
+   type URI
+} from '@hydranium/langium';
 import type { LogNameOptions } from '../diagnostics/logger.js';
 import type { HydraniumLanguageServices } from '../language-module.js';
 import { type DescriptionTier, type TieredAstNodeDescription } from './scoped-ast-node-description.js';
@@ -32,9 +40,11 @@ import { type DescriptionTier, type TieredAstNodeDescription } from './scoped-as
  */
 export class HydraniumAstNodeDescriptionProvider extends DefaultAstNodeDescriptionProvider {
    protected readonly tracer: Tracer;
+   protected readonly services: HydraniumLanguageServices;
 
    constructor(services: HydraniumLanguageServices, options: LogNameOptions = {}) {
       super(services);
+      this.services = services;
       this.tracer = services.shared.Tracer.for(options.logName ?? 'AstNodeDescriptionProvider').trace('instantiated');
    }
 
@@ -44,12 +54,11 @@ export class HydraniumAstNodeDescriptionProvider extends DefaultAstNodeDescripti
     * filter pipeline. Callers that need a different tier must use
     * {@link createProject}, {@link createPublic}, or {@link createUniversal}.
     *
-    * The named factory methods bypass this override by calling
-    * `super.createDescription` to get a plain base before stamping the
-    * correct tier — so there is no create-then-overwrite cost.
+    * Langium's own `createDescription` is not called: every factory builds
+    * through {@link createTiered}.
     */
-   override createDescription(node: AstNode, name: string, document: LangiumDocument): TieredAstNodeDescription {
-      return this.toTiered(super.createDescription(node, name, document), 'local');
+   override createDescription(node: AstNode, name: string | undefined, document?: LangiumDocument): TieredAstNodeDescription {
+      return this.createTiered(node, name, document, 'local');
    }
 
    /**
@@ -62,7 +71,7 @@ export class HydraniumAstNodeDescriptionProvider extends DefaultAstNodeDescripti
     * never sees them, so a project tag would be unused.
     */
    createLocal(options: { readonly node: AstNode; readonly name: string; readonly document: LangiumDocument }): TieredAstNodeDescription {
-      return this.toTiered(super.createDescription(options.node, options.name, options.document), 'local');
+      return this.createTiered(options.node, options.name, options.document, 'local');
    }
 
    /**
@@ -84,7 +93,7 @@ export class HydraniumAstNodeDescriptionProvider extends DefaultAstNodeDescripti
       readonly document: LangiumDocument;
       readonly projectId: string;
    }): TieredAstNodeDescription {
-      return this.toTiered(super.createDescription(options.node, options.name, options.document), 'project', options.projectId);
+      return this.createTiered(options.node, options.name, options.document, 'project', options.projectId);
    }
 
    /**
@@ -108,7 +117,7 @@ export class HydraniumAstNodeDescriptionProvider extends DefaultAstNodeDescripti
       readonly document: LangiumDocument;
       readonly projectId: string;
    }): TieredAstNodeDescription {
-      return this.toTiered(super.createDescription(options.node, options.name, options.document), 'public', options.projectId);
+      return this.createTiered(options.node, options.name, options.document, 'public', options.projectId);
    }
 
    /**
@@ -126,16 +135,102 @@ export class HydraniumAstNodeDescriptionProvider extends DefaultAstNodeDescripti
       readonly name: string;
       readonly document: LangiumDocument;
    }): TieredAstNodeDescription {
-      return this.toTiered(super.createDescription(options.node, options.name, options.document), 'universal');
+      return this.createTiered(options.node, options.name, options.document, 'universal');
    }
 
    /**
-    * Attach `tier` + `projectId` fields to a plain {@link AstNodeDescription}
-    * in place, narrowing the static type to {@link TieredAstNodeDescription}.
-    * Mutates `base` rather than copying — the input is treated as
-    * just-constructed and not aliased elsewhere.
+    * Resolve the fields of the description every factory returns and build it
+    * through {@link newDescription}. Mirrors Langium's `createDescription`:
+    * the name defaults to the name provider's, and a node without one throws.
     */
-   protected toTiered(base: AstNodeDescription, tier: DescriptionTier, projectId?: string): TieredAstNodeDescription {
-      return Object.assign(base, { tier, projectId }) as TieredAstNodeDescription;
+   protected createTiered(
+      node: AstNode,
+      name: string | undefined,
+      document: LangiumDocument | undefined,
+      tier: DescriptionTier,
+      projectId?: string
+   ): TieredAstNodeDescription {
+      const path = this.astNodeLocator.getAstNodePath(node);
+      const resolvedName = name ?? this.nameProvider.getName(node);
+      if (!resolvedName) {
+         throw new Error(`Node at path ${path} has no name.`);
+      }
+      const documentUri = (document ?? AstUtils.getDocument(node)).uri;
+      return this.newDescription(node, resolvedName, documentUri, path, tier, projectId);
+   }
+
+   /** Construct the description from resolved fields; override to build a subclass of {@link DefaultTieredAstNodeDescription}. */
+   protected newDescription(
+      node: AstNode,
+      name: string,
+      documentUri: URI,
+      path: string,
+      tier: DescriptionTier,
+      projectId: string | undefined
+   ): TieredAstNodeDescription {
+      return new DefaultTieredAstNodeDescription(this, node, name, documentUri, path, tier, projectId);
+   }
+
+   /**
+    * The segment of `node`'s name, or of the whole node when the name
+    * provider finds no name node, restoring a shed CST first: a name provider
+    * need not restore it, and an absent segment is not computed again.
+    */
+   nameSegmentOf(node: AstNode): DocumentSegment | undefined {
+      this.services.shared.workspace.CstResidencyService.rehydrateNode(node);
+      return CstUtils.toDocumentSegment(this.nameProvider.getNameNode(node) ?? node.$cstNode);
+   }
+
+   /** The segment of the whole node, restoring a shed CST first. */
+   selectionSegmentOf(node: AstNode): DocumentSegment | undefined {
+      this.services.shared.workspace.CstResidencyService.rehydrateNode(node);
+      return CstUtils.toDocumentSegment(node.$cstNode);
+   }
+}
+
+/**
+ * The description {@link HydraniumAstNodeDescriptionProvider} builds. Every
+ * field is set in the constructor, so all descriptions share one V8 hidden
+ * class; Langium's object literal with a `nameSegment` accessor is kept in
+ * dictionary mode and carries two closures, several times the bytes.
+ *
+ * `nameSegment` and `selectionSegment` are prototype getters, not own
+ * properties: a spread, `Object.keys`, a JSON round trip or `structuredClone`
+ * of a description drops them. Each is computed on its first read, from the
+ * node the description was built for, restoring a shed CST first; an eager
+ * `selectionSegment` would keep a segment per description that nothing reads.
+ */
+export class DefaultTieredAstNodeDescription implements TieredAstNodeDescription {
+   readonly type: string;
+   // `null` records a segment computed while the node had no CST. It is
+   // recomputed only once the node has one again: retrying without one would
+   // attempt a restore, a re-parse, on every read.
+   protected nameSegmentCache: DocumentSegment | null | undefined;
+   protected selectionSegmentCache: DocumentSegment | null | undefined;
+
+   constructor(
+      protected readonly provider: HydraniumAstNodeDescriptionProvider,
+      readonly node: AstNode,
+      readonly name: string,
+      readonly documentUri: URI,
+      readonly path: string,
+      readonly tier: DescriptionTier,
+      readonly projectId: string | undefined
+   ) {
+      this.type = node.$type;
+   }
+
+   get nameSegment(): DocumentSegment | undefined {
+      if (this.nameSegmentCache === undefined || (this.nameSegmentCache === null && this.node.$cstNode !== undefined)) {
+         this.nameSegmentCache = this.provider.nameSegmentOf(this.node) ?? null;
+      }
+      return this.nameSegmentCache ?? undefined;
+   }
+
+   get selectionSegment(): DocumentSegment | undefined {
+      if (this.selectionSegmentCache === undefined || (this.selectionSegmentCache === null && this.node.$cstNode !== undefined)) {
+         this.selectionSegmentCache = this.provider.selectionSegmentOf(this.node) ?? null;
+      }
+      return this.selectionSegmentCache ?? undefined;
    }
 }

package/src/langium/scope/built-local-symbols.ts

@@ -0,0 +1,13 @@
+/********************************************************************************
+ * Copyright (c) 2026 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, LocalSymbols } from '@hydranium/langium';
+
+/** The local symbols each build computed, by the root it computed them for. */
+export const builtLocalSymbols = new WeakMap<AstNode, LocalSymbols>();

package/src/langium/scope/fallback-scope.ts

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 Scope, type Stream } from '@hydranium/langium';
+
+/**
+ * A scope that answers from `primary`, and from `fallback` only for a name
+ * `primary` does not hold.
+ *
+ * Langium fixes a scope's outer scope when the scope is built, so a tier cannot
+ * be put below a scope that already exists, such as a cached one. Re-wrapping
+ * that scope's elements instead would turn its keyed lookup into a scan of
+ * every element; chaining keeps each scope's own lookup.
+ */
+export class FallbackScope implements Scope {
+   constructor(
+      protected readonly primary: Scope,
+      protected readonly fallback: Scope
+   ) {}
+
+   getElement(name: string): AstNodeDescription | undefined {
+      return this.primary.getElement(name) ?? this.fallback.getElement(name);
+   }
+
+   getElements(name: string): Stream<AstNodeDescription> {
+      return this.primary.getElements(name).concat(this.fallback.getElements(name));
+   }
+
+   getAllElements(): Stream<AstNodeDescription> {
+      return this.primary.getAllElements().concat(this.fallback.getAllElements());
+   }
+}

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

@@ -10,15 +10,13 @@
 import {
    type AstNode,
    type AstNodeDescription,
-   AstUtils,
    DefaultScopeComputation,
-   interruptAndCheck,
    type LangiumDocument,
    type LocalSymbols,
-   MultiMap,
+   type MultiMap,
    UriUtils
 } from '@hydranium/langium';
-import { Logger, type Tracer } from '@hydranium/protocol';
+import { Logger, type ProfileSession, type Tracer } from '@hydranium/protocol';
 import type { CancellationToken } from 'vscode-languageserver-protocol';
 import type { LogNameOptions } from '../diagnostics/logger.js';
 import type { HydraniumLanguageServices } from '../language-module.js';
@@ -35,8 +33,9 @@ import { type HydraniumAstNodeDescriptionProvider } from './ast-node-description
  *   `NameProvider.getName` defaults to the workspace-unique
  *   `getProjectQualifiedName`. Routing the local-symbols pass through
  *   `getName` would put qualified names in the per-document symbol map
- *   and break within-document bare-name references. {@link addLocalSymbol}
- *   bypasses the default and calls {@link NameProvider.getOwnName}
+ *   and break within-document bare-name references.
+ *   {@link addLocalSymbolByOwnName} bypasses the default and calls
+ *   {@link NameProvider.getOwnName}
  *   directly so local symbols stay keyed by bare names regardless of
  *   what `getName` returns.
  *
@@ -55,11 +54,15 @@ import { type HydraniumAstNodeDescriptionProvider } from './ast-node-description
  *
  * Performance: piggybacks on the existing single AST walk Langium does
  * for local-symbol collection — the AST-extension dispatch and the
- * own-name read both happen in `addLocalSymbol`, no extra traversal.
+ * own-name read both happen in `addLocalSymbolByOwnName`, no extra traversal.
  * The exported-symbol pass reads both name tiers once per node, no
  * duplicated walks.
  */
 export class HydraniumScopeComputation extends DefaultScopeComputation {
+   /** The framework's name provider, which its language module binds to the slot. */
+   declare protected readonly nameProvider: NameProvider;
+   /** The framework's description provider, which its language module binds to the slot. */
+   declare protected readonly descriptions: HydraniumAstNodeDescriptionProvider;
    protected readonly tracer: Tracer;
 
    constructor(
@@ -70,38 +73,30 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
       this.tracer = services.shared.Tracer.for(options.logName ?? 'ScopeComputation').trace('instantiated');
    }
 
+   /** The session {@link addLocalSymbol} records into while a `debug`-level walk runs. */
+   protected localSymbolsProfile: ProfileSession | undefined;
+
    /**
-    * Local-symbol collection with optional per-`$type` self-time profiling.
-    *
-    * Langium's default walks the full AST and calls {@link addLocalSymbol} per
-    * node. At the default `info` level this delegates straight to `super` (zero
-    * cost). At `debug` it reproduces the same walk under a `ProfileSession`
-    * so each `$type`'s contribution to the heaviest scope-computation pass is
-    * aggregated and reported line-based — the walk is gated rather than the
-    * per-node `scope`, since `ProfileSession.scope` is not itself level-gated.
-    *
-    * The instance carries no profiling state: the session is local to the call,
-    * which is safe because Langium's document builder runs `collectLocalSymbols`
-    * strictly one document at a time (`runCancelable`'s sequential `for…await`).
+    * Langium's local-symbol walk, with per-`$type` self-time profiling at
+    * `debug`. The walk is Langium's at every level: a copy run only at `debug`
+    * would drift from the one every other level runs. Overlapping builds share
+    * the session and blur each other's report.
     */
    override async collectLocalSymbols(document: LangiumDocument, cancelToken?: CancellationToken): Promise<LocalSymbols> {
       if (!Logger.isLevelEnabled('debug')) {
          return super.collectLocalSymbols(document, cancelToken);
       }
-      // Faithfully reproduces Langium's local-symbol walk (root's full-AST stream
-      // → addLocalSymbol per node) under a session. The MultiMap conforms to
-      // LocalSymbols. interruptAndCheck only when a token is supplied (the base
-      // defaults to CancellationToken.None, a no-op token).
-      const rootNode = document.parseResult.value;
-      const symbols = new MultiMap<AstNode, AstNodeDescription>();
-      const session = this.tracer.profile(`scope-local ${UriUtils.basename(document.uri)}`);
-      for (const node of AstUtils.streamAllContents(rootNode)) {
-         if (cancelToken) {
-            await interruptAndCheck(cancelToken);
+      const profile = this.tracer.profile(`scope-local ${UriUtils.basename(document.uri)}`);
+      this.localSymbolsProfile = profile;
+      let symbols: LocalSymbols;
+      try {
+         symbols = await super.collectLocalSymbols(document, cancelToken);
+      } finally {
+         if (this.localSymbolsProfile === profile) {
+            this.localSymbolsProfile = undefined;
          }
-         session.scope(node.$type, () => this.addLocalSymbol(node, document, symbols));
       }
-      session.report('debug');
+      profile.report('debug');
       return symbols;
    }
 
@@ -164,17 +159,15 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
     * workspace-visible rather than being filtered out everywhere.
     */
    protected exportProject(node: AstNode, exports: AstNodeDescription[], document: LangiumDocument): void {
-      const nameProvider = this.nameProvider as NameProvider;
-      const documentName = nameProvider.getDocumentQualifiedName(node);
+      const documentName = this.nameProvider.getDocumentQualifiedName(node);
       if (!documentName) {
          return;
       }
       const projectId = this.getProjectIdForDocument(document);
-      const descriptions = this.descriptions as HydraniumAstNodeDescriptionProvider;
       exports.push(
          projectId !== undefined
-            ? descriptions.createProject({ node, name: documentName, document, projectId })
-            : descriptions.createUniversal({ node, name: documentName, document })
+            ? this.descriptions.createProject({ node, name: documentName, document, projectId })
+            : this.descriptions.createUniversal({ node, name: documentName, document })
       );
    }
 
@@ -191,16 +184,14 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
     * document-qualified name.
     */
    protected exportPublic(node: AstNode, exports: AstNodeDescription[], document: LangiumDocument): void {
-      const nameProvider = this.nameProvider as NameProvider;
       const projectId = this.getProjectIdForDocument(document);
       if (projectId === undefined) {
          return;
       }
-      const documentName = nameProvider.getDocumentQualifiedName(node);
-      const projectName = nameProvider.getProjectQualifiedName(node);
+      const documentName = this.nameProvider.getDocumentQualifiedName(node);
+      const projectName = this.nameProvider.getProjectQualifiedName(node);
       if (projectName && projectName !== documentName) {
-         const descriptions = this.descriptions as HydraniumAstNodeDescriptionProvider;
-         exports.push(descriptions.createPublic({ node, name: projectName, document, projectId }));
+         exports.push(this.descriptions.createPublic({ node, name: projectName, document, projectId }));
       }
    }
 
@@ -218,6 +209,16 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
       return this.services.shared.workspace.ProjectManager.getProject(document.uri)?.id;
    }
 
+   /** {@link addLocalSymbolByOwnName}, timed per `$type` while {@link localSymbolsProfile} is set. */
+   protected override addLocalSymbol(node: AstNode, document: LangiumDocument, symbols: MultiMap<AstNode, AstNodeDescription>): void {
+      const profile = this.localSymbolsProfile;
+      if (profile) {
+         profile.scope(node.$type, () => this.addLocalSymbolByOwnName(node, document, symbols));
+      } else {
+         this.addLocalSymbolByOwnName(node, document, symbols);
+      }
+   }
+
    /**
     * Bypasses Langium's `super.addLocalSymbol` (which would key the
     * local-symbols map by `nameProvider.getName(node)`, qualified by
@@ -233,14 +234,14 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
     * extension `compute` callbacks fire after this `addLocalSymbol` pass
     * completes for the whole document.
     */
-   protected override addLocalSymbol(node: AstNode, document: LangiumDocument, symbols: MultiMap<AstNode, AstNodeDescription>): void {
+   protected addLocalSymbolByOwnName(node: AstNode, document: LangiumDocument, symbols: MultiMap<AstNode, AstNodeDescription>): void {
       const container = node.$container;
       if (!container) {
          return;
       }
-      const name = (this.nameProvider as NameProvider).getOwnName(node);
+      const name = this.nameProvider.getOwnName(node);
       if (name) {
-         symbols.add(container, (this.descriptions as HydraniumAstNodeDescriptionProvider).createLocal({ node, name, document }));
+         symbols.add(container, this.descriptions.createLocal({ node, name, document }));
       }
    }
 }