@hydranium/core 1.0.0-next.23 → 1.0.0-next.232

package/lib/langium/document-builder/build-pipeline-integration.js

@@ -26,13 +26,24 @@ const AST_EXTENSION_PHASES = [
     DocumentState.Validated
 ];
 /**
- * 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 = AST_EXTENSION_PHASES;
+const BUILD_PHASE_PASS_STATES = [
+    DocumentState.Parsed,
+    DocumentState.IndexedContent,
+    DocumentState.ComputedScopes,
+    DocumentState.Linked,
+    DocumentState.IndexedReferences,
+    DocumentState.Validated
+];
 /**
  * Default priority of the framework integrity passes. Integrity mutates / cleans
  * the AST that every derived-state pass reads, so it is *foundational* and must
@@ -71,7 +82,7 @@ export const INTEGRITY_PASS_PRIORITY = -1000;
  * Eagerly constructed (via `DEFAULT_EAGER_SERVICES`) so the listeners are
  * attached before the first build cycle.
  */
-export class BuildPipelineIntegration {
+export class DefaultBuildPipelineIntegration {
     services;
     constructor(services, options = {}) {
         this.services = services;
@@ -99,6 +110,10 @@ export class BuildPipelineIntegration {
         for (const phase of BUILD_PHASE_PASS_STATES) {
             builder.onBuildPhase(phase, labelPhaseListener((documents, cancelToken) => this.runBuildPhase(documents, phase, cancelToken), `BuildPipeline.runBuildPhase.${DocumentState[phase]}`));
         }
+        // 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
@@ -132,6 +147,18 @@ export class BuildPipelineIntegration {
             await languageServices.integrity.IntegrityService.enforceBatch(group, phase, cancelToken);
         }
     }
+    /**
+     * 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.
+     */
+    clearScopeCaches() {
+        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. */
     extendAst(document, phase, cancelToken) {
         this.services.ServiceRegistry.getServices(document.uri).ast.AstExtensionService.extendDocument(document, phase, cancelToken);

package/lib/langium/document-builder/build-pipeline-integration.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-pipeline-integration.js","sourceRoot":"","sources":["../../../src/langium/document-builder/build-pipeline-integration.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build-pipeline-integration.js","sourceRoot":"","sources":["../../../src/langium/document-builder/build-pipeline-integration.ts"],"names":[],"mappings":"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"}

package/lib/langium/document-builder/build-session.d.ts

@@ -0,0 +1,93 @@
+/********************************************************************************
+ * 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 declare class BuildSession {
+    /** 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;
+    /**
+     * `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: boolean;
+    /** Phase-reached lines produced so far; the first one measures from {@link startMs} rather than from the previous phase. */
+    phasesLogged: number;
+    /** 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()`. */
+    startMs: number, 
+    /** What caused this build — a formatted URI, a count summary, or an adopter label. */
+    trigger: string, 
+    /** True when {@link trigger} already states the document count, so a phase line must not repeat it. */
+    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.
+     */
+    detailThresholdMs: number);
+    /** True while lines are being held rather than emitted as they are produced. */
+    get buffers(): boolean;
+}
+//# sourceMappingURL=build-session.d.ts.map

package/lib/langium/document-builder/build-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-session.d.ts","sourceRoot":"","sources":["../../../src/langium/document-builder/build-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAE9C,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,EAAE,CAAC;IACjC,8GAA8G;IAC9G,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IAenB,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,uGAAuG;IACvG,QAAQ,CAAC,iBAAiB,EAAE,OAAO;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM;IA1BrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sGAAsG;IACtG,SAAS,UAAS;IAClB,4HAA4H;IAC5H,YAAY,SAAK;IACjB,4FAA4F;IAC5F,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,CAAM;IAEtC;IACG,4FAA4F;IACnF,OAAO,EAAE,MAAM;IACxB,sFAAsF;IAC7E,OAAO,EAAE,MAAM;IACxB,uGAAuG;IAC9F,iBAAiB,EAAE,OAAO;IACnC;;;;;OAKG;IACM,iBAAiB,EAAE,MAAM,EACjC;IAEJ,gFAAgF;IAChF,IAAI,OAAO,IAAI,OAAO,CAErB;CACH"}

package/lib/langium/document-builder/build-session.js

@@ -0,0 +1,72 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * 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 {
+    startMs;
+    trigger;
+    triggerCountsDocs;
+    detailThresholdMs;
+    /**
+     * `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;
+    /** 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. */
+    bufferedLines = [];
+    constructor(
+    /** Millisecond timestamp the build started at, on the same clock as `performance.now()`. */
+    startMs, 
+    /** What caused this build — a formatted URI, a count summary, or an adopter label. */
+    trigger, 
+    /** True when {@link trigger} already states the document count, so a phase line must not repeat it. */
+    triggerCountsDocs, 
+    /**
+     * 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.
+     */
+    detailThresholdMs) {
+        this.startMs = startMs;
+        this.trigger = trigger;
+        this.triggerCountsDocs = triggerCountsDocs;
+        this.detailThresholdMs = detailThresholdMs;
+    }
+    /** True while lines are being held rather than emitted as they are produced. */
+    get buffers() {
+        return this.detailThresholdMs > 0;
+    }
+}
+//# sourceMappingURL=build-session.js.map

package/lib/langium/document-builder/build-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-session.js","sourceRoot":"","sources":["../../../src/langium/document-builder/build-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAuBlF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,YAAY;IAgBV,OAAO;IAEP,OAAO;IAEP,iBAAiB;IAOjB,iBAAiB;IA1B7B;;;;OAIG;IACH,OAAO,CAAU;IACjB,sGAAsG;IACtG,SAAS,GAAG,KAAK,CAAC;IAClB,4HAA4H;IAC5H,YAAY,GAAG,CAAC,CAAC;IACjB,4FAA4F;IACnF,aAAa,GAAa,EAAE,CAAC;IAEtC;IACG,4FAA4F;IACnF,OAAe;IACxB,sFAAsF;IAC7E,OAAe;IACxB,uGAAuG;IAC9F,iBAA0B;IACnC;;;;;OAKG;IACM,iBAAyB;uBAXzB,OAAO;uBAEP,OAAO;iCAEP,iBAAiB;iCAOjB,iBAAiB;IAC1B,CAAC;IAEJ,gFAAgF;IAChF,IAAI,OAAO;QACR,OAAO,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;IACrC,CAAC;CACH"}