@hydranium/core 1.0.0-next.259 → 1.0.0-next.260

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

@@ -7,9 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type AstNode, AstUtils, type LangiumDocument, MapScope, type Scope, StreamScope, stream } from '@hydranium/langium';
+import { type AstNode, AstUtils, type LangiumDocument } from '@hydranium/langium';
 import { type Disposable } from 'vscode-languageserver';
-import { type Tracer } from '@hydranium/protocol';
+import { Format, Logger, type ProfileRecord, type ProfileSession, 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';
@@ -49,8 +49,7 @@ export interface ScopeDescriptionAcceptor {
     * 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.
+    * because {@link ScopeExtensionDescriptions} holds only those two.
     */
    push(description: TieredAstNodeDescription): void;
 }
@@ -87,38 +86,32 @@ export interface ScopeExtension extends RegistryItem {
    addDescriptions(context: AstNode, referenceType: string, document: LangiumDocument, accept: ScopeDescriptionAcceptor): void;
 }
 
+/** The scope-extension descriptions for one reference, split by tier. */
+export interface ScopeExtensionDescriptions {
+   readonly local: readonly TieredAstNodeDescription[];
+   readonly universal: readonly TieredAstNodeDescription[];
+}
+
 /**
  * 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.
+ * contributions use) with the query `HydraniumScopeProvider` builds its
+ * extension tiers from.
  */
 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).
+    * Run every extension registered for `referenceType` once against
+    * `context`, and answer its descriptions by tier. A caller that needs
+    * both tiers takes them from one call: a call per tier runs every
+    * extension twice.
     */
-   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;
+   getDescriptions(referenceType: string, context: AstNode): ScopeExtensionDescriptions;
 }
 
 export type ScopeExtensionServiceOptions = LogNameOptions;
 
+const NO_DESCRIPTIONS: ScopeExtensionDescriptions = { local: [], universal: [] };
+
 /**
  * Default {@link ScopeExtensionService} implementation. Per-language
  * registry for dynamic scope contributions: extra resolvable descriptions
@@ -128,13 +121,19 @@ export type ScopeExtensionServiceOptions = LogNameOptions;
  * 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
+ * which consumes {@link getDescriptions}. Designed as a base class; adopters
  * extend it and call `register` in their constructor.
+ *
+ * At `debug`, each extension's calls and self-time go into one profile
+ * session, reported when a build starts and when it ends. A report thus
+ * covers one build, validation included, or the calls made between two
+ * builds, such as a reference picker's.
  */
 export class DefaultScopeExtensionService implements ScopeExtensionService {
    protected readonly scopeExtensions = new Registry<ScopeExtension>();
    protected readonly tracer: Tracer;
+   /** Open from the first profiled call until {@link reportProfile}. */
+   protected profileSession?: ProfileSession;
 
    constructor(
       protected readonly services: ServerLanguageServices,
@@ -150,6 +149,10 @@ export class DefaultScopeExtensionService implements ScopeExtensionService {
       for (const contribution of Object.values(contributions)) {
          contribution.registerScopeExtensions(this);
       }
+      // Optional for the same reason: a stub tree may carry no builder.
+      const builder = services.shared.workspace.DocumentBuilder;
+      builder?.onUpdate(() => this.reportProfile());
+      builder?.onBuildEnded(() => this.reportProfile());
    }
 
    /**
@@ -162,46 +165,58 @@ export class DefaultScopeExtensionService implements ScopeExtensionService {
       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.)
+    * Holds the profile wrap, which an override would have to copy; to change
+    * which extensions run, override {@link extensionsFor}.
     */
-   protected collectExtensionDescriptions(
-      referenceType: string,
-      context: AstNode,
-      tier: 'local' | 'universal'
-   ): TieredAstNodeDescription[] {
-      const extensionsForType = this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+   getDescriptions(referenceType: string, context: AstNode): ScopeExtensionDescriptions {
+      const extensionsForType = this.extensionsFor(referenceType, context);
       if (extensionsForType.length === 0) {
-         return [];
+         return NO_DESCRIPTIONS;
       }
       const document = AstUtils.getDocument(context);
       const collected: TieredAstNodeDescription[] = [];
       const accept = createScopeDescriptionAcceptor(collected, this.services.workspace.AstNodeDescriptionProvider);
+      const session = Logger.isLevelEnabled('debug') ? (this.profileSession ??= this.tracer.profile('scope-extension')) : undefined;
       for (const extension of extensionsForType) {
-         extension.addDescriptions(context, referenceType, document, accept);
+         if (session) {
+            session.scope(extension.id, () => extension.addDescriptions(context, referenceType, document, accept));
+         } else {
+            extension.addDescriptions(context, referenceType, document, accept);
+         }
+      }
+      return {
+         local: collected.filter(description => description.tier === 'local'),
+         universal: collected.filter(description => description.tier === 'universal')
+      };
+   }
+
+   /** The extensions that run for one reference: by default, those registered for `referenceType`. */
+   protected extensionsFor(referenceType: string, _context: AstNode): ScopeExtension[] {
+      return this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+   }
+
+   /**
+    * Report the profile session, if one is open, and start the next one fresh:
+    * one line per extension, its calls and self-time. Not a share of the
+    * session's time, which runs from the first call to the report and so takes
+    * in whatever happened between the calls.
+    */
+   protected reportProfile(): void {
+      const session = this.profileSession;
+      this.profileSession = undefined;
+      for (const record of session?.records() ?? []) {
+         this.tracer.debug(this.formatProfileRecord(record));
       }
-      return collected.filter(description => description.tier === tier);
+   }
+
+   /**
+    * The log line of one extension's {@link reportProfile} entry. It names the
+    * language: each has its own session, and an extension id is unique only
+    * within its language.
+    */
+   protected formatProfileRecord(record: ProfileRecord): string {
+      const language = this.services.LanguageMetaData.languageId;
+      return `[profile scope-extension ${language}] ${record.id} ×${record.count} ${Format.elapsed(record.selfMs)}`;
    }
 }

package/src/langium/shared-services.ts

@@ -23,6 +23,7 @@ import type { ProjectManager } from './project/project-manager.js';
 import type { ExtendedServiceRegistry } from './service-registry.js';
 import type { DocumentUriPolicy } from './workspace/document-uri-policy.js';
 import type { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
+import type { HydraniumDocumentBuilder } from './document-builder/document-builder.js';
 import type { AdditionalDocumentContribution } from './workspace/additional-document-contribution.js';
 
 /**
@@ -94,6 +95,10 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
       // only through this narrowing — a scope provider querying a URI before
       // the file exists is the caller that needs it.
       /* override */ LangiumDocuments: HydraniumDocumentRegistry;
+      // Same, for the builder: only the framework's has `onBuildEnded`, which a
+      // per-build report needs because Langium's phases stay silent for a
+      // build that validates nothing.
+      /* override */ DocumentBuilder: HydraniumDocumentBuilder;
       ProjectManager: ProjectManager<TProject>;
       SelfSaveRegistry: SelfSaveRegistry;
       BuildPipelineIntegration: BuildPipelineIntegration;

package/src/node/rename-over-open-readers.ts

@@ -7,6 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { type Clock, SystemClock } from '@hydranium/protocol';
 import * as fsp from 'node:fs/promises';
 
 /**
@@ -37,6 +38,7 @@ export const RENAME_BUDGET_MS = 10_000;
 export interface RenameOverOpenReadersOptions {
    readonly rename?: (from: string, to: string) => Promise<void>;
    readonly budgetMs?: number;
+   readonly clock?: Clock;
 }
 
 /**
@@ -60,18 +62,21 @@ export async function renameOverOpenReaders(
    options: RenameOverOpenReadersOptions = {}
 ): Promise<void> {
    const rename = options.rename ?? fsp.rename;
-   const deadline = Date.now() + (options.budgetMs ?? RENAME_BUDGET_MS);
+   const clock = options.clock ?? new SystemClock();
+   const deadline = clock.now() + (options.budgetMs ?? RENAME_BUDGET_MS);
    for (let attempt = 0; ; attempt++) {
       try {
          await rename(staging, destination);
          return;
       } catch (err: unknown) {
          const code = err instanceof Error && 'code' in err ? String((err as NodeJS.ErrnoException).code) : undefined;
-         if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || Date.now() >= deadline) {
+         if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || clock.now() >= deadline) {
             throw err;
          }
          // Backs off to keep a long contention window from spinning, capped so
          // a late attempt still lands promptly once the handle is released.
+         // Not `clock.setTimer`: it unrefs its timer, so a process with only
+         // this write pending could exit mid-backoff.
          await new Promise(resolve => setTimeout(resolve, Math.min(2 ** attempt, 50)));
       }
    }

package/src/testing/playwright/server-log-capture.ts

@@ -83,6 +83,10 @@ export interface CaptureServerLogOptions {
     *
     * The server's own threshold is left alone: it governs what the client sees,
     * not the file, and the setting replaces it within moments of startup.
+    *
+    * The server runs every path guarded on a level this admits, its debug
+    * profiling included, so a timing run captured at a level that admits debug
+    * measures that work too.
     */
    level?: LogThreshold;
 }

package/src/testing/stub-document-builder.ts

@@ -19,7 +19,7 @@ import {
    type WorkspaceLock
 } from '@hydranium/langium';
 import { type CancellationToken, Disposable } from 'vscode-languageserver';
-import { HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
+import { type BuildEndedEvent, HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
 
 /** Recorded call to a stubbed {@link DocumentBuilder} method. */
 export interface RecordedBuilderCall<TArgs extends unknown[]> {
@@ -77,7 +77,7 @@ export interface StubWaitUntilGate {
 export interface StubDocumentBuilder
    extends
       Pick<DocumentBuilder, 'update' | 'onDocumentPhase' | 'onUpdate' | 'build' | 'onBuildPhase' | 'resetToState' | 'updateBuildOptions'>,
-      Pick<HydraniumDocumentBuilder, 'onDocumentPhaseDelivered' | 'scheduleUpdate' | 'finalBuildState'> {
+      Pick<HydraniumDocumentBuilder, 'onDocumentPhaseDelivered' | 'scheduleUpdate' | 'finalBuildState' | 'onBuildEnded'> {
    /**
     * Single-overload stub of {@link DocumentBuilder.waitUntil}. Real has
     * two overloads (`(state, cancelToken?): Promise<void>` and
@@ -107,6 +107,13 @@ export interface StubDocumentBuilder
     * looking wired.
     */
    fireBuildPhase(state: DocumentState, built: LangiumDocument[], cancelToken?: CancellationToken): void;
+   /**
+    * Synchronously fire every {@link HydraniumDocumentBuilder.onBuildEnded}
+    * listener with `event`. As in the real builder, one that throws does not
+    * stop the others; the real builder logs the error, and this stub, having
+    * no logger, rethrows the first one once all have run.
+    */
+   fireBuildEnded(event: BuildEndedEvent): void;
    /**
     * Hold the next {@link waitUntil} call. The returned handle releases it;
     * the call's return value resolves on the next tick after `resolve` runs.
@@ -152,6 +159,7 @@ export function makeStubDocumentBuilder(workspaceLock?: WorkspaceLock): StubDocu
    const deliveredListeners = new Map<DocumentState, Array<(document: LangiumDocument, version: number) => void>>();
    const buildPhaseListeners = new Map<DocumentState, DocumentBuildListener[]>();
    const onUpdateListeners: DocumentUpdateListener[] = [];
+   const buildEndedListeners: Array<(event: BuildEndedEvent) => void> = [];
    const gates: Array<{ take(release: () => void): void }> = [];
    const updateCalls: RecordedBuilderCall<[URI[], URI[]]>[] = [];
    const waitUntilCalls: RecordedBuilderCall<[DocumentState, URI | undefined]>[] = [];
@@ -258,6 +266,28 @@ export function makeStubDocumentBuilder(workspaceLock?: WorkspaceLock): StubDocu
             reraise(listener(changed, deleted));
          }
       },
+      onBuildEnded(listener: (event: BuildEndedEvent) => void) {
+         buildEndedListeners.push(listener);
+         return Disposable.create(() => {
+            const idx = buildEndedListeners.indexOf(listener);
+            if (idx >= 0) {
+               buildEndedListeners.splice(idx, 1);
+            }
+         });
+      },
+      fireBuildEnded(event: BuildEndedEvent) {
+         const failures: unknown[] = [];
+         for (const listener of buildEndedListeners.slice()) {
+            try {
+               listener(event);
+            } catch (error: unknown) {
+               failures.push(error);
+            }
+         }
+         if (failures.length > 0) {
+            throw failures[0];
+         }
+      },
       onBuildPhase(state: DocumentState, listener: DocumentBuildListener) {
          const list = buildPhaseListeners.get(state) ?? [];
          list.push(listener);
@@ -317,6 +347,7 @@ export function makeStubDocumentBuilder(workspaceLock?: WorkspaceLock): StubDocu
          phaseListeners.clear();
          deliveredListeners.clear();
          onUpdateListeners.length = 0;
+         buildEndedListeners.length = 0;
          gates.length = 0;
          updateCalls.length = 0;
          waitUntilCalls.length = 0;