@hydranium/core 1.0.0-next.35 → 1.0.0-next.350

package/lib/langium/validation/document-validator.d.ts

@@ -6,15 +6,21 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer } from '@hydranium/protocol';
-import { type AstNode, type AstNodeLocator, type AstReflection, DefaultDocumentValidator, type DiagnosticInfo, type LangiumDocument, type LangiumCoreServices, type ValidateSingleNodeOptions, type ValidationOptions, type ValidationSeverity } from '@hydranium/langium';
+import { type MessageDefinition, type MessageParams, type ParamsArg, type ParamsOf, type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer } from '@hydranium/protocol';
+import { type AstNode, type AstNodeLocator, type AstReflection, DefaultDocumentValidator, type DiagnosticInfo, type LangiumDocument, type LangiumCoreServices, type Lexer, type ValidateSingleNodeOptions, type ValidationOptions, type ValidationSeverity } from '@hydranium/langium';
 import type { CancellationToken } from 'vscode-languageserver-protocol';
 import { Diagnostic } from 'vscode-languageserver-types';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 /**
- * Diagnostic read off a `LangiumDocument`: an LSP {@link Diagnostic} that MAY
- * carry the protocol-level `element` path and `property` name from
- * {@link TransferDiagnostic}.
+ * The AST-layer diagnostic: what the build left on `LangiumDocument`, and what
+ * an `AstDocument` carries. An LSP {@link Diagnostic} that MAY also carry the
+ * `element` path and `property` name from {@link TransferDiagnostic}.
+ *
+ * **Not interchangeable with {@link TransferDiagnostic}, which is the other end
+ * of the same conversion.** They disagree on field types as well as on which
+ * fields exist — `severity` is LSP's numeric enum here and a string union there
+ * — so a slot typed with the wrong one still accepts the value and then reads
+ * `undefined`, or compares equal to nothing.
  *
  * `element` is optional because a document's diagnostics do not all come from
  * this validator. {@link HydraniumDocumentValidator.toDiagnostic} always sets
@@ -29,7 +35,7 @@ import { type LogNameOptions } from '../diagnostics/logger.js';
  * condition. Consumers therefore cast at the read, and the cast is sound only
  * because this field is optional.
  */
-export interface TransferLspDiagnostic extends Diagnostic {
+export interface AstDiagnostic extends Diagnostic {
     element?: string;
     property?: string;
 }
@@ -48,7 +54,7 @@ export interface TransferLspDiagnostic extends Diagnostic {
  * `Diagnostic.code` — so without a framework identity every adopter wanting to
  * render it has to special-case Langium's shape.
  */
-export declare const UNRESOLVED_REFERENCE: import("@hydranium/protocol").MessageDefinition<"Could not resolve reference to {referenceType} named '{refText}'.">;
+export declare const UNRESOLVED_REFERENCE: MessageDefinition<"Could not resolve reference to {referenceType} named '{refText}'.">;
 /**
  * A character no token of the grammar can start with.
  *
@@ -74,7 +80,77 @@ export declare const UNRESOLVED_REFERENCE: import("@hydranium/protocol").Message
  * means: chevrotain reports how many characters the lexer discarded to recover,
  * which for a single stray character is one and for a run of them is the run.
  */
-export declare const LEXING_ERROR: import("@hydranium/protocol").MessageDefinition<"unexpected character: ->{character}<- at offset: {offset}, skipped {skipped} characters.">;
+export declare const UNEXPECTED_CHARACTER: MessageDefinition<"unexpected character: ->{character}<- at offset: {offset}, skipped {skipped} characters.">;
+/**
+ * A token the grammar does not admit at this position.
+ *
+ * **The English is byte-identical to Langium's
+ * `LangiumParserErrorMessageProvider.buildMismatchTokenMessage`, and must stay
+ * so**, on the same rule as {@link UNRESOLVED_REFERENCE}.
+ *
+ * `expected` is a token type name, which is grammar vocabulary rather than
+ * translatable text — only the frame around it is. Promoting it into the code
+ * instead would make the catalogue as large as the grammar.
+ */
+export declare const UNEXPECTED_TOKEN: MessageDefinition<"Expecting token of type '{expected}' but found `{found}`.">;
+/**
+ * Input left over once the entry rule had matched.
+ *
+ * **The English is byte-identical to Langium's
+ * `LangiumParserErrorMessageProvider.buildNotAllInputParsedMessage`, and must
+ * stay so.**
+ */
+export declare const TRAILING_INPUT: MessageDefinition<"Expecting end of file but found `{found}`.">;
+/**
+ * A mode-popping token reached with nothing on the lexer's mode stack.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultLexerErrorProvider.buildUnableToPopLexerModeMessage`, and must stay
+ * so**, the closing clause running on without punctuation exactly as upstream
+ * writes it.
+ *
+ * Reachable only from a multi-mode lexer, which a grammar opts into through a
+ * custom token builder.
+ */
+export declare const UNPOPPABLE_LEXER_MODE: MessageDefinition<"Unable to pop Lexer Mode after encountering Token ->{image}<- The Mode Stack is empty">;
+/**
+ * A dedent that lines up with no enclosing indentation level.
+ *
+ * **The English is byte-identical to LANGIUM's `IndentationAwareTokenBuilder`,
+ * and must stay so** — the one lexing sentence Langium words itself rather than
+ * relaying from chevrotain, which is why it renders through no
+ * `ILexerErrorMessageProvider` and an adopter cannot reach it by replacing one.
+ *
+ * `stack` is the indentation stack as the template literal upstream stringifies
+ * it, comma-joined: structure would have to survive {@link MessageParams}, which
+ * holds scalars, and a translation has nothing to say about the numbers anyway.
+ */
+export declare const INVALID_DEDENT: MessageDefinition<"Invalid dedent level {level} at offset: {offset}. Current indentation stack: {stack}">;
+/**
+ * A position where none of a rule's alternatives can start.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultParserErrorProvider.buildNoViableAltMessage`, and must stay so** —
+ * one layer further out than {@link UNEXPECTED_TOKEN}, because Langium overrides
+ * only two of the four parser sentences and passes this one straight through.
+ *
+ * `sequences` is the token-sequence list chevrotain generated, carried whole
+ * rather than as structure: {@link MessageParams} holds scalars, and the list is
+ * token names in any case, so only the frame around it is translatable.
+ */
+export declare const NO_VIABLE_ALTERNATIVE: MessageDefinition<"Expecting: one of these possible Token sequences:\n{sequences}\nbut found: '{found}'">;
+/**
+ * A repetition that had to match at least once and matched nothing.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultParserErrorProvider.buildEarlyExitMessage`, and must stay so**,
+ * including the doubled colon after `sequences::`, which is upstream's and not a
+ * typo to repair here — a divergence would silently stop the identity attaching.
+ *
+ * Named for the empty repetition rather than for chevrotain's `EarlyExit`, which
+ * describes its own control flow rather than the reader's problem.
+ */
+export declare const MISSING_ITERATION: MessageDefinition<"Expecting: expecting at least one iteration which starts with one of these possible Token sequences::\n  <{sequences}>\nbut found: '{found}'">;
 export interface DocumentValidatorOptions extends LogNameOptions {
     /**
      * Level at which the `validateDocument` timing line is emitted, or `'off'`
@@ -112,7 +188,7 @@ export interface DocumentValidatorOptions extends LogNameOptions {
  * - **Skip-validation hook** via the virtual {@link shouldSkipValidation}
  *   predicate, which adopters override to compose additional skip reasons.
  * - **Diagnostic mapping** to {@link TransferDiagnostic}-shaped
- *   {@link TransferLspDiagnostic}: every emitted diagnostic carries the AST
+ *   {@link AstDiagnostic}: every emitted diagnostic carries the AST
  *   node's path (built via Langium's `AstNodeLocator`) plus the optional
  *   offending property name.
  * - **Optional timing wrap** on `validateDocument`, on by default.
@@ -121,6 +197,12 @@ export declare class HydraniumDocumentValidator extends DefaultDocumentValidator
     protected readonly tracer: Tracer;
     protected readonly astNodeLocator: AstNodeLocator;
     protected readonly reflection: AstReflection;
+    protected readonly lexer: Lexer;
+    /**
+     * {@link tokenTypeNames}' answer. Nothing invalidates it: the vocabulary
+     * comes from the grammar, which is fixed once the DI tree is composed.
+     */
+    protected expectedNames?: readonly string[];
     protected readonly logLevel: ObservableValue<LogThreshold>;
     protected readonly logAfterMs: ObservableValue<number>;
     protected readonly validateVirtualDocuments: ObservableValue<boolean>;
@@ -132,26 +214,31 @@ export declare class HydraniumDocumentValidator extends DefaultDocumentValidator
     }, options?: DocumentValidatorOptions);
     validateDocument(document: LangiumDocument, options?: ValidationOptions, cancelToken?: CancellationToken): Promise<Diagnostic[]>;
     /**
-     * Langium's validation pass, plus the framework identity on the lexing
-     * diagnostics it produced.
+     * Langium's validation pass, plus the framework identity on the lexing and
+     * parsing diagnostics it produced.
+     *
+     * **Here rather than in an override of `processLexingErrors` /
+     * `processParsingErrors`, and the reason is that neither seam can see what
+     * the identity needs.** Langium hands them a `ParseResult`, which carries the
+     * AST and the error lists but not the source text — and the offending
+     * CHARACTER, or the offending TOKEN, is the parameter a translation exists to
+     * interpolate. The document does carry it, and this is the innermost point
+     * that still holds one.
      *
-     * **Here rather than in an override of `processLexingErrors`, and the reason
-     * is that the seam cannot see what the identity needs.** Langium hands that
-     * method a `ParseResult`, which carries the AST and the error lists but not
-     * the source text — and the offending CHARACTER is the parameter a
-     * translation exists to interpolate. The document does carry it, and this is
-     * the innermost point that still holds one. Reconstructing the character by
-     * matching it out of the finished sentence was the alternative, and it
-     * inverts the direction the rest of this file works in: every other identity
-     * here is derived from structured fields and CHECKED against the prose.
+     * Correlating the finished diagnostics back to the `ParseResult`'s error
+     * lists positionally is the alternative, and it is unsound for the parsing
+     * half: `processParsingErrors` DROPS an error whose token offsets are `NaN`
+     * and whose exception carries no `previousToken`, so the two lists differ in
+     * length exactly when recovery has been at work.
      *
      * Inside the timing span rather than around it, so the line accounts for the
      * whole pass.
      */
     protected validateAndIdentify(document: LangiumDocument, options?: ValidationOptions, cancelToken?: CancellationToken): Promise<Diagnostic[]>;
     /**
-     * Add the {@link LEXING_ERROR} identity to one diagnostic, or return it
-     * untouched when it is not the sentence that identity renders.
+     * Add whichever lexing identity renders `diagnostic`'s sentence, or return it
+     * untouched when none of them does — a custom lexer's own report, which
+     * Langium admits through `lexerReport`, being the case that reaches the end.
      *
      * The parameters come from the diagnostic's own RANGE, not from
      * `parseResult.lexerErrors`. Both hold the same numbers, and the range is the
@@ -166,6 +253,64 @@ export declare class HydraniumDocumentValidator extends DefaultDocumentValidator
      * message.
      */
     protected identifyLexingError(document: LangiumDocument, diagnostic: Diagnostic): Diagnostic;
+    /**
+     * Add whichever parser identity renders `diagnostic`'s sentence, or return it
+     * untouched when none of them does — an adopter that replaced the parser
+     * error-message provider being the case that reaches the last branch.
+     *
+     * `found` comes from the diagnostic's own RANGE, for the same reason
+     * {@link identifyLexingError} reads its parameters there. A token whose
+     * offsets chevrotain could not report collapses to a zero-width range, which
+     * yields the empty string the sentence already renders for it.
+     *
+     * **`expected` is recovered by SEARCHING the vocabulary, because nothing
+     * carries it.** Chevrotain hands the expected token type to the message
+     * provider and keeps it on neither the exception nor the diagnostic, so the
+     * only structured source left is the grammar's own vocabulary: every token
+     * type is offered to the same `format` the identity renders with, and the one
+     * that reproduces the message supplies the parameter. Matching it out of the
+     * prose instead would derive a parameter from a sentence that a Langium
+     * reword can change without warning. Two distinct names cannot render one
+     * sentence, so the match is unique where it exists.
+     */
+    protected identifyParsingError(document: LangiumDocument, diagnostic: Diagnostic): Diagnostic;
+    /** `diagnostic` carrying `definition`'s identity, over whatever `data` it already had. */
+    protected identified<S extends string>(diagnostic: Diagnostic, definition: MessageDefinition<S>, ...params: ParamsArg<S>): Diagnostic;
+    /**
+     * `definition`'s parameters as they appear in `message`, taking the ones in
+     * `known` as given, or `undefined` when `message` is not that sentence.
+     *
+     * **The only parameters in this file taken OUT of the prose rather than
+     * derived and checked against it, and the bound on that is what `known`
+     * is for.** A generated token-sequence list, a lexer's indentation stack: for
+     * these there is no finite candidate set to offer to `format` the way a token
+     * type name can be, and no structured field carries them. What keeps the read
+     * honest is that everything else in the sentence is either a fixed literal or
+     * a parameter the caller derived independently, so the frame either matches
+     * exactly or the sentence is declined.
+     *
+     * **The trailing format-and-compare is load-bearing once more than one
+     * parameter is unknown.** Each is captured up to the NEXT fixed separator, so
+     * a separator that also occurs inside a value would cut early — re-rendering
+     * catches that, where for a single unknown between two affixes it could not
+     * fail. Two adjacent placeholders are declined outright: nothing marks the
+     * boundary, so no capture is recoverable.
+     *
+     * The frame is split off the declaration's own `text`, so it cannot drift
+     * from the sentence `format` renders.
+     */
+    protected sliceFramed<S extends string>(message: string, definition: MessageDefinition<S>, known: MessageParams): ParamsOf<S> | undefined;
+    /**
+     * Every token type name the grammar declares, as
+     * {@link identifyParsingError} candidates.
+     *
+     * Read off the lexer, whose `definition` the `Lexer` INTERFACE declares —
+     * the parser holds the same vocabulary only behind Langium's default class,
+     * where an adopter's replacement need not keep it. A token type the parser
+     * expects but the lexer does not declare yields no match, which declines the
+     * identity rather than attaching a wrong one.
+     */
+    protected tokenTypeNames(): readonly string[];
     /**
      * Skip validation for a node **and its children** when
      * {@link shouldSkipValidation} returns true.
@@ -228,7 +373,7 @@ export declare class HydraniumDocumentValidator extends DefaultDocumentValidator
      * {@link UNRESOLVED_REFERENCE} claims.
      */
     protected referenceTypeOf(containerType: string, property: string, refText: string): string | undefined;
-    protected toDiagnostic<N extends AstNode>(severity: ValidationSeverity, message: string, info: DiagnosticInfo<N, string>): TransferLspDiagnostic;
+    protected toDiagnostic<N extends AstNode>(severity: ValidationSeverity, message: string, info: DiagnosticInfo<N, string>): AstDiagnostic;
     /**
      * Construct the `element` path for a diagnostic. Falls back through:
      * - the node's own AST path, then

package/lib/langium/validation/document-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-validator.d.ts","sourceRoot":"","sources":["../../../src/langium/validation/document-validator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"document-validator.d.ts","sourceRoot":"","sources":["../../../src/langium/validation/document-validator.ts"],"names":[],"mappings":"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"}

package/lib/langium/validation/document-validator.js

@@ -6,10 +6,10 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { defineMessage, describeError, messageData, ObservableValue, TransferDiagnostic } from '@hydranium/protocol';
+import { defineMessage, describeError, interpolate, messageData, ObservableValue, TransferDiagnostic } from '@hydranium/protocol';
 import { DefaultDocumentValidator, DocumentValidator } from '@hydranium/langium';
 // A VALUE import, for `Diagnostic.getMessageString`: `message` is
-// `string | MarkupContent` in LSP 3.17+, so upstream's own reader is what
+// `string | MarkupContent` since LSP 3.18, so upstream's own reader is what
 // narrows it rather than a hand-rolled union check here.
 import { Diagnostic } from 'vscode-languageserver-types';
 import { isSyntheticNode } from '../workspace/synthetic.js';
@@ -55,7 +55,90 @@ export const UNRESOLVED_REFERENCE = defineMessage('hydranium/core/unresolved-ref
  * means: chevrotain reports how many characters the lexer discarded to recover,
  * which for a single stray character is one and for a run of them is the run.
  */
-export const LEXING_ERROR = defineMessage('hydranium/core/lexing-error', 'unexpected character: ->{character}<- at offset: {offset}, skipped {skipped} characters.');
+export const UNEXPECTED_CHARACTER = defineMessage('hydranium/core/unexpected-character', 'unexpected character: ->{character}<- at offset: {offset}, skipped {skipped} characters.');
+/**
+ * A token the grammar does not admit at this position.
+ *
+ * **The English is byte-identical to Langium's
+ * `LangiumParserErrorMessageProvider.buildMismatchTokenMessage`, and must stay
+ * so**, on the same rule as {@link UNRESOLVED_REFERENCE}.
+ *
+ * `expected` is a token type name, which is grammar vocabulary rather than
+ * translatable text — only the frame around it is. Promoting it into the code
+ * instead would make the catalogue as large as the grammar.
+ */
+export const UNEXPECTED_TOKEN = defineMessage('hydranium/core/unexpected-token', "Expecting token of type '{expected}' but found `{found}`.");
+/**
+ * Input left over once the entry rule had matched.
+ *
+ * **The English is byte-identical to Langium's
+ * `LangiumParserErrorMessageProvider.buildNotAllInputParsedMessage`, and must
+ * stay so.**
+ */
+export const TRAILING_INPUT = defineMessage('hydranium/core/trailing-input', 'Expecting end of file but found `{found}`.');
+/**
+ * A mode-popping token reached with nothing on the lexer's mode stack.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultLexerErrorProvider.buildUnableToPopLexerModeMessage`, and must stay
+ * so**, the closing clause running on without punctuation exactly as upstream
+ * writes it.
+ *
+ * Reachable only from a multi-mode lexer, which a grammar opts into through a
+ * custom token builder.
+ */
+export const UNPOPPABLE_LEXER_MODE = defineMessage('hydranium/core/unpoppable-lexer-mode', 'Unable to pop Lexer Mode after encountering Token ->{image}<- The Mode Stack is empty');
+/**
+ * A dedent that lines up with no enclosing indentation level.
+ *
+ * **The English is byte-identical to LANGIUM's `IndentationAwareTokenBuilder`,
+ * and must stay so** — the one lexing sentence Langium words itself rather than
+ * relaying from chevrotain, which is why it renders through no
+ * `ILexerErrorMessageProvider` and an adopter cannot reach it by replacing one.
+ *
+ * `stack` is the indentation stack as the template literal upstream stringifies
+ * it, comma-joined: structure would have to survive {@link MessageParams}, which
+ * holds scalars, and a translation has nothing to say about the numbers anyway.
+ */
+export const INVALID_DEDENT = defineMessage('hydranium/core/invalid-dedent', 'Invalid dedent level {level} at offset: {offset}. Current indentation stack: {stack}');
+/**
+ * A position where none of a rule's alternatives can start.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultParserErrorProvider.buildNoViableAltMessage`, and must stay so** —
+ * one layer further out than {@link UNEXPECTED_TOKEN}, because Langium overrides
+ * only two of the four parser sentences and passes this one straight through.
+ *
+ * `sequences` is the token-sequence list chevrotain generated, carried whole
+ * rather than as structure: {@link MessageParams} holds scalars, and the list is
+ * token names in any case, so only the frame around it is translatable.
+ */
+export const NO_VIABLE_ALTERNATIVE = defineMessage('hydranium/core/no-viable-alternative', "Expecting: one of these possible Token sequences:\n{sequences}\nbut found: '{found}'");
+/**
+ * A repetition that had to match at least once and matched nothing.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultParserErrorProvider.buildEarlyExitMessage`, and must stay so**,
+ * including the doubled colon after `sequences::`, which is upstream's and not a
+ * typo to repair here — a divergence would silently stop the identity attaching.
+ *
+ * Named for the empty repetition rather than for chevrotain's `EarlyExit`, which
+ * describes its own control flow rather than the reader's problem.
+ */
+export const MISSING_ITERATION = defineMessage('hydranium/core/missing-iteration', "Expecting: expecting at least one iteration which starts with one of these possible Token sequences::\n  <{sequences}>\nbut found: '{found}'");
+/**
+ * The two sentences whose only free parameter is a generated list, in the order
+ * {@link HydraniumDocumentValidator.identifyParsingError} tries them. Order is
+ * free: their frames share a prefix but diverge before the list begins, so at
+ * most one can match.
+ */
+const SEQUENCE_LISTING_MESSAGES = [NO_VIABLE_ALTERNATIVE, MISSING_ITERATION];
+/**
+ * Splits a template into alternating frame and placeholder NAME, for
+ * {@link HydraniumDocumentValidator.sliceFramed}. The capturing group is what
+ * keeps the names in the result rather than discarding them.
+ */
+const PLACEHOLDER_CAPTURE = /\{([^}]+)\}/;
 /**
  * Langium's own `data.code` values for a diagnostic that came out of the lexer.
  *
@@ -76,7 +159,7 @@ const LEXING_CODES = new Set([
  * - **Skip-validation hook** via the virtual {@link shouldSkipValidation}
  *   predicate, which adopters override to compose additional skip reasons.
  * - **Diagnostic mapping** to {@link TransferDiagnostic}-shaped
- *   {@link TransferLspDiagnostic}: every emitted diagnostic carries the AST
+ *   {@link AstDiagnostic}: every emitted diagnostic carries the AST
  *   node's path (built via Langium's `AstNodeLocator`) plus the optional
  *   offending property name.
  * - **Optional timing wrap** on `validateDocument`, on by default.
@@ -85,6 +168,12 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
     tracer;
     astNodeLocator;
     reflection;
+    lexer;
+    /**
+     * {@link tokenTypeNames}' answer. Nothing invalidates it: the vocabulary
+     * comes from the grammar, which is fixed once the DI tree is composed.
+     */
+    expectedNames;
     logLevel;
     logAfterMs;
     validateVirtualDocuments;
@@ -94,6 +183,7 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
         this.tracer = services.shared.Tracer.for(options.logName ?? 'DocumentValidator').trace('instantiated');
         this.astNodeLocator = services.workspace.AstNodeLocator;
         this.reflection = services.shared.AstReflection;
+        this.lexer = services.parser.Lexer;
         this.logLevel = ObservableValue.from(options.logLevel ?? 'debug');
         this.logAfterMs = ObservableValue.from(options.logAfterMs ?? 20);
         this.validateVirtualDocuments = ObservableValue.from(options.validateVirtualDocuments ?? false);
@@ -120,18 +210,22 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
         });
     }
     /**
-     * Langium's validation pass, plus the framework identity on the lexing
-     * diagnostics it produced.
+     * Langium's validation pass, plus the framework identity on the lexing and
+     * parsing diagnostics it produced.
      *
-     * **Here rather than in an override of `processLexingErrors`, and the reason
-     * is that the seam cannot see what the identity needs.** Langium hands that
-     * method a `ParseResult`, which carries the AST and the error lists but not
-     * the source text — and the offending CHARACTER is the parameter a
-     * translation exists to interpolate. The document does carry it, and this is
-     * the innermost point that still holds one. Reconstructing the character by
-     * matching it out of the finished sentence was the alternative, and it
-     * inverts the direction the rest of this file works in: every other identity
-     * here is derived from structured fields and CHECKED against the prose.
+     * **Here rather than in an override of `processLexingErrors` /
+     * `processParsingErrors`, and the reason is that neither seam can see what
+     * the identity needs.** Langium hands them a `ParseResult`, which carries the
+     * AST and the error lists but not the source text — and the offending
+     * CHARACTER, or the offending TOKEN, is the parameter a translation exists to
+     * interpolate. The document does carry it, and this is the innermost point
+     * that still holds one.
+     *
+     * Correlating the finished diagnostics back to the `ParseResult`'s error
+     * lists positionally is the alternative, and it is unsound for the parsing
+     * half: `processParsingErrors` DROPS an error whose token offsets are `NaN`
+     * and whose exception carries no `previousToken`, so the two lists differ in
+     * length exactly when recovery has been at work.
      *
      * Inside the timing span rather than around it, so the line accounts for the
      * whole pass.
@@ -141,14 +235,18 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
         // Mapped in place over the array Langium built, rather than filtered and
         // re-concatenated: the publish order is the diagnostic order and a
         // reordering would move a squiggle's entry in the problems list.
+        // Each pass guards on its own `data.code`, so at most one can claim a
+        // given diagnostic and the order between them carries no meaning.
         for (let index = 0; index < diagnostics.length; index++) {
             diagnostics[index] = this.identifyLexingError(document, diagnostics[index]);
+            diagnostics[index] = this.identifyParsingError(document, diagnostics[index]);
         }
         return diagnostics;
     }
     /**
-     * Add the {@link LEXING_ERROR} identity to one diagnostic, or return it
-     * untouched when it is not the sentence that identity renders.
+     * Add whichever lexing identity renders `diagnostic`'s sentence, or return it
+     * untouched when none of them does — a custom lexer's own report, which
+     * Langium admits through `lexerReport`, being the case that reaches the end.
      *
      * The parameters come from the diagnostic's own RANGE, not from
      * `parseResult.lexerErrors`. Both hold the same numbers, and the range is the
@@ -168,19 +266,157 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
             return diagnostic;
         }
         const text = document.textDocument;
+        const message = Diagnostic.getMessageString(diagnostic);
         const offset = text.offsetAt(diagnostic.range.start);
-        const params = {
+        const stray = {
             character: text.getText().charAt(offset),
             offset,
             skipped: text.offsetAt(diagnostic.range.end) - offset
         };
-        if (Diagnostic.getMessageString(diagnostic) !== LEXING_ERROR.format(params)) {
+        if (message === UNEXPECTED_CHARACTER.format(stray)) {
+            return this.identified(diagnostic, UNEXPECTED_CHARACTER, stray);
+        }
+        // The mode-pop error's range spans the offending token exactly, upstream
+        // reporting its `startOffset` with the image's own length.
+        const image = text.getText(diagnostic.range);
+        if (message === UNPOPPABLE_LEXER_MODE.format({ image })) {
+            return this.identified(diagnostic, UNPOPPABLE_LEXER_MODE, { image });
+        }
+        // `level` and `stack` are lexer state that reaches no field here, so they
+        // are sliced; `offset` is given, which is what anchors the slice.
+        const dedent = this.sliceFramed(message, INVALID_DEDENT, { offset });
+        return dedent === undefined ? diagnostic : this.identified(diagnostic, INVALID_DEDENT, dedent);
+    }
+    /**
+     * Add whichever parser identity renders `diagnostic`'s sentence, or return it
+     * untouched when none of them does — an adopter that replaced the parser
+     * error-message provider being the case that reaches the last branch.
+     *
+     * `found` comes from the diagnostic's own RANGE, for the same reason
+     * {@link identifyLexingError} reads its parameters there. A token whose
+     * offsets chevrotain could not report collapses to a zero-width range, which
+     * yields the empty string the sentence already renders for it.
+     *
+     * **`expected` is recovered by SEARCHING the vocabulary, because nothing
+     * carries it.** Chevrotain hands the expected token type to the message
+     * provider and keeps it on neither the exception nor the diagnostic, so the
+     * only structured source left is the grammar's own vocabulary: every token
+     * type is offered to the same `format` the identity renders with, and the one
+     * that reproduces the message supplies the parameter. Matching it out of the
+     * prose instead would derive a parameter from a sentence that a Langium
+     * reword can change without warning. Two distinct names cannot render one
+     * sentence, so the match is unique where it exists.
+     */
+    identifyParsingError(document, diagnostic) {
+        const data = diagnostic.data;
+        if (data?.code !== DocumentValidator.ParsingError) {
             return diagnostic;
         }
-        // Merged OVER Langium's data, so `data.code` survives for the readers that
-        // switch on it — `stopAfterLexingErrors` is one, and the GLSP head's
-        // read-only decision is another.
-        return { ...diagnostic, code: LEXING_ERROR.code, data: { ...data, ...messageData(LEXING_ERROR, params) } };
+        const message = Diagnostic.getMessageString(diagnostic);
+        const found = document.textDocument.getText(diagnostic.range);
+        if (message === TRAILING_INPUT.format({ found })) {
+            return this.identified(diagnostic, TRAILING_INPUT, { found });
+        }
+        const expected = this.tokenTypeNames().find(name => UNEXPECTED_TOKEN.format({ expected: name, found }) === message);
+        if (expected !== undefined) {
+            return this.identified(diagnostic, UNEXPECTED_TOKEN, { expected, found });
+        }
+        for (const definition of SEQUENCE_LISTING_MESSAGES) {
+            const params = this.sliceFramed(message, definition, { found });
+            if (params !== undefined) {
+                return this.identified(diagnostic, definition, params);
+            }
+        }
+        return diagnostic;
+    }
+    /** `diagnostic` carrying `definition`'s identity, over whatever `data` it already had. */
+    identified(diagnostic, definition, ...params) {
+        // Merged OVER the existing data, so Langium's `code` survives for the
+        // readers that switch on it — `stopAfterParsingErrors` is one, and the
+        // GLSP head's read-only decision is another.
+        const data = diagnostic.data;
+        return { ...diagnostic, code: definition.code, data: { ...data, ...messageData(definition, ...params) } };
+    }
+    /**
+     * `definition`'s parameters as they appear in `message`, taking the ones in
+     * `known` as given, or `undefined` when `message` is not that sentence.
+     *
+     * **The only parameters in this file taken OUT of the prose rather than
+     * derived and checked against it, and the bound on that is what `known`
+     * is for.** A generated token-sequence list, a lexer's indentation stack: for
+     * these there is no finite candidate set to offer to `format` the way a token
+     * type name can be, and no structured field carries them. What keeps the read
+     * honest is that everything else in the sentence is either a fixed literal or
+     * a parameter the caller derived independently, so the frame either matches
+     * exactly or the sentence is declined.
+     *
+     * **The trailing format-and-compare is load-bearing once more than one
+     * parameter is unknown.** Each is captured up to the NEXT fixed separator, so
+     * a separator that also occurs inside a value would cut early — re-rendering
+     * catches that, where for a single unknown between two affixes it could not
+     * fail. Two adjacent placeholders are declined outright: nothing marks the
+     * boundary, so no capture is recoverable.
+     *
+     * The frame is split off the declaration's own `text`, so it cannot drift
+     * from the sentence `format` renders.
+     */
+    sliceFramed(message, definition, known) {
+        // `split` with a capturing group interleaves literals and placeholder
+        // names, so even indices are frame and odd ones are parameters.
+        const parts = definition.text.split(PLACEHOLDER_CAPTURE);
+        const params = { ...known };
+        let cursor = 0;
+        for (let index = 0; index < parts.length; index += 2) {
+            const literal = parts[index];
+            if (!message.startsWith(literal, cursor)) {
+                return undefined;
+            }
+            cursor += literal.length;
+            const name = parts[index + 1];
+            if (name === undefined) {
+                break;
+            }
+            const given = params[name];
+            if (given !== undefined) {
+                const rendered = String(given);
+                if (!message.startsWith(rendered, cursor)) {
+                    return undefined;
+                }
+                cursor += rendered.length;
+                continue;
+            }
+            const separator = parts[index + 2];
+            const trailing = parts[index + 3] === undefined;
+            if (separator === '' && !trailing) {
+                return undefined;
+            }
+            const at = trailing && separator === '' ? message.length : message.indexOf(separator, cursor);
+            if (at < cursor) {
+                return undefined;
+            }
+            params[name] = message.slice(cursor, at);
+            cursor = at;
+        }
+        if (cursor !== message.length || interpolate(definition.text, params) !== message) {
+            return undefined;
+        }
+        // Narrowing only: every placeholder the template names was either given or
+        // captured above, which is precisely what `ParamsOf` requires.
+        return params;
+    }
+    /**
+     * Every token type name the grammar declares, as
+     * {@link identifyParsingError} candidates.
+     *
+     * Read off the lexer, whose `definition` the `Lexer` INTERFACE declares —
+     * the parser holds the same vocabulary only behind Langium's default class,
+     * where an adopter's replacement need not keep it. A token type the parser
+     * expects but the lexer does not declare yields no match, which declines the
+     * identity rather than attaching a wrong one.
+     */
+    tokenTypeNames() {
+        this.expectedNames ??= Object.keys(this.lexer.definition);
+        return this.expectedNames;
     }
     /**
      * Skip validation for a node **and its children** when
@@ -308,9 +544,11 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
      */
     buildElementPath(node, info) {
         const directPath = this.astNodeLocator.getAstNodePath(node);
-        const containerPath = directPath ? undefined : this.astNodeLocator.getAstNodePath(node.$container ?? { $type: 'Dummy' });
-        const nodePath = directPath || containerPath;
-        if (!nodePath) {
+        // The locator answers '' for the root, which is the root's path rather than a miss.
+        const isRoot = node.$container === undefined;
+        const containerPath = directPath || isRoot ? undefined : this.astNodeLocator.getAstNodePath(node.$container);
+        const nodePath = directPath || containerPath || '';
+        if (!nodePath && !isRoot) {
             this.tracer.warn('Cannot create diagnostic element path: Unable to determine AST node path.');
             return '';
         }