@hydranium/core 1.0.0-next.8 → 1.0.0-next.86

package/src/langium/transfer/transfer-encoder.ts

@@ -8,10 +8,11 @@
  ********************************************************************************/
 
 import {
+   hasMessageIdentity,
    type Tracer,
    type TransferDiagnostic,
    type TransferElement,
-   type TransferDocument,
+   TransferDocument,
    type TransferTypeFor
 } from '@hydranium/protocol';
 import { AstUtils, type AstNode, DocumentCache, DocumentState, isAstNode, isReference, type LangiumDocument } from '@hydranium/langium';
@@ -19,7 +20,7 @@ import { Diagnostic, DiagnosticSeverity } from 'vscode-languageserver-protocol';
 import { type AstDocument } from '../../documents/ast-document-manager.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
-import { type TransferLspDiagnostic } from '../validation/document-validator.js';
+import { type AstDiagnostic } from '../validation/document-validator.js';
 
 /**
  * Which set of properties {@link TransferEncoder.toTransfer} emits.
@@ -28,11 +29,13 @@ import { type TransferLspDiagnostic } from '../validation/document-validator.js'
  *   including AST-extension-derived computed scalars and synthetic child
  *   mirrors. This is the wire shape clients consume, and the default.
  * - `'grammar'` — only the grammar-declared properties, per
- *   `AstReflection.getTypeMetaData($type).properties`. Excludes every
- *   computed / synthetic property by construction (no naming convention,
- *   no registration). Yields the authored state a serializer round-trips —
- *   a diffable, acyclic baseline for field-level recording / forward-write
- *   reconcile.
+ *   `AstReflection.getTypeMetaData($type).properties`, each carrying the
+ *   node's own authored value. Excludes every computed / synthetic property
+ *   by construction (no naming convention, no registration) and bypasses the
+ *   `resolvePropertyValue` substitution hook, so neither a computed KEY nor a
+ *   computed VALUE can reach this shape. Yields the authored state a
+ *   serializer round-trips — a diffable, acyclic baseline for field-level
+ *   recording / forward-write reconcile.
  */
 export type TransferMode = 'full' | 'grammar';
 
@@ -79,6 +82,37 @@ export interface TransferEnvelopeSource<TDiagnostic> {
    readonly diagnostics: readonly (TDiagnostic | Diagnostic)[];
 }
 
+/**
+ * The AST→transfer contract a DI slot holds, implemented by
+ * {@link DefaultTransferEncoder}.
+ *
+ * **This is an interface and not the class, and that is load-bearing.** A class
+ * in a slot drags its `protected` members into every assignability check, which
+ * TypeScript compares NOMINALLY — so the slot type could not be satisfied by a
+ * subclass declared against a second physical copy of this package, and an
+ * adopter narrowing the slot had to intersect with the framework's declaration
+ * rather than replace it, leaving method resolution dependent on declaration
+ * order. An interface has no protected members and is compared structurally, so
+ * neither applies.
+ *
+ * **The transfer returns are the structural base ({@link TransferElement}), not
+ * the per-grammar overlay.** The overlay cannot parameterise this contract:
+ * `TransferTypeFor` reaches `keyof TTransferMap`, which makes that parameter
+ * measured-INVARIANT, and invariant parameters relate only when their arguments
+ * are mutually assignable — so a map-parameterised contract admits no adopter
+ * instantiation at all. Heads read this contract and do not know adopter maps;
+ * an adopter recovers the precise type by declaring its own slot, which it can
+ * now do by replacement.
+ */
+export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   toTransfer<T extends AstNode>(ast: T, mode?: TransferMode): TransferElement;
+   toTransferDocument(langiumDocument: LangiumDocument): TransferDocument<TransferElement, TDiagnostic>;
+   astDocumentToTransferDocument<TAst extends AstNode>(
+      document: AstDocument<TAst, AstDiagnostic>
+   ): TransferDocument<TransferElement, TDiagnostic>;
+   toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic;
+}
+
 /**
  * One-directional structural mapper from a Langium AST into the wire
  * transfer-model shape ({@link TransferElement}-based JSON).
@@ -112,7 +146,8 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  * - {@link propertyKeys} — which property names the walk visits.
  * - {@link shouldEmitProperty} — per-key filter on top of the default
  *   `$`-internals strip.
- * - {@link resolvePropertyValue} — value substitution per property.
+ * - {@link resolvePropertyValue} — value substitution per property, `'full'`
+ *   mode only (see there for why `'grammar'` bypasses it).
  * - {@link finalizeTransferNode} — post-decoration per encoded node.
  * - {@link toTransferValue} — recursion seam per property value. Override
  *   to special-case reference encoding or to drop specific value shapes.
@@ -120,10 +155,10 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  * - {@link toTransferDocument} — bundle root + diagnostics into the wire
  *   {@link TransferDocument} envelope. Override to filter / merge
  *   diagnostics from auxiliary sources or to project a synthesised root.
- * - {@link toTransferDiagnostic} — project a {@link TransferLspDiagnostic}
+ * - {@link toTransferDiagnostic} — project a {@link AstDiagnostic}
  *   (the framework validator's output) to {@link TDiagnostic}.
  */
-export class TransferEncoder<
+export class DefaultTransferEncoder<
    // The map is intentionally unconstrained — adopters supply typed
    // overlays whose specific-key shapes don't structurally satisfy a
    // `Record<string, TransferElement>` index signature. `TransferTypeFor`
@@ -226,7 +261,14 @@ export class TransferEncoder<
          if (!this.shouldEmitProperty(ast, key, context)) {
             continue;
          }
-         const value = this.resolvePropertyValue(ast, key, context);
+         // `'grammar'` reads the authored value straight off the node rather than
+         // through `resolvePropertyValue`. The mode promises a shape the serializer
+         // round-trips, and a value-substitution hook cannot honour that: what it
+         // returns is by construction not what the document declared. Scoping the
+         // hook to `'full'` is what makes that guarantee structural instead of a
+         // rule every override has to remember.
+         const value =
+            context.mode === 'grammar' ? (ast as unknown as Record<string, unknown>)[key] : this.resolvePropertyValue(ast, key, context);
          // `'grammar'` lists every declared property, including those absent on
          // this node; skip the absent ones. (`'full'` enumerates only own
          // properties, so absent properties never surface there.) Part of the
@@ -267,8 +309,17 @@ export class TransferEncoder<
    }
 
    /**
-    * Which value the walk emits under `key`. Default: the node's own value.
-    * Override to substitute a derived value under a grammar property name.
+    * Which value the walk emits under `key`, in `'full'` mode ONLY. Default:
+    * the node's own value.
+    *
+    * Override to substitute a derived value under a grammar property name — an
+    * inheritance-resolved field, a preference-dependent label. `'grammar'`
+    * bypasses this hook and reads the node directly: that mode's contract is
+    * the authored state a serializer round-trips, and a substituted value is by
+    * construction not the one the document declared. An override that applied
+    * in both modes would leave the grammar shape carrying derived values under
+    * declared property names — diffable and acyclic still, but no longer
+    * authored, which is the property every consumer of that mode relies on.
     */
    protected resolvePropertyValue(ast: AstNode, key: string, _context: EncodeContext): unknown {
       return (ast as unknown as Record<string, unknown>)[key];
@@ -340,12 +391,12 @@ export class TransferEncoder<
       source: TransferEnvelopeSource<TDiagnostic>,
       root: TransferTypeFor<TAst, TTransferMap>
    ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
-      return {
-         uri: source.uri,
-         version: source.version,
+      return TransferDocument.create(
+         source.uri,
+         source.version,
          root,
-         diagnostics: source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as TransferLspDiagnostic))
-      };
+         source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as AstDiagnostic))
+      );
    }
 
    /**
@@ -359,7 +410,7 @@ export class TransferEncoder<
     * second `LangiumDocuments.getDocument` lookup.
     *
     * The `diagnostic` projection assumes the snapshot's diagnostics carry
-    * the `TransferLspDiagnostic` shape ({@link Diagnostic} plus the
+    * the `AstDiagnostic` shape ({@link Diagnostic} plus the
     * framework validator's `element` / `property` decoration). Snapshots
     * built from raw Langium diagnostics structurally satisfy this — the
     * extra fields are optional in the projection.
@@ -370,7 +421,7 @@ export class TransferEncoder<
     * assembly seam rather than duplicating it.
     */
    astDocumentToTransferDocument<TAst extends AstNode>(
-      document: AstDocument<TAst, TDiagnostic | TransferLspDiagnostic>
+      document: AstDocument<TAst, AstDiagnostic>
    ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
       const root = this.encodeNode(document.root, this.createEncodeContext('full', document.uri)) as TransferTypeFor<TAst, TTransferMap>;
       return this.assembleTransferDocument<TAst>(document, root);
@@ -378,7 +429,7 @@ export class TransferEncoder<
 
    /**
     * Project an LSP-shaped diagnostic (typically a
-    * {@link TransferLspDiagnostic} produced by
+    * {@link AstDiagnostic} produced by
     * `HydraniumDocumentValidator` — adds `element` + optional `property`
     * to the standard {@link Diagnostic} shape) to the wire-diagnostic
     * shape.
@@ -387,15 +438,24 @@ export class TransferEncoder<
     * LSP severity enum to the wire string union, discriminates the
     * diagnostic type from Langium's `data.code` (`'lexing-error'` /
     * `'parsing-error'` else `'validation-error'`), passes through
-    * message / element / property / code. Adopters whose validator
+    * message / element / property / code, and lifts the framework message
+    * params out of `data` so a translating surface can render a
+    * parameterised diagnostic rather than a template with its placeholders
+    * left standing. Adopters whose validator
     * doesn't decorate diagnostics with `element` still get a valid
     * `TransferDiagnostic` — the field falls back to `''`.
     *
     * Override only if the wire-diagnostic shape needs fields beyond
     * what {@link TransferDiagnostic} carries.
     */
-   toTransferDiagnostic(diagnostic: TransferLspDiagnostic): TDiagnostic {
+   toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic {
       const langiumCode = (diagnostic.data as { code?: string } | undefined)?.code;
+      // The same `data` the Langium code comes out of also carries the framework
+      // message identity, under its own key so the two conventions co-exist.
+      // Taking the params from there rather than from `code` is what lets a
+      // translating surface render a PARAMETERISED diagnostic: `code` survives on
+      // its own and yields a template with its placeholders left standing.
+      const identity = hasMessageIdentity(diagnostic.data) ? diagnostic.data.hydranium : undefined;
       const result: TransferDiagnostic = {
          type: langiumCode === 'lexing-error' ? 'lexing-error' : langiumCode === 'parsing-error' ? 'parsing-error' : 'validation-error',
          element: diagnostic.element ?? '',
@@ -408,7 +468,8 @@ export class TransferEncoder<
                : diagnostic.severity === DiagnosticSeverity.Warning
                  ? 'warning'
                  : 'info',
-         code: typeof diagnostic.code === 'number' || typeof diagnostic.code === 'string' ? diagnostic.code : langiumCode
+         code: typeof diagnostic.code === 'number' || typeof diagnostic.code === 'string' ? diagnostic.code : langiumCode,
+         params: identity?.params
       };
       return result as TDiagnostic;
    }