@hydranium/core 1.0.0-next.10

package/lib/langium/ast-extension/ast-extension-service.d.ts

@@ -0,0 +1,212 @@
+/********************************************************************************
+ * 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 Mutable, type Tracer } from '@hydranium/protocol';
+import { type AstNode, DocumentState, type LangiumDocument } from '@hydranium/langium';
+import type { CancellationToken, Disposable } from 'vscode-languageserver';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { Registry, type RegistryItem } from '../../util/registry.js';
+import { type AstExtensionRegistry } from './ast-extension-contribution.js';
+/**
+ * A registration that derives data from an AST node and attaches it to the
+ * node at a declared document-build phase.
+ *
+ * **Storage:** plain assignment (`node._foo = value`) is correct for primitives,
+ * objects, and arrays of non-AstNode values — Langium's `streamContents` walks
+ * own *enumerable* properties whose values are AstNodes (or arrays of them) and
+ * skips everything else.
+ *
+ * **Synthetic children** (AstNode-shaped values that should *not* be walked as
+ * containment children) must be assigned via {@link setHiddenProperty} so they
+ * are stored as non-enumerable own properties. Otherwise symbol providers,
+ * folding, semantic tokens, and validators will treat them as real children.
+ *
+ * **Phase semantics:** {@link state} declares the single phase at which
+ * {@link compute} fires. The framework wires one `onDocumentPhase` listener per
+ * useful state unconditionally, rather than deriving the set from the states
+ * registrations declare — so a registration's state must be one of those, and
+ * adding one is a framework change, not a registration-time choice.
+ *
+ * **`.ref`-dependent derivations: declare `state: ComputedScopes`, not `Linked`.**
+ * Lazy reference resolution is available from `ComputedScopes` onward — the
+ * global scope is built by `IndexedContent` (which runs before
+ * `ComputedScopes`), so reading a reference's `.ref` inside a `ComputedScopes`
+ * callback triggers Langium's lazy lookup and returns the resolved target node.
+ *
+ * **DO NOT** stage a `state: ComputedScopes` placeholder hoping to refine it
+ * via a separate `state: Linked` registration when a downstream consumer
+ * (typically a `ScopeExtension.addDescriptions` firing during link)
+ * iterates the derived value to build a scope: `onDocumentPhase(Linked)` fires
+ * AFTER Langium's `Linker.link()` has already walked the document, by which
+ * time the linker has resolved references against the placeholder and cached
+ * them as `LinkingError`. Populate at `ComputedScopes` via lazy `.ref`
+ * resolution instead.
+ *
+ * **Description contribution.** This hook does not return descriptions — it
+ * mutates the node only. Per-reference-type description contribution lives on
+ * `ScopeExtension.addDescriptions` (the acceptor-style sibling).
+ */
+export interface AstExtension<T extends AstNode = AstNode> extends RegistryItem {
+    /** Type-guard predicate — `compute` runs only on nodes for which this returns `true`. */
+    nodeFilter: (node: AstNode) => node is T;
+    /**
+     * Per-document early-out. When set, the framework only invokes the
+     * registration's callback for documents the filter accepts. If every
+     * registration at a given state rejects the document, the framework skips
+     * the `streamAllContents` walk entirely — important for large workspaces
+     * where most documents carry none of the AST shapes a given extension
+     * targets.
+     *
+     * Default: no filter (registration applies to every document at its state).
+     */
+    documentFilter?: (document: LangiumDocument) => boolean;
+    /**
+     * The single document-build state at which {@link compute} fires.
+     *
+     * Useful values:
+     * - `Parsed` — derivations from AST shape only, no `.ref` reads.
+     * - `ComputedScopes` — lazy `.ref` resolution available; the most common state.
+     * - `Linked` — derivations needing fully resolved cross-references.
+     * - `IndexedReferences` — cross-document reverse-lookup derivations.
+     * - `Validated` — derivations depending on diagnostics (rare).
+     *
+     * Any other state type-checks but never fires: the framework wires a
+     * listener only for the states above. `Changed` has no AST yet, and
+     * `IndexedContent` carries the same per-document information as `Parsed`,
+     * so neither is wired.
+     */
+    state: DocumentState;
+    /**
+     * Mutate `node` for this registration at {@link state}. The framework hands
+     * `node` typed as {@link Mutable} so computed / synthetic property
+     * assignments (`node._foo = ...`) compile without per-callback
+     * `asMutable(...)` casts.
+     *
+     * Sync-only by Langium contract: `ScopeComputation.collectLocalSymbols`
+     * iterates without awaiting, and `onDocumentPhase(ComputedScopes)` fires
+     * right after — async work returned would resolve out of order vs the
+     * local-symbol table read. Adopters needing async derivation must build
+     * the data ahead of time and hand a sync callback.
+     */
+    compute(node: Mutable<T>, document: LangiumDocument): void;
+}
+/**
+ * Public contract for the per-language AST-extension service. Extends the
+ * {@link AstExtensionRegistry} (the imperative `register` surface
+ * contributions use) with the dispatch entry points. Only
+ * {@link AstExtensionService.extendDocument} is called cross-class from
+ * `BuildPipelineIntegration`, as documents reach each wired phase;
+ * {@link AstExtensionService.extendNode} has no production caller.
+ *
+ * Adopter overrides go through {@link DefaultAstExtensionService}; the
+ * interface keeps the public API stable while internals (the bucket-
+ * by-state cache) stay `protected` on the default class.
+ */
+export interface AstExtensionService extends AstExtensionRegistry {
+    /**
+     * Run a single AST node through every registration declaring
+     * `phase` as its state. Honours `documentFilter` and `nodeFilter`.
+     * Primarily for tests that need to invoke an extension callback without
+     * driving Langium's full document-build pipeline.
+     */
+    extendNode(node: AstNode, document: LangiumDocument, phase: DocumentState): void;
+    /**
+     * Re-run all `compute` callbacks declaring `phase` as their state against
+     * every node in the document. Single-pass. Called by
+     * `BuildPipelineIntegration` from an `onDocumentPhase` listener;
+     * not for general adopter use.
+     */
+    extendDocument(document: LangiumDocument, phase: DocumentState, cancelToken?: CancellationToken): void;
+}
+/** Construction options for {@link DefaultAstExtensionService}. */
+export type AstExtensionServiceOptions = LogNameOptions;
+/**
+ * Default {@link AstExtensionService} implementation. Generic registry for
+ * build-phase AST-node enrichment: computed properties and synthetic
+ * children. The sibling scope-contribution concern (extra resolvable
+ * descriptions at query time) lives in `ScopeExtensionService`.
+ *
+ * Designed as a base class; consumers extend it and call `register` in
+ * their constructor.
+ *
+ * Build-phase invocation is driven by `BuildPipelineIntegration`,
+ * which calls {@link extendDocument} for the wired phases — this class
+ * owns the registry + per-node logic, not the listener lifecycle.
+ *
+ * **Performance:** `extendDocument` shares a single `streamAllContents` walk
+ * per document per wired phase; cost is O(registrations-for-state × nodes),
+ * and it early-outs when no registration targets the state or the document.
+ */
+export declare class DefaultAstExtensionService implements AstExtensionService {
+    protected readonly services: ServerLanguageServices;
+    protected readonly extensions: Registry<AstExtension<AstNode>>;
+    /**
+     * Per-state bucket of registrations targeting each state. Rebuilt lazily
+     * on the first refresh after a registry mutation — staleness is detected
+     * via reference identity of the registry's cached array (see {@link Registry.all}).
+     */
+    protected stateBuckets: Map<DocumentState, readonly AstExtension<AstNode>[]>;
+    protected stateBucketsFor: readonly AstExtension[] | undefined;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerLanguageServices, options?: AstExtensionServiceOptions);
+    /**
+     * Register a single AST extension. Doubles as the imperative low-level
+     * API and as the {@link AstExtensionRegistry} entry point that
+     * `AstExtensionContribution.registerAstExtensions` hands to
+     * contributions. Throws on duplicate id.
+     *
+     * Build-phase invocation is driven by `BuildPipelineIntegration`,
+     * which calls {@link extendDocument} for the wired phases.
+     */
+    register<T extends AstNode>(extension: AstExtension<T>): Disposable;
+    /**
+     * Production code goes through {@link extendDocument} via the
+     * `onDocumentPhase(state)` listener wired by `BuildPipelineIntegration`.
+     */
+    extendNode(node: AstNode, document: LangiumDocument, phase: DocumentState): void;
+    /**
+     * Skips the walk entirely when no registration applies to this document
+     * (either no registration declares `phase`, or every applicable
+     * registration's `documentFilter` rejects the document).
+     *
+     * `cancelToken` is checked at entry — `onDocumentPhase` is invoked once per
+     * document by Langium, so an entry-check skips the `streamAllContents`
+     * walk for any document arriving after the build is preempted. The
+     * per-registration / per-node loops stay sync (no inner `interruptAndCheck`)
+     * to avoid async coloring through the property-walk callbacks; the
+     * downstream throughput hit from running one extra document's walk is
+     * smaller than the microtask cost of yielding inside the walk.
+     */
+    extendDocument(document: LangiumDocument, phase: DocumentState, cancelToken?: CancellationToken): void;
+    /**
+     * Bucket-by-state view of {@link extensions}, rebuilt lazily when the
+     * registry's cached `all()` reference changes. Replaces per-call allocation
+     * on the per-node hot path — for a workspace with many documents at the
+     * same state, the bucket is computed once and reused until the next
+     * register / unregister.
+     */
+    protected getStateBucket(phase: DocumentState): readonly AstExtension[];
+}
+/**
+ * Assign a non-enumerable own property — for synthetic children that must NOT
+ * be walked by Langium's `streamContents`.
+ *
+ * Direct reads (`node._foo`) still work. In its default `full` transfer mode
+ * the encoder enumerates via `Object.getOwnPropertyNames`, so the property
+ * still crosses to the wire shape; `grammar` mode enumerates the reflection's
+ * declared-property allowlist instead and therefore drops it.
+ *
+ * Use when assigning AstNode-shaped values that should not appear as
+ * containment children to symbol providers, folding, semantic tokens, or
+ * validators. Plain non-AstNode values (strings, booleans, plain objects) can
+ * be assigned with `node._foo = value` directly — Langium's iteration only
+ * yields AstNode-shaped values, so non-AST data is naturally invisible.
+ */
+export declare function setHiddenProperty<V>(node: object, property: string, value: V): void;
+//# sourceMappingURL=ast-extension-service.d.ts.map

package/lib/langium/ast-extension/ast-extension-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-extension-service.d.ts","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-extension-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAU,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,KAAK,OAAO,EAAY,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACjG,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,CAAE,SAAQ,YAAY;IAC5E,yFAAyF;IACzF,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC;IACzC;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC;IACxD;;;;;;;;;;;;;;OAcG;IACH,KAAK,EAAE,aAAa,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAC7D;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC9D;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACjF;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACzG;AAED,mEAAmE;AACnE,MAAM,MAAM,0BAA0B,GAAG,cAAc,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,0BAA2B,YAAW,mBAAmB;IAahE,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB;IAZtD,SAAS,CAAC,QAAQ,CAAC,UAAU,kCAAgC;IAC7D;;;;OAIG;IACH,SAAS,CAAC,YAAY,uDAAqD;IAC3E,SAAS,CAAC,eAAe,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,CAAC;IAE/D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,sBAAsB,EACnD,OAAO,GAAE,0BAA+B;IAc3C;;;;;;;;OAQG;IACH,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,UAAU;IAMnE;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI;IAahF;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAoCtG;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,YAAY,EAAE;CAiBzE;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAOnF"}

package/lib/langium/ast-extension/ast-extension-service.js

@@ -0,0 +1,181 @@
+/********************************************************************************
+ * 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 { Logger } from '@hydranium/protocol';
+import { AstUtils, DocumentState } from '@hydranium/langium';
+import { Registry } from '../../util/registry.js';
+/**
+ * Default {@link AstExtensionService} implementation. Generic registry for
+ * build-phase AST-node enrichment: computed properties and synthetic
+ * children. The sibling scope-contribution concern (extra resolvable
+ * descriptions at query time) lives in `ScopeExtensionService`.
+ *
+ * Designed as a base class; consumers extend it and call `register` in
+ * their constructor.
+ *
+ * Build-phase invocation is driven by `BuildPipelineIntegration`,
+ * which calls {@link extendDocument} for the wired phases — this class
+ * owns the registry + per-node logic, not the listener lifecycle.
+ *
+ * **Performance:** `extendDocument` shares a single `streamAllContents` walk
+ * per document per wired phase; cost is O(registrations-for-state × nodes),
+ * and it early-outs when no registration targets the state or the document.
+ */
+export class DefaultAstExtensionService {
+    services;
+    extensions = new Registry();
+    /**
+     * Per-state bucket of registrations targeting each state. Rebuilt lazily
+     * on the first refresh after a registry mutation — staleness is detected
+     * via reference identity of the registry's cached array (see {@link Registry.all}).
+     */
+    stateBuckets = new Map();
+    stateBucketsFor;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'AstExtension').trace('instantiated');
+        // Read the language's AstExtensionContribution group and let each
+        // contribution register one or many extensions through this service.
+        // Optional chaining tolerates incomplete test stubs; production
+        // wiring always provides the slot via `createServerLanguageModule`.
+        const contributions = services.ast?.extensions ?? {};
+        for (const contribution of Object.values(contributions)) {
+            contribution.registerAstExtensions(this);
+        }
+    }
+    /**
+     * Register a single AST extension. Doubles as the imperative low-level
+     * API and as the {@link AstExtensionRegistry} entry point that
+     * `AstExtensionContribution.registerAstExtensions` hands to
+     * contributions. Throws on duplicate id.
+     *
+     * Build-phase invocation is driven by `BuildPipelineIntegration`,
+     * which calls {@link extendDocument} for the wired phases.
+     */
+    register(extension) {
+        // Cast: TypeScript can't see that `T extends AstNode` makes the extension
+        // assignable to the default-parameter form. The runtime contract is the same.
+        return this.extensions.register(extension);
+    }
+    /**
+     * Production code goes through {@link extendDocument} via the
+     * `onDocumentPhase(state)` listener wired by `BuildPipelineIntegration`.
+     */
+    extendNode(node, document, phase) {
+        const bucket = this.getStateBucket(phase);
+        for (const extension of bucket) {
+            if (extension.documentFilter && !extension.documentFilter(document)) {
+                continue;
+            }
+            if (!extension.nodeFilter(node)) {
+                continue;
+            }
+            extension.compute(node, document);
+        }
+    }
+    /**
+     * Skips the walk entirely when no registration applies to this document
+     * (either no registration declares `phase`, or every applicable
+     * registration's `documentFilter` rejects the document).
+     *
+     * `cancelToken` is checked at entry — `onDocumentPhase` is invoked once per
+     * document by Langium, so an entry-check skips the `streamAllContents`
+     * walk for any document arriving after the build is preempted. The
+     * per-registration / per-node loops stay sync (no inner `interruptAndCheck`)
+     * to avoid async coloring through the property-walk callbacks; the
+     * downstream throughput hit from running one extra document's walk is
+     * smaller than the microtask cost of yielding inside the walk.
+     */
+    extendDocument(document, phase, cancelToken) {
+        if (cancelToken?.isCancellationRequested) {
+            return;
+        }
+        const bucket = this.getStateBucket(phase);
+        if (bucket.length === 0) {
+            return;
+        }
+        // Per-document filter: registrations without `documentFilter` always apply.
+        // If every registration rejects the document, skip the streamAllContents walk.
+        const applicable = bucket.filter(extension => !extension.documentFilter || extension.documentFilter(document));
+        if (applicable.length === 0) {
+            return;
+        }
+        // Per-registration self-time profiling is opt-in: only open a session when
+        // the debug threshold is active, so the production path allocates nothing
+        // and the per-(node×registration) loop stays a single const-branch off
+        // `session`. `ProfileSession.scope` is NOT itself level-gated.
+        const session = Logger.isLevelEnabled('debug') ? this.tracer.profile(`ast-extension ${DocumentState[phase]}`) : undefined;
+        for (const node of AstUtils.streamAllContents(document.parseResult.value)) {
+            for (const extension of applicable) {
+                if (extension.nodeFilter(node)) {
+                    // Scope per registration id so the session aggregates self-time by
+                    // extension across every node; off the profiling path call directly.
+                    if (session) {
+                        session.scope(extension.id, () => extension.compute(node, document));
+                    }
+                    else {
+                        extension.compute(node, document);
+                    }
+                }
+            }
+        }
+        // One line per registration (count + self-% + self-ms), sorted — only when profiling.
+        session?.report('debug');
+    }
+    /**
+     * Bucket-by-state view of {@link extensions}, rebuilt lazily when the
+     * registry's cached `all()` reference changes. Replaces per-call allocation
+     * on the per-node hot path — for a workspace with many documents at the
+     * same state, the bucket is computed once and reused until the next
+     * register / unregister.
+     */
+    getStateBucket(phase) {
+        const current = this.extensions.all();
+        if (this.stateBucketsFor !== current) {
+            const next = new Map();
+            for (const extension of current) {
+                let bucket = next.get(extension.state);
+                if (!bucket) {
+                    bucket = [];
+                    next.set(extension.state, bucket);
+                }
+                bucket.push(extension);
+            }
+            this.stateBuckets = next;
+            this.stateBucketsFor = current;
+        }
+        return this.stateBuckets.get(phase) ?? EMPTY_STATE_BUCKET;
+    }
+}
+/** Shared empty result so `getStateBucket` doesn't allocate per call on the cold path. */
+const EMPTY_STATE_BUCKET = Object.freeze([]);
+/**
+ * Assign a non-enumerable own property — for synthetic children that must NOT
+ * be walked by Langium's `streamContents`.
+ *
+ * Direct reads (`node._foo`) still work. In its default `full` transfer mode
+ * the encoder enumerates via `Object.getOwnPropertyNames`, so the property
+ * still crosses to the wire shape; `grammar` mode enumerates the reflection's
+ * declared-property allowlist instead and therefore drops it.
+ *
+ * Use when assigning AstNode-shaped values that should not appear as
+ * containment children to symbol providers, folding, semantic tokens, or
+ * validators. Plain non-AstNode values (strings, booleans, plain objects) can
+ * be assigned with `node._foo = value` directly — Langium's iteration only
+ * yields AstNode-shaped values, so non-AST data is naturally invisible.
+ */
+export function setHiddenProperty(node, property, value) {
+    Object.defineProperty(node, property, {
+        value,
+        writable: true,
+        configurable: true,
+        enumerable: false
+    });
+}
+//# sourceMappingURL=ast-extension-service.js.map

package/lib/langium/ast-extension/ast-extension-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-extension-service.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-extension-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,MAAM,EAA6B,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAgB,QAAQ,EAAE,aAAa,EAAwB,MAAM,oBAAoB,CAAC;AAIjG,OAAO,EAAE,QAAQ,EAAqB,MAAM,wBAAwB,CAAC;AAuHrE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,0BAA0B;IAad;IAZH,UAAU,GAAG,IAAI,QAAQ,EAAgB,CAAC;IAC7D;;;;OAIG;IACO,YAAY,GAAG,IAAI,GAAG,EAA0C,CAAC;IACjE,eAAe,CAAsC;IAE5C,MAAM,CAAS;IAElC,YACsB,QAAgC,EACnD,UAAsC,EAAE;QADrB,aAAQ,GAAR,QAAQ,CAAwB;QAGnD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAElG,kEAAkE;QAClE,qEAAqE;QACrE,gEAAgE;QAChE,oEAAoE;QACpE,MAAM,aAAa,GAAG,QAAQ,CAAC,GAAG,EAAE,UAAU,IAAI,EAAE,CAAC;QACrD,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;YACvD,YAAY,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAoB,SAA0B;QACnD,0EAA0E;QAC1E,8EAA8E;QAC9E,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAyB,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,IAAa,EAAE,QAAyB,EAAE,KAAoB;QACtE,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC1C,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;YAC9B,IAAI,SAAS,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnE,SAAS;YACZ,CAAC;YACD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,SAAS;YACZ,CAAC;YACD,SAAS,CAAC,OAAO,CAAC,IAAwB,EAAE,QAAQ,CAAC,CAAC;QACzD,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,QAAyB,EAAE,KAAoB,EAAE,WAA+B;QAC5F,IAAI,WAAW,EAAE,uBAAuB,EAAE,CAAC;YACxC,OAAO;QACV,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO;QACV,CAAC;QACD,4EAA4E;QAC5E,+EAA+E;QAC/E,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,cAAc,IAAI,SAAS,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/G,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO;QACV,CAAC;QACD,2EAA2E;QAC3E,0EAA0E;QAC1E,uEAAuE;QACvE,+DAA+D;QAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1H,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,iBAAiB,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACzE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBAClC,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC9B,mEAAmE;oBACnE,qEAAqE;oBACrE,IAAI,OAAO,EAAE,CAAC;wBACX,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,IAAwB,EAAE,QAAQ,CAAC,CAAC,CAAC;oBAC5F,CAAC;yBAAM,CAAC;wBACL,SAAS,CAAC,OAAO,CAAC,IAAwB,EAAE,QAAQ,CAAC,CAAC;oBACzD,CAAC;gBACJ,CAAC;YACJ,CAAC;QACJ,CAAC;QACD,sFAAsF;QACtF,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACO,cAAc,CAAC,KAAoB;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,eAAe,KAAK,OAAO,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAiC,CAAC;YACtD,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE,CAAC;gBAC/B,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBACvC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACX,MAAM,GAAG,EAAE,CAAC;oBACZ,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;gBACrC,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC1B,CAAC;YACD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC;IAC7D,CAAC;CACH;AAED,0FAA0F;AAC1F,MAAM,kBAAkB,GAA4B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAI,IAAY,EAAE,QAAgB,EAAE,KAAQ;IAC1E,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE;QACnC,KAAK;QACL,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,KAAK;KACnB,CAAC,CAAC;AACN,CAAC"}

package/lib/langium/ast-extension/ast-node-builder.d.ts

@@ -0,0 +1,90 @@
+/********************************************************************************
+ * 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 { AstNode, AstReflection } from '@hydranium/langium';
+/**
+ * Shape of the per-type constants Langium emits alongside each
+ * grammar-generated interface — a `const` of the same name whose `$type` field
+ * carries the type name and whose remaining keys mirror the property names.
+ *
+ * The builder consumes this constant to drive `$type` at runtime; the
+ * `$type`-literal type ties the constant to the AST interface at compile time.
+ */
+export interface AstTypeConstant<TType extends string = string> {
+    readonly $type: TType;
+}
+/**
+ * Keys of `T` whose values are array-typed. Used to mark array-valued fields
+ * as optional in the init shape — the builder auto-defaults them to `[]` from
+ * Langium's reflection metadata, so callers need not spell out an empty array
+ * for every containment list on the type.
+ */
+type ArrayKeys<T> = {
+    [K in keyof T]-?: T[K] extends ReadonlyArray<unknown> ? K : never;
+}[keyof T];
+/**
+ * Init payload for {@link AstNodeBuilder}: every non-array, non-Langium field
+ * of `T` is required (so TS still catches missing mandatory data); array
+ * fields are optional (auto-defaulted from the grammar's reflection metadata);
+ * Langium plumbing (`$container` / `$containerProperty` / `$containerIndex`)
+ * and `$synthetic` are optional overrides.
+ *
+ * `$type` is supplied by the type constant, not the init.
+ */
+export type AstNodeInit<T extends AstNode> = Omit<T, keyof AstNode | ArrayKeys<T>> & Partial<Pick<T, ArrayKeys<T>>> & Partial<Pick<AstNode, '$container' | '$containerProperty' | '$containerIndex'>> & {
+    $synthetic?: boolean;
+};
+/**
+ * Pre-bound AST-node factory. Adopters bind once at language-module load
+ * (see {@link makeAstNodeBuilder}) and re-export the result so call sites can
+ * `import { astNode } from '...'` without threading reflection through.
+ *
+ * `TMap` is the grammar's type-name → AST-interface registry. Langium emits
+ * this as `<LanguageName>AstType` next to the reflection (in the grammar's
+ * generated `ast.js`). Threading the map through the builder lets TS resolve
+ * the AST interface from a constant's `$type` literal alone, so call sites do
+ * not have to write the type name twice.
+ *
+ * @param typeConstant the per-type constant Langium emits (drives `$type`).
+ * @param init typed fields — TS enforces mandatory non-array fields here.
+ * @param extras explicitly-unchecked escape hatch for properties not declared
+ *               on the AST interface. Use sparingly; lives in a separate
+ *               argument so typos can't silently pass into the typed slot.
+ */
+export type AstNodeBuilder<TMap> = <TType extends string & keyof TMap>(typeConstant: AstTypeConstant<TType>, init: AstNodeInit<Extract<TMap[TType], AstNode>>, extras?: Record<string, unknown>) => Extract<TMap[TType], AstNode>;
+/**
+ * Build an {@link AstNodeBuilder} pre-bound to a language's `AstReflection`
+ * and its grammar `AstType` registry.
+ *
+ * The factory shape exists so the framework stays grammar-agnostic: each
+ * adopter binds the helper once next to their language module, passing their
+ * generated reflection and `AstType` registry, and exports the resulting
+ * `astNode` function. The registry generic gives TS the grammar's `$type` →
+ * AST-interface mapping, so call sites get full inference from the type
+ * constant alone — no explicit generic parameter at every call site.
+ *
+ * Runtime behaviour: reads `reflection.getTypeMetaData(type).properties` and,
+ * for every property whose metadata carries a `defaultValue`, pre-fills the
+ * result before merging the caller's `init`. Array defaults are materialised
+ * as a fresh `[]` per call (never shared with the metadata's array instance,
+ * which downstream callers mutate); scalar defaults (`false`, `0`, `''`, …)
+ * are copied as-is since they're immutable. Grammar-generated containment
+ * lists and `?=`-style boolean flags therefore default automatically;
+ * TS-augmented fields (declared via `declare module './generated/ast.js'`)
+ * are unaffected by the runtime defaulting but remain typed at call sites.
+ *
+ * The init shape only relaxes array-typed fields to optional (via
+ * {@link ArrayKeys}) — there is no equivalent structural signal for "this
+ * property has a default in the metadata", so non-array defaulted fields
+ * (e.g. boolean flags) still appear required in {@link AstNodeInit}. The
+ * runtime defaulting is therefore a safety net for casts / partial inits
+ * rather than a way to drop fields from the typed call site.
+ */
+export declare function makeAstNodeBuilder<TMap>(reflection: AstReflection): AstNodeBuilder<TMap>;
+export {};
+//# sourceMappingURL=ast-node-builder.d.ts.map

package/lib/langium/ast-extension/ast-node-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-node-builder.d.ts","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACxB;AAED;;;;;GAKG;AACH,KAAK,SAAS,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK;CAAE,CAAC,MAAM,CAAC,CAAC,CAAC;AAEnG;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,GAC/E,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,oBAAoB,GAAG,iBAAiB,CAAC,CAAC,GAAG;IAC/E,UAAU,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEL;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,IAAI,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,IAAI,EAClE,YAAY,EAAE,eAAe,CAAC,KAAK,CAAC,EACpC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,aAAa,GAAG,cAAc,CAAC,IAAI,CAAC,CA2BxF"}

package/lib/langium/ast-extension/ast-node-builder.js

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Build an {@link AstNodeBuilder} pre-bound to a language's `AstReflection`
+ * and its grammar `AstType` registry.
+ *
+ * The factory shape exists so the framework stays grammar-agnostic: each
+ * adopter binds the helper once next to their language module, passing their
+ * generated reflection and `AstType` registry, and exports the resulting
+ * `astNode` function. The registry generic gives TS the grammar's `$type` →
+ * AST-interface mapping, so call sites get full inference from the type
+ * constant alone — no explicit generic parameter at every call site.
+ *
+ * Runtime behaviour: reads `reflection.getTypeMetaData(type).properties` and,
+ * for every property whose metadata carries a `defaultValue`, pre-fills the
+ * result before merging the caller's `init`. Array defaults are materialised
+ * as a fresh `[]` per call (never shared with the metadata's array instance,
+ * which downstream callers mutate); scalar defaults (`false`, `0`, `''`, …)
+ * are copied as-is since they're immutable. Grammar-generated containment
+ * lists and `?=`-style boolean flags therefore default automatically;
+ * TS-augmented fields (declared via `declare module './generated/ast.js'`)
+ * are unaffected by the runtime defaulting but remain typed at call sites.
+ *
+ * The init shape only relaxes array-typed fields to optional (via
+ * {@link ArrayKeys}) — there is no equivalent structural signal for "this
+ * property has a default in the metadata", so non-array defaulted fields
+ * (e.g. boolean flags) still appear required in {@link AstNodeInit}. The
+ * runtime defaulting is therefore a safety net for casts / partial inits
+ * rather than a way to drop fields from the typed call site.
+ */
+export function makeAstNodeBuilder(reflection) {
+    return function astNode(typeConstant, init, extras) {
+        const meta = reflection.getTypeMetaData(typeConstant.$type);
+        const result = { $type: typeConstant.$type };
+        if (meta?.properties) {
+            for (const [propName, propInfo] of Object.entries(meta.properties)) {
+                const defaultValue = propInfo.defaultValue;
+                if (defaultValue === undefined) {
+                    continue;
+                }
+                // Arrays are duplicated so each node carries its own mutable instance;
+                // scalars are immutable and safe to copy by reference.
+                result[propName] = Array.isArray(defaultValue) ? [...defaultValue] : defaultValue;
+            }
+        }
+        Object.assign(result, init);
+        if (extras) {
+            // Extras win over init: this is the explicit escape hatch, so when a
+            // call site uses it, treat that as deliberate override intent.
+            Object.assign(result, extras);
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=ast-node-builder.js.map

package/lib/langium/ast-extension/ast-node-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-node-builder.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AA8DlF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,kBAAkB,CAAO,UAAyB;IAC/D,OAAO,SAAS,OAAO,CACpB,YAAoC,EACpC,IAAgD,EAChD,MAAgC;QAEhC,MAAM,IAAI,GAAG,UAAU,CAAC,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC5D,MAAM,MAAM,GAA4B,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;QACtE,IAAI,IAAI,EAAE,UAAU,EAAE,CAAC;YACpB,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;gBAClE,MAAM,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;gBAC3C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;oBAC9B,SAAS;gBACZ,CAAC;gBACD,uEAAuE;gBACvE,uDAAuD;gBACvD,MAAM,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;YACrF,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC5B,IAAI,MAAM,EAAE,CAAC;YACV,qEAAqE;YACrE,+DAA+D;YAC/D,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,MAAkD,CAAC;IAC7D,CAAC,CAAC;AACL,CAAC"}

package/lib/langium/ast-extension/index.d.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export * from './ast-extension-contribution.js';
+export * from './ast-extension-service.js';
+export * from './ast-node-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/langium/ast-extension/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/langium/ast-extension/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC"}

package/lib/langium/ast-extension/index.js

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export * from './ast-extension-contribution.js';
+export * from './ast-extension-service.js';
+export * from './ast-node-builder.js';
+//# sourceMappingURL=index.js.map

package/lib/langium/ast-extension/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC"}