@hydranium/core 1.0.0-next.18 → 1.0.0-next.181

package/src/langium/document-builder/build-pipeline-integration.ts

@@ -31,13 +31,24 @@ const AST_EXTENSION_PHASES: readonly DocumentState[] = [
 ];
 
 /**
- * Build phases at which the `BuildPhasePassService` is driven. Same useful
- * set as {@link AST_EXTENSION_PHASES}: a pass registered at any other state
- * never fires (the listener is not wired), mirroring the AST-extension contract.
+ * Build phases at which the `BuildPhasePassService` is driven. A pass
+ * registered at any other state never fires (the listener is not wired), and
  * `runPasses` no-ops at a phase with no registered pass, so wiring the full set
  * unconditionally costs only an empty-bucket check per phase.
+ *
+ * `IndexedContent` belongs here and NOT in {@link AST_EXTENSION_PHASES}, so the
+ * two cannot be collapsed. Per document it carries nothing `Parsed` does; per
+ * BATCH it is the only phase meaning the global index is whole again, which
+ * batch work keyed on a complete index has nowhere else to run.
  */
-const BUILD_PHASE_PASS_STATES: readonly DocumentState[] = AST_EXTENSION_PHASES;
+const BUILD_PHASE_PASS_STATES: readonly DocumentState[] = [
+   DocumentState.Parsed,
+   DocumentState.IndexedContent,
+   DocumentState.ComputedScopes,
+   DocumentState.Linked,
+   DocumentState.IndexedReferences,
+   DocumentState.Validated
+];
 
 /**
  * Default priority of the framework integrity passes. Integrity mutates / cleans
@@ -65,6 +76,19 @@ export interface BuildPipelineIntegrationOptions {
    readonly integrityPriority?: number;
 }
 
+/**
+ * The build-pipeline slot. Empty because nothing calls this service — it wires
+ * itself in its constructor and every seam it offers is `protected`.
+ *
+ * Typing the slot by the class instead would stop an adopter's subclass
+ * satisfying it, since a class carries its `protected` members into the check
+ * and they compare by declaration rather than by shape. The cost of the empty
+ * shape is that any non-null value satisfies it, so a mis-bound slot compiles
+ * and the framework's phase listeners are then never attached.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the slot has no public member to name
+export interface BuildPipelineIntegration {}
+
 /**
  * Wires the framework's build-time features (integrity rules, AST
  * enrichment) into Langium's document-build pipeline. The single shared
@@ -90,7 +114,7 @@ export interface BuildPipelineIntegrationOptions {
  * Eagerly constructed (via `DEFAULT_EAGER_SERVICES`) so the listeners are
  * attached before the first build cycle.
  */
-export class BuildPipelineIntegration {
+export class DefaultBuildPipelineIntegration implements BuildPipelineIntegration {
    constructor(
       protected readonly services: ServerSharedServices,
       options: BuildPipelineIntegrationOptions = {}
@@ -128,6 +152,14 @@ export class BuildPipelineIntegration {
          );
       }
 
+      // Per DOCUMENT as well: `reparseAndRelink` re-indexes one document from
+      // inside the `Linked` phase and fires no build-phase notification, so a
+      // batch-level listener cannot see the AST it replaced.
+      builder.onDocumentPhase(
+         DocumentState.IndexedContent,
+         labelPhaseListener(() => this.clearScopeCaches(), 'BuildPipeline.clearScopeCaches')
+      );
+
       // AST enrichment stays per-document (onDocumentPhase) and node-granular —
       // unchanged by the build-phase-pass registry, which is batch-granular. The
       // listener calls the `extendAst` seam directly (the document-phase analog of
@@ -174,6 +206,19 @@ export class BuildPipelineIntegration {
       }
    }
 
+   /**
+    * Drop the cached scopes of every REGISTERED language, not of those owning a
+    * document in the batch. The index a scope is built from is
+    * workspace-global, so narrowing to the batch with
+    * {@link groupDocumentsByLanguage}, the way {@link callIntegrity} does,
+    * leaves a cross-grammar reference resolving against a mid-rebuild scope.
+    */
+   protected clearScopeCaches(): void {
+      for (const languageServices of this.services.ServiceRegistry.all) {
+         languageServices.references.ScopeProvider.clearScopeCaches();
+      }
+   }
+
    /** Run AST enrichment for a single document at `phase` via its language service. */
    protected extendAst(document: LangiumDocument, phase: DocumentState, cancelToken: CancellationToken): void {
       this.services.ServiceRegistry.getServices(document.uri).ast.AstExtensionService.extendDocument(document, phase, cancelToken);

package/src/langium/document-builder/build-session.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * 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 URI } from '@hydranium/langium';
+
+/** What a build is about, handed to `HydraniumDocumentBuilder.createBuildSession`. */
+export interface BuildSessionContext {
+   /**
+    * Which entry point opened the build: `'build'` is the workspace-wide pass
+    * (initialization), `'update'` an incremental rebuild. A subclass deriving
+    * cascade state skips the work for `'build'`, where every document is in the
+    * set already and `shouldRelink` is never consulted.
+    */
+   readonly kind: 'build' | 'update';
+   /** Formatted description of what caused the build — a URI, a count summary. */
+   readonly trigger: string;
+   /** True when {@link trigger} already states the document count. */
+   readonly triggerCountsDocs: boolean;
+   /** URIs the build was asked to rebuild, already flattened and canonicalized. */
+   readonly changed: readonly URI[];
+   /** URIs the build was asked to delete, already expanded by `collectDeletedURIs`. Empty for a `build` call. */
+   readonly deleted: readonly URI[];
+}
+
+/**
+ * One rebuild, treated as a correlated unit.
+ *
+ * Everything a build phase needs to know about the build it belongs to — what
+ * triggered it, when it started, whether it was cancelled, and the log lines it
+ * has produced so far. A `HydraniumDocumentBuilder` opens one per `update` /
+ * `build` call and holds it for the duration, so a per-phase hook can reach
+ * build-wide facts that no per-line formatting hook could.
+ *
+ * **Identity is the object, not {@link traceId}.** `Tracer.time` short-circuits
+ * when its log level is suppressed and never calls `captureId`, so `traceId` is
+ * `undefined` on every build in a production configuration that logs above
+ * `debug`. A teardown guard keyed on the id would then compare `undefined`
+ * against `undefined` and let a preempted build clear its successor's state.
+ * Reference equality against `HydraniumDocumentBuilder.activeSession` holds in
+ * both configurations, which is why nothing here is keyed on the id.
+ *
+ * Adopters carrying build-scoped state of their own subclass this and return it
+ * from `HydraniumDocumentBuilder.createBuildSession`, narrowing with an
+ * `instanceof` where they read it back. That buys them the framework's
+ * preemption-correct teardown rather than a second copy of it.
+ */
+export class BuildSession {
+   /**
+    * `Tracer.time` correlation id, so a phase line and the build line share a
+    * `#N`. `undefined` until the timer starts, and permanently `undefined` when
+    * the timing line is suppressed.
+    */
+   traceId?: number;
+   /** Set when the build ended in `OperationCancelled`, so the successor can tag itself "cancels #N". */
+   cancelled = false;
+   /** Phase-reached lines produced so far; the first one measures from {@link startMs} rather than from the previous phase. */
+   phasesLogged = 0;
+   /** Lines held back by {@link detailThresholdMs}; flushed or dropped when the build ends. */
+   readonly bufferedLines: string[] = [];
+
+   constructor(
+      /** Millisecond timestamp the build started at, on the same clock as `performance.now()`. */
+      readonly startMs: number,
+      /** What caused this build — a formatted URI, a count summary, or an adopter label. */
+      readonly trigger: string,
+      /** True when {@link trigger} already states the document count, so a phase line must not repeat it. */
+      readonly triggerCountsDocs: boolean,
+      /**
+       * Build duration at or above which the buffered lines are emitted; `0`
+       * disables buffering entirely. Captured per session so the flush decision
+       * uses the same value the buffering decision did, even if the underlying
+       * observable changed mid-build.
+       */
+      readonly detailThresholdMs: number
+   ) {}
+
+   /** True while lines are being held rather than emitted as they are produced. */
+   get buffers(): boolean {
+      return this.detailThresholdMs > 0;
+   }
+}