@hydranium/core 1.0.0-next.10

package/lib/langium/integrity/integrity-service.js

@@ -0,0 +1,328 @@
+/********************************************************************************
+ * 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 { isPromiseLike, Logger } from '@hydranium/protocol';
+import { AstUtils, DocumentState, interruptAndCheck, UriUtils } from '@hydranium/langium';
+import { Registry } from '../../util/registry.js';
+import { IntegrityPhase } from './integrity-rule.js';
+export var IntegrityService;
+(function (IntegrityService) {
+    /**
+     * The earliest document state at which integrity rules have completed and the
+     * resulting AST + serialised text are stable. Use this when you need
+     * consumable post-integrity content: syncing text to language clients,
+     * settling a save, loading the AST for diagram rendering, or resolving a
+     * deferred update().
+     *
+     * Do NOT use this when you need validation diagnostics — those are computed
+     * at `DocumentState.Validated` and delivered separately via `publishDiagnostics`
+     * or the `onModelUpdated` event.
+     *
+     * Invariant: integrity rules only register at Parsed or Linked, so the build
+     * is guaranteed post-integrity once it advances past `onBuildPhase(Linked)`
+     * into `IndexedReferences`. {@link IntegrityService.register} enforces this at
+     * runtime; if a future rule needs a later phase, this value must move forward
+     * and every call site re-evaluated.
+     */
+    IntegrityService.SettledState = DocumentState.IndexedReferences;
+})(IntegrityService || (IntegrityService = {}));
+/**
+ * Default {@link IntegrityService} implementation. Enforces rules,
+ * resyncs document text after mutations, and propagates corrections.
+ * The build-pipeline wiring lives in `BuildPipelineIntegration`,
+ * which registers the integrity passes that call {@link enforceBatch} —
+ * this class owns the rule logic, not the pass lifecycle.
+ *
+ * **Per-language service.** Bound in the per-language module and
+ * constructed with {@link ServerLanguageServices}: shared dependencies
+ * (text-document manager, file-system provider, workspace manager,
+ * logger, document builder) come from `services.shared`, while
+ * serialisation uses the service's own language
+ * `services.serializer.Serializer` directly — no per-URI
+ * `ServiceRegistry` lookup, because every document this instance
+ * processes is its own grammar (the orchestrator routes per language).
+ * Adopter subclasses thread the same `(services, options?)` shape.
+ */
+export class DefaultIntegrityService {
+    services;
+    /** Registry of integrity rules, keyed by id. Adopters can `unregister(id)` to drop a built-in rule. */
+    rules = new Registry();
+    /** One logger per rule, created at registration and dropped on unregister. */
+    ruleLoggers = new Map();
+    /**
+     * Rules bucketed by the phase they target, preserving the registry's
+     * priority order within each bucket. Rebuilt lazily on the first
+     * `enforceIntegrity` call after a registry mutation — staleness is detected
+     * via reference identity of the registry's cached array (see
+     * {@link Registry.all}). Filtering the rule list per call would instead
+     * allocate one transient array per document per phase, which a workspace
+     * whose documents all settle at the same phase pays on every build.
+     */
+    phaseBuckets = new Map();
+    phaseBucketsFor;
+    /** Controls how corrections are persisted for closed files. See {@link IntegritySyncMode}. */
+    syncMode;
+    textDocuments;
+    fileSystemProvider;
+    tracer;
+    /**
+     * The framework document builder, used to re-parse + re-link a document in place after a
+     * Linked-phase correction (see {@link resyncDocument}). The framework binds
+     * `shared.workspace.DocumentBuilder` to {@link HydraniumDocumentBuilder}; the narrowing
+     * cast surfaces its single-document phase runner.
+     */
+    documentBuilder;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.textDocuments = services.shared.workspace.TextDocuments;
+        this.fileSystemProvider = services.shared.workspace.FileSystemProvider;
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'Integrity').trace('instantiated');
+        this.documentBuilder = services.shared.workspace.DocumentBuilder;
+        this.syncMode = options.syncMode ?? 'silent';
+        // Read the language's IntegrityRuleContribution group and let each
+        // contribution register one or many rules through this service (the
+        // declarative path; equivalent to imperative `register(rule)` calls).
+        // Optional chaining tolerates incomplete test stubs; production
+        // wiring always provides the slot via `createServerLanguageModule`.
+        const contributions = services.integrity?.rules ?? {};
+        for (const contribution of Object.values(contributions)) {
+            contribution.registerIntegrityRules(this);
+        }
+    }
+    /**
+     * Enforce all rules for `phase` across a batch of documents that have
+     * reached that build state: per document run the rules and, if any
+     * mutated the AST, resync the document text and propagate corrections.
+     *
+     * Driven by the framework integrity pass `BuildPipelineIntegration`
+     * registers — a batch-level (not per-document) pass, because a mutation
+     * here reparses the document and must not race the per-document build
+     * progression. `cancelToken` is supplied by
+     * Langium's build pipeline and honoured between documents (and inside
+     * `enforceIntegrity` between nodes) so a build preempted by a
+     * concurrent write lock interrupts cleanly rather than running the
+     * rule set to completion against a doomed build.
+     */
+    async enforceBatch(documents, phase, cancelToken) {
+        const phaseStart = performance.now();
+        let mutatedCount = 0;
+        // Per-rule self-time profiling is opt-in: only spin up a session when the
+        // debug threshold is active, so the production `info` path allocates
+        // nothing and the hot rule loop stays a single const-branch off `session`.
+        const session = Logger.isLevelEnabled('debug') ? this.tracer.profile(`integrity ${DocumentState[phase]}`) : undefined;
+        for (const document of documents) {
+            const changed = await this.enforceIntegrity(document, phase, cancelToken, session);
+            if (changed) {
+                mutatedCount++;
+                await this.resyncDocument(document, cancelToken);
+            }
+            await interruptAndCheck(cancelToken);
+        }
+        const totalMs = Math.round(performance.now() - phaseStart);
+        if (totalMs >= 25 || mutatedCount > 0) {
+            this.tracer.info(`enforce ${DocumentState[phase]}: docs=${documents.length}, mutated=${mutatedCount} [${totalMs}ms]`);
+        }
+        // One line per rule (count + self-% + self-ms), sorted by cost — only when profiling.
+        session?.report('debug');
+    }
+    /** Register a single integrity rule. The {@link IntegrityRuleRegistry} entry point. */
+    register(rule) {
+        // The IntegrityService.SettledState landmark assumes rules only run at Parsed or Linked.
+        // Reject anything later — moving the boundary requires updating both SettledState and
+        // every call site that depends on "post-integrity" semantics.
+        if (!IntegrityPhase.all().includes(rule.phase)) {
+            throw new Error(`Integrity rule '${this.formatRule(rule)}' registered at phase ` +
+                `${DocumentState[rule.phase]} would invalidate IntegrityService.SettledState. ` +
+                'Allowed phases are Parsed and Linked.');
+        }
+        const disposable = this.rules.register(rule);
+        this.ruleLoggers.set(rule.id, this.tracer.sub(IntegrityPhase.toString(rule.phase)).sub(rule.label ?? rule.id));
+        return {
+            dispose: () => {
+                disposable.dispose();
+                this.ruleLoggers.delete(rule.id);
+            }
+        };
+    }
+    /** Remove a rule by id. Returns `true` if a rule was removed. Useful for adopters that want to swap a built-in rule. */
+    unregister(id) {
+        const removed = this.rules.unregister(id);
+        if (removed) {
+            this.ruleLoggers.delete(id);
+        }
+        return removed;
+    }
+    /**
+     * Run all rules for the given phase against matching AST nodes. Returns
+     * `true` if any rule mutated the AST.
+     *
+     * Per-rule await is gated by {@link isPromiseLike} so sync rules
+     * (the common case) skip the microtask per iteration — important on the
+     * Parsed/Linked phases which gate the rest of the build pipeline. The
+     * outer caller still pays exactly one microtask tick per
+     * `enforceIntegrity` call (any `async` function does), but no per-node ×
+     * per-rule cost is added when nothing is async.
+     *
+     * Single pass over the document's AST, with the phase's rules read from
+     * the cached bucket rather than filtered per call.
+     *
+     * `cancelToken` is honoured at the per-node boundary (after each node's
+     * full rule sweep) — coarser than per (node × rule) to avoid a microtask
+     * per inner iteration, finer than per-document so a long-running rule set
+     * on a large file can still interrupt mid-stream. Throws
+     * `OperationCancelled` when the token is cancelled; Langium's build
+     * pipeline absorbs the throw at the lock-holder.
+     */
+    async enforceIntegrity(document, phase, cancelToken, session) {
+        if (cancelToken?.isCancellationRequested) {
+            return false;
+        }
+        let changed = false;
+        const rulesForPhase = this.getPhaseBucket(phase);
+        if (rulesForPhase.length === 0) {
+            return false;
+        }
+        const relativeUri = this.services.shared.workspace.WorkspaceManager.wsRelativePath(document.uri);
+        for (const node of AstUtils.streamAst(document.parseResult.value)) {
+            for (const rule of rulesForPhase) {
+                if (node.$type === rule.nodeType) {
+                    const ruleLogger = this.ruleLoggers.get(rule.id).with(relativeUri);
+                    // Scope per rule so the session aggregates self-time by rule id across all
+                    // nodes; off the profiling path `session` is undefined and we call directly.
+                    const enforced = session
+                        ? session.scope(rule.id, () => rule.enforce(node, document, ruleLogger))
+                        : rule.enforce(node, document, ruleLogger);
+                    const mutated = isPromiseLike(enforced) ? await enforced : enforced;
+                    if (mutated) {
+                        ruleLogger.trace(`[${relativeUri}] Mutated ${this.formatNode(node)}`);
+                    }
+                    changed = mutated || changed;
+                }
+            }
+            if (cancelToken !== undefined) {
+                await interruptAndCheck(cancelToken);
+            }
+        }
+        return changed;
+    }
+    /**
+     * Re-serialise the document text after AST mutations, propagate corrections,
+     * and re-parse at Parsed phase (safe because linking hasn't occurred yet).
+     *
+     * `cancelToken` is checked at entry so a preempted build skips the
+     * serialise / disk-write atomic; the steps inside resync are not further
+     * subdivided because each is a single fast operation that does not yield
+     * a natural interruption point.
+     */
+    async resyncDocument(document, cancelToken) {
+        if (cancelToken?.isCancellationRequested) {
+            return;
+        }
+        const root = document.parseResult.value;
+        const newText = await this.services.serializer.Serializer.serializeAst(root);
+        const oldText = document.textDocument.getText();
+        if (oldText === newText) {
+            return;
+        }
+        // Keep the same version so HydraniumTextDocuments doesn't reject subsequent client edits.
+        // Use manager.update so the `instanceof FullTextDocument` gate in the bare
+        // `TextDocument.update` doesn't trip on adopter-custom text-document types.
+        const textDocument = this.textDocuments.update(document.textDocument, [{ text: newText }], document.textDocument.version);
+        await this.syncCorrections(textDocument);
+        if (document.state <= DocumentState.Parsed) {
+            // Parsed-phase correction: re-parse only. The build pipeline still runs
+            // IndexedContent → ComputedScopes → Linked → … on the fresh AST afterwards,
+            // so the document reconciles naturally with no extra work here.
+            await this.documentBuilder.reparse(document, cancelToken);
+        }
+        else {
+            // Linked-phase (or later) correction. The rule mutated the AST in place but
+            // left the CST untouched, so CST and AST now disagree, and Langium's
+            // re-parse gate keys on the CST — a bare re-parse would be skipped on a
+            // later build and strand the mutated AST. Reconcile within this build via
+            // the builder's single-document phase runner, which leaves the document
+            // self-consistent (text + CST + AST + links) without re-firing the
+            // build-phase listeners (which would re-enter integrity). The phase logic
+            // stays in the builder, its proper home, rather than being duplicated here.
+            await this.documentBuilder.reparseAndRelink(document, cancelToken);
+        }
+    }
+    /**
+     * Propagate a correction to disk and/or the editor. The corrected text is
+     * already in the synced store (in-place in {@link resyncDocument}); this
+     * method routes the out-of-band part by document registration:
+     *
+     * - **Open in the language client** → nothing to push here. The AST mutation
+     *   rode the current build, so `ModelService.syncToLanguageClient` (the
+     *   persistent integrity-settled listener) mirrors the corrected text to the
+     *   client by *content* (shadow diff) — no authorship rewrite, no second
+     *   rebuild.
+     * - **Closed, silent mode** → write to disk directly (disk is authoritative).
+     * - **Closed, editor mode** → stage so the next open picks it up via applyEdit.
+     */
+    async syncCorrections(document) {
+        // Open files: delivery is the ModelService settled listener's job (by
+        // content, via the shadow) — nothing to do here. Only the open/closed
+        // question is asked, so no reverse address resolution is needed: a file
+        // open under a symlinked path still answers `true`.
+        if (this.textDocuments.isOpenInLanguageClient(document.uri)) {
+            return;
+        }
+        // Closed files, silent mode: write to disk directly.
+        if (this.syncMode === 'silent') {
+            // Async write so the integrity pass does not block the event loop on a slow filesystem.
+            await this.fileSystemProvider.writeFile(UriUtils.toUri(document.uri), document.getText());
+            return;
+        }
+        // Closed files, editor mode: stage content so the next open picks it up via applyEdit.
+        this.textDocuments.stagePendingContent(document.uri, document.getText());
+    }
+    /**
+     * Format a rule's name for inclusion in user-facing diagnostic strings
+     * (error messages thrown during registration). Defaults to
+     * `label ?? id`. Adopters override when their error reporting needs
+     * richer rule context.
+     */
+    formatRule(rule) {
+        return rule.label ?? rule.id;
+    }
+    /**
+     * Format an AST node for the per-mutation `trace` log line. Returns
+     * `'TypeName'` or `"TypeName('label')"` when the node carries a string
+     * `name` (preferred) or `id`. Empty-string name falls through to id;
+     * non-string properties are ignored. Adopters override to fold in
+     * domain-specific context.
+     */
+    formatNode(node) {
+        const named = node;
+        const fromName = typeof named.name === 'string' && named.name ? named.name : undefined;
+        const fromId = typeof named.id === 'string' && named.id ? named.id : undefined;
+        const label = fromName ?? fromId;
+        return label ? `${node.$type}('${label}')` : node.$type;
+    }
+    getPhaseBucket(phase) {
+        const current = this.rules.all();
+        if (this.phaseBucketsFor !== current) {
+            const next = new Map();
+            for (const rule of current) {
+                let bucket = next.get(rule.phase);
+                if (!bucket) {
+                    bucket = [];
+                    next.set(rule.phase, bucket);
+                }
+                bucket.push(rule);
+            }
+            this.phaseBuckets = next;
+            this.phaseBucketsFor = current;
+        }
+        return this.phaseBuckets.get(phase) ?? EMPTY_PHASE_BUCKET;
+    }
+}
+/** Shared empty result so `getPhaseBucket` doesn't allocate per call on the cold path. */
+const EMPTY_PHASE_BUCKET = Object.freeze([]);
+//# sourceMappingURL=integrity-service.js.map

package/lib/langium/integrity/integrity-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity-service.js","sourceRoot":"","sources":["../../../src/langium/integrity/integrity-service.ts"],"names":[],"mappings":"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"}

package/lib/langium/keys/default-element-key-provider.d.ts

@@ -0,0 +1,19 @@
+/********************************************************************************
+ * 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 { NameBasedKeyProvider } from './name-based-key-provider.js';
+/**
+ * Re-export of {@link NameBasedKeyProvider} under the conventional
+ * "default" name — the framework's default key strategy. Aliased
+ * rather than subclassed so the editorial intent ("this IS the default")
+ * is visible at the binding line; the concrete implementation lives on
+ * {@link NameBasedKeyProvider} with its full stability documentation.
+ */
+export declare const DefaultElementKeyProvider: typeof NameBasedKeyProvider;
+export type DefaultElementKeyProvider = NameBasedKeyProvider;
+//# sourceMappingURL=default-element-key-provider.d.ts.map

package/lib/langium/keys/default-element-key-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-element-key-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/keys/default-element-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,6BAAuB,CAAC;AAC9D,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,CAAC"}

package/lib/langium/keys/default-element-key-provider.js

@@ -0,0 +1,18 @@
+/********************************************************************************
+ * 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 { NameBasedKeyProvider } from './name-based-key-provider.js';
+/**
+ * Re-export of {@link NameBasedKeyProvider} under the conventional
+ * "default" name — the framework's default key strategy. Aliased
+ * rather than subclassed so the editorial intent ("this IS the default")
+ * is visible at the binding line; the concrete implementation lives on
+ * {@link NameBasedKeyProvider} with its full stability documentation.
+ */
+export const DefaultElementKeyProvider = NameBasedKeyProvider;
+//# sourceMappingURL=default-element-key-provider.js.map

package/lib/langium/keys/default-element-key-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-element-key-provider.js","sourceRoot":"","sources":["../../../src/langium/keys/default-element-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,oBAAoB,CAAC"}

package/lib/langium/keys/element-key-provider.d.ts

@@ -0,0 +1,106 @@
+/********************************************************************************
+ * 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 } from '@hydranium/langium';
+/**
+ * Element-key service — produces a string **handle** that round-trips to an
+ * AST node *within a document*. Its consumer is the GLSP head, which keys its
+ * GModel index by the result so UI state (selection, focus, expansion, scroll
+ * position) survives the AST rebuilds triggered by user edits.
+ *
+ * # Why "key", not "id"
+ *
+ * A key is a lookup token, not a unique id: under the default name-based
+ * strategy it is **neither unique nor rename-stable**, and it is allowed to
+ * collide — collisions are resolved by the consumer's index, in
+ * `HydraniumGlspIndex`'s duplicate-prune. The honest mental model is a *node
+ * locator*, scoped to a single document; the positional strategy below
+ * literally IS Langium's `AstNodeLocator` path. Reserve "id" for values that
+ * are genuinely unique and stable (`Project.id`); this is not one.
+ *
+ * Distinct from `NameProvider`,
+ * which produces the user-facing names used in reference syntax, completion
+ * and search — non-unique and rename-sensitive. The two axes are separate
+ * services so an adopter can override the one it needs; the locator role is
+ * general (selection persistence, cross-session bookmarks, structural
+ * diffing), not specific to the GLSP head that consumes it.
+ *
+ * # Two ready-to-use strategies
+ *
+ * The framework ships two concrete implementations; pick at the binding line
+ * based on how the adopter's users interact with the model. Each class
+ * documents its own stability profile.
+ *
+ * 1. **`NameBasedKeyProvider`
+ *    (default)** — segments are names, so keys survive sibling reorder and
+ *    mid-array insert / delete but flip on rename. **Why it is the default:
+ *    interactive editing is the flagship use case, and reorder/insert/delete
+ *    dominate that workload.** Forward-only — its inverse needs a subtree
+ *    scan (see {@link resolveElement}).
+ *
+ * 2. **`PositionalKeyProvider`** —
+ *    segments are positions, so keys are unique within the document,
+ *    self-resolving and rename-stable, but flip whenever a `$containerIndex`
+ *    shifts.
+ *
+ * # Other strategies adopters can plug in
+ *
+ * 1. **Source-persisted UUIDs** — extend the grammar with a hidden id
+ *    field per node, generate fresh UUIDs in create-handlers, preserve
+ *    them through serialisation. Truly stable across all mutations
+ *    including renames; supports cross-session bookmarks. Cost: source
+ *    files carry visible bookkeeping ids; serializer must round-trip
+ *    them; create-handlers must generate them.
+ *
+ * 2. **Cross-rebuild heuristic matcher** — allocate opaque keys on first
+ *    indexing; on rebuild, diff old vs new AST and preserve keys for
+ *    structurally-matched node pairs. Best-effort full stability with
+ *    no source-file impact. Substantial implementation.
+ *
+ * Adopters select a strategy by binding `references.ElementKeyProvider` in
+ * their language module.
+ */
+export interface ElementKeyProvider {
+    /**
+     * The key for `node` within its document, or `undefined` for `undefined`
+     * input and for a node the strategy cannot key.
+     */
+    getElementKey(node?: AstNode): string | undefined;
+    /**
+     * The inverse of {@link getElementKey} within a scope: the node in
+     * `context`'s tree whose key equals `key`, or `undefined`.
+     *
+     * `context` is **any node** belonging to the tree the key was minted in —
+     * it defines the *resolution scope*, not a position. Each strategy reads it
+     * as its own uniqueness scope: the positional strategy resolves against
+     * `context`'s document root (its keys are document-absolute); the
+     * name-based strategy scans `context`'s subtree (its keys are
+     * semantic-root-relative). Pass a document's root for whole-document
+     * resolution, or a semantic root to narrow to one diagram.
+     *
+     * Keys are not guaranteed unique under the name-based default, so this is a
+     * round-trippability contract, **not** a uniqueness guarantee: when two
+     * nodes in scope share a key it returns the first (document-order) match.
+     * The conformance law — for any node `n` under a scope root `r`,
+     * `resolveElement(getElementKey(n), r) === n` — therefore holds for every
+     * node iff keys are unique within `r`, which is exactly the invariant an
+     * adopter's duplicate-name validation is responsible for.
+     */
+    resolveElement(key: string, context: AstNode): AstNode | undefined;
+}
+/**
+ * Shared default for {@link ElementKeyProvider.resolveElement}: scan the
+ * subtree rooted at `context` (including `context` itself) and return the
+ * first node whose {@link ElementKeyProvider.getElementKey} equals `key`.
+ * Used by the name-based strategy, which has no structural inverse; the
+ * positional strategy overrides with the cheaper `AstNodeLocator.getAstNode`.
+ * Scans `context`'s subtree — not the whole document — so a semantic-root
+ * `context` narrows resolution to one scope.
+ */
+export declare function resolveElementByScan(keyOf: (node: AstNode) => string | undefined, key: string, context: AstNode): AstNode | undefined;
+//# sourceMappingURL=element-key-provider.d.ts.map

package/lib/langium/keys/element-key-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-key-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/keys/element-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAY,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,WAAW,kBAAkB;IAChC;;;OAGG;IACH,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAElD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;CACrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAKrI"}

package/lib/langium/keys/element-key-provider.js

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * 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 { AstUtils } from '@hydranium/langium';
+/**
+ * Shared default for {@link ElementKeyProvider.resolveElement}: scan the
+ * subtree rooted at `context` (including `context` itself) and return the
+ * first node whose {@link ElementKeyProvider.getElementKey} equals `key`.
+ * Used by the name-based strategy, which has no structural inverse; the
+ * positional strategy overrides with the cheaper `AstNodeLocator.getAstNode`.
+ * Scans `context`'s subtree — not the whole document — so a semantic-root
+ * `context` narrows resolution to one scope.
+ */
+export function resolveElementByScan(keyOf, key, context) {
+    if (keyOf(context) === key) {
+        return context;
+    }
+    return AstUtils.streamAllContents(context).find(node => keyOf(node) === key);
+}
+//# sourceMappingURL=element-key-provider.js.map

package/lib/langium/keys/element-key-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-key-provider.js","sourceRoot":"","sources":["../../../src/langium/keys/element-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAgB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AA0F5D;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAA4C,EAAE,GAAW,EAAE,OAAgB;IAC7G,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC;IAClB,CAAC;IACD,OAAO,QAAQ,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;AAChF,CAAC"}

package/lib/langium/keys/index.d.ts

@@ -0,0 +1,13 @@
+/********************************************************************************
+ * 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 './element-key-provider.js';
+export * from './name-based-key-provider.js';
+export * from './positional-key-provider.js';
+export * from './default-element-key-provider.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/langium/keys/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/langium/keys/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC"}

package/lib/langium/keys/index.js

@@ -0,0 +1,13 @@
+/********************************************************************************
+ * 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 './element-key-provider.js';
+export * from './name-based-key-provider.js';
+export * from './positional-key-provider.js';
+export * from './default-element-key-provider.js';
+//# sourceMappingURL=index.js.map

package/lib/langium/keys/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/langium/keys/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC"}