@hydranium/core 1.0.0-next.38 → 1.0.0-next.381

package/src/langium/scope/reference-candidate-provider.ts

@@ -102,9 +102,9 @@ export interface ResolvedCandidate {
 export interface ReferenceCandidateProvider {
    /**
     * UI-facing entry point: returns the candidate scope's elements as
-    * {@link ReferenceCandidate}s.
+    * {@link ReferenceCandidate}s. Accepts what {@link getCandidateScope} does.
     */
-   find(ctx: ReferenceContext): ReferenceCandidate[];
+   find(ctx: ReferenceContext | ReferenceInfo): ReferenceCandidate[];
 
    /**
     * Build a ranked + deduped scope for candidate selection at the
@@ -195,14 +195,15 @@ export class DefaultReferenceCandidateProvider implements ReferenceCandidateProv
     * and never matches: a self-reference filter silently stops excluding, and
     * the element offers itself as its own target.
     *
-    * The mirror of `ReferenceBuilder.nameProviderFor`, and the same fallback
-    * reasoning: an unroutable target has no better answer than the source's.
+    * The mirror of `DefaultReferenceBuilder.nameProviderFor`, and the same
+    * fallback reasoning: an unroutable target has no better answer than the
+    * source's.
     */
    protected nameProviderFor(target: AstNode): NameProvider {
       return this.services.shared.ServiceRegistry?.getServicesFor(target)?.references.NameProvider ?? this.nameProvider;
    }
 
-   find(ctx: ReferenceContext): ReferenceCandidate[] {
+   find(ctx: ReferenceContext | ReferenceInfo): ReferenceCandidate[] {
       const scope = this.getCandidateScope(ctx);
       return scope.elementScope
          .getAllElements()

package/src/langium/scope/scope-extension-service.ts

@@ -7,9 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type AstNode, AstUtils, type LangiumDocument, MapScope, type Scope, StreamScope, stream } from '@hydranium/langium';
+import { type AstNode, AstUtils, DocumentCache, DocumentState, type LangiumDocument } from '@hydranium/langium';
 import { type Disposable } from 'vscode-languageserver';
-import { type Tracer } from '@hydranium/protocol';
+import { Format, Logger, type ProfileRecord, type ProfileSession, type Tracer } from '@hydranium/protocol';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerLanguageServices } from '../language-module.js';
 import { Registry, type RegistryItem } from '../../util/registry.js';
@@ -49,8 +49,7 @@ export interface ScopeDescriptionAcceptor {
     * descriptions are constructed ahead of time, to avoid per-query
     * allocation. The pushed description's `tier` must be `'local'` or
     * `'universal'`; a description of any other tier is silently dropped,
-    * because the per-tier query methods only return descriptions matching
-    * the tier they were asked for.
+    * because {@link ScopeExtensionDescriptions} holds only those two.
     */
    push(description: TieredAstNodeDescription): void;
 }
@@ -85,40 +84,51 @@ export interface ScopeExtension extends RegistryItem {
     * build the data up-front and hand a sync acceptor here.
     */
    addDescriptions(context: AstNode, referenceType: string, document: LangiumDocument, accept: ScopeDescriptionAcceptor): void;
+   /**
+    * The node the descriptions for `context` belong to, so that while the
+    * referencing document is being linked, they, and the scope made of them,
+    * are built once per node rather than once per reference: a reference with
+    * the same node is answered with the first one's descriptions. Without it, for
+    * `undefined`, outside a link, such as a completion request, or for a
+    * `context` outside a built document, such as an operation's copy,
+    * {@link addDescriptions} runs for every reference.
+    *
+    * The descriptions must depend on the node and `referenceType` alone. What
+    * they read through the node may come from another document: each link
+    * builds them afresh. A change made during one link, in place, is not seen
+    * until the next.
+    */
+   cacheKey?(context: AstNode, referenceType: string): AstNode | undefined;
+}
+
+/** One scope extension's descriptions for a reference, split by tier. */
+export interface ScopeExtensionDescriptions {
+   readonly local: readonly TieredAstNodeDescription[];
+   readonly universal: readonly TieredAstNodeDescription[];
 }
 
 /**
  * Public contract for the per-language scope-extension service. Extends
  * the {@link ScopeExtensionRegistry} (the imperative `register` surface
- * contributions use) with the per-tier query methods called cross-class
- * from `HydraniumScopeProvider`'s `layerLocalExtension` /
- * `layerUniversalExtension` helpers, which layer scope-extension
- * contributions around the cached project chain.
- *
- * Adopter overrides go through {@link DefaultScopeExtensionService}; the
- * interface keeps the public API stable while internals
- * (`collectExtensionDescriptions` walk) stay `protected` on the default
- * class.
+ * contributions use) with the query `HydraniumScopeProvider` builds its
+ * extension tiers from.
  */
 export interface ScopeExtensionService extends ScopeExtensionRegistry {
    /**
-    * Layer this language's `local`-tier scope-extension descriptions on
-    * top of `outerScope` for the given reference type. Returns
-    * `outerScope` unchanged when no extension contributes a `local`-tier
-    * description for the type (zero-cost common path).
-    */
-   getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
-   /**
-    * Layer this language's `universal`-tier scope-extension descriptions
-    * BELOW `outerScope` for the given reference type. Returns `outerScope`
-    * unchanged when no extension contributes a `universal`-tier
-    * description for the type.
+    * The descriptions of each extension registered for `referenceType` that
+    * contributes to `context`, in registration order. An extension's entry is
+    * the same object for every reference of one {@link ScopeExtension.cacheKey},
+    * so a caller can key what it builds of it by identity. A caller that needs
+    * both tiers takes them from one call: a call per tier runs every extension
+    * twice.
     */
-   getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
+   getDescriptions(referenceType: string, context: AstNode): readonly ScopeExtensionDescriptions[];
 }
 
 export type ScopeExtensionServiceOptions = LogNameOptions;
 
+const NO_DESCRIPTIONS: readonly ScopeExtensionDescriptions[] = [];
+
 /**
  * Default {@link ScopeExtensionService} implementation. Per-language
  * registry for dynamic scope contributions: extra resolvable descriptions
@@ -128,13 +138,26 @@ export type ScopeExtensionServiceOptions = LogNameOptions;
  * separate from the query-time scope-resolution concern (which only reads).
  *
  * Lives in the per-language `references` group alongside `ScopeProvider`,
- * which consumes the per-tier query methods ({@link getLocalExtensionScope}
- * / {@link getUniversalExtensionScope}). Designed as a base class; adopters
+ * which consumes {@link getDescriptions}. Designed as a base class; adopters
  * extend it and call `register` in their constructor.
+ *
+ * At `debug`, each extension's calls and self-time go into one profile
+ * session, reported when a build starts and when it ends. A report thus
+ * covers one build, validation included, or the calls made between two
+ * builds, such as a reference picker's.
  */
 export class DefaultScopeExtensionService implements ScopeExtensionService {
    protected readonly scopeExtensions = new Registry<ScopeExtension>();
    protected readonly tracer: Tracer;
+   /** Open from the first profiled call until {@link reportProfile}. */
+   protected profileSession?: ProfileSession;
+   /**
+    * Per referencing document, key node, extension and reference type, the
+    * descriptions answered during that document's link, dropped when it ends,
+    * when a build starts and right before its link. Absent without a document
+    * builder, which leaves every extension uncached.
+    */
+   protected readonly kept?: DocumentCache<AstNode, Map<ScopeExtension, Map<string, ScopeExtensionDescriptions>>>;
 
    constructor(
       protected readonly services: ServerLanguageServices,
@@ -150,6 +173,16 @@ export class DefaultScopeExtensionService implements ScopeExtensionService {
       for (const contribution of Object.values(contributions)) {
          contribution.registerScopeExtensions(this);
       }
+      // Optional for the same reason: a stub tree may carry no builder.
+      const builder = services.shared.workspace.DocumentBuilder;
+      builder?.onUpdate(() => this.reportProfile());
+      builder?.onBuildEnded(() => this.reportProfile());
+      // Dropped once the document is linked, and all of it when a build starts and
+      // again right before its link, so neither a lookup made after the build starts
+      // nor a link a cancelled build left unfinished answers this link.
+      this.kept = builder ? new DocumentCache(services.shared, DocumentState.Linked) : undefined;
+      builder?.onUpdate(() => this.kept?.clear());
+      builder?.onBuildPhase(DocumentState.ComputedScopes, () => this.kept?.clear());
    }
 
    /**
@@ -162,46 +195,105 @@ export class DefaultScopeExtensionService implements ScopeExtensionService {
       return this.scopeExtensions.register(extension);
    }
 
-   getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope {
-      const local = this.collectExtensionDescriptions(referenceType, context, 'local');
-      if (local.length === 0) {
-         return outerScope;
+   /**
+    * Holds the profile wrap, which an override would have to copy; to change
+    * which extensions run, override {@link extensionsFor}.
+    */
+   getDescriptions(referenceType: string, context: AstNode): readonly ScopeExtensionDescriptions[] {
+      const extensionsForType = this.extensionsFor(referenceType, context);
+      if (extensionsForType.length === 0) {
+         return NO_DESCRIPTIONS;
       }
-      return new StreamScope(stream(local), outerScope);
+      const document = AstUtils.getDocument(context);
+      // Only while the document is being linked: nothing tells a cache that a relink is about to start.
+      const linking = document.state < DocumentState.Linked && AstUtils.findRootNode(context) === document.parseResult.value;
+      const answered: ScopeExtensionDescriptions[] = [];
+      for (const extension of extensionsForType) {
+         const node = linking ? extension.cacheKey?.(context, referenceType) : undefined;
+         const descriptions = node
+            ? this.keptDescriptions(document, node, extension, referenceType, () =>
+                 this.runExtension(extension, referenceType, context, document)
+              )
+            : this.runExtension(extension, referenceType, context, document);
+         if (descriptions.local.length > 0 || descriptions.universal.length > 0) {
+            answered.push(descriptions);
+         }
+      }
+      return answered;
    }
 
-   getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope {
-      const universal = this.collectExtensionDescriptions(referenceType, context, 'universal');
-      if (universal.length === 0) {
-         return outerScope;
+   /** The descriptions kept for `node` in `document`, built through `build` when there are none. */
+   protected keptDescriptions(
+      document: LangiumDocument,
+      node: AstNode,
+      extension: ScopeExtension,
+      referenceType: string,
+      build: () => ScopeExtensionDescriptions
+   ): ScopeExtensionDescriptions {
+      const byExtension = this.kept?.get(document.uri, node, () => new Map());
+      if (byExtension === undefined) {
+         return build();
       }
-      return new StreamScope(outerScope.getAllElements(), new MapScope(universal));
+      let byType = byExtension.get(extension);
+      if (byType === undefined) {
+         byType = new Map();
+         byExtension.set(extension, byType);
+      }
+      let descriptions = byType.get(referenceType);
+      if (descriptions === undefined) {
+         descriptions = build();
+         byType.set(referenceType, descriptions);
+      }
+      return descriptions;
    }
 
-   /**
-    * Walk this language's registered scope extensions matching
-    * `referenceType` and collect descriptions of the requested `tier`.
-    * `push`-ed descriptions of other tiers are silently dropped here —
-    * the per-tier query methods only return descriptions matching their
-    * tier. (`local` and `universal` are the only acceptor entry points;
-    * `push` is the escape hatch for pre-built descriptions and is the
-    * only path that could carry other tiers.)
-    */
-   protected collectExtensionDescriptions(
+   /** Run `extension` against `context`, inside the profile session at `debug`. */
+   protected runExtension(
+      extension: ScopeExtension,
       referenceType: string,
       context: AstNode,
-      tier: 'local' | 'universal'
-   ): TieredAstNodeDescription[] {
-      const extensionsForType = this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
-      if (extensionsForType.length === 0) {
-         return [];
-      }
-      const document = AstUtils.getDocument(context);
+      document: LangiumDocument
+   ): ScopeExtensionDescriptions {
       const collected: TieredAstNodeDescription[] = [];
       const accept = createScopeDescriptionAcceptor(collected, this.services.workspace.AstNodeDescriptionProvider);
-      for (const extension of extensionsForType) {
+      const session = Logger.isLevelEnabled('debug') ? (this.profileSession ??= this.tracer.profile('scope-extension')) : undefined;
+      if (session) {
+         session.scope(extension.id, () => extension.addDescriptions(context, referenceType, document, accept));
+      } else {
          extension.addDescriptions(context, referenceType, document, accept);
       }
-      return collected.filter(description => description.tier === tier);
+      return {
+         local: collected.filter(description => description.tier === 'local'),
+         universal: collected.filter(description => description.tier === 'universal')
+      };
+   }
+
+   /** The extensions that run for one reference: by default, those registered for `referenceType`. */
+   protected extensionsFor(referenceType: string, _context: AstNode): ScopeExtension[] {
+      return this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+   }
+
+   /**
+    * Report the profile session, if one is open, and start the next one fresh:
+    * one line per extension, its calls and self-time. Not a share of the
+    * session's time, which runs from the first call to the report and so takes
+    * in whatever happened between the calls.
+    */
+   protected reportProfile(): void {
+      const session = this.profileSession;
+      this.profileSession = undefined;
+      for (const record of session?.records() ?? []) {
+         this.tracer.debug(this.formatProfileRecord(record));
+      }
+   }
+
+   /**
+    * The log line of one extension's {@link reportProfile} entry. It names the
+    * language: each has its own session, and an extension id is unique only
+    * within its language.
+    */
+   protected formatProfileRecord(record: ProfileRecord): string {
+      const language = this.services.LanguageMetaData.languageId;
+      return `[profile scope-extension ${language}] ${record.id} ×${record.count} ${Format.elapsed(record.selfMs)}`;
    }
 }

package/src/langium/scope/scoped-ast-node-description.ts

@@ -157,9 +157,7 @@ export function isUniversalTier(description: AstNodeDescription): description is
  * URI's project, the public-tier sibling belonging to that
  * same project is redundant (the project-tier sibling under a shorter
  * name is already in scope) and should be hidden from completion /
- * linking. The framework's
- * `HydraniumScopeProvider.bucketFor` uses this
- * predicate to enforce the own-project canonical filter on the typed scope path.
+ * linking.
  *
  * `projectId` accepts `string | undefined` for adopter-call-site
  * ergonomics: when the source has no resolvable project (standalone

package/src/langium/serialization/abstract-serializer.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { isPromiseLike, type MaybePromise, type Tracer, type TransferElement } from '@hydranium/protocol';
+import { type MaybePromise, type Tracer, type TransferElement } from '@hydranium/protocol';
 import { type AstNode, type AstReflection, type GenericAstNode, isAstNode } from '@hydranium/langium';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumLanguageServices } from '../language-module.js';
@@ -66,16 +66,6 @@ export interface AbstractSerializerOptions extends LogNameOptions {
     * the extra property carries a value.
     */
    readonly referenceWrapperTypes?: ReadonlyMap<string, string>;
-   /**
-    * Whether {@link AbstractSerializer.serializeAst} trims trailing whitespace
-    * from the final output (leading whitespace is always trimmed). Defaults to
-    * `true` — the conventional "no trailing blank lines" document shape. Set to
-    * `false` for grammars whose values may legitimately END the document with
-    * blank lines that must survive a round-trip — e.g. a multi-line block-scalar
-    * property (see `YamlSerializerOptions.blockScalarProperties`),
-    * where a trailing-trim would silently eat user-typed blank lines.
-    */
-   readonly trimTrailingWhitespace?: boolean;
 }
 
 /**
@@ -110,8 +100,11 @@ export interface AbstractSerializerOptions extends LogNameOptions {
  * **Extension points** (override in a subclass):
  * - {@link serializeReferenceText} — extract the textual form of a
  *   cross-reference; defaults to the value's `$refText`.
+ * - {@link formatString} — quote a string, as a primitive or a reference, for
+ *   the grammar's string terminal; the one override for a grammar whose
+ *   terminal or value converter differs from Langium's default.
  * - {@link formatReferenceValue} — format a cross-reference value for emission;
- *   defaults to `JSON.stringify`.
+ *   defaults to {@link formatString}.
  * - {@link serializeCustomValue} — type-specific serialization for values
  *   that don't fit the generic paths. Runs after all reference detection, so
  *   references never reach this hook. Returns `undefined` to fall through to
@@ -124,6 +117,25 @@ export abstract class AbstractSerializer<
    TAst extends AstNode = AstNode,
    TTransfer extends TransferElement = TransferElement
 > implements Serializer<TAst, TTransfer> {
+   /**
+    * The escapes {@link formatString} writes, read through the subclass, so a
+    * grammar adding one overrides this table alone. Langium's
+    * `ValueConverter.convertString` decodes the short escapes here and reads
+    * any other escaped character as itself, which is how `\\` and `\"` read
+    * back, and why a `\u` escape would read back as `u`.
+    */
+   protected static readonly STRING_ESCAPES: ReadonlyMap<string, string> = new Map([
+      ['\\', '\\\\'],
+      ['"', '\\"'],
+      ['\b', '\\b'],
+      ['\f', '\\f'],
+      ['\n', '\\n'],
+      ['\r', '\\r'],
+      ['\t', '\\t'],
+      ['\v', '\\v'],
+      ['\0', '\\0']
+   ]);
+
    protected readonly reflection: AstReflection;
    protected readonly tracer: Tracer;
 
@@ -139,29 +151,20 @@ export abstract class AbstractSerializer<
     * Entry point for AST-shape inputs. Typically the grammar root, but any
     * AST node works — the walker is recursive and shape-agnostic.
     *
-    * Preserves the sync fast path: when every subclass override and every
-    * adopter hook is sync, the return is a bare `string` (no Promise
-    * allocation, no microtask). The async branch fires only if at least one
-    * recursive `serializeNode` call resolved to a Promise.
+    * **Emits the model and nothing else — do not trim here.** Trailing
+    * whitespace belongs to the author, and a write path holding the prior
+    * document restores it from there; trimming at this end deletes it before
+    * that restore sees it. A serializer has no prior document to consult, so it
+    * cannot tell a deliberate blank line from an accidental one.
+    *
+    * **Nothing trims what a subclass emits**, at either end. Emitting leading
+    * whitespace therefore puts it in the file, where no write path removes it.
+    *
+    * Returns whatever `serializeNode` returns, so a fully sync subclass keeps a
+    * bare `string` with no promise allocation.
     */
    serializeAst(model: TAst): MaybePromise<string> {
-      const result = this.serializeNode(model, 0);
-      if (isPromiseLike(result)) {
-         return result.then(text => this.trimSerialized(text));
-      }
-      return this.trimSerialized(result);
-   }
-
-   /**
-    * Trim the final serialized output. Leading whitespace is always removed;
-    * trailing whitespace is removed unless {@link AbstractSerializerOptions.trimTrailingWhitespace}
-    * is `false` (which preserves document-ending blank lines, e.g. inside a block scalar).
-    */
-   protected trimSerialized(text: string | undefined): string {
-      if (text === undefined) {
-         return '';
-      }
-      return this.options.trimTrailingWhitespace === false ? text.trimStart() : text.trim();
+      return this.serializeNode(model, 0);
    }
 
    /**
@@ -426,29 +429,42 @@ export abstract class AbstractSerializer<
    }
 
    /**
-    * Format a cross-reference value for emission. Defaults to `JSON.stringify`.
-    * Override to apply language-specific reference quoting — e.g. an
-    * id-reference formatter that mirrors the grammar's id convention.
+    * Format a cross-reference value for emission. Defaults to
+    * {@link formatString}. Override to apply language-specific reference
+    * quoting — e.g. an id-reference formatter that mirrors the grammar's id
+    * convention.
     *
     * Returns {@link MaybePromise} so adopters with async formatting needs
     * (remote schema lookup, external canonical-id resolution) can return a
     * `Promise<string>`. Sync overrides remain valid.
     */
    protected formatReferenceValue(value: string): MaybePromise<string> {
-      return JSON.stringify(value);
+      return this.formatString(value);
    }
 
    /**
-    * Format a primitive value (string, number, boolean) for emission. Defaults
-    * to `JSON.stringify`, which quotes strings, formats numbers/booleans, and
-    * is valid both as a YAML scalar and a JSON value.
+    * Format a primitive value (string, number, boolean) for emission. A string
+    * goes through {@link formatString}, any other value through
+    * `JSON.stringify`.
     *
     * Returns {@link MaybePromise} so adopters with async formatting needs
     * (e.g. delegating to `prettier.format` for a specific value class) can
     * return a `Promise<string>`.
     */
    protected formatPrimitive(value: unknown): MaybePromise<string> {
-      return JSON.stringify(value);
+      return typeof value === 'string' ? this.formatString(value) : JSON.stringify(value);
+   }
+
+   /**
+    * Quote a string, as a primitive or a reference, for its reader: the
+    * grammar's string terminal and value converter. Defaults to the inverse of
+    * Langium's default `STRING` terminal and converter: double quotes, `\` and
+    * `"` escaped, the converter's short escapes, every other character as it
+    * is. A grammar with another terminal or converter overrides this.
+    */
+   protected formatString(value: string): string {
+      const escapes = (this.constructor as typeof AbstractSerializer).STRING_ESCAPES;
+      return `"${Array.from(value, char => escapes.get(char) ?? char).join('')}"`;
    }
 
    /**

package/src/langium/serialization/json-serializer.ts

@@ -224,13 +224,24 @@ export class JsonSerializer<TAst extends AstNode = AstNode, TTransfer extends Tr
     * encodings.
     */
    protected override formatReferenceValue(value: string): MaybePromise<string> {
+      const quoted = this.formatString(value);
       if (this.referenceEncoding === 'string') {
-         return JSON.stringify(value);
+         return quoted;
       }
       if (this.compact) {
-         return `{${JSON.stringify('$ref')}:${JSON.stringify(value)}}`;
+         return `{${JSON.stringify('$ref')}:${quoted}}`;
       }
-      return `{ ${JSON.stringify('$ref')}: ${JSON.stringify(value)} }`;
+      return `{ ${JSON.stringify('$ref')}: ${quoted} }`;
+   }
+
+   /**
+    * `JSON.stringify`, so the output stays valid JSON for other tools. The
+    * grammar reading it back needs a terminal and value converter that decode
+    * the `\u` escape JSON writes for a control character without a short
+    * escape; Langium's default converter reads `\u0001` as `u0001`.
+    */
+   protected override formatString(value: string): string {
+      return JSON.stringify(value);
    }
 
    protected composeObject(entries: readonly (readonly [string, string])[], indentationLevel: number): string {

package/src/langium/serialization/serializer.ts

@@ -34,7 +34,7 @@ import type { AstNode } from '@hydranium/langium';
  * Neither method requires the input to be the grammar root — the walker is
  * recursive and shape-agnostic, so any element from either tree serializes
  * correctly. Callers typically pass a root (that's what
- * `ModelService.serialize`
+ * `DefaultModelService.serialize`
  * and the GLSP source-model flows hand in), but sub-tree serialization works
  * for unit tests, snippet rendering, and tooling.
  */

package/src/langium/serialization/yaml-serializer.ts

@@ -87,6 +87,10 @@ export interface YamlSerializerOptions extends AbstractSerializerOptions {
  * points. YAML's one addition is unquoted-terminal emission, handled by its
  * {@link serializeCustomValue} override driven by
  * {@link YamlSerializerOptions.unquotedProperties}.
+ *
+ * The grammar, not a YAML parser, reads its quoted strings back, so a control
+ * character without a short escape is written raw, which a strict YAML parser
+ * such as js-yaml refuses.
  */
 export class YamlSerializer<TAst extends AstNode = AstNode, TTransfer extends TransferElement = TransferElement> extends AbstractSerializer<
    TAst,
@@ -114,6 +118,9 @@ export class YamlSerializer<TAst extends AstNode = AstNode, TTransfer extends Tr
       this.newlineChar = options.newlineChar ?? YamlSerializer.DEFAULT_NEWLINE_CHAR;
       this.indentationChar = options.indentationChar ?? YamlSerializer.DEFAULT_INDENTATION_CHAR;
       this.indentationAmount = options.indentationAmount ?? YamlSerializer.DEFAULT_INDENTATION_AMOUNT;
+      if (!Number.isInteger(this.indentationAmount) || this.indentationAmount < 1) {
+         throw new Error(`[hydranium] YamlSerializer indentationAmount must be a positive integer, got ${this.indentationAmount}.`);
+      }
       this.typeSpecificKeywords = options.typeSpecificKeywords ?? YamlSerializer.DEFAULT_TYPE_SPECIFIC_KEYWORDS;
    }
 
@@ -258,11 +265,11 @@ export class YamlSerializer<TAst extends AstNode = AstNode, TTransfer extends Tr
          if (isPromiseLike(maybe)) {
             const resumeAt = i + 1;
             return maybe.then(formatted => {
-               lines.push(this.indent(`  - ${formatted}`, indentationLevel - 1));
+               lines.push(this.arrayItemLine(formatted, indentationLevel));
                return this.collectReferenceArrayLines(items, indentationLevel, lines, resumeAt);
             });
          }
-         lines.push(this.indent(`  - ${maybe}`, indentationLevel - 1));
+         lines.push(this.arrayItemLine(maybe, indentationLevel));
       }
       return lines.join(this.newlineChar);
    }
@@ -286,7 +293,7 @@ export class YamlSerializer<TAst extends AstNode = AstNode, TTransfer extends Tr
          if (item === undefined) {
             continue;
          }
-         const maybe = this.serializePropertyValue(nodeType, key, item, indentationLevel, /* isArrayElement */ true);
+         const maybe = this.serializePropertyValue(nodeType, key, item, this.arrayItemLevel(indentationLevel), /* isArrayElement */ true);
          if (isPromiseLike(maybe)) {
             const resumeAt = i + 1;
             return maybe.then(serialized => {
@@ -303,7 +310,22 @@ export class YamlSerializer<TAst extends AstNode = AstNode, TTransfer extends Tr
       if (serialized === undefined) {
          return;
       }
-      lines.push(this.indent(`  - ${serialized}`, indentationLevel - 1));
+      lines.push(this.arrayItemLine(serialized, indentationLevel));
+   }
+
+   /**
+    * Level an array item's properties sit at: the first level at least four columns
+    * right of the array's key, so `- ` fits under the key and every property of the
+    * item starts at one column. Columns count {@link indentationChar} as one.
+    */
+   protected arrayItemLevel(indentationLevel: number): number {
+      return indentationLevel - 1 + Math.ceil(4 / this.indentationAmount);
+   }
+
+   /** Prefix an array item with `- `, placed so the item's content starts at {@link arrayItemLevel}. */
+   protected arrayItemLine(text: string, indentationLevel: number): string {
+      const column = this.arrayItemLevel(indentationLevel) * this.indentationAmount - '- '.length;
+      return `${this.indentationChar.repeat(column)}- ${text}`;
    }
 
    /**

package/src/langium/service-registry.ts

@@ -209,6 +209,19 @@ export class ExtendedServiceRegistry<
       return super.getServices(arg);
    }
 
+   /**
+    * Every registered language's services, typed as `TServices` like the
+    * lookups here rather than as Langium's base shape, so a sweep of the whole
+    * set reaches what a URI or a typed handle would have given it.
+    *
+    * The cast is sound because {@link register} is the only way a language
+    * enters and takes `TServices`; the inherited accessor is typed to Langium's
+    * base, which is the only reason one is needed.
+    */
+   override get all(): readonly TServices[] {
+      return super.all as readonly TServices[];
+   }
+
    /**
     * Lookup by anything that identifies a document — an AST node (routed by
     * the document it lives in), a `URI`, or a URI string. `undefined` when the
@@ -255,9 +268,13 @@ export class ExtendedServiceRegistry<
     * inherited Langium semantics, which throws on miss). Used for
     * dynamically-routed lookups where the language id comes from
     * external input.
+    *
+    * The cast is sound because {@link register} is the only way a language
+    * enters and takes `TServices`; `languageIdMap` is inherited and typed to
+    * Langium's base, which is the only reason one is needed.
     */
-   getServicesById(languageId: string): LangiumCoreServices | undefined {
-      return this.languageIdMap.get(languageId);
+   getServicesById(languageId: string): TServices | undefined {
+      return this.languageIdMap.get(languageId) as TServices | undefined;
    }
 
    /**
@@ -299,6 +316,28 @@ export class ExtendedServiceRegistry<
       return owners.length === 1 ? owners[0] : undefined;
    }
 
+   /**
+    * The language the strongest signal given names: a declared `languageId`,
+    * then `target`'s document, then the only registered language, then the sole
+    * producer of `type`. `undefined` when none answers, which leaves the
+    * fallback to the caller, since it differs per caller.
+    *
+    * A declared id comes first because every later signal is inferred, and an
+    * inference must not override a caller that said which grammar it means.
+    */
+   getLanguageFor(hint: { readonly languageId?: string; readonly target?: LanguageTarget; readonly type?: string }): TServices | undefined {
+      const declared = hint.languageId === undefined ? undefined : this.getServicesById(hint.languageId);
+      const located = declared ?? this.getServicesFor(hint.target);
+      if (located) {
+         return located;
+      }
+      const all = this.all;
+      if (all.length === 1) {
+         return all[0];
+      }
+      return hint.type === undefined ? undefined : this.soleServicesByType(hint.type);
+   }
+
    /**
     * Drop the memoised type index, so a language registered after the first
     * type lookup is accounted for. The reason this index belongs on the