@hydranium/core 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 +64 -87
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,43 +1,19 @@
1
1
  # `@hydranium/core`
2
2
 
3
- The framework runtime of [hydranium](../../README.md): the shared Langium
4
- workspace an adopter's modeling-language server is built from, plus the LSP
5
- textual head folded in at the `/lsp` subpath. Every adopter server installs it,
6
- and so does every other head package (`@hydranium/data-server`,
7
- `@hydranium/glsp-server`).
3
+ The runtime of [Hydranium](https://github.com/eclipse-emfcloud/hydranium): the
4
+ shared Langium workspace your language server is built from, plus the LSP head.
5
+ Every Hydranium server installs it, and `@hydranium/data-server` and
6
+ `@hydranium/glsp-server` build on it.
8
7
 
9
8
  ## What it gives you
10
9
 
11
- - **A composable services tree.** `createServerSharedModule` and
12
- `createServerLanguageModule` supply the shared- and language-tier DI slots;
13
- `bootstrapLangium` registers a language on the shared `ServiceRegistry`,
14
- asserts the core slots are bound, and eager-constructs the services that must
15
- exist before the first build.
16
- - **Semantics layered onto the AST** that an adopter would otherwise rewrite per
17
- language: tiered scoping (`HydraniumScopeProvider`,
18
- `ReferenceCandidateProvider`), qualified naming (`NameProvider`), computed and
19
- synthetic properties (`AstExtensionService`), AST-integrity rules
20
- (`IntegrityRule`, `IntegrityRuleRegistry`), batch build passes
21
- (`BuildPhasePassService`), and a CST-residency memory policy
22
- (`CstResidencyService`).
23
- - **A build pipeline you can hook by phase.** `HydraniumDocumentBuilder` and
24
- `BuildPipelineIntegration` dispatch work at Langium `DocumentState` phases,
25
- while the project tier (`ProjectManager`) discovers and groups documents.
26
- - **Multi-client document coordination.** `AstDocumentManager` and
27
- `HydraniumTextDocuments` generalise the LSP document lifecycle to several
28
- co-editing heads, so an edit made on one surface is observable on the others
29
- without a head-to-head synchronisation protocol. A participant works through
30
- a `ClientSession` from `ModelService.createSession`, which writes only what it
31
- has open; see [how it works](../../docs/concepts/how-it-works.md#documents-sessions-and-saves). Saves
32
- go through a `WritableFileSystemProvider`, and `SelfSaveRegistry` keeps the
33
- server's own writes from coming back as external changes.
34
- - **The projection the non-LSP heads build on:** `ModelService` (the in-process
35
- workspace facade), `TransferEncoder` (AST → transfer model), and the
36
- `Serializer` slot.
37
- - **The LSP head at `./lsp`:** `startLanguageServer`,
38
- `createLspServerSharedModule` / `createLspServerLanguageModule`,
39
- `HydraniumCompletionProvider`, `HydraniumDocumentUpdateHandler`, and
40
- `AbstractHydraniumSemanticTokenProvider`.
10
+ - One call, `createIntegrationServices`, that composes your language's services
11
+ with Langium's defaults and the framework's.
12
+ - Scoping, naming, validation and build hooks you extend per language, rather
13
+ than rewrite.
14
+ - One workspace every head works on: an edit made through one head is seen by
15
+ the others.
16
+ - The LSP head, and launchers that serve another head over stdio or a socket.
41
17
 
42
18
  ## Install
43
19
 
@@ -45,61 +21,62 @@ and so does every other head package (`@hydranium/data-server`,
45
21
  npm install @hydranium/core
46
22
  ```
47
23
 
48
- Nothing is bundled for you — the peers must be present in the consuming project:
49
-
50
- - `@hydranium/protocol` (the wire contract) and `@hydranium/langium` (the pinned
51
- Langium re-export). Import Langium through `@hydranium/langium` so the whole
52
- workspace resolves one physical copy of it.
53
- - `vscode-jsonrpc`, `vscode-languageserver`, `vscode-languageserver-protocol`,
54
- `vscode-languageserver-textdocument`, `vscode-languageserver-types`.
55
- - `@playwright/test` — optional, and needed only for `./testing/playwright`.
56
-
57
- The single bundled runtime dependency is `diff`. You also need a Langium grammar
58
- and its generated AST already in place; `hydranium-cli init` scaffolds both.
59
-
60
- ## Exports
61
-
62
- | subpath | holds | platform |
63
- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
64
- | `.` | The head-neutral framework core: DI modules, AST semantics, build pipeline, model coordination. | browser-neutral |
65
- | `./lsp` | The LSP textual head — `startLanguageServer`, its two DI modules, and the Langium-LSP overrides. | browser-neutral |
66
- | `./node` | Server-only: `DefaultFileSystemProvider` / `NodeFileSystem`, `startStdioServer`, `startSocketServer`, `publishPortOnLspConnection`, and the headless tools `validateWorkspace` / `reflectGrammar` / `lintGrammar`. | Node-only |
67
- | `./messages` | Every user-facing message the package raises, by code — what a translation catalogue keys on. | browser-neutral |
68
- | `./testing` | Langium-layer doubles plus `makeTestServices` and `makeFakeDocument`. | browser-neutral |
69
- | `./testing/node` | Test support that needs a real filesystem, a stream transport or a child process: scratch workspace, golden corpus, `makeLspHarness`, `startSpawnedServer`. | Node-only |
70
- | `./testing/playwright`| Playwright fixtures for end-to-end profiling and server-log capture. | Node-only |
71
-
72
- The browser-neutral entries are gated in CI (`scripts/check-neutral-bundles.mts`
73
- bundles them for the browser and fails on a `node:*` import, including a
74
- transitive one) — see [what "gated neutral" does and does not promise](../../docs/contributing/design/browser-hosting.md#what-gated-neutral-does-and-does-not-promise).
75
- Resolve the subpaths with [a resolver that reads
76
- `exports`](../../docs/adopting/requirements.md#a-resolver-that-reads-exports);
77
- `"Node"` (node10) reaches none of them.
78
-
79
- Importing `./node` has two deliberate side effects at module load: it installs
80
- the `node:fs`-backed log-file sink and the `node:async_hooks`-backed write-lock
81
- reentrancy check, both of which the neutral tree can only declare.
82
-
83
- ## Getting oriented
84
-
85
- A server composes one shared services tree per process and one language module
86
- per grammar, then hands that tree to whichever heads it wants to run. The
87
- worked, compiling version of that composition is the compose-a-server guide in
88
- [Adopting Hydranium](../../docs/ADOPTING.md), which also explains the layering
89
- behind it. The class-role naming, the `./node`
90
- boundary and the registration-contribution pattern the services follow are in
91
- [`docs/contributing/conventions.md`](../../docs/contributing/conventions.md).
24
+ | Peer | Range |
25
+ | ------------------------------------ | ------------- |
26
+ | `@hydranium/langium` | `^1.0.0-next` |
27
+ | `@hydranium/protocol` | `^1.0.0-next` |
28
+ | `@playwright/test` | `^1.40.0` |
29
+ | `vscode-jsonrpc` | `^9.0.0` |
30
+ | `vscode-languageserver` | `~10.0.1` |
31
+ | `vscode-languageserver-protocol` | `~3.18.1` |
32
+ | `vscode-languageserver-textdocument` | `^1.0.12` |
33
+ | `vscode-languageserver-types` | `^3.17.5` |
34
+
35
+ Import Langium through `@hydranium/langium`, so your project uses the same copy
36
+ as the framework. `@playwright/test` is optional; only `./testing/playwright`
37
+ needs it.
38
+
39
+ ## Wiring
40
+
41
+ `hydranium-cli init` scaffolds a starter grammar and all of this wiring.
42
+
43
+ 1. Compose the services with `createIntegrationServices`, passing
44
+ `createLspServerSharedModule` and `createLspServerLanguageModule` as the
45
+ extra modules. Your language module binds a `Serializer`.
46
+ 2. Create the LSP connection with `withHydraniumLspFeatures`, and start it with
47
+ `startLanguageServer` from `./lsp`, not Langium's: it fails the start when
48
+ the LSP shared module is missing.
49
+ 3. Start other heads on the same shared services, with `startSocketServer` and
50
+ `publishPortOnLspConnection` beside the LSP head, or `startStdioServer`
51
+ alone.
52
+
53
+ See *Compose a server by hand* and *Add a validation check* in
54
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
55
+
56
+ ## Entry points
57
+
58
+ | Subpath | Use it for | Runs in |
59
+ | ---------------------- | ---------------------------------------------------------------------------- | --------------- |
60
+ | `.` | Composing services and extending the language's semantics | browser-neutral |
61
+ | `./lsp` | The LSP head and its modules | browser-neutral |
62
+ | `./node` | The Node filesystem, the stdio and socket launchers, the headless tools | Node-only |
63
+ | `./messages` | Validation messages with stable codes, and the codes this package raises | browser-neutral |
64
+ | `./testing` | Parsing and service doubles for unit tests | browser-neutral |
65
+ | `./testing/node` | Scratch workspaces, the LSP harness, a spawned server | Node-only |
66
+ | `./testing/playwright` | Playwright fixtures that capture the server log | Node-only |
67
+
68
+ The subpaths need a TypeScript `moduleResolution` that reads `exports`
69
+ (`NodeNext` or `Bundler`); see *Requirements* in
70
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
92
71
 
93
72
  ## Status
94
73
 
95
- Alpha — pre-v0, published as a `1.0.0-next` prerelease on every merge to `main`.
96
- The API is not stable and may change without a deprecation cycle. See the
97
- [repository README](../../README.md) for the current status and known
98
- limitations.
99
-
100
- For task-shaped adoption paths, start with the [validation check guide](../../docs/guides/add-validation-check.md). It shows the validation contribution boundary that this package supplies.
74
+ Alpha: every release is a prerelease that may break the API, so pin an exact
75
+ version. Guides and known limitations:
76
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
101
77
 
102
78
  ## License
103
79
 
104
- `MIT` — see this package's [`LICENSE`](./LICENSE). Third-party notices for the
105
- repository are recorded in [`NOTICE.md`](../../NOTICE.md).
80
+ `MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
81
+ [`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
82
+ for third-party notices.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hydranium/core",
3
- "version": "1.0.0-next.244",
3
+ "version": "1.0.0-next.246",
4
4
  "description": "Foundational runtime of the hydranium framework: AST coordination layer (services, integrity, AST extension, serialization, multi-client documents) plus the LSP textual head at the /lsp subpath. Consumed by protocol-head packages (@hydranium/data-server, @hydranium/glsp-server).",
5
5
  "keywords": [
6
6
  "ast",
@@ -83,8 +83,8 @@
83
83
  "diff": "^5.2.0"
84
84
  },
85
85
  "devDependencies": {
86
- "@hydranium/langium": "1.0.0-next.244",
87
- "@hydranium/protocol": "1.0.0-next.244",
86
+ "@hydranium/langium": "1.0.0-next.246",
87
+ "@hydranium/protocol": "1.0.0-next.246",
88
88
  "@playwright/test": "^1.40.0",
89
89
  "@types/diff": "^5.2.0",
90
90
  "rimraf": "^5.0.0",
@@ -96,8 +96,8 @@
96
96
  "vscode-languageserver-types": "^3.17.5"
97
97
  },
98
98
  "peerDependencies": {
99
- "@hydranium/langium": "1.0.0-next.244",
100
- "@hydranium/protocol": "1.0.0-next.244",
99
+ "@hydranium/langium": "1.0.0-next.246",
100
+ "@hydranium/protocol": "1.0.0-next.246",
101
101
  "@playwright/test": "^1.40.0",
102
102
  "vscode-jsonrpc": "^9.0.0",
103
103
  "vscode-languageserver": "~10.0.1",