@hydranium/core 1.0.0-next.37 → 1.0.0-next.371

package/src/langium/residency/cst-residency-service.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { asMutable, type Clock, Debouncer, Format, type Tracer } from '@hydranium/protocol';
+import { asMutable, type Clock, Debouncer, Format, type Tracer, UNRECORDED_VERSION } from '@hydranium/protocol';
 import {
    type AstNode,
    AstUtils,
@@ -45,8 +45,11 @@ export const CST_RESIDENCY_PASS_PRIORITY = 1_000_000;
  *   "off" toggle.
  * - `{ kind: 'shed-closed-when-idle', idleMs }`: shed a closed document's CST
  *   once it has been idle (not in any build) for `idleMs`, keeping the AST
- *   resident. Open documents are always kept. `idleMs: 0` sheds as soon as a
- *   document is closed (a pure close-triggered threshold of this strategy).
+ *   resident. Open documents are always kept. The timer starts when a build
+ *   includes the document, so `idleMs: 0` sheds a closed document on the tick
+ *   after each such build. A shed document that re-enters a build is re-parsed
+ *   in full, so a window shorter than the gap between a document's builds
+ *   re-parses a closed document on every build it rides in.
  */
 export type CstResidencyStrategy = { readonly kind: 'always-keep' } | { readonly kind: 'shed-closed-when-idle'; readonly idleMs: number };
 
@@ -185,12 +188,16 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
 }
 
 /**
- * Residency policy that reclaims memory by shedding the concrete syntax tree
- * (CST) of closed documents while keeping their AST resident. Each build refreshes
+ * Keeps a document's CST available to the readers that need one, shedding it
+ * for documents that have gone idle and re-grafting on demand.
+ *
+ * Each build refreshes
  * the idle window of the documents in its batch; when a closed, sheddable
  * document's window elapses, every AST node's `$cstNode` and every reference's
- * `$refNode` are nulled, and the CST root, `Range`s and `Position`s become
- * unreachable and are collected.
+ * `$refNode` are nulled, and the CST becomes unreachable with the `Range`s
+ * and `Position`s only it holds. The reference index's segments, and a
+ * description's segments once read, share the CST's `Range` objects, so
+ * those stay.
  *
  * **Terminology.** *Residency* is the state axis (is the CST in memory? —
  * `resident` vs `shed`); *shed* is both the act and the policy vocabulary (drop
@@ -231,10 +238,6 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
  * `NameProvider.getNameNode` chokepoint, the comment provider, and
  * `HydraniumLangiumDocuments.getOrCreateDocument`.
  */
-/**
- * Keeps a document's CST available to the readers that need one, shedding it
- * for documents that have gone idle and re-grafting on demand.
- */
 export interface CstResidencyService {
    /**
     * Ensure `document` has a CST, re-parsing its retained text if it was shed.
@@ -246,7 +249,8 @@ export interface CstResidencyService {
    /**
     * Node-level convenience over {@link rehydrate}, cheap enough for an
     * unconditional call: a node whose `$cstNode` is already set returns
-    * without resolving its document.
+    * without resolving its document, and a node outside any document, such as
+    * a detached synthetic node, has nothing to restore and returns too.
     */
    rehydrateNode(node: AstNode): void;
 }
@@ -281,7 +285,7 @@ export class DefaultCstResidencyService implements CstResidencyService {
       this.langiumDocs = services.workspace.LangiumDocuments;
       services.workspace.BuildPhasePassService.register({
          id: 'framework:cst-residency:shed',
-         state: DocumentState.Validated,
+         phase: DocumentState.Validated,
          priority: options.priority ?? CST_RESIDENCY_PASS_PRIORITY,
          run: documents => this.onBuild(documents)
       });
@@ -315,7 +319,10 @@ export class DefaultCstResidencyService implements CstResidencyService {
       if (node.$cstNode !== undefined) {
          return;
       }
-      this.rehydrate(AstUtils.getDocument(node));
+      const document = AstUtils.findRootNode(node).$document;
+      if (document) {
+         this.rehydrate(document);
+      }
    }
 
    /**
@@ -407,6 +414,15 @@ export class DefaultCstResidencyService implements CstResidencyService {
       if (root === undefined || root.$cstNode === undefined) {
          return 0;
       }
+      // Readers of the parsed text, the `'text-diagnostics'` fingerprint among
+      // them, otherwise see none once the CST is gone. Recorded in the ledger
+      // directly: no root is produced, and reconciling it with the store would
+      // step a closed document's sequence for a root behind its text.
+      const ledger = this.services.workspace.ModelLedger;
+      const version = ledger.versionOf(root);
+      if (version !== UNRECORDED_VERSION) {
+         ledger.record(root, version, ledger.textOf(root));
+      }
       let cleared = 0;
       for (const node of AstUtils.streamAst(root)) {
          if (node.$cstNode) {

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 }));
       }
    }
 }