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

package/src/testing/data-doubles.ts

@@ -34,7 +34,14 @@
 import { Emitter, type MessageConnection } from 'vscode-jsonrpc';
 import type { DataPort } from '../client/data-port';
 import type { DataClientProtocol } from '../data/data-server-protocol';
-import type { ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from '../data/events';
+import type {
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from '../data/events';
+import type { ResolvedMessage } from '../messages/primitives';
 import type { Project } from '../project';
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
@@ -51,13 +58,6 @@ export interface FakeDataPortOptions {
     * which the consumer surfaces through {@link FakeDataPort.reported}.
     */
    connect(): MessageConnection | Promise<MessageConnection>;
-   /**
-    * Stable client identity. Defaults to `'fake-data-port'`, which avoids the
-    * three sentinels the framework reserves (`'language-client'`, `'unknown'`,
-    * `'revert-on-close'`); override it when a test needs two distinguishable
-    * clients on one server.
-    */
-   clientId?: string;
 }
 
 /** A {@link DataPort} that records what passed through it. */
@@ -73,10 +73,11 @@ export interface FakeDataPort extends DataPort {
    /**
     * Every {@link DataPort.reportError} call, in order. Read from outside: this
     * is the only place a transport failure surfaces, so a test for the failure
-    * path asserts on the `context` string here rather than on a rejection that
-    * the consumer may legitimately swallow.
+    * path asserts here rather than on a rejection the consumer may legitimately
+    * swallow. Prefer asserting on `message.code`, which is stable, over
+    * `message.text`, which is the English default and may be reworded.
     */
-   readonly reported: readonly { readonly error: unknown; readonly context: string }[];
+   readonly reported: readonly { readonly error: unknown; readonly message: ResolvedMessage }[];
    /**
     * Fire {@link DataPort.onDispose} — the host tearing the transport down, a
     * language-server restart being the case that forces the event to exist.
@@ -96,10 +97,9 @@ export interface FakeDataPort extends DataPort {
  */
 export function makeFakeDataPort(options: FakeDataPortOptions): FakeDataPort {
    const connections: MessageConnection[] = [];
-   const reported: { error: unknown; context: string }[] = [];
+   const reported: { error: unknown; message: ResolvedMessage }[] = [];
    const disposeEmitter = new Emitter<void>();
    return {
-      clientId: options.clientId ?? 'fake-data-port',
       connections,
       reported,
       onDispose: disposeEmitter.event,
@@ -108,8 +108,8 @@ export function makeFakeDataPort(options: FakeDataPortOptions): FakeDataPort {
          connections.push(connection);
          return connection;
       },
-      reportError(error: unknown, context: string): void {
-         reported.push({ error, context });
+      reportError(error: unknown, message: ResolvedMessage): void {
+         reported.push({ error, message });
       },
       fireDispose(): void {
          disposeEmitter.fire(undefined);
@@ -132,6 +132,10 @@ export interface CapturingDataClient<
    readonly updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[];
    /** Every `onDocumentSaved` event, in arrival order. */
    readonly saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[];
+   /** Every `onDocumentDeleted` event, in arrival order. */
+   readonly deletions: TransferDocumentDeletedEvent[];
+   /** Every `onDocumentsBuilt` event, in arrival order. */
+   readonly builds: TransferDocumentsBuiltEvent[];
    /** Every `onProjectsChanged` event, in arrival order. */
    readonly projectsChanges: ProjectsChangedEvent<TProject>[];
 }
@@ -139,7 +143,7 @@ export interface CapturingDataClient<
 /**
  * A {@link DataClientProtocol} that records every notification it receives.
  *
- * Recording ALL THREE channels even when a suite reads one is deliberate: an
+ * Recording EVERY channel even when a suite reads one is deliberate: an
  * event delivered on the wrong channel is a real defect of the data head, and a
  * double that drops the other two turns it into silence on the one being
  * watched.
@@ -156,6 +160,8 @@ export function makeCapturingDataClient<
 >(overrides: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>> = {}): CapturingDataClient<TTransfer, TDiagnostic, TProject> {
    const updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[] = [];
    const saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[] = [];
+   const deletions: TransferDocumentDeletedEvent[] = [];
+   const builds: TransferDocumentsBuiltEvent[] = [];
    const projectsChanges: ProjectsChangedEvent<TProject>[] = [];
    const client: DataClientProtocol<TTransfer, TDiagnostic, TProject> = {
       onDocumentUpdated:
@@ -168,11 +174,21 @@ export function makeCapturingDataClient<
          (event => {
             saves.push(event);
          }),
+      onDocumentDeleted:
+         overrides.onDocumentDeleted ??
+         (event => {
+            deletions.push(event);
+         }),
+      onDocumentsBuilt:
+         overrides.onDocumentsBuilt ??
+         (event => {
+            builds.push(event);
+         }),
       onProjectsChanged:
          overrides.onProjectsChanged ??
          (event => {
             projectsChanges.push(event);
          })
    };
-   return { client, updates, saves, projectsChanges };
+   return { client, updates, saves, deletions, builds, projectsChanges };
 }

package/src/testing/index.ts

@@ -10,7 +10,9 @@
 // Subpath barrel for `@hydranium/protocol/testing` — the BROWSER-NEUTRAL shared
 // primitives: `makeFakeClock` (deterministic `Clock` double on one virtual time
 // axis), `waitFor` / `tick`, the client-side data-head doubles
-// (`makeFakeDataPort` / `makeCapturingDataClient`), and the `Harness` marker
+// (`makeFakeDataPort` / `makeCapturingDataClient`), the translation-catalogue
+// audit (`flattenCatalogue` / `findUndeclaredCodes` / `findSharedCodes`), and
+// the `Harness` marker
 // interface every framework harness extends. Kept out of the main barrel so production bundles don't pull
 // the test scaffolding in by default; adopters opt in by importing from
 // `@hydranium/protocol/testing`.
@@ -20,6 +22,7 @@
 // type, so they cannot be made portable and live at `./testing/node` instead.
 // The same rule the package surface uses — the portable name is the short one.
 
+export * from './catalogue-audit';
 export * from './data-doubles';
 export * from './fake-clock';
 export * from './harness';

package/src/transfer-diagnostic.ts

@@ -7,6 +7,8 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { type MessageParams, type ResolvedMessage } from './messages/primitives';
+
 /**
  * Generic, transport-friendly diagnostic shape used by the model-server protocol.
  *
@@ -56,6 +58,21 @@ export interface TransferDiagnostic {
     * is not usable as a rule identity on its own.
     */
    code?: number | string;
+   /**
+    * Substitutions for the placeholders in the message this {@link code} names,
+    * present only for a diagnostic raised from a framework message declaration.
+    *
+    * Without them a translated template renders with its `{name}` tokens left
+    * standing, because substitution leaves an unmatched token in place rather
+    * than raising — so a surface that translates from {@link code} alone is
+    * correct for a parameterless sentence and visibly wrong for a parameterised
+    * one. This is the field that makes the second case work; the LSP carrier has
+    * always moved the params, and no carrier below it did.
+    *
+    * Prefer {@link TransferDiagnostic.resolved} over reading this: it decides
+    * whether an identity is present at all, which a lone `params` cannot.
+    */
+   params?: MessageParams;
 }
 
 export namespace TransferDiagnostic {
@@ -74,6 +91,29 @@ export namespace TransferDiagnostic {
       return diagnostic.type === 'parsing-error';
    }
 
+   /**
+    * The diagnostic as a renderable message, for a surface that translates.
+    * `undefined` when it carries no framework identity — a syntactic error, an
+    * adopter's own check, a linker failure — which is the case a caller must
+    * distinguish rather than render.
+    *
+    * Hand the result to `renderFrameworkMessage` with whatever catalogue the
+    * host has loaded. The `text` is the server's English, so a code the
+    * catalogue does not carry still yields a complete sentence.
+    *
+    * `code` alone does not establish an identity: it also holds Langium's
+    * internal code and an adopter's own, and either would be looked up against a
+    * catalogue that cannot have it. Requiring `params` is what discriminates,
+    * and it is why a parameterless framework message still populates the field
+    * with an empty object rather than omitting it.
+    */
+   export function resolved(diagnostic: TransferDiagnostic): ResolvedMessage | undefined {
+      if (typeof diagnostic.code !== 'string' || diagnostic.params === undefined) {
+         return undefined;
+      }
+      return { code: diagnostic.code, params: diagnostic.params, text: diagnostic.message };
+   }
+
    export function getPath(diagnostic: TransferDiagnostic): string {
       return diagnostic.property ? `${diagnostic.element}${ELEMENT_PROPERTY_SEPARATOR}${diagnostic.property}` : diagnostic.element;
    }

package/src/transfer-document.ts

@@ -9,6 +9,7 @@
 
 import type { TransferDiagnostic } from './transfer-diagnostic';
 import type { TransferElement } from './transfer-element';
+import { asSnapshotVersion, type SnapshotVersion } from './model-service/based-on';
 
 /**
  * Wire envelope exchanged between the model-server's data-server head and
@@ -27,14 +28,14 @@ export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic
    uri: string;
    /**
     * The document version this snapshot was taken at — sourced from the
-    * server's text-document version counter. Callers that mutate the
-    * document subsequently pass this value back as `TransferUpdateArgs.baseVersion`
-    * (or `TransferSaveArgs.baseVersion`) so the server can detect stale-based
-    * updates and reject them with `ConflictError`.
+    * server's text-document version counter. A caller that mutates the document
+    * subsequently sends this straight back as `TransferUpdateArgs.basedOn` (or
+    * `TransferSaveArgs.basedOn`), and the server rejects a stale-based update
+    * with `ConflictError`.
     *
     * See `@hydranium/protocol#errors` for the conflict-detection contract.
     */
-   version: number;
+   version: SnapshotVersion;
    /**
     * Absent when the document does not exist — the server answers an unknown URI
     * with a shaped envelope rather than an error, so absence is an ordinary
@@ -82,6 +83,21 @@ export namespace TransferDocument {
       return document;
    }
 
+   /**
+    * The envelope for a document the server does not have — `root` absent, and
+    * the version a read of a URI the store never saw reports.
+    *
+    * Exists so the absent branch is built the same way the present one is: both
+    * doors mark the version as coming from a read, and neither asks a caller to
+    * do it.
+    */
+   export function absent<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(
+      uri: string,
+      diagnostics: TDiagnostic[] = []
+   ): TransferDocument<TTransfer, TDiagnostic> {
+      return { uri, version: asSnapshotVersion(0), root: undefined, diagnostics };
+   }
+
    /**
     * Construct a {@link TransferDocument} envelope. `diagnostics` defaults
     * to `[]` so test fixtures, fake protocol implementations, and the
@@ -94,6 +110,6 @@ export namespace TransferDocument {
       root: TTransfer,
       diagnostics: TDiagnostic[] = []
    ): TransferDocument<TTransfer, TDiagnostic> {
-      return { uri, version, root, diagnostics };
+      return { uri, version: asSnapshotVersion(version), root, diagnostics };
    }
 }