@hydranium/core 1.0.0-next.335 → 1.0.0-next.339

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

@@ -24,7 +24,9 @@ import {
    type AstNodeLocator,
    AstUtils,
    DefaultScopeProvider,
+   type LocalSymbols,
    MapScope,
+   MultiMapScope,
    type ReferenceInfo,
    type Scope,
    type ScopeOptions,
@@ -104,16 +106,16 @@ export interface ScopeContext {
  * ## Scope chain (high → low, inner shadows outer)
  *
  * ```
- *   document-local (Langium precomputed)        [DefaultScopeProvider.getScope]
+ *   document-local (Langium precomputed)        [getScope, CACHED per build in localScope]
  *     extension:local                           [layerLocalExtension, per-context]
  *       own-project → dependency → universal-index   [createGlobalScope default, CACHED per ${project}::${refType}]
  *         extension:universal                   [layerUniversalExtension, per-context, 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
  *
@@ -162,6 +164,12 @@ 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>>>();
    protected readonly tracer: Tracer;
    /**
     * Narrows the inherited Langium {@link NameProvider} field to the framework's
@@ -204,14 +212,72 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
       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 = AstUtils.getDocument(context.container).localSymbols;
+      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 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 grouped by 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);
@@ -318,7 +384,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 {
@@ -376,11 +442,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);
    }
 
    /**
@@ -389,7 +455,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);
    }
 
    /**
@@ -401,13 +467,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));
    }
 
    /**

package/src/langium/trivia/comment-preserver.ts

@@ -143,6 +143,36 @@ export interface IndentationTokenNames {
    readonly dedent: string;
 }
 
+/**
+ * A container a run of comment lines can be placed in: the run's own, or one
+ * it is lifted into when a block's DEDENT follows the run. `last` is the index
+ * in its content the run is placed after, `closed` the block the run is lifted
+ * out of, and `liftBelow` the column a comment line has to start left of to be
+ * lifted this far.
+ */
+export interface CommentLiftTarget {
+   readonly container: CompositeCstNode;
+   readonly last: number;
+   readonly closed?: CompositeCstNode;
+   readonly liftBelow?: number;
+}
+
+/**
+ * A run of hidden nodes in `content`, from `start` to `end`, with the syntax
+ * before it and the containers its comments can be placed in, innermost first.
+ */
+export interface CommentRun {
+   readonly content: readonly CstNode[];
+   readonly start: number;
+   readonly end: number;
+   readonly previous?: { readonly end: number };
+   readonly targets: readonly CommentLiftTarget[];
+   /** The nodes {@link CommentPreserver.neighbours} finds before the run, in order. */
+   readonly before: readonly CstNode[];
+   /** Per target, the nodes {@link CommentPreserver.neighbours} finds after its `last`. */
+   readonly after: readonly (readonly CstNode[])[];
+}
+
 /**
  * One splice, with what it takes to check the risky kind afterwards.
  *
@@ -192,6 +222,18 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
    protected readonly maxIsolatedEdits: number;
    protected commentTokenNames?: readonly string[];
    protected indentationTokenNames?: IndentationTokenNames | null;
+   /**
+    * Set for the duration of one {@link extract}: the run
+    * {@link resolveCommentRun} resolved last, so the run's next comment reuses
+    * it.
+    */
+   protected commentRun?: CommentRun;
+   /**
+    * Set for the duration of one {@link extract}: {@link syntaxSpan} per node,
+    * as a block a run is lifted out of would otherwise be measured once per
+    * comment.
+    */
+   protected spanMemo?: Map<CstNode, { readonly offset: number; readonly end: number } | undefined>;
    /** Set for the duration of one {@link apply}; see {@link cachedAnchorKey}. */
    protected keyMemo?: Map<AstNode, string | undefined>;
    /** Set for the duration of one {@link apply}; see {@link ambiguousRetainedKey}. */
@@ -259,9 +301,14 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
       if (this.getIndentationTokenNames() === undefined) {
          return node;
       }
+      if (this.spanMemo?.has(node)) {
+         return this.spanMemo.get(node);
+      }
       const first = this.edgeToken(node, 1);
       const last = this.edgeToken(node, -1);
-      return first && last && { offset: first.offset, end: last.end };
+      const span = first && last && { offset: first.offset, end: last.end };
+      this.spanMemo?.set(node, span);
+      return span;
    }
 
    /** The first token of `node` for a `step` of 1, the last for -1, that is neither hidden nor indentation. */
@@ -355,7 +402,14 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
       }
       const source = document.textDocument.getText();
       const comments: DocumentComment[] = [];
-      this.captureFrom(root, source, commentTokens, comments);
+      this.commentRun = undefined;
+      this.spanMemo = new Map();
+      try {
+         this.captureFrom(root, source, commentTokens, comments);
+      } finally {
+         this.commentRun = undefined;
+         this.spanMemo = undefined;
+      }
       return { comments, sourceRoot: document.parseResult.value };
    }
 
@@ -409,7 +463,14 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
       const following = content[at + 1];
       const blankLinesAfter = following === undefined ? 0 : this.countBlankLines(source.slice(comment.end, offsetOf(following)));
       const preceding = at > 0 ? content[at - 1] : undefined;
-      const blankLinesBefore = preceding === undefined ? 0 : this.countBlankLines(source.slice(endOf(preceding), comment.offset));
+      // From the last text before the comment: a block it is lifted out of can
+      // end with comment lines of its own, after the block's syntax.
+      const precedingEnd = preceding === undefined ? comment.offset : endOf(preceding);
+      let gapStart = comment.offset;
+      while (gapStart > precedingEnd && /\s/.test(source[gapStart - 1])) {
+         gapStart--;
+      }
+      const blankLinesBefore = preceding === undefined ? 0 : this.countBlankLines(source.slice(gapStart, comment.offset));
 
       // Only a comment that OWNS its line can be reindented — one sharing a line
       // with code keeps whatever spacing that line gives it.
@@ -418,7 +479,7 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
       const sourceIndent = beforeOnLine.trim().length === 0 ? beforeOnLine : undefined;
 
       const text = this.normalizeLineEndings(comment.text);
-      const sharesLineWithPrevious = previous !== undefined && !source.slice(endOf(previous), comment.offset).includes('\n');
+      const sharesLineWithPrevious = previous !== undefined && !this.breaksLine(source, endOf(previous), comment.offset);
 
       if (sharesLineWithPrevious) {
          // On the same line as whatever precedes it, so it annotates that line.
@@ -451,8 +512,10 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
    }
 
    /**
-    * Resolves the container {@link classify} anchors `comment` in and its
-    * siblings there without INDENT and DEDENT tokens.
+    * Resolves the container {@link classify} anchors `comment` in, and the
+    * comment's adjacent siblings there and the nearest syntax on each side,
+    * without INDENT and DEDENT tokens. The content is that window, not all of
+    * the container's siblings.
     *
     * An indentation-aware lexer can emit a block's DEDENT after the comment
     * lines that follow the block, so the parser nests them in it. An own-line
@@ -466,10 +529,35 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
       container: CompositeCstNode,
       source: string
    ): { readonly container: CompositeCstNode; readonly content: readonly CstNode[]; readonly index: number } {
-      if (this.getIndentationTokenNames() === undefined) {
-         return { container, content: container.content, index };
+      const content = container.content;
+      const run = this.resolveCommentRun(index, container, source);
+      let placed = 0;
+      if (run.targets.length > 1 && (run.previous === undefined || this.breaksLine(source, run.previous.end, comment.offset))) {
+         const column = this.columnAt(source, comment.offset);
+         while (placed + 1 < run.targets.length && column < (run.targets[placed + 1].liftBelow ?? 0)) {
+            placed++;
+         }
       }
+      const { container: parent, closed } = run.targets[placed];
+      const before = closed ? [closed] : run.before;
+      const around = content.slice(Math.max(index - 1, run.start), Math.min(index + 1, run.end) + 1);
+      const view = [...before, ...around, ...run.after[placed]];
+      return { container: parent, content: view, index: before.length + (index > run.start ? 1 : 0) };
+   }
+
+   /**
+    * The run of hidden nodes around `container.content[index]`, and the blocks
+    * it can be lifted out of: each that ends right after the run and whose
+    * INDENT opened a column, up to the first that does not.
+    */
+   protected resolveCommentRun(index: number, container: CompositeCstNode, source: string): CommentRun {
       const content = container.content;
+      const cached = this.commentRun;
+      // Resolved once per run, not per comment: a run of k comment lines would
+      // otherwise cost k scans of the run.
+      if (cached?.content === content && index >= cached.start && index <= cached.end) {
+         return cached;
+      }
       let start = index;
       while (start > 0 && content[start - 1].hidden) {
          start--;
@@ -478,37 +566,62 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
       while (end + 1 < content.length && content[end + 1].hidden) {
          end++;
       }
-      const run = content.slice(start, end + 1);
       let previous: { readonly end: number } | undefined;
-      for (let scan = start - 1; scan >= 0 && previous === undefined; scan--) {
-         previous = content[scan].hidden ? undefined : this.syntaxSpan(content[scan]);
+      const targets: CommentLiftTarget[] = [{ container, last: end }];
+      if (this.getIndentationTokenNames() !== undefined) {
+         for (let scan = start - 1; scan >= 0 && previous === undefined; scan--) {
+            previous = content[scan].hidden ? undefined : this.syntaxSpan(content[scan]);
+         }
+         let target = targets[0];
+         while (target.container.container && this.closesAfter(target.container.content, target.last)) {
+            const opened = this.openedColumn(target.container.content, target.closed ? target.last : start, source) ?? 0;
+            if (opened === 0) {
+               break;
+            }
+            const parent = target.container.container;
+            target = {
+               container: parent,
+               last: this.indexIn(parent.content, target.container),
+               closed: target.container,
+               liftBelow: opened
+            };
+            targets.push(target);
+         }
       }
-      let parent = container;
-      let closed: CstNode | undefined;
-      if (previous === undefined || source.slice(previous.end, comment.offset).includes('\n')) {
-         const column = this.columnAt(source, comment.offset);
-         while (
-            parent.container &&
-            this.closesAfter(parent.content, closed ?? run[run.length - 1]) &&
-            column < (this.openedColumn(parent.content, closed ?? run[0], source) ?? 0)
-         ) {
-            closed = parent;
-            parent = parent.container;
+      const before = this.neighbours(content, start - 1, -1).reverse();
+      const after = targets.map(target => this.neighbours(target.container.content, target.last + 1, 1));
+      return (this.commentRun = { content, start, end, previous, targets, before, after });
+   }
+
+   /** The nodes of `content` from `from` in `step` direction up to the first that is syntax, without indentation tokens. */
+   protected neighbours(content: readonly CstNode[], from: number, step: 1 | -1): CstNode[] {
+      const found: CstNode[] = [];
+      for (let scan = from; scan >= 0 && scan < content.length; scan += step) {
+         const node = content[scan];
+         if (!this.isIndentation(node)) {
+            found.push(node);
+            if (!node.hidden) {
+               break;
+            }
          }
       }
-      const view = parent.content.flatMap(node => (node === closed ? [node, ...run] : this.isIndentation(node) ? [] : [node]));
-      return { container: parent, content: view, index: view.indexOf(comment) };
+      return found;
    }
 
-   /** Whether only hidden and indentation tokens follow `node` in `content`. */
-   protected closesAfter(content: readonly CstNode[], node: CstNode): boolean {
-      return content.slice(content.indexOf(node) + 1).every(sibling => sibling.hidden || this.isIndentation(sibling));
+   /** Whether only hidden and indentation tokens follow `index` in `content`. */
+   protected closesAfter(content: readonly CstNode[], index: number): boolean {
+      for (let scan = index + 1; scan < content.length; scan++) {
+         if (!content[scan].hidden && !this.isIndentation(content[scan])) {
+            return false;
+         }
+      }
+      return true;
    }
 
-   /** The column the last INDENT before `node` in `content` opens, `undefined` without one. */
-   protected openedColumn(content: readonly CstNode[], node: CstNode, source: string): number | undefined {
+   /** The column the last INDENT before `content[index]` opens, `undefined` without one. */
+   protected openedColumn(content: readonly CstNode[], index: number, source: string): number | undefined {
       const indent = this.getIndentationTokenNames()?.indent;
-      for (let scan = content.indexOf(node) - 1; scan >= 0; scan--) {
+      for (let scan = index - 1; scan >= 0; scan--) {
          if (tokenNameOf(content[scan]) === indent) {
             return this.columnAt(source, content[scan].end);
          }
@@ -516,6 +629,41 @@ export class CommentPreserver implements TriviaPreserver<CommentTrivia> {
       return undefined;
    }
 
+   /**
+    * The index of `node` in `content`, found by offset: `indexOf` per lifted
+    * block makes extraction quadratic in a block's siblings.
+    */
+   protected indexIn(content: readonly CstNode[], node: CstNode): number {
+      let low = 0;
+      let high = content.length;
+      while (low < high) {
+         const middle = (low + high) >> 1;
+         if (content[middle].offset < node.offset) {
+            low = middle + 1;
+         } else {
+            high = middle;
+         }
+      }
+      // Zero-width tokens can share the node's offset.
+      for (let index = low; index < content.length && content[index].offset === node.offset; index++) {
+         if (content[index] === node) {
+            return index;
+         }
+      }
+      return content.indexOf(node);
+   }
+
+   /** Whether `text` has a line break from `from` up to `to`, without copying the span. */
+   protected breaksLine(text: string, from: number, to: number): boolean {
+      // Not indexOf, which scans on to the next line break past `to`.
+      for (let offset = from; offset < to; offset++) {
+         if (text.charCodeAt(offset) === 10) {
+            return true;
+         }
+      }
+      return false;
+   }
+
    /** The column of `offset` in `text`. */
    protected columnAt(text: string, offset: number): number {
       return offset - (text.lastIndexOf('\n', offset - 1) + 1);

package/src/langium/validation/document-validator.ts

@@ -38,7 +38,7 @@ import {
 } from '@hydranium/langium';
 import type { CancellationToken } from 'vscode-languageserver-protocol';
 // A VALUE import, for `Diagnostic.getMessageString`: `message` is
-// `string | MarkupContent` in LSP 3.17+, so upstream's own reader is what
+// `string | MarkupContent` since LSP 3.18, so upstream's own reader is what
 // narrows it rather than a hand-rolled union check here.
 import { Diagnostic } from 'vscode-languageserver-types';
 import { type LogNameOptions } from '../diagnostics/logger.js';

package/src/messages/carriers.ts

@@ -63,7 +63,7 @@ export function acceptMessage<S extends string, N extends AstNode, P extends Pro
  * Recover the identity from a published diagnostic, for a surface that
  * identifies or renders diagnostics itself.
  *
- * `Diagnostic.message` is `string | MarkupContent` in LSP 3.17+, so the text
+ * `Diagnostic.message` is `string | MarkupContent` since LSP 3.18, so the text
  * comes from upstream's own `Diagnostic.getMessageString` rather than a
  * hand-rolled narrowing — consuming the library in its style, and one fewer
  * place restating the union.