@hydranium/core 1.0.0-next.10

package/src/langium/keys/name-based-key-provider.ts

@@ -0,0 +1,146 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { type ElementKeyProvider, resolveElementByScan } from './element-key-provider.js';
+import { type NameProvider } from '../naming/name-provider.js';
+
+/**
+ * Name-based {@link ElementKeyProvider} — walks named ancestors stopping at the
+ * semantic root, joining segments with `NameProvider.nameSeparator`.
+ *
+ * **The framework's default key strategy.** Optimised for interactive
+ * editing workloads where reorder/insert/delete are frequent and renames
+ * of intermediate ancestors are rare.
+ *
+ * # Stability profile
+ *
+ * **The bullets below hold for nodes that HAVE a name.** A node with no
+ * name — and any node below one — is keyed through
+ * {@link unidentifiedSegment}, which encodes `$containerIndex`; see the
+ * caveat below.
+ *
+ * - **Stable across sibling reorder** — segments are names, not indices,
+ *   so reordering siblings of a named node does not change its key.
+ * - **Stable across mid-array insert / delete** — same reason: indices
+ *   are not encoded.
+ * - **Stable across semantic-root rename** — the predicate excludes the
+ *   semantic root from the key by construction.
+ * - **Flips on rename of any named segment** within the walked path.
+ *
+ * # Caveat: unnamed nodes are keyed positionally
+ *
+ * {@link unidentifiedSegment} falls back to
+ * `` `${$containerProperty}@${$containerIndex}` `` for a node the
+ * `NameProvider` gives no name. For grammars with unnamed element types the
+ * reorder / insert / delete stability above does NOT apply to those nodes:
+ * their keys move when their index moves, so a mid-array insert or delete
+ * renumbers every later sibling.
+ *
+ * Two consequences for a caller creating such nodes programmatically
+ * (a GLSP operation handler is the usual case):
+ *
+ * - A node appended with a bare `array.push` has no `$containerProperty` /
+ *   `$containerIndex`, so `getElementKey` returns `undefined` and the node
+ *   has no key at all. The containment plumbing has to be stamped.
+ * - After a removal, surviving siblings need their `$containerIndex`
+ *   renumbered, or a key derived afterwards addresses the wrong node.
+ *
+ * Adopters that need insert / delete stability for unnamed types should
+ * give those types a name in the grammar, or bind a key provider whose
+ * fallback is content-derived rather than positional.
+ *
+ * Override {@link isSemanticRoot} if the grammar's root structure does not
+ * match either shape that predicate handles.
+ */
+export class NameBasedKeyProvider implements ElementKeyProvider {
+   protected readonly nameProvider: NameProvider;
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerLanguageServices,
+      options: LogNameOptions = {}
+   ) {
+      this.nameProvider = services.references.NameProvider;
+      this.tracer = services.shared.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   getElementKey(node?: AstNode): string | undefined {
+      if (!node) {
+         return undefined;
+      }
+      let id = this.nameProvider.getOwnName(node) ?? this.unidentifiedSegment(node);
+      if (!id) {
+         return undefined;
+      }
+      if (this.isSemanticRoot(node)) {
+         return id;
+      }
+      const separator = this.nameProvider.nameSeparator;
+      let parent = node.$container;
+      while (parent && !this.isSemanticRoot(parent)) {
+         const segment = this.nameProvider.getOwnName(parent) ?? this.unidentifiedSegment(parent);
+         if (segment) {
+            id = segment + separator + id;
+         }
+         parent = parent.$container;
+      }
+      return id;
+   }
+
+   /**
+    * No structural inverse — keys are name-paths, not addressable locations —
+    * so resolve by scanning `context`'s subtree for the first node whose key
+    * matches. O(subtree); the GLSP index keeps its own key-to-node map, so
+    * this is the canonical / testable inverse rather than a hot path. See
+    * {@link ElementKeyProvider.resolveElement} for the scope and uniqueness
+    * contract.
+    */
+   resolveElement(key: string, context: AstNode): AstNode | undefined {
+      return resolveElementByScan(node => this.getElementKey(node), key, context);
+   }
+
+   /**
+    * Semantic-root predicate. Default implementation matches two common
+    * grammar shapes; override for non-standard structures:
+    *
+    * - **Document root with no container**: the root itself is the
+    *   semantic root iff it has a name (covers unwrapped grammars whose
+    *   named root element IS the semantic root).
+    * - **Direct child of an unnamed wrapper**: the child is the semantic
+    *   root (covers wrapper grammars with an unnamed root node).
+    *
+    * A node more than one container below the document root is never a
+    * semantic root in the default heuristic.
+    */
+   protected isSemanticRoot(node: AstNode): boolean {
+      if (!node.$container) {
+         return this.nameProvider.hasName(node);
+      }
+      if (!node.$container.$container) {
+         return !this.nameProvider.hasName(node.$container);
+      }
+      return false;
+   }
+
+   /**
+    * Fallback segment for unnamed intermediate ancestors —
+    * `containerProperty@containerIndex`. Returns `undefined` when the
+    * node has no container position, which short-circuits the walk.
+    */
+   protected unidentifiedSegment(node: AstNode): string | undefined {
+      if (node.$containerProperty === undefined || node.$containerIndex === undefined) {
+         return undefined;
+      }
+      return `${node.$containerProperty}@${node.$containerIndex}`;
+   }
+}

package/src/langium/keys/positional-key-provider.ts

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { type AstNode, AstUtils } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { type ElementKeyProvider } from './element-key-provider.js';
+
+/**
+ * Positional {@link ElementKeyProvider} — delegates to Langium's
+ * `AstNodeLocator.getAstNodePath` for a path like
+ * `/elements@0/children@2`.
+ *
+ * Use when the adopter is read-only / LSP-only with no diagram editor,
+ * or when sibling order is semantically meaningful and reorder is rare.
+ *
+ * # Stability profile
+ *
+ * - **Stable across all renames** — no names appear in the path.
+ * - **Always unique within a document** — positional segments are
+ *   unique by AST construction.
+ * - **Flips on sibling reorder / mid-array insert / mid-array delete**.
+ */
+export class PositionalKeyProvider implements ElementKeyProvider {
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: HydraniumLanguageServices,
+      options: LogNameOptions = {}
+   ) {
+      this.tracer = services.shared.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   getElementKey(node?: AstNode): string | undefined {
+      if (!node) {
+         return undefined;
+      }
+      return this.services.workspace.AstNodeLocator.getAstNodePath(node);
+   }
+
+   /**
+    * Self-resolving: `getAstNodePath` is invertible via `getAstNode`. The
+    * path is document-absolute, so `context` only identifies the document —
+    * resolution runs from its root regardless of where `context` sits.
+    */
+   resolveElement(key: string, context: AstNode): AstNode | undefined {
+      const root = AstUtils.findRootNode(context);
+      return this.services.workspace.AstNodeLocator.getAstNode(root, key);
+   }
+}

package/src/langium/labeling/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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 './label-provider.js';

package/src/langium/labeling/label-provider.ts

@@ -0,0 +1,110 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { type NameProvider } from '../naming/name-provider.js';
+
+/** Construction-time options for {@link DefaultLabelProvider}. */
+export interface LabelProviderOptions extends LogNameOptions {
+   /**
+    * Property names checked, in order, when reading a node's own label.
+    * Default `['name']` — matches the common case where the grammar's
+    * `name` property is the human-readable label. Adopters whose grammar
+    * carries the display string on a different property override here;
+    * the property is deliberately separate from the
+    * {@link NameProvider}'s `nameProperties` (identifier axis).
+    */
+   readonly labelProperties?: readonly string[];
+}
+
+/**
+ * Labeling service — **the UI axis**, sibling to {@link NameProvider}.
+ *
+ * `NameProvider` answers "what identifier does the language engine index /
+ * resolve this node by" (read from `nameProperties`); `LabelProvider` answers
+ * "what string do we show a human for this node" (read from
+ * `labelProperties`). For the common adopter the two coincide (`['name']`),
+ * but they are genuinely distinct concerns — an adopter might resolve by an
+ * `id` field yet label by `name` — so the framework keeps them on separate
+ * services. Folding labeling back into `NameProvider` would mean a method that
+ * bypasses `nameProperties`, which is the thing that makes the identifier axis
+ * predictable.
+ *
+ * Depends one-way on {@link NameProvider}: {@link getLabelOrName} falls back
+ * to the identifier when no label exists, which is the only method that
+ * reaches across the two axes.
+ *
+ * **No total method on purpose.** "Produce a non-empty string come what may"
+ * is a per-call-site presentation decision, so both methods may return
+ * `undefined` and every caller owns its own tail `??`.
+ */
+export interface LabelProvider {
+   /**
+    * The node's own label from {@link LabelProviderOptions.labelProperties},
+    * or `undefined` when none is present (or for `undefined` input). The
+    * primitive — callers compose their own fallback.
+    */
+   getLabel(node?: AstNode): string | undefined;
+
+   /** Predicate form of {@link getLabel}. */
+   hasLabel(node?: AstNode): boolean;
+
+   /**
+    * The label, falling back to the identifier when no label exists:
+    * `getLabel(node) ?? NameProvider.getOwnName(node)`. May still be
+    * `undefined` (a fully anonymous node) — the caller supplies the final
+    * placeholder. The one method that bridges the label and name axes, so a UI
+    * site need inject only this service.
+    */
+   getLabelOrName(node?: AstNode): string | undefined;
+}
+
+/**
+ * Default {@link LabelProvider}. Reads a node's label from the configured
+ * {@link LabelProviderOptions.labelProperties} (default `['name']`).
+ */
+export class DefaultLabelProvider implements LabelProvider {
+   protected readonly labelProperties: readonly string[];
+   protected readonly nameProvider: NameProvider;
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: HydraniumLanguageServices,
+      options: LabelProviderOptions = {}
+   ) {
+      this.labelProperties = options.labelProperties ?? ['name'];
+      this.nameProvider = services.references.NameProvider;
+      this.tracer = services.shared.Tracer.for(options.logName ?? 'LabelProvider').trace('instantiated');
+   }
+
+   getLabel(node?: AstNode): string | undefined {
+      if (!node) {
+         return undefined;
+      }
+      const indexed = node as unknown as Record<string, unknown>;
+      for (const property of this.labelProperties) {
+         const value = indexed[property];
+         if (typeof value === 'string') {
+            return value;
+         }
+      }
+      return undefined;
+   }
+
+   hasLabel(node?: AstNode): boolean {
+      return this.getLabel(node) !== undefined;
+   }
+
+   getLabelOrName(node?: AstNode): string | undefined {
+      return this.getLabel(node) ?? this.nameProvider.getOwnName(node);
+   }
+}