langium-tools 0.3.3 → 0.4.0

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.
package/README.md CHANGED
@@ -28,12 +28,13 @@
28
28
  A collection of tools for implementing and testing DSLs with <a href="https://langium.org/"><strong>Langium</strong>!</a>
29
29
  <br />
30
30
  <br />
31
- <a href="#documentation"><strong>Explore the docs »</strong></a>
31
+ <a href="https://langium-tools.openbrod.org"><strong>Website »</strong></a>
32
32
  <br />
33
- <a href="https://borisbrodski.github.io/langium-tools"><strong>Explore the typedocs »</strong></a>
33
+ <a href="https://langium-tools.openbrod.org/api"><strong>API reference »</strong></a>
34
+ <br />
35
+ <a href="#documentation"><strong>Documentation in this README »</strong></a>
34
36
  <br />
35
37
  <br />
36
-
37
38
  <a href="https://github.com/borisbrodski/langium-tools/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
38
39
  ·
39
40
  <a href="https://github.com/borisbrodski/langium-tools/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
@@ -109,7 +110,7 @@ This section should list any major frameworks/libraries used to bootstrap your p
109
110
 
110
111
  - Add package to your project
111
112
  - Start using one or more features it provides
112
- - Check out example project to see `langium-tools` in action
113
+ - Read the [state machine showcase](https://github.com/borisbrodski/langium-tools-showcases/tree/main/statemachine) for a full language that uses the library
113
114
 
114
115
  ### Installation
115
116
 
@@ -123,13 +124,35 @@ Add the package to your `package.json`
123
124
 
124
125
  ### Example project
125
126
 
126
- You can check out The Umltimative Example: the default langium example project <strong>statemachine</strong> enhanced with all features of `langium-tools`:
127
+ The [state machine showcase](https://github.com/borisbrodski/langium-tools-showcases/tree/main/statemachine) is the official Langium statemachine. The grammar and the C++ program are the original example. langium-tools replaces the hand-written parts around them. `git diff upstream -- statemachine` in that repository is the extension.
128
+
129
+ Clone it next to this repository. The example depends on `file:../../langium-tools`, and this package exports `dist/`, so build here first:
130
+
131
+ ```sh
132
+ git clone https://github.com/borisbrodski/langium-tools.git
133
+ git clone https://github.com/borisbrodski/langium-tools-showcases.git
134
+ cd langium-tools && npm install && npm run build
135
+ cd ../langium-tools-showcases/statemachine && npm install && npm test
136
+ ```
127
137
 
128
- - TODO - ADD LINK HERE
138
+ What that language uses, and why it is less code:
139
+
140
+ - `getDocumentIssueSummary` is the CLI's only error report. Lexer, parser, and validation errors share one count. Warnings are printed and generation continues. The old loop kept diagnostics of severity 1 and could miss a syntax error.
141
+ - `toHaveNoErrors` ignores warnings. `toHaveNoIssues` does not. A lowercase state name is the test that shows the difference, so a style warning does not have to fail a parse test.
142
+ - `parseWithMarks` and `toHaveDocumentIssues` use `<<{|` … `|}>>` as the expected range. The matcher fails when an issue is missing and when an extra issue appears. Hard-coded ranges such as `[1:19..1:26]` do not.
143
+ - `generate` only calls `createFile`. The CLI writes the directory. Identical bytes keep their modification time. The same path with different text throws before a file is overwritten. The C++ templates themselves are unchanged.
144
+ - `npm test` verifies `generated/` and `generated-metadata.json`. `npm run test:generate` rewrites them. The mode is `GENERATOR_TEST`. The C++ no longer has to be pasted into the test source.
145
+ - `JavaImportManager` turns the events into a Java enum. `useClass('java.util.function.Consumer')` prints `Consumer` and adds the import. A second type with that simple name stays fully qualified. Classes in the current package are not imported.
146
+
147
+ `generateJavaFile` is the one-call wrapper around the import manager. It builds the file with generator nodes from this package's Langium install. A project that also depends on Langium has a second copy, and those nodes print as `[object Object]`. The showcase calls the import manager and `createFile` instead. The note is in `statemachine/src/cli/generator.ts`.
148
+
149
+ `arraySortBy`, `adjustedUnix`, and named generator targets are real features. The state machine does not use them: event order is the language order, the snapshots are `\n`, and the `.cpp` and `.java` share one output directory. Named targets are the next step when those two files must land in different directories.
129
150
 
130
151
  ## Documentation
131
152
 
132
- See [typedoc documentation](https://borisbrodski.github.io/langium-tools)
153
+ Guides for every part of the library, with examples, are on the website: [langium-tools.openbrod.org](https://langium-tools.openbrod.org). The [showcases](https://langium-tools.openbrod.org/showcases/) page is the index of working languages, starting with the state machine.
154
+
155
+ The generated API reference is [typedoc](https://langium-tools.openbrod.org/api).
133
156
 
134
157
  ### Document Issues
135
158
 
@@ -234,13 +257,13 @@ The module defines the following enums for issue sources and severities:
234
257
 
235
258
  For detailed API documentation, see the Typedoc documentation.
236
259
 
237
- - [getDocumentIssueSummary](https://borisbrodski.github.io/langium-tools/functions/base.getDocumentIssueSummary.html)
238
- - [getDocumentIssues](https://borisbrodski.github.io/langium-tools/functions/base.getDocumentIssues.html)
239
- - [documentIssueToString](https://borisbrodski.github.io/langium-tools/functions/base.documentIssueToString.html)
240
- - [DocumentIssue](https://borisbrodski.github.io/langium-tools/types/base.DocumentIssue.html)
241
- - [DocumentIssueSummary](https://borisbrodski.github.io/langium-tools/types/base.DocumentIssueSummary.html)
242
- - [DocumentIssueSource](https://borisbrodski.github.io/langium-tools/enums/base.DocumentIssueSource.html)
243
- - [DocumentIssueSeverity](https://borisbrodski.github.io/langium-tools/enums/base.DocumentIssueSeverity.html)
260
+ - [getDocumentIssueSummary](https://langium-tools.openbrod.org/api/functions/base.getDocumentIssueSummary.html)
261
+ - [getDocumentIssues](https://langium-tools.openbrod.org/api/functions/base.getDocumentIssues.html)
262
+ - [documentIssueToString](https://langium-tools.openbrod.org/api/functions/base.documentIssueToString.html)
263
+ - [DocumentIssue](https://langium-tools.openbrod.org/api/types/base.DocumentIssue.html)
264
+ - [DocumentIssueSummary](https://langium-tools.openbrod.org/api/types/base.DocumentIssueSummary.html)
265
+ - [DocumentIssueSource](https://langium-tools.openbrod.org/api/enums/base.DocumentIssueSource.html)
266
+ - [DocumentIssueSeverity](https://langium-tools.openbrod.org/api/enums/base.DocumentIssueSeverity.html)
244
267
 
245
268
  #### Notes
246
269
 
@@ -379,10 +402,10 @@ await manager.writeToDisk(outputDir: string, target?: string, clean?: boolean);
379
402
 
380
403
  For detailed API documentation, see the Typedoc documentation.
381
404
 
382
- - [GeneratedContentManager](https://borisbrodski.github.io/langium-tools/classes/generator.GeneratedContentManager.html)
383
- - [GeneratorManager](https://borisbrodski.github.io/langium-tools/interfaces/generator.GeneratorManager.html)
384
- - [GeneratorTarget](https://borisbrodski.github.io/langium-tools/interfaces/generator.GeneratorTarget.html)
385
- - [CreateFileOptions](https://borisbrodski.github.io/langium-tools/interfaces/generator.CreateFileOptions.html)
405
+ - [GeneratedContentManager](https://langium-tools.openbrod.org/api/classes/generator.GeneratedContentManager.html)
406
+ - [GeneratorManager](https://langium-tools.openbrod.org/api/interfaces/generator.GeneratorManager.html)
407
+ - [GeneratorTarget](https://langium-tools.openbrod.org/api/interfaces/generator.GeneratorTarget.html)
408
+ - [CreateFileOptions](https://langium-tools.openbrod.org/api/interfaces/generator.CreateFileOptions.html)
386
409
 
387
410
  #### Notes
388
411
 
@@ -556,16 +579,16 @@ The generator testing utilities work by:
556
579
 
557
580
  #### API Reference
558
581
 
559
- For detailed API documentation, see the [Typedoc documentation](https://borisbrodski.github.io/langium-tools).
582
+ For detailed API documentation, see the [Typedoc documentation](https://langium-tools.openbrod.org/api).
560
583
 
561
- - [langiumGeneratorSuite](https://borisbrodski.github.io/langium-tools/functions/testing.langiumGeneratorSuite.html)
562
- - [GeneratorTestOptions](https://borisbrodski.github.io/langium-tools/interfaces/testing.GeneratorTestOptions.html)
563
- - [GeneratedContentManager](https://borisbrodski.github.io/langium-tools/classes/generator.GeneratedContentManager.html)
584
+ - [langiumGeneratorSuite](https://langium-tools.openbrod.org/api/functions/testing.langiumGeneratorSuite.html)
585
+ - [GeneratorTestOptions](https://langium-tools.openbrod.org/api/interfaces/testing.GeneratorTestOptions.html)
586
+ - [GeneratedContentManager](https://langium-tools.openbrod.org/api/classes/generator.GeneratedContentManager.html)
564
587
 
565
588
  #### Notes
566
589
 
567
590
  - **Environment Variable**: The `GENERATOR_TEST` environment variable controls the test mode (`verify` or `generate`).
568
- - **Testing Framework**: The examples use `vitest`, but the utilities can be used with any testing framework, if you are not using automatic workspace discovery, but rather define one test for one workspace using [langiumGeneratorTest](https://borisbrodski.github.io/langium-tools/functions/testing.langiumGeneratorTest.html).
591
+ - **Testing Framework**: The examples use `vitest`, but the utilities can be used with any testing framework, if you are not using automatic workspace discovery, but rather define one test for one workspace using [langiumGeneratorTest](https://langium-tools.openbrod.org/api/functions/testing.langiumGeneratorTest.html).
569
592
 
570
593
  #### Example Workflow
571
594
 
@@ -883,16 +906,16 @@ test("document has no errors, ignoring lexer errors", async () => {
883
906
  #### API Reference
884
907
 
885
908
  - Matchers:
886
- - [toHaveNoErrors](https://borisbrodski.github.io/langium-tools/functions/testing.toHaveNoErrors.html)
887
- - [toHaveNoIssues](https://borisbrodski.github.io/langium-tools/functions/testing.toHaveNoIssues.html)
888
- - [toHaveDocumentIssues](https://borisbrodski.github.io/langium-tools/functions/testing.toHaveDocumentIssues.html)
889
- - [toContainIssue](https://borisbrodski.github.io/langium-tools/functions/testing.toContainIssue.html)
909
+ - [toHaveNoErrors](https://langium-tools.openbrod.org/api/functions/testing.toHaveNoErrors.html)
910
+ - [toHaveNoIssues](https://langium-tools.openbrod.org/api/functions/testing.toHaveNoIssues.html)
911
+ - [toHaveDocumentIssues](https://langium-tools.openbrod.org/api/functions/testing.toHaveDocumentIssues.html)
912
+ - [toContainIssue](https://langium-tools.openbrod.org/api/functions/testing.toContainIssue.html)
890
913
  - Interfaces:
891
- - [IssueExpectation](https://borisbrodski.github.io/langium-tools/interfaces/testing.IssueExpectation.html)
892
- - [IgnoreParameters](https://borisbrodski.github.io/langium-tools/interfaces/testing.IgnoreParameters.html)
914
+ - [IssueExpectation](https://langium-tools.openbrod.org/api/interfaces/testing.IssueExpectation.html)
915
+ - [IgnoreParameters](https://langium-tools.openbrod.org/api/interfaces/testing.IgnoreParameters.html)
893
916
  - Enums:
894
- - [DocumentIssueSeverity](https://borisbrodski.github.io/langium-tools/types/base.DocumentIssue.html)
895
- - [DocumentIssueSource](https://borisbrodski.github.io/langium-tools/enums/base.DocumentIssueSource.html)
917
+ - [DocumentIssueSeverity](https://langium-tools.openbrod.org/api/types/base.DocumentIssue.html)
918
+ - [DocumentIssueSource](https://langium-tools.openbrod.org/api/enums/base.DocumentIssueSource.html)
896
919
 
897
920
  #### Notes
898
921
 
@@ -903,7 +926,7 @@ test("document has no errors, ignoring lexer errors", async () => {
903
926
 
904
927
  In the examples, you might notice the use of a <a href="#adjusted">`adjusted`</a> function to format template strings. This is a utility to clean up multiline strings in tests.
905
928
 
906
- See [`adjusted` typedoc](https://borisbrodski.github.io/langium-tools/functions/base.adjusted.html) for more information.
929
+ See [`adjusted` typedoc](https://langium-tools.openbrod.org/api/functions/base.adjusted.html) for more information.
907
930
 
908
931
  #### Conclusion
909
932
 
@@ -919,7 +942,7 @@ For more detailed information, refer to the API documentation.
919
942
 
920
943
  The adjusted function is a utility for formatting multi-line template strings, ensuring that indentation and line breaks are preserved correctly. This is particularly useful for generating code snippets or structured text where indentation is essential.
921
944
 
922
- See [`adjusted` typedoc](https://borisbrodski.github.io/langium-tools/functions/base.adjusted.html) for more information.
945
+ See [`adjusted` typedoc](https://langium-tools.openbrod.org/api/functions/base.adjusted.html) for more information.
923
946
 
924
947
  ##### Features
925
948
 
@@ -968,7 +991,7 @@ The function returns a formatted string with the following properties:
968
991
 
969
992
  ##### API Reference
970
993
 
971
- - [adjusted](https://borisbrodski.github.io/langium-tools/functions/base.adjusted.html)
994
+ - [adjusted](https://langium-tools.openbrod.org/api/functions/base.adjusted.html)
972
995
 
973
996
  <p align="right">(<a href="#readme-top">back to top</a>)</p>
974
997
 
@@ -37,6 +37,13 @@ export var DocumentIssueSeverity;
37
37
  * @param severity - The `DiagnosticSeverity` to map.
38
38
  * @returns The corresponding `DocumentIssueSeverity`.
39
39
  */
40
+ /**
41
+ * LSP 3.18 allows a diagnostic message to be {@link MarkupContent}.
42
+ * Langium still emits plain strings. Keep the public issue message a string.
43
+ */
44
+ function diagnosticMessage(message) {
45
+ return typeof message === 'string' ? message : message.value;
46
+ }
40
47
  function mapSeverity(severity) {
41
48
  if (!severity) {
42
49
  return DocumentIssueSeverity.UNKNOWN;
@@ -84,7 +91,8 @@ export function getDocumentIssues(document, params) {
84
91
  }
85
92
  if (!skipParserErrors) {
86
93
  document.parseResult.parserErrors.forEach((parserError) => {
87
- // Try to get the previous token from the internal Chevrotain structure to get a better position
94
+ // Chevrotain exposes the token before the failure. Inserted EOF tokens use -1
95
+ // for offset, line, and column, which is not a real position.
88
96
  const previousToken = parserError === null || parserError === void 0 ? void 0 : parserError.previousToken;
89
97
  issues.push({
90
98
  source: DocumentIssueSource.PARSER,
@@ -106,7 +114,7 @@ export function getDocumentIssues(document, params) {
106
114
  issues.push({
107
115
  source: DocumentIssueSource.VALIDATION,
108
116
  severity: mapSeverity(diagnostic.severity),
109
- message: diagnostic.message,
117
+ message: diagnosticMessage(diagnostic.message),
110
118
  startLine: diagnostic.range.start.line,
111
119
  startColumn: diagnostic.range.start.character,
112
120
  endLine: diagnostic.range.end.line,
@@ -280,17 +288,19 @@ function at(issue) {
280
288
  return result;
281
289
  }
282
290
  /**
283
- * Returns the first meaningful (non-null, non-NaN) value from two options.
291
+ * Returns the first usable source position from two options.
292
+ * `null`, `undefined`, `NaN`, and negative values are skipped. Chevrotain uses `-1`
293
+ * on inserted tokens (typically EOF) when it has no position.
284
294
  *
285
295
  * @param a - The first number to consider.
286
296
  * @param b - The second number to consider.
287
- * @returns The first meaningful number, or `undefined` if both are `null` or `NaN`.
297
+ * @returns The first usable number, or `undefined` if both are unusable.
288
298
  */
289
299
  function firstDefinedNumber(a, b) {
290
- if (a != null && !Number.isNaN(a)) {
300
+ if (a != null && !Number.isNaN(a) && a >= 0) {
291
301
  return a;
292
302
  }
293
- if (b != null && !Number.isNaN(b)) {
303
+ if (b != null && !Number.isNaN(b) && b >= 0) {
294
304
  return b;
295
305
  }
296
306
  return undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "langium-tools",
3
- "version": "0.3.3",
3
+ "version": "0.4.0",
4
4
  "description": "A set of tools for Langium",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -28,11 +28,15 @@
28
28
  ],
29
29
  "author": "Boris Brodski",
30
30
  "license": "MIT",
31
+ "engines": {
32
+ "node": "^22.22.2 || ^24.15.0 || >=26",
33
+ "npm": ">=10.2.3"
34
+ },
31
35
  "dependencies": {
32
36
  "@types/node": "^22.0.0",
33
37
  "change-case": "^5.4.4",
34
38
  "escape-string-regexp": "^5.0.0",
35
- "langium": "^3.4.0"
39
+ "langium": "^4.4.2"
36
40
  },
37
41
  "peerDependencies": {
38
42
  "vitest": "~2.0.5"
@@ -43,7 +47,7 @@
43
47
  "typedoc": "^0.27.0",
44
48
  "typedoc-plugin-extras": "^4.0.0",
45
49
  "typedoc-plugin-markdown": "^3.0.0",
46
- "typescript": "^5.5.4",
50
+ "typescript": "~5.8.3",
47
51
  "typescript-eslint": "^7.18.0",
48
52
  "vitest": "~2.0.5"
49
53
  },
@@ -56,5 +60,8 @@
56
60
  "*.config.*",
57
61
  "package-lock.json",
58
62
  "*.json"
59
- ]
63
+ ],
64
+ "volta": {
65
+ "node": "22.22.2"
66
+ }
60
67
  }
@@ -1,6 +1,6 @@
1
1
  import "./string.js";
2
2
  import { LangiumDocument } from "langium";
3
- import { DiagnosticSeverity } from "vscode-languageserver";
3
+ import { DiagnosticSeverity, MarkupContent } from "vscode-languageserver";
4
4
  import type { IToken } from 'chevrotain';
5
5
  import { EOL } from "node:os";
6
6
 
@@ -131,6 +131,14 @@ export interface GetDocumentIssuesParams {
131
131
  * @param severity - The `DiagnosticSeverity` to map.
132
132
  * @returns The corresponding `DocumentIssueSeverity`.
133
133
  */
134
+ /**
135
+ * LSP 3.18 allows a diagnostic message to be {@link MarkupContent}.
136
+ * Langium still emits plain strings. Keep the public issue message a string.
137
+ */
138
+ function diagnosticMessage(message: string | MarkupContent): string {
139
+ return typeof message === 'string' ? message : message.value;
140
+ }
141
+
134
142
  function mapSeverity(severity?: DiagnosticSeverity): DocumentIssueSeverity {
135
143
  if (!severity) {
136
144
  return DocumentIssueSeverity.UNKNOWN;
@@ -188,7 +196,8 @@ export function getDocumentIssues(
188
196
 
189
197
  if (!skipParserErrors) {
190
198
  document.parseResult.parserErrors.forEach((parserError) => {
191
- // Try to get the previous token from the internal Chevrotain structure to get a better position
199
+ // Chevrotain exposes the token before the failure. Inserted EOF tokens use -1
200
+ // for offset, line, and column, which is not a real position.
192
201
  const previousToken = (parserError as unknown as { previousToken: IToken })?.previousToken as IToken;
193
202
  issues.push({
194
203
  source: DocumentIssueSource.PARSER,
@@ -212,7 +221,7 @@ export function getDocumentIssues(
212
221
  issues.push({
213
222
  source: DocumentIssueSource.VALIDATION,
214
223
  severity: mapSeverity(diagnostic.severity),
215
- message: diagnostic.message,
224
+ message: diagnosticMessage(diagnostic.message),
216
225
  startLine: diagnostic.range.start.line,
217
226
  startColumn: diagnostic.range.start.character,
218
227
  endLine: diagnostic.range.end.line,
@@ -403,17 +412,19 @@ function at(issue: DocumentIssue): string {
403
412
  }
404
413
 
405
414
  /**
406
- * Returns the first meaningful (non-null, non-NaN) value from two options.
415
+ * Returns the first usable source position from two options.
416
+ * `null`, `undefined`, `NaN`, and negative values are skipped. Chevrotain uses `-1`
417
+ * on inserted tokens (typically EOF) when it has no position.
407
418
  *
408
419
  * @param a - The first number to consider.
409
420
  * @param b - The second number to consider.
410
- * @returns The first meaningful number, or `undefined` if both are `null` or `NaN`.
421
+ * @returns The first usable number, or `undefined` if both are unusable.
411
422
  */
412
423
  function firstDefinedNumber(a?: number, b?: number): number | undefined {
413
- if (a != null && !Number.isNaN(a)) {
424
+ if (a != null && !Number.isNaN(a) && a >= 0) {
414
425
  return a;
415
426
  }
416
- if (b != null && !Number.isNaN(b)) {
427
+ if (b != null && !Number.isNaN(b) && b >= 0) {
417
428
  return b;
418
429
  }
419
430
  return undefined;