@hydranium/langium 1.0.0-next.245 → 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 +30 -66
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,50 +1,20 @@
1
1
  # `@hydranium/langium`
2
2
 
3
- The pinned [Langium](https://langium.org/) re-export for the
4
- [Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework — the single chokepoint every
5
- `@hydranium/*` package, and every adopter of them, imports Langium through.
6
-
7
- You do not install this for its own API: it is almost entirely passthrough. You install it because a
8
- framework package will resolve it anyway, and because importing Langium through it is how your
9
- project stays in lockstep with the version the framework was built against.
10
-
11
- ## Why this package exists
12
-
13
- Langium is pinned to **one exact version** here, to guarantee a **single physical copy** across the
14
- workspace. Re-export is transparent — given one physical install, importing `AstUtils` or
15
- `OperationCancelled` from `@hydranium/langium` and from `langium` yields the same object and the
16
- same declaration. That transparency is exactly what a split install destroys: two copies of Langium
17
- mean two sets of declarations, which TypeScript refuses to mix, and two sets of module-level values,
18
- so one that Langium compares by identity, such as its cancellation signal, is not recognised by the
19
- other copy. The framework refuses to start a server whose AST reflection is built on a copy other
20
- than its own. Without the pin, single-copy is only a semver-dedup coincidence, one minor bump away
21
- from breaking.
22
-
23
- For an **adopter**, the reason to route imports here is not runtime identity (that already holds) —
24
- it is **version coupling**. Langium sits in a chain with `vscode-languageserver`,
25
- `vscode-languageserver-protocol` and `vscode-jsonrpc`, whose links move together. An
26
- adopter importing `langium` directly owns that pin itself and can drift out of lockstep with the
27
- framework it composes; importing it from here means the framework owns it.
28
-
29
- The chokepoint is **lint-enforced**, not merely conventional: an oxlint
30
- `no-restricted-imports` rule over `packages/**` and `examples/**` rejects direct imports of
31
- `langium`, `langium/lsp`, `langium/node`, `langium/test` and `vscode-uri` (whose `URI` Langium
32
- re-exports and owns the version of). This package itself is exempt, as is any `generated` directory —
33
- `langium-cli` emits direct imports there and rewrites them on every build, which is also why
34
- `langium` stays a declared dependency of an adopter's own package.
3
+ [Langium](https://langium.org/), re-exported for the
4
+ [Hydranium](https://github.com/eclipse-emfcloud/hydranium) framework. Import
5
+ Langium through this package so your install has one copy of it and the
6
+ framework owns the Langium version chain. `@hydranium/core` takes it as a peer,
7
+ so you install it alongside.
35
8
 
36
9
  ## What it gives you
37
10
 
38
- - Langium's full API surface, re-exported: `AstNode`, `AstUtils`, `URI`, `UriUtils`, the service
39
- types, the DI helpers — everything, unfiltered.
40
- - A subpath per upstream subpath, so `langium/lsp`, `langium/node` and `langium/test` each have a
41
- chokepoint mirror.
42
- - One ambient type augmentation: `AstNode.$synthetic`, a marker for a node that was programmatically
43
- constructed rather than parsed. Type-level only — the behaviour that reads it lives in
44
- `@hydranium/core`.
45
- - Two additions to the `UriUtils` namespace, so framework URI helpers sit beside Langium's own:
46
- `UriUtils.toUri` (normalise a `URI | string`) and `UriUtils.isAncestorOrEqual` (a scheme- and
47
- authority-aware containment check, unlike `UriUtils.contains`).
11
+ - Langium's full API, unfiltered. Replace `langium` with `@hydranium/langium` in
12
+ your imports; nothing else changes, because the symbols are the same objects.
13
+ - A mirror of each Langium subpath, so `langium/lsp`, `langium/node` and
14
+ `langium/test` go through the same pin.
15
+ - Langium and its `vscode-languageserver`, `vscode-languageserver-protocol` and
16
+ `vscode-jsonrpc` chain move together, at the versions the framework was built
17
+ against, instead of a pin you maintain yourself.
48
18
 
49
19
  ## Install
50
20
 
@@ -54,37 +24,31 @@ npm install @hydranium/langium
54
24
 
55
25
  No peer dependencies: `langium` is a direct, exact dependency of this package.
56
26
 
57
- ## Subpaths
58
-
59
- | Subpath | Re-exports | Contents |
60
- | -------- | -------------- | ----------------------------------------- |
61
- | `.` | `langium` | Core API + the framework's augmentations. |
62
- | `./lsp` | `langium/lsp` | LSP service defaults. |
63
- | `./node` | `langium/node` | `NodeFileSystem`. |
64
- | `./test` | `langium/test` | Parsing / validation test helpers. |
65
-
66
- Resolve the subpaths with [a resolver that reads `exports`](../../docs/adopting/requirements.md#a-resolver-that-reads-exports);
67
- `"Node"` (node10) reaches none of them.
27
+ Still declare `langium` in your own package, at the version this package pins:
28
+ the code `langium-cli` generates imports `langium` directly. If your install
29
+ resolves a second copy, the framework refuses to start your language server.
68
30
 
69
- ## Usage
31
+ ## Entry points
70
32
 
71
- Replace `langium` with `@hydranium/langium` in your import specifiers; nothing else changes, because
72
- the symbols are the same objects.
33
+ | Subpath | Use it for | Runs in |
34
+ | -------- | ----------------------------- | --------------- |
35
+ | `.` | instead of `langium` | browser-neutral |
36
+ | `./lsp` | instead of `langium/lsp` | browser-neutral |
37
+ | `./node` | instead of `langium/node` | Node-only |
38
+ | `./test` | instead of `langium/test` | Node-only |
73
39
 
74
- The one thing to know is that the root entry is **side-effecting**: importing anything from
75
- `@hydranium/langium` loads the `UriUtils` augmentation, which mutates the runtime `UriUtils` object.
76
- That is why the added helpers are visible process-wide once any framework package has loaded — and
77
- why code that imports `UriUtils` from `langium` without ever loading the framework correctly sees
78
- only the stock surface.
40
+ The subpaths need a TypeScript `moduleResolution` that reads `exports`
41
+ (`NodeNext` or `Bundler`); see *Requirements* in
42
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
79
43
 
80
44
  ## Status
81
45
 
82
- Alpha — pre-v0, published as a `1.0.0-next` prerelease on every merge to `main`. The API is
83
- Langium's and is stable to the extent Langium's is; what is not yet settled is the augmentation set
84
- and the pinned version. See the [repository README](../../README.md) for the current status and
85
- known limitations.
46
+ Alpha: every release is a prerelease that may break the API, so pin an exact
47
+ version. Guides and known limitations:
48
+ [Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
86
49
 
87
50
  ## License
88
51
 
89
52
  `MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
90
- [`NOTICE.md`](../../NOTICE.md) for third-party notices.
53
+ [`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
54
+ for third-party notices.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hydranium/langium",
3
- "version": "1.0.0-next.245",
3
+ "version": "1.0.0-next.246",
4
4
  "description": "Augmented re-export of the Langium API for the hydranium framework: the single chokepoint where hydranium pins the Langium version and layers its type/namespace augmentations. ~99% passthrough today.",
5
5
  "keywords": [
6
6
  "hydranium",