@hydranium/core 1.0.0-next.34 → 1.0.0-next.341

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

@@ -8,11 +8,12 @@
  ********************************************************************************/
 
 import {
+   asModelVersion,
    hasMessageIdentity,
+   type TransferModelSnapshot,
    type Tracer,
    type TransferDiagnostic,
    type TransferElement,
-   type TransferDocument,
    type TransferTypeFor
 } from '@hydranium/protocol';
 import { AstUtils, type AstNode, DocumentCache, DocumentState, isAstNode, isReference, type LangiumDocument } from '@hydranium/langium';
@@ -20,7 +21,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.
@@ -29,26 +30,29 @@ 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';
 
 /**
  * Per-encode inputs threaded through the {@link TransferEncoder} walk and its
  * hooks. Created once per encode entry (see
- * {@link TransferEncoder.createEncodeContext}) and passed unchanged through
- * the recursion, so every hook invocation of one encode observes the same
- * inputs — unlike instance state, which two interleaving encodes would
+ * {@link DefaultTransferEncoder.createEncodeContext}) and passed unchanged
+ * through the recursion, so every hook invocation of one encode observes the
+ * same inputs — unlike instance state, which two interleaving encodes would
  * clobber.
  *
  * Adopters widen the context by overriding `createEncodeContext` with a
  * covariant return type and narrowing the hook parameter types accordingly
  * (TypeScript method bivariance admits the narrowing). An input that changes
- * the encoded output must also be folded into {@link TransferEncoder.rootCacheKey}.
+ * the encoded output must also be folded into
+ * {@link DefaultTransferEncoder.rootCacheKey}.
  */
 export interface EncodeContext {
    /** Property-set selection for this encode — see {@link TransferMode}. */
@@ -63,21 +67,62 @@ export interface EncodeContext {
 }
 
 /**
- * The non-root inputs {@link TransferEncoder.assembleTransferDocument} needs to
- * build a wire envelope. Both of the encoder's document paths narrow to this
- * before assembling — a built `LangiumDocument` (whose `uri` / `version` live on
- * its `textDocument`) and a server-internal `AstDocument` snapshot, which
- * satisfies the shape structurally — so the assembly seam has exactly one
- * implementation to override.
+ * The non-root inputs {@link DefaultTransferEncoder.assembleTransferDocument}
+ * needs to build a wire envelope. Both of the encoder's document paths narrow
+ * to this before assembling — a built `LangiumDocument` (whose `uri` /
+ * `version` live on its `textDocument`) and a server-internal `AstDocument`
+ * snapshot, which satisfies the shape structurally — so the assembly seam has
+ * exactly one implementation to override.
  *
  * `diagnostics` accepts either the wire shape (an already-projected
  * `TDiagnostic`, as a snapshot may carry) or a raw LSP {@link Diagnostic}; the
  * assembly projects each through {@link TransferEncoder.toTransferDiagnostic}.
+ * Absent for a document not validated yet, and left absent on the wire.
  */
 export interface TransferEnvelopeSource<TDiagnostic> {
    readonly uri: string;
    readonly version: number;
-   readonly diagnostics: readonly (TDiagnostic | Diagnostic)[];
+   readonly diagnostics?: readonly (TDiagnostic | Diagnostic)[];
+}
+
+/**
+ * A `TransferDocument` as the encoder produces it: the model block without
+ * its `hash`, which the data server computes from the encoded model.
+ */
+export interface EncodedTransferDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> {
+   uri: string;
+   model: Omit<TransferModelSnapshot<TTransfer, TDiagnostic>, 'hash'>;
+}
+
+/**
+ * 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): EncodedTransferDocument<TransferElement, TDiagnostic>;
+   astDocumentToTransferDocument<TAst extends AstNode>(
+      document: AstDocument<TAst, AstDiagnostic>
+   ): EncodedTransferDocument<TransferElement, TDiagnostic>;
+   toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic;
 }
 
 /**
@@ -97,8 +142,8 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  *   resolving each AST type to its declared wire shape. Default is
  *   `Record<string, TransferElement>`, which collapses every encoded node
  *   to the structural base — adequate for adopters without a generated
- *   overlay; richer adopters declare typed maps for autocomplete on the
- *   encoder's return types.
+ *   overlay; an adopter passes the generated `<LanguageId>TransferTypes` to
+ *   type the encoder's returns by the grammar.
  * - `TDiagnostic` — wire-diagnostic shape produced by
  *   {@link toTransferDiagnostic}. Constrained to extend
  *   {@link TransferDiagnostic} so the framework default (which constructs a
@@ -113,18 +158,19 @@ 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.
  * Envelope-level seams:
  * - {@link toTransferDocument} — bundle root + diagnostics into the wire
- *   {@link TransferDocument} envelope. Override to filter / merge
+ *   {@link EncodedTransferDocument} 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`
@@ -227,7 +273,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
@@ -268,8 +321,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];
@@ -286,7 +348,7 @@ export class TransferEncoder<
    }
 
    /**
-    * Build a wire {@link TransferDocument} envelope from a built
+    * Build a wire {@link EncodedTransferDocument} envelope from a built
     * {@link LangiumDocument}. The `'full'` root is served from the internal
     * {@link rootCache} (memoised per document until it next rebuilds), under
     * {@link rootCacheKey} — so the data-server's fingerprint and emitted
@@ -310,7 +372,7 @@ export class TransferEncoder<
     */
    toTransferDocument<TAst extends AstNode>(
       langiumDocument: LangiumDocument
-   ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
+   ): EncodedTransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
       const context = this.createEncodeContext('full', langiumDocument.uri.toString());
       const root = this.rootCache.get(langiumDocument.uri, this.rootCacheKey(context), () =>
          this.encodeNode(langiumDocument.parseResult.value, context)
@@ -318,8 +380,8 @@ export class TransferEncoder<
       return this.assembleTransferDocument<TAst>(
          {
             uri: langiumDocument.textDocument.uri,
-            version: langiumDocument.textDocument.version,
-            diagnostics: langiumDocument.diagnostics ?? []
+            version: this.services.workspace.ModelLedger.versionOf(langiumDocument.parseResult.value),
+            diagnostics: langiumDocument.diagnostics
          },
          root
       );
@@ -340,27 +402,22 @@ export class TransferEncoder<
    protected assembleTransferDocument<TAst extends AstNode>(
       source: TransferEnvelopeSource<TDiagnostic>,
       root: TransferTypeFor<TAst, TTransferMap>
-   ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
-      return {
-         uri: source.uri,
-         version: source.version,
-         root,
-         diagnostics: source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as TransferLspDiagnostic))
-      };
+   ): EncodedTransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
+      const diagnostics = source.diagnostics?.map(diagnostic => this.toTransferDiagnostic(diagnostic as AstDiagnostic));
+      return { uri: source.uri, model: { root, version: asModelVersion(source.version), ...(diagnostics ? { diagnostics } : {}) } };
    }
 
    /**
-    * Build a wire {@link TransferDocument} envelope from a server-internal
-    * {@link AstDocument} snapshot (the AST-typed envelope emitted by
-    * `AstDocumentManager.onUpdate` / `onSave` and returned from
-    * `ModelService.request` / `update` / `save`). Distinct from
+    * Build a wire {@link EncodedTransferDocument} envelope from a server-internal
+    * {@link AstDocument} snapshot (the AST-typed envelope `ModelService`'s
+    * events carry and its reads and session writes return). Distinct from
     * {@link toTransferDocument}(`LangiumDocument`) which encodes against
     * the live build artifact — adopter facade returns hold the snapshot
     * directly, and this helper bridges that to the wire shape without a
     * 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.
@@ -371,15 +428,15 @@ export class TransferEncoder<
     * assembly seam rather than duplicating it.
     */
    astDocumentToTransferDocument<TAst extends AstNode>(
-      document: AstDocument<TAst, TDiagnostic | TransferLspDiagnostic>
-   ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
+      document: AstDocument<TAst, AstDiagnostic>
+   ): EncodedTransferDocument<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);
    }
 
    /**
     * 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.
@@ -398,7 +455,7 @@ export class TransferEncoder<
     * 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.