@hydranium/conformance 1.0.0-next.23 → 1.0.0-next.232

package/README.md

@@ -29,6 +29,19 @@ author, and that keeps checking you as the framework moves.
 - **A false-green guard in the fixture type.** `LanguageFixture` requires **both** a `valid` and an
   `invalid` model, so an "invalid" model that in fact parses clean fails the diagnostics checks
   instead of passing vacuously.
+- **Server-side rendering, opt-in.** Supply `renderedDiagnostic: { locale, expected,
+  absentWithLocale }` on a fixture and the `/lsp` battery declares that locale at `initialize`,
+  then asserts the fragment appears — and, from `absentWithLocale`, that the untranslated fragment
+  DISAPPEARS with the locale and is present without it. It is opt-in because the framework ships no
+  catalogue and selects no locale, so a server that renders nothing is correct; and it is a PAIR
+  because "the message contains X" alone passes for a server whose English contains X. Omit
+  `absentWithLocale` and the control reports skipped rather than being quietly dropped.
+- **Client sessions, on the data head.** The `/data` battery opens and writes every document as a
+  client session and holds the head to how sessions behave: a session writes and saves only what it
+  has open, ids are refused while live or reserved, a write answers with its document's
+  diagnostics, `text.dirty` follows the file, `text.hash` follows the text, and the release after the last close
+  reverts a document to what its save wrote, or drops it when it was never saved. See
+  [client sessions](../../docs/concepts/client-sessions.md).
 
 ## Install
 
@@ -51,8 +64,9 @@ package has no runtime dependencies of its own.
 | `./vitest` | Vitest adapter: `run{Data,Lsp,Glsp}Conformance`.             |
 | `./jest`   | Jest adapter: the same three entry points.                   |
 
-Each named subpath also resolves as `@hydranium/conformance/lib/<name>`, so a consumer on classic
-`moduleResolution: "Node"` can reach it. The root barrel deliberately re-exports none of the slices.
+Resolve the subpaths with [a resolver that reads `exports`](../../docs/adopting/requirements.md#a-resolver-that-reads-exports);
+`"Node"` (node10) reaches none of them.
+The root barrel deliberately re-exports none of the slices.
 
 ## Usage
 
@@ -65,12 +79,19 @@ Each takes `connect` plus `languages`:
 - **`connect`** returns a freshly wired driver and is called **once per check**, so checks cannot
   interfere; the kit disposes the driver afterwards. The data slice wants a server already ready; the
   LSP slice drives the `initialize` handshake itself, so `connect` must **not** pre-initialise; the
-  GLSP slice drives `start()`.
-- **`languages`** is an array of `LanguageFixture`: `valid` and `invalid` (both read by every
-  slice), plus two opt-ins — `edit` (data slice only: a replacement text and an `expect(root)`
-  predicate, because only you know what "the edit landed" means for your grammar) and
-  `completionPosition` (LSP slice only). A fixture's `uri` and `text` may be thunks, resolved after
-  `connect`, which is how each check gets pristine input in a workspace `connect` just created.
+  GLSP slice drives `start()`. The data slice saves documents beside each fixture's `valid`, so its
+  `connect` should give each check a workspace the kit may write to and throw away.
+- **`languages`** is an array of `LanguageFixture`: `valid` and `invalid` are required and read by
+  every slice; every other field is an opt-in whose checks report **skipped with a named reason**
+  when it is absent, so an opt-out stays distinguishable from lost coverage. Read the current set
+  off the `LanguageFixture` type, which says per field which slice reads it and what supplying it
+  claims — the two that carry the most are `edit` (a replacement text plus an `expect(root)`
+  predicate, because only you know what "the edit landed" means for your grammar) and `dependent`
+  (a document that references `valid`, which is what lets the data slice provoke a cascade; add
+  `breakingEdit`, a text for `valid` that breaks that reference, and the slice also checks who a
+  dependent's update event is credited to). A fixture's `uri` and `text` may be thunks, resolved
+  after `connect`, which is how each check gets pristine input in a workspace `connect` just
+  created.
 
 The GLSP slice is generic over your action type and takes `GlspFixture` per diagram type — the
 fixture builds the native actions and the kit matches responses by `kind`, so no `@eclipse-glsp/*`
@@ -87,9 +108,10 @@ among the framework's test layers, see [`docs/contributing/testing.md`](../../do
 
 ## Status
 
-Alpha — pre-v0, not yet published. The check batteries are being populated incrementally and the
-driver ports are not yet stable — a new check can turn a passing adopter red by design. See the
-[repository README](../../README.md) for the current status and known limitations.
+Alpha — pre-v0, published as a `1.0.0-next` prerelease on every merge to `main`. The check batteries
+are being populated incrementally and the driver ports are not yet stable — a new check can turn a
+passing adopter red by design. See the [repository README](../../README.md) for the current status
+and known limitations.
 
 ## License
 

package/lib/data/index.d.ts

@@ -7,28 +7,40 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { type TransferDiagnostic, type TransferElement } from '@hydranium/protocol';
-import type { DataServerProtocol, TransferDocumentUpdatedEvent } from '@hydranium/protocol/data';
+import type { DataServerProtocol, ReferenceServerProtocol, TransferDocumentsBuiltEvent, TransferDocumentUpdatedEvent } from '@hydranium/protocol/data';
 import { type Harness } from '@hydranium/protocol/testing';
 import type { ConformanceCheck } from '../conformance-suite.js';
 import { type LanguageFixture } from '../model.js';
 /**
  * The data-server driver port — a live, connected, READY data-server exposed
- * through its protocol-native proxy plus the captured client-side update
- * events. The kit names only `@hydranium/protocol` types, so a
+ * through its protocol-native proxy plus the captured client-side
+ * notifications. The kit names only `@hydranium/protocol` types, so a
  * `DataServerHarness` satisfies the port structurally (it has `proxy` +
- * `events` + `dispose`) with NO adapter. `extends Harness` gives the kit the
+ * `events`, `builds` and `dispose`) with NO adapter. `extends Harness` gives the kit the
  * universal `dispose()` teardown.
  *
- * The kit seeds documents purely through the proxy: `updateModelDocument` is
- * an upsert (it creates a cold URI from the payload, not just modifies an
- * existing one), so the slice needs no services-level open hook. The adopter
- * only has to stand the server up READY in its `connect` — see
- * {@link DataConformanceOptions.connect}.
+ * The kit seeds documents purely through the proxy, as client sessions: it
+ * registers one with `createSession`, opens the document, or creates it with
+ * `createModelDocument` when there is no file to open, and writes it. So the
+ * head under test must implement sessions, and the slice needs no
+ * services-level open hook. The adopter only has to stand the server up READY
+ * in its `connect` — see {@link DataConformanceOptions.connect}.
  */
 export interface DataConformanceDriver<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> extends Harness {
     readonly proxy: DataServerProtocol<TTransfer, TDiagnostic>;
-    /** Captured `onDocumentUpdated` events, append order — the subscription check's observation target. */
+    /** Captured `onDocumentUpdated` events, in append order. */
     readonly events: ReadonlyArray<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
+    /** Captured `onDocumentsBuilt` events, append order — the cascade check's observation target. */
+    readonly builds: ReadonlyArray<TransferDocumentsBuiltEvent>;
+    /**
+     * The opt-in reference surface, when the head serves it.
+     *
+     * Separate from {@link proxy} because `ReferenceServerProtocol` is NOT part
+     * of `DataServerProtocol` — a head may serve documents and no references at
+     * all. Absent means the reference check reports skipped with a named reason
+     * rather than failing a head that never claimed the surface.
+     */
+    readonly references?: ReferenceServerProtocol;
 }
 /** Options for `runDataConformance`. */
 export interface DataConformanceOptions<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
@@ -37,6 +49,10 @@ export interface DataConformanceOptions<TTransfer extends TransferElement, TDiag
      * once per check for isolation; the kit disposes it after the check. The
      * adopter must initialise the workspace before returning, so `waitForReady`
      * resolves rather than hanging.
+     *
+     * Some checks save documents beside each fixture's `valid`, and nothing in
+     * the protocol deletes a file, so give each check a workspace the kit may
+     * write to and throw away.
      */
     readonly connect: () => DataConformanceDriver<TTransfer, TDiagnostic> | Promise<DataConformanceDriver<TTransfer, TDiagnostic>>;
     /** Per-language fixtures; the grammar-bearing checks run once per language. */
@@ -52,6 +68,13 @@ export interface DataConformanceOptions<TTransfer extends TransferElement, TDiag
      * from "never implemented" without the adopter saying which it is.
      */
     readonly expectsProjects?: boolean;
+    /**
+     * Open another connection to the same server as `driver`, for the check
+     * that a connection's sessions end with it while the server lives on. That
+     * check disposes `driver` and needs its `dispose` to close the connection as
+     * the server sees it. Absent, the check reports skipped.
+     */
+    readonly attach?: (driver: DataConformanceDriver<TTransfer, TDiagnostic>) => DataConformanceDriver<TTransfer, TDiagnostic> | Promise<DataConformanceDriver<TTransfer, TDiagnostic>>;
     /** Suite title override. Default `'conformance: data-server'`. */
     readonly suiteTitle?: string;
 }
@@ -62,7 +85,7 @@ export interface DataConformanceOptions<TTransfer extends TransferElement, TDiag
  * unit tests; adopters call `runDataConformance`.
  *
  * `LanguageFixture.edit` is read HERE and nowhere else in the kit, and is
- * optional: its two checks report skipped when it is absent. See
+ * optional: every check that needs one reports skipped when it is absent. See
  * {@link LanguageFixture} for which slice reads which field.
  */
 export declare function buildDataChecks<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic>(options: DataConformanceOptions<TTransfer, TDiagnostic>): ConformanceCheck[];

package/lib/data/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAWlF,OAAO,EAAoB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,KAAK,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACjG,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,KAAK,eAAe,EAAiC,MAAM,aAAa,CAAC;AAElF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,qBAAqB,CACnC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,CAC5D,SAAQ,OAAO;IACd,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC3D,uGAAuG;IACvG,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;CACvF;AAED,wCAAwC;AACxC,MAAM,WAAW,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IACnI;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAC/H,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACnD;;;;;;;;;OASG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC/B;AAeD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3H,OAAO,EAAE,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,GACvD,gBAAgB,EAAE,CAsMpB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAWlF,OAAO,EAWJ,KAAK,kBAAkB,EACvB,KAAK,eAAe,EAEtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACT,kBAAkB,EAClB,uBAAuB,EACvB,2BAA2B,EAC3B,4BAA4B,EAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,KAAK,eAAe,EAAiC,MAAM,aAAa,CAAC;AAElF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB,CACnC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,CAC5D,SAAQ,OAAO;IACd,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC3D,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACrF,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,2BAA2B,CAAC,CAAC;IAC5D;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAC;CAChD;AAED,wCAAwC;AACxC,MAAM,WAAW,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IACnI;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAC/H,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACnD;;;;;;;;;OASG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CACf,MAAM,EAAE,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,KACnD,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAC5G,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC/B;AA6HD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3H,OAAO,EAAE,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,GACvD,gBAAgB,EAAE,CAq8BpB"}