langium-tools 0.1.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.
Files changed (61) hide show
  1. package/README.md +1171 -0
  2. package/dist/base/arrays.d.ts +6 -0
  3. package/dist/base/arrays.js +34 -0
  4. package/dist/base/document-errors.d.ts +56 -0
  5. package/dist/base/document-errors.js +198 -0
  6. package/dist/base/document-issues.d.ts +178 -0
  7. package/dist/base/document-issues.js +306 -0
  8. package/dist/base/index.d.ts +4 -0
  9. package/dist/base/index.js +4 -0
  10. package/dist/base/marker-parser.d.ts +36 -0
  11. package/dist/base/marker-parser.js +51 -0
  12. package/dist/base/string.d.ts +89 -0
  13. package/dist/base/string.js +104 -0
  14. package/dist/generator/generated-content-manager.d.ts +207 -0
  15. package/dist/generator/generated-content-manager.js +242 -0
  16. package/dist/generator/index.d.ts +2 -0
  17. package/dist/generator/index.js +2 -0
  18. package/dist/generator/tools.d.ts +9 -0
  19. package/dist/generator/tools.js +12 -0
  20. package/dist/index.d.ts +4 -0
  21. package/dist/index.js +4 -0
  22. package/dist/lang/index.d.ts +1 -0
  23. package/dist/lang/index.js +1 -0
  24. package/dist/lang/java/common.d.ts +1 -0
  25. package/dist/lang/java/common.js +3 -0
  26. package/dist/lang/java/generator-tools.d.ts +37 -0
  27. package/dist/lang/java/generator-tools.js +48 -0
  28. package/dist/lang/java/import-manager.d.ts +61 -0
  29. package/dist/lang/java/import-manager.js +88 -0
  30. package/dist/lang/java/index.d.ts +3 -0
  31. package/dist/lang/java/index.js +3 -0
  32. package/dist/testing/common.d.ts +1 -0
  33. package/dist/testing/common.js +5 -0
  34. package/dist/testing/generator-testing.d.ts +56 -0
  35. package/dist/testing/generator-testing.js +184 -0
  36. package/dist/testing/index.d.ts +4 -0
  37. package/dist/testing/index.js +4 -0
  38. package/dist/testing/matchers.d.ts +209 -0
  39. package/dist/testing/matchers.js +306 -0
  40. package/dist/testing/parser-tools.d.ts +19 -0
  41. package/dist/testing/parser-tools.js +18 -0
  42. package/package.json +59 -0
  43. package/src/base/arrays.ts +40 -0
  44. package/src/base/document-issues.ts +430 -0
  45. package/src/base/index.ts +4 -0
  46. package/src/base/marker-parser.ts +96 -0
  47. package/src/base/string.ts +117 -0
  48. package/src/generator/generated-content-manager.ts +368 -0
  49. package/src/generator/index.ts +2 -0
  50. package/src/generator/tools.ts +14 -0
  51. package/src/index.ts +5 -0
  52. package/src/lang/index.ts +1 -0
  53. package/src/lang/java/common.ts +4 -0
  54. package/src/lang/java/generator-tools.ts +59 -0
  55. package/src/lang/java/import-manager.ts +98 -0
  56. package/src/lang/java/index.ts +3 -0
  57. package/src/testing/common.ts +5 -0
  58. package/src/testing/generator-testing.ts +266 -0
  59. package/src/testing/index.ts +4 -0
  60. package/src/testing/matchers.ts +503 -0
  61. package/src/testing/parser-tools.ts +34 -0
@@ -0,0 +1,503 @@
1
+ import 'vitest';
2
+ import { LangiumDocument } from "langium";
3
+ import { expect } from "vitest";
4
+ import {
5
+ DocumentIssue,
6
+ DocumentIssueSeverity,
7
+ DocumentIssueSource,
8
+ documentIssueToString,
9
+ getDocumentIssues,
10
+ getDocumentIssueSummary
11
+ } from "../base/document-issues.js";
12
+ import { ParsedDocument } from './parser-tools.js';
13
+ import { expandToNode, toString } from 'langium/generate';
14
+ import { sentenceCase } from 'change-case';
15
+ import { EOL } from 'node:os';
16
+
17
+ /**
18
+ * Parameters to customize which types of issues to ignore during document validation.
19
+ */
20
+ export interface IgnoreParameters {
21
+ /** Whether to ignore parser errors. Default is `false`. */
22
+ ignoreParserErrors?: boolean;
23
+ /** Whether to ignore lexer errors. Default is `false`. */
24
+ ignoreLexerErrors?: boolean;
25
+ /** Whether to ignore validation errors. Default is `false`. */
26
+ ignoreValidationErrors?: boolean;
27
+ /** Whether to ignore non-error diagnostics (e.g., warnings, hints). Default is `false`. */
28
+ ignoreNonErrorDiagnostics?: boolean;
29
+ }
30
+
31
+ /**
32
+ * Expects a Langium document to have no errors after parsing.
33
+ * Non-error diagnostics are ignored by default.
34
+ *
35
+ * @param document - The Langium document or parsed document to check for errors.
36
+ * @param parameters - Optional parameters to customize which errors to ignore.
37
+ *
38
+ * @example
39
+ * ```typescript
40
+ * import { expect, test } from 'vitest';
41
+ * import { parse } from './your-langium-test-setup';
42
+ *
43
+ * test('document has no errors', async () => {
44
+ * const doc = await parse('const x = 5;');
45
+ * expect(doc).toHaveNoErrors();
46
+ * });
47
+ *
48
+ * test('document has no errors, ignoring lexer errors', async () => {
49
+ * const doc = await parse('const x = @;', { validation: true });
50
+ * expect(doc).toHaveNoErrors({ ignoreLexerErrors: true });
51
+ * });
52
+ * ```
53
+ */
54
+ export function toHaveNoErrors(
55
+ document: LangiumDocument | ParsedDocument,
56
+ parameters?: IgnoreParameters
57
+ ) {
58
+ const {
59
+ ignoreParserErrors = false,
60
+ ignoreLexerErrors = false,
61
+ ignoreValidationErrors = false,
62
+ ignoreNonErrorDiagnostics = true, // Default to true for 'toHaveNoErrors'
63
+ } = parameters || {};
64
+ return toHaveNoIssues(document, {
65
+ ignoreParserErrors,
66
+ ignoreLexerErrors,
67
+ ignoreValidationErrors,
68
+ ignoreNonErrorDiagnostics,
69
+ });
70
+ }
71
+
72
+ /**
73
+ * Expects a Langium document to have no issues after parsing.
74
+ *
75
+ * @param document - The Langium document or parsed document to check for issues.
76
+ * @param parameters - Optional parameters to customize which issues to ignore.
77
+ *
78
+ * @example
79
+ * ```typescript
80
+ * import { expect, test } from 'vitest';
81
+ * import { parse } from './your-langium-test-setup';
82
+ *
83
+ * test('document has no issues', async () => {
84
+ * const doc = await parse('const x = 5;');
85
+ * expect(doc).toHaveNoIssues();
86
+ * });
87
+ *
88
+ * test('document has no issues, ignoring lexer errors', async () => {
89
+ * const doc = await parse('const x = @;', { validation: true });
90
+ * expect(doc).toHaveNoIssues({ ignoreLexerErrors: true });
91
+ * });
92
+ * ```
93
+ */
94
+ export function toHaveNoIssues(
95
+ document: LangiumDocument | ParsedDocument,
96
+ parameters?: IgnoreParameters
97
+ ) {
98
+ const {
99
+ ignoreParserErrors = false,
100
+ ignoreLexerErrors = false,
101
+ ignoreValidationErrors = false,
102
+ ignoreNonErrorDiagnostics = false,
103
+ } = parameters || {};
104
+ const langiumDocument: LangiumDocument =
105
+ 'document' in document ? document.document : document;
106
+ const issues = getDocumentIssueSummary(langiumDocument, {
107
+ skipLexerErrors: ignoreLexerErrors,
108
+ skipParserErrors: ignoreParserErrors,
109
+ skipValidation: ignoreValidationErrors,
110
+ skipNonErrorDiagnostics: ignoreNonErrorDiagnostics,
111
+ });
112
+ return {
113
+ pass: issues.countTotal === 0,
114
+ message: () => issues.message,
115
+ };
116
+ }
117
+
118
+ /**
119
+ * Represents an expected issue in a Langium document.
120
+ */
121
+ export interface IssueExpectation {
122
+ /**
123
+ * The severity of the issue.
124
+ * Defaults to `DocumentIssueSeverity.ERROR` if not specified.
125
+ */
126
+ severity?: DocumentIssueSeverity;
127
+
128
+ /**
129
+ * The source of the issue (lexer, parser, validator, etc.).
130
+ * Not asserted if not provided.
131
+ */
132
+ source?: DocumentIssueSource;
133
+
134
+ /**
135
+ * The expected message of the issue.
136
+ * Can be a string or a regular expression to match against the actual message.
137
+ */
138
+ message: string | RegExp;
139
+
140
+ /**
141
+ * 0-based marker ID in the DSL.
142
+ * Not asserted if not provided.
143
+ */
144
+ markerId?: number;
145
+ }
146
+
147
+ /**
148
+ * Expects a parsed Langium document with markers to have specific issues.
149
+ *
150
+ * @param parsedDocument - The parsed Langium document with markers to check for issues.
151
+ * @param expectedIssues - An array of expected issues.
152
+ * @param parameters - Optional parameters to customize which issues to ignore.
153
+ *
154
+ * @example
155
+ * ```typescript
156
+ * import { expect, test } from 'vitest';
157
+ * import { parseDocument } from './your-langium-test-setup';
158
+ *
159
+ * test('document has expected issues', async () => {
160
+ * const parsedDoc = await parseMarkedDSL(`
161
+ * let [[x: string]] = 5;
162
+ * print(x);
163
+ * `, '[[', ']]');
164
+ * expect(parsedDoc).toHaveDocumentIssues([
165
+ * {
166
+ * message: "Type 'number' is not assignable to type 'string'",
167
+ * markerId: 0
168
+ * }
169
+ * ]);
170
+ * });
171
+ *
172
+ * test('document has a warning, ignoring errors', async () => {
173
+ * const parsedDoc = await parseMarkedDSL(`
174
+ * let [[foo]];
175
+ * `, '[[', ']]');
176
+ * expect(parsedDoc).toHaveDocumentIssues(
177
+ * [
178
+ * {
179
+ * severity: DocumentIssueSeverity.WARNING,
180
+ * message: "Variable 'foo' is never used",
181
+ * markerId: 0
182
+ * }
183
+ * ],
184
+ * { ignoreValidationErrors: true }
185
+ * );
186
+ * });
187
+ * ```
188
+ */
189
+ export function toHaveDocumentIssues(
190
+ parsedDocument: ParsedDocument,
191
+ expectedIssues: Array<IssueExpectation>,
192
+ parameters?: IgnoreParameters
193
+ ) {
194
+ if (!('document' in parsedDocument)) {
195
+ throw new Error(
196
+ `Expected ParsedDocument object. Use 'parseMarkedDSL' to parse.`
197
+ );
198
+ }
199
+ const {
200
+ ignoreParserErrors = false,
201
+ ignoreLexerErrors = false,
202
+ ignoreValidationErrors = false,
203
+ ignoreNonErrorDiagnostics = false,
204
+ } = parameters || {};
205
+ const actualIssues = getDocumentIssues(parsedDocument.document, {
206
+ skipLexerErrors: ignoreLexerErrors,
207
+ skipParserErrors: ignoreParserErrors,
208
+ skipValidation: ignoreValidationErrors,
209
+ skipNonErrorDiagnostics: ignoreNonErrorDiagnostics,
210
+ });
211
+
212
+ if (!actualIssues || actualIssues.length === 0) {
213
+ if (expectedIssues.length === 0) {
214
+ return {
215
+ pass: true,
216
+ message: () => "",
217
+ };
218
+ }
219
+ return {
220
+ pass: false,
221
+ message: () =>
222
+ `Expected ${expectedIssues.length} issues, but none were present in the document.${EOL}${expectedIssues
223
+ .map((issue) => issueExpectationToString(parsedDocument, issue))
224
+ .join(EOL)}`,
225
+ };
226
+ }
227
+
228
+ const unmatchedExpectedIssues: Array<IssueExpectation> = [];
229
+ let remainingActualIssues = [...actualIssues];
230
+
231
+ expectedIssues.forEach((expectedIssue) => {
232
+ const matchedActualIssue = remainingActualIssues.find((actualIssue) =>
233
+ matchesIssueExpectation(actualIssue, expectedIssue, parsedDocument)
234
+ );
235
+ if (matchedActualIssue) {
236
+ remainingActualIssues = remainingActualIssues.filter(
237
+ (issue) => issue !== matchedActualIssue
238
+ );
239
+ } else {
240
+ unmatchedExpectedIssues.push(expectedIssue);
241
+ }
242
+ });
243
+
244
+ const errors: Array<string> = [];
245
+ if (remainingActualIssues.length > 0) {
246
+ errors.push("Unmatched actual issues:");
247
+ errors.push(...remainingActualIssues.map((issue) => {
248
+ const source = issue.source ? `(${sentenceCase(issue.source)}) ` : '';
249
+ return `${source}${documentIssueToString(issue)}`;
250
+ }));
251
+ }
252
+ if (unmatchedExpectedIssues.length > 0) {
253
+ errors.push("Unmatched expected issues:");
254
+ errors.push(
255
+ ...unmatchedExpectedIssues.map((issue) =>
256
+ issueExpectationToString(parsedDocument, issue)
257
+ )
258
+ );
259
+ }
260
+
261
+ return {
262
+ pass: errors.length === 0,
263
+ message: () => errors.join(EOL),
264
+ };
265
+ }
266
+
267
+ /**
268
+ * Expects that a specific issue is present in the Langium document.
269
+ *
270
+ * @param document - The Langium document or parsed document to check for the issue.
271
+ * @param expectedIssue - The expected issue to look for.
272
+ * @param parameters - Optional parameters to customize which issues to ignore.
273
+ *
274
+ * @example
275
+ * ```typescript
276
+ * import { expect, test } from 'vitest';
277
+ * import { parse } from './your-langium-test-setup';
278
+ *
279
+ * test('document contains specific issue', async () => {
280
+ * const doc = await parse('const x = @;', { validation: true });
281
+ * expect(doc).toContainIssue({
282
+ * message: /Unexpected character/,
283
+ * severity: DocumentIssueSeverity.ERROR,
284
+ * source: DocumentIssueSource.LEXER,
285
+ * });
286
+ * });
287
+ * ```
288
+ */
289
+ export function toContainIssue(
290
+ document: LangiumDocument | ParsedDocument,
291
+ expectedIssue: IssueExpectation,
292
+ parameters?: IgnoreParameters
293
+ ) {
294
+ const {
295
+ ignoreParserErrors = false,
296
+ ignoreLexerErrors = false,
297
+ ignoreValidationErrors = false,
298
+ ignoreNonErrorDiagnostics = false,
299
+ } = parameters || {};
300
+
301
+ const langiumDocument: LangiumDocument =
302
+ 'document' in document ? document.document : document;
303
+
304
+ const actualIssues = getDocumentIssues(langiumDocument, {
305
+ skipLexerErrors: ignoreLexerErrors,
306
+ skipParserErrors: ignoreParserErrors,
307
+ skipValidation: ignoreValidationErrors,
308
+ skipNonErrorDiagnostics: ignoreNonErrorDiagnostics,
309
+ });
310
+
311
+ if (!actualIssues || actualIssues.length === 0) {
312
+ return {
313
+ pass: false,
314
+ message: () => `No issues were found in the document.`,
315
+ };
316
+ }
317
+
318
+ const matchedIssue = actualIssues.find((actualIssue) =>
319
+ matchesIssueExpectation(
320
+ actualIssue,
321
+ expectedIssue,
322
+ 'markerData' in document ? document : undefined
323
+ )
324
+ );
325
+
326
+ if (matchedIssue) {
327
+ return {
328
+ pass: true,
329
+ message: () => '',
330
+ };
331
+ } else {
332
+ const issueDescription = issueExpectationToString(
333
+ 'markerData' in document ? document : undefined,
334
+ expectedIssue
335
+ );
336
+ return {
337
+ pass: false,
338
+ message: () => toString(expandToNode`
339
+ Expected issue was not found in the document:
340
+ ${issueDescription}
341
+
342
+ Issues in the document:
343
+ ${getDocumentIssueSummary(langiumDocument).message}
344
+ `)
345
+ };
346
+ }
347
+ }
348
+
349
+ /**
350
+ * Helper function to determine if an actual issue matches an expected issue.
351
+ *
352
+ * @param actualIssue - The actual issue from the document.
353
+ * @param expectedIssue - The expected issue defined by the user.
354
+ * @param parsedDocument - The parsed document containing marker data (optional).
355
+ * @returns `true` if the actual issue matches the expected issue; otherwise, `false`.
356
+ */
357
+ function matchesIssueExpectation(
358
+ actualIssue: DocumentIssue,
359
+ expectedIssue: IssueExpectation,
360
+ parsedDocument?: ParsedDocument
361
+ ): boolean {
362
+ let match =
363
+ typeof expectedIssue.message === 'string'
364
+ ? actualIssue.message === expectedIssue.message
365
+ : expectedIssue.message.test(actualIssue.message);
366
+
367
+ match &&=
368
+ actualIssue.severity === (expectedIssue.severity || DocumentIssueSeverity.ERROR);
369
+
370
+ match &&= expectedIssue.source === undefined || actualIssue.source === expectedIssue.source;
371
+
372
+ if (expectedIssue.markerId !== undefined && parsedDocument) {
373
+ const marker = parsedDocument.markerData.markers[expectedIssue.markerId];
374
+ if (!marker) {
375
+ throw new Error(
376
+ `Invalid markerId ${expectedIssue.markerId}. Available markers range from 0 to ${parsedDocument.markerData.markers.length - 1
377
+ }.`
378
+ );
379
+ }
380
+ if (actualIssue.startLine !== undefined && marker.startLine !== undefined) {
381
+ match &&= actualIssue.startLine === marker.startLine;
382
+ }
383
+ if (actualIssue.startColumn !== undefined && marker.startColumn !== undefined) {
384
+ match &&= actualIssue.startColumn === marker.startColumn;
385
+ }
386
+ if (actualIssue.startOffset !== undefined && marker.startOffset !== undefined) {
387
+ match &&= actualIssue.startOffset === marker.startOffset;
388
+ }
389
+ if (actualIssue.endLine !== undefined && marker.endLine !== undefined) {
390
+ match &&= actualIssue.endLine === marker.endLine;
391
+ }
392
+ if (actualIssue.endColumn !== undefined && marker.endColumn !== undefined) {
393
+ match &&= actualIssue.endColumn === marker.endColumn;
394
+ }
395
+ if (actualIssue.endOffset !== undefined && marker.endOffset !== undefined) {
396
+ match &&= actualIssue.endOffset === marker.endOffset;
397
+ }
398
+ }
399
+
400
+ return match;
401
+ }
402
+
403
+ /**
404
+ * Extends Vitest's expect function with custom matchers for Langium documents.
405
+ */
406
+ expect.extend({
407
+ toHaveNoErrors,
408
+ toHaveNoIssues,
409
+ toHaveDocumentIssues,
410
+ toContainIssue,
411
+ });
412
+
413
+ /**
414
+ * Interface extending Vitest's matchers with Langium-specific assertions.
415
+ */
416
+ interface LangiumMatchers<R = unknown> {
417
+ /**
418
+ * Asserts that a document has no errors after parsing.
419
+ * Non-error diagnostics (warnings, hints) are ignored by default.
420
+ *
421
+ * @param parameters - Optional parameters to customize which errors to ignore.
422
+ */
423
+ toHaveNoErrors: R extends LangiumDocument | ParsedDocument
424
+ ? (parameters?: IgnoreParameters) => void
425
+ : never;
426
+
427
+ /**
428
+ * Asserts that a document has no issues after parsing.
429
+ *
430
+ * @param parameters - Optional parameters to customize which issues to ignore.
431
+ */
432
+ toHaveNoIssues: R extends LangiumDocument | ParsedDocument
433
+ ? (parameters?: IgnoreParameters) => void
434
+ : never;
435
+
436
+ /**
437
+ * Asserts that a parsed document has specific issues at specified markers.
438
+ *
439
+ * @param expectedIssues - An array of expected issues.
440
+ * @param parameters - Optional parameters to customize which issues to ignore.
441
+ */
442
+ toHaveDocumentIssues: R extends ParsedDocument
443
+ ? (
444
+ expectedIssues: Array<IssueExpectation>,
445
+ parameters?: IgnoreParameters
446
+ ) => void
447
+ : never;
448
+
449
+ /**
450
+ * Asserts that a document contains a specific issue.
451
+ *
452
+ * @param expectedIssue - The expected issue to look for.
453
+ * @param parameters - Optional parameters to customize which issues to ignore.
454
+ */
455
+ toContainIssue: R extends LangiumDocument | ParsedDocument
456
+ ? (expectedIssue: IssueExpectation, parameters?: IgnoreParameters) => void
457
+ : never;
458
+ }
459
+
460
+ /**
461
+ * Augments Vitest's assertion interface with Langium-specific matchers.
462
+ */
463
+ declare module 'vitest' {
464
+
465
+ interface Assertion<T> extends LangiumMatchers<T> { }
466
+
467
+ interface AsymmetricMatchersContaining<R = unknown> extends LangiumMatchers<R> { }
468
+ }
469
+
470
+ /**
471
+ * Converts an issue expectation into a readable string representation.
472
+ *
473
+ * @param parsedDocument - The parsed document containing marker data (optional).
474
+ * @param issue - The issue expectation to convert.
475
+ * @returns A string representation of the issue expectation.
476
+ */
477
+ function issueExpectationToString(
478
+ parsedDocument: ParsedDocument | undefined,
479
+ issue: IssueExpectation
480
+ ): string {
481
+ const severity = issue.severity || DocumentIssueSeverity.ERROR;
482
+ const source = issue.source ? `(${sentenceCase(issue.source)}) ` : '';
483
+ let message = `${source}${sentenceCase(severity)}`;
484
+ if (issue.markerId !== undefined && parsedDocument) {
485
+ if (issue.markerId < 0 || issue.markerId >= parsedDocument.markerData.markers.length) {
486
+ throw new Error(`Invalid markerId ${issue.markerId}. Available markers range from 0 to ${parsedDocument.markerData.markers.length - 1}.`);
487
+ }
488
+ const marker = parsedDocument.markerData.markers[issue.markerId];
489
+ message += ` at ${marker.startLine + 1}:${marker.startColumn + 1}`;
490
+ if (marker.startOffset < marker.endOffset) {
491
+ message += "-";
492
+ if (marker.startLine < marker.endLine) {
493
+ message += `${marker.endLine + 1}:`;
494
+ }
495
+ message += `${marker.endColumn}`;
496
+ }
497
+ }
498
+ const messageText =
499
+ issue.message instanceof RegExp ? issue.message.toString() : issue.message;
500
+ message += ` - ${messageText}`;
501
+ return message;
502
+ }
503
+
@@ -0,0 +1,34 @@
1
+ import { LangiumDocument } from "langium";
2
+ import { parseMarkedText, ParseMarkedTextResult } from "../base/marker-parser.js";
3
+ import { parseHelper } from "langium/test";
4
+
5
+ export interface ParsedDocument {
6
+ markedText: string,
7
+ document: LangiumDocument,
8
+ markerData: ParseMarkedTextResult
9
+ }
10
+
11
+ type DoParse = ReturnType<typeof parseHelper>
12
+
13
+ /**
14
+ * Extract markers and parse dsl and run validation.
15
+ *
16
+ * @param doParse parse method returned from `parseHelper` method.
17
+ * @param text DSL with markers
18
+ * @param [endMarker="|}>>"] (optional) begin marker
19
+ * @param [beginMarker="<<{|"] (optional) end marker
20
+ */
21
+ export async function parseWithMarks(
22
+ doParse: DoParse,
23
+ text: string,
24
+ beginMarker: string = "<<{|",
25
+ endMarker: string = "|}>>"
26
+ ): Promise<ParsedDocument> {
27
+ const markerData = parseMarkedText(text, beginMarker, endMarker);
28
+ const document = await doParse(markerData.text, { validation: true });
29
+ return {
30
+ markedText: text,
31
+ document: document,
32
+ markerData: markerData
33
+ };
34
+ }