@hydranium/conformance 1.0.0-next.25 → 1.0.0-next.251

package/README.md

@@ -1,34 +1,22 @@
 # `@hydranium/conformance`
 
-The protocol conformance kit — a TCK — for the
-[Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework.
-
-A TCK is a test suite you do not write: the framework ships the checks, and **you run them against
-your own server** to prove it actually speaks each head's protocol. You supply two things — a way to
-stand a server up (`connect`) and per-language fixtures (a valid and an invalid model) — and the kit
-emits one test per check in your own test runner, alongside your own suites.
-
-Install it if you are building a Hydranium head and want a protocol contract you did not have to
-author, and that keeps checking you as the framework moves.
+The protocol conformance kit of the
+[Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework. You
+install it as a dev dependency to check that your server speaks each head's
+protocol: you supply a way to start the server and a few models, and the kit
+adds one test per check to your own test runner.
 
 ## What it gives you
 
-- **Per-head batteries**, one subpath each: `/data`, `/lsp` and `/glsp`. Importing one never pulls
-  another head's protocol types in, so an LSP-only adopter takes no data-head surface.
-- **Driver ports rather than adapters.** Each slice names a minimal port — `DataConformanceDriver`,
-  `LspConformanceDriver`, `GlspConformanceDriver<TAction>` — spelled in `@hydranium/protocol` types,
-  plain coordinates and tiny structural minima. The framework's own harnesses
-  (`DataServerHarness`, `LspHarness`, `GlspHarness`) satisfy them **structurally, with no adapter**,
-  and so can a hand-rolled driver.
-- **Runner-agnostic core.** `ConformanceCheck`, `ConformanceRunner` and `emitConformanceSuite` name
-  no test runner and assert with `node:assert/strict`; the thin `/vitest` and `/jest` adapters bind
-  `describe` / `it` / `it.skip` / `afterAll`.
-- **Skips that are visible, not silent.** A check whose optional fixture input is absent is emitted
-  as a named `it.skip`, and every suite prints a ran-vs-skipped summary (`formatSummary`), so a
-  half-wired adopter reads as _skipped_ rather than as a green run.
-- **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.
+- A battery of checks per head, data, LSP and GLSP, that you run against your
+  own server rather than write.
+- A driver port per head that the framework's test harnesses already satisfy,
+  so you can pass a harness in, or write a driver of your own.
+- Adapters for vitest and Jest; the checks themselves name no test runner.
+- Skips you can see: a check whose optional input you did not supply shows up
+  skipped with its reason, and each suite prints what ran and what was skipped.
+- A guard against a false green: every language needs an invalid model, so a
+  model that parses clean fails the diagnostics checks.
 
 ## Install
 
@@ -36,62 +24,66 @@ author, and that keeps checking you as the framework moves.
 npm install --save-dev @hydranium/conformance
 ```
 
-`@hydranium/protocol` is a required peer. The two runners are **optional** peers — `vitest` and
-`@jest/globals` — so you install only the one you use, and the core never loads the other. The
-package has no runtime dependencies of its own.
-
-## Subpaths
+| Peer                  | Range         |
+| --------------------- | ------------- |
+| `@hydranium/protocol` | `^1.0.0-next` |
+| `@jest/globals`       | `^29.0.0`     |
+| `vitest`              | `^4.0.0`      |
 
-| Subpath    | Contents                                                    |
-| ---------- | ----------------------------------------------------------- |
-| `.`        | Fixture model + check/runner primitives. No head, no runner. |
-| `./data`   | Data-head driver port + `buildDataChecks`.                   |
-| `./lsp`    | LSP-head driver port + `buildLspChecks`.                     |
-| `./glsp`   | GLSP-head driver port + `buildGlspChecks`.                   |
-| `./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.
+`vitest` and `@jest/globals` are optional peers: install the runner you use.
 
 ## Usage
 
-In one test file per head, call the `run*Conformance` function from your runner's adapter subpath —
-`@hydranium/conformance/vitest` or `@hydranium/conformance/jest`. Both adapters also re-export the
-slice types (driver ports, options, fixtures), so a suite needs a single import site.
-
-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.
-
-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/*`
-type enters the kit.
-
-Then run your normal test command:
-
-```bash
-npx vitest run test/data-conformance.integration.test.ts
-```
-
-The suite prints, per head, how many checks ran and which were skipped and why. For where this sits
-among the framework's test layers, see [`docs/contributing/testing.md`](../../docs/contributing/testing.md).
+Write one test file per head, and call the `run*Conformance` function from
+your runner's adapter, `@hydranium/conformance/vitest` or
+`@hydranium/conformance/jest`. The adapter also exports the driver ports, the
+options and `GlspFixture`; `LanguageFixture` comes from the package root.
+
+Each function takes `connect` and `languages`:
+
+- **`connect`** returns a freshly wired driver. The kit calls it once per check
+  and disposes the driver afterwards, so checks cannot interfere. The data
+  slice wants the server ready, and saves documents beside each fixture's
+  `valid`, so give each check a workspace the kit may write to and throw away.
+  The LSP slice drives the `initialize` handshake itself, so `connect` must not
+  initialise. The GLSP slice calls `start()` itself.
+- **`languages`** is an array of `LanguageFixture`. `valid` and `invalid` are
+  required, and every slice reads them. Every other field is opt-in: when you
+  leave it out, its checks report skipped with a named reason. The
+  `LanguageFixture` type says, per field, which slice reads it and what
+  supplying it claims. A fixture's `uri` and `text` may be functions, read
+  after `connect`, so they can point into the workspace `connect` just made.
+
+The GLSP slice is generic over your action type and takes a `GlspFixture` per
+diagram type. The fixture builds your native actions, and the kit matches the
+responses by `kind`.
+
+For where the kit fits among your other tests, see *Test your language* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## Entry points
+
+| Subpath    | Use it for                                                   | Runs in |
+| ---------- | ------------------------------------------------------------ | ------- |
+| `.`        | `LanguageFixture` and the runner-agnostic check primitives.  | Node    |
+| `./data`   | The data-head checks and driver port.                        | Node    |
+| `./lsp`    | The LSP-head checks and driver port.                         | Node    |
+| `./glsp`   | The GLSP-head checks and driver port.                        | Node    |
+| `./vitest` | Run the checks under vitest.                                 | Node    |
+| `./jest`   | Run the checks under Jest.                                   | Node    |
+
+The subpaths need a TypeScript `moduleResolution` that reads `exports`
+(`NodeNext` or `Bundler`); see *Requirements* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
 
 ## 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: every release is a prerelease that may break the API, so pin an exact
+version. Guides and known limitations:
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
 
 ## License
 
 `MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
-[`NOTICE.md`](../../NOTICE.md) for third-party notices.
+[`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
+for third-party notices.

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"}