@hydranium/conformance 1.0.0-next.244 → 1.0.0-next.246

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +66 -96
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,47 +1,22 @@
1
1
  # `@hydranium/conformance`
2
2
 
3
- The protocol conformance kit — a TCK — for the
4
- [Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework.
5
-
6
- A TCK is a test suite you do not write: the framework ships the checks, and **you run them against
7
- your own server** to prove it actually speaks each head's protocol. You supply two things — a way to
8
- stand a server up (`connect`) and per-language fixtures (a valid and an invalid model) — and the kit
9
- emits one test per check in your own test runner, alongside your own suites.
10
-
11
- Install it if you are building a Hydranium head and want a protocol contract you did not have to
12
- author, and that keeps checking you as the framework moves.
3
+ The protocol conformance kit of the
4
+ [Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework. You
5
+ install it as a dev dependency to check that your server speaks each head's
6
+ protocol: you supply a way to start the server and a few models, and the kit
7
+ adds one test per check to your own test runner.
13
8
 
14
9
  ## What it gives you
15
10
 
16
- - **Per-head batteries**, one subpath each: `/data`, `/lsp` and `/glsp`. Importing one never pulls
17
- another head's protocol types in, so an LSP-only adopter takes no data-head surface.
18
- - **Driver ports rather than adapters.** Each slice names a minimal port — `DataConformanceDriver`,
19
- `LspConformanceDriver`, `GlspConformanceDriver<TAction>` — spelled in `@hydranium/protocol` types,
20
- plain coordinates and tiny structural minima. The framework's own harnesses
21
- (`DataServerHarness`, `LspHarness`, `GlspHarness`) satisfy them **structurally, with no adapter**,
22
- and so can a hand-rolled driver.
23
- - **Runner-agnostic core.** `ConformanceCheck`, `ConformanceRunner` and `emitConformanceSuite` name
24
- no test runner and assert with `node:assert/strict`; the thin `/vitest` and `/jest` adapters bind
25
- `describe` / `it` / `it.skip` / `afterAll`.
26
- - **Skips that are visible, not silent.** A check whose optional fixture input is absent is emitted
27
- as a named `it.skip`, and every suite prints a ran-vs-skipped summary (`formatSummary`), so a
28
- half-wired adopter reads as _skipped_ rather than as a green run.
29
- - **A false-green guard in the fixture type.** `LanguageFixture` requires **both** a `valid` and an
30
- `invalid` model, so an "invalid" model that in fact parses clean fails the diagnostics checks
31
- instead of passing vacuously.
32
- - **Server-side rendering, opt-in.** Supply `renderedDiagnostic: { locale, expected,
33
- absentWithLocale }` on a fixture and the `/lsp` battery declares that locale at `initialize`,
34
- then asserts the fragment appears — and, from `absentWithLocale`, that the untranslated fragment
35
- DISAPPEARS with the locale and is present without it. It is opt-in because the framework ships no
36
- catalogue and selects no locale, so a server that renders nothing is correct; and it is a PAIR
37
- because "the message contains X" alone passes for a server whose English contains X. Omit
38
- `absentWithLocale` and the control reports skipped rather than being quietly dropped.
39
- - **Client sessions, on the data head.** The `/data` battery opens and writes every document as a
40
- client session and holds the head to how sessions behave: a session writes and saves only what it
41
- has open, ids are refused while live or reserved, a write answers with its document's
42
- diagnostics, `text.dirty` follows the file, `text.hash` follows the text, and the release after the last close
43
- reverts a document to what its save wrote, or drops it when it was never saved. See
44
- [client sessions](../../docs/contributing/design/client-sessions.md).
11
+ - A battery of checks per head, data, LSP and GLSP, that you run against your
12
+ own server rather than write.
13
+ - A driver port per head that the framework's test harnesses already satisfy,
14
+ so you can pass a harness in, or write a driver of your own.
15
+ - Adapters for vitest and Jest; the checks themselves name no test runner.
16
+ - Skips you can see: a check whose optional input you did not supply shows up
17
+ skipped with its reason, and each suite prints what ran and what was skipped.
18
+ - A guard against a false green: every language needs an invalid model, so a
19
+ model that parses clean fails the diagnostics checks.
45
20
 
46
21
  ## Install
47
22
 
@@ -49,71 +24,66 @@ author, and that keeps checking you as the framework moves.
49
24
  npm install --save-dev @hydranium/conformance
50
25
  ```
51
26
 
52
- `@hydranium/protocol` is a required peer. The two runners are **optional** peers — `vitest` and
53
- `@jest/globals` — so you install only the one you use, and the core never loads the other. The
54
- package has no runtime dependencies of its own.
55
-
56
- ## Subpaths
57
-
58
- | Subpath | Contents |
59
- | ---------- | ----------------------------------------------------------- |
60
- | `.` | Fixture model + check/runner primitives. No head, no runner. |
61
- | `./data` | Data-head driver port + `buildDataChecks`. |
62
- | `./lsp` | LSP-head driver port + `buildLspChecks`. |
63
- | `./glsp` | GLSP-head driver port + `buildGlspChecks`. |
64
- | `./vitest` | Vitest adapter: `run{Data,Lsp,Glsp}Conformance`. |
65
- | `./jest` | Jest adapter: the same three entry points. |
27
+ | Peer | Range |
28
+ | --------------------- | ------------- |
29
+ | `@hydranium/protocol` | `^1.0.0-next` |
30
+ | `@jest/globals` | `^29.0.0` |
31
+ | `vitest` | `^4.0.0` |
66
32
 
67
- Resolve the subpaths with [a resolver that reads `exports`](../../docs/adopting/requirements.md#a-resolver-that-reads-exports);
68
- `"Node"` (node10) reaches none of them.
69
- The root barrel deliberately re-exports none of the slices.
33
+ `vitest` and `@jest/globals` are optional peers: install the runner you use.
70
34
 
71
35
  ## Usage
72
36
 
73
- In one test file per head, call the `run*Conformance` function from your runner's adapter subpath —
74
- `@hydranium/conformance/vitest` or `@hydranium/conformance/jest`. Both adapters also re-export the
75
- slice types (driver ports, options, fixtures), so a suite needs a single import site.
76
-
77
- Each takes `connect` plus `languages`:
78
-
79
- - **`connect`** returns a freshly wired driver and is called **once per check**, so checks cannot
80
- interfere; the kit disposes the driver afterwards. The data slice wants a server already ready; the
81
- LSP slice drives the `initialize` handshake itself, so `connect` must **not** pre-initialise; the
82
- GLSP slice drives `start()`. The data slice saves documents beside each fixture's `valid`, so its
83
- `connect` should give each check a workspace the kit may write to and throw away.
84
- - **`languages`** is an array of `LanguageFixture`: `valid` and `invalid` are required and read by
85
- every slice; every other field is an opt-in whose checks report **skipped with a named reason**
86
- when it is absent, so an opt-out stays distinguishable from lost coverage. Read the current set
87
- off the `LanguageFixture` type, which says per field which slice reads it and what supplying it
88
- claims — the two that carry the most are `edit` (a replacement text plus an `expect(root)`
89
- predicate, because only you know what "the edit landed" means for your grammar) and `dependent`
90
- (a document that references `valid`, which is what lets the data slice provoke a cascade; add
91
- `breakingEdit`, a text for `valid` that breaks that reference, and the slice also checks who a
92
- dependent's update event is credited to). A fixture's `uri` and `text` may be thunks, resolved
93
- after `connect`, which is how each check gets pristine input in a workspace `connect` just
94
- created.
95
-
96
- The GLSP slice is generic over your action type and takes `GlspFixture` per diagram type — the
97
- fixture builds the native actions and the kit matches responses by `kind`, so no `@eclipse-glsp/*`
98
- type enters the kit.
99
-
100
- Then run your normal test command:
101
-
102
- ```bash
103
- npx vitest run test/data-conformance.integration.test.ts
104
- ```
105
-
106
- The suite prints, per head, how many checks ran and which were skipped and why. For where this sits
107
- among the framework's test layers, see [`docs/contributing/testing.md`](../../docs/contributing/testing.md).
37
+ Write one test file per head, and call the `run*Conformance` function from
38
+ your runner's adapter, `@hydranium/conformance/vitest` or
39
+ `@hydranium/conformance/jest`. The adapter also exports the driver ports, the
40
+ options and `GlspFixture`; `LanguageFixture` comes from the package root.
41
+
42
+ Each function takes `connect` and `languages`:
43
+
44
+ - **`connect`** returns a freshly wired driver. The kit calls it once per check
45
+ and disposes the driver afterwards, so checks cannot interfere. The data
46
+ slice wants the server ready, and saves documents beside each fixture's
47
+ `valid`, so give each check a workspace the kit may write to and throw away.
48
+ The LSP slice drives the `initialize` handshake itself, so `connect` must not
49
+ initialise. The GLSP slice calls `start()` itself.
50
+ - **`languages`** is an array of `LanguageFixture`. `valid` and `invalid` are
51
+ required, and every slice reads them. Every other field is opt-in: when you
52
+ leave it out, its checks report skipped with a named reason. The
53
+ `LanguageFixture` type says, per field, which slice reads it and what
54
+ supplying it claims. A fixture's `uri` and `text` may be functions, read
55
+ after `connect`, so they can point into the workspace `connect` just made.
56
+
57
+ The GLSP slice is generic over your action type and takes a `GlspFixture` per
58
+ diagram type. The fixture builds your native actions, and the kit matches the
59
+ responses by `kind`.
60
+
61
+ For where the kit fits among your other tests, see *Test your language* in
62
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
63
+
64
+ ## Entry points
65
+
66
+ | Subpath | Use it for | Runs in |
67
+ | ---------- | ------------------------------------------------------------ | ------- |
68
+ | `.` | `LanguageFixture` and the runner-agnostic check primitives. | Node |
69
+ | `./data` | The data-head checks and driver port. | Node |
70
+ | `./lsp` | The LSP-head checks and driver port. | Node |
71
+ | `./glsp` | The GLSP-head checks and driver port. | Node |
72
+ | `./vitest` | Run the checks under vitest. | Node |
73
+ | `./jest` | Run the checks under Jest. | Node |
74
+
75
+ The subpaths need a TypeScript `moduleResolution` that reads `exports`
76
+ (`NodeNext` or `Bundler`); see *Requirements* in
77
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
108
78
 
109
79
  ## Status
110
80
 
111
- Alpha — pre-v0, published as a `1.0.0-next` prerelease on every merge to `main`. The check batteries
112
- are being populated incrementally and the driver ports are not yet stable — a new check can turn a
113
- passing adopter red by design. See the [repository README](../../README.md) for the current status
114
- and known limitations.
81
+ Alpha: every release is a prerelease that may break the API, so pin an exact
82
+ version. Guides and known limitations:
83
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
115
84
 
116
85
  ## License
117
86
 
118
87
  `MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
119
- [`NOTICE.md`](../../NOTICE.md) for third-party notices.
88
+ [`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
89
+ for third-party notices.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hydranium/conformance",
3
- "version": "1.0.0-next.244",
3
+ "version": "1.0.0-next.246",
4
4
  "description": "Protocol conformance kit (TCK) for hydranium adopters. Per-head slices (/data, /lsp, /glsp) of fixture-parameterized, protocol-only smoke checks an adopter runs against its own server.",
5
5
  "keywords": [
6
6
  "conformance",
@@ -71,7 +71,7 @@
71
71
  "watch": "tsc -b -w --preserveWatchOutput"
72
72
  },
73
73
  "devDependencies": {
74
- "@hydranium/protocol": "1.0.0-next.244",
74
+ "@hydranium/protocol": "1.0.0-next.246",
75
75
  "@jest/globals": "^29.7.0",
76
76
  "@types/jest": "^29.5.12",
77
77
  "esbuild": "^0.28.0",
@@ -81,7 +81,7 @@
81
81
  "vitest": "^4.0.0"
82
82
  },
83
83
  "peerDependencies": {
84
- "@hydranium/protocol": "1.0.0-next.244",
84
+ "@hydranium/protocol": "1.0.0-next.246",
85
85
  "@jest/globals": "^29.0.0",
86
86
  "vitest": "^4.0.0"
87
87
  },