From 291957bc11d8b2677d9c2347e4abfdbd094464a6 Mon Sep 17 00:00:00 2001 From: Jonas Zeltner Date: Mon, 2 Mar 2026 16:51:48 +0100 Subject: [PATCH 1/5] chore: add npm script to clean all build artifacts Problem: `npm run build` generates lots of artifacts, many of them inside the source tree, but currently there is no way to remove them. Solution: add an npm script that clears the nx cache and removes generates files. --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 0f2cdcd7..c06b1bd2 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,8 @@ "example:gtfs": "nx run interpreter:run -d example/gtfs-static.jv -dg peek", "example:gtfs-rt": "nx run interpreter:run -d example/gtfs-rt.jv -dg peek", "example:workbooks": "nx run interpreter:run -d example/workbooks-xlsx.jv -dg peek", - "example:vehicles": "nx run interpreter:run -d -e DB_HOST=localhost -e DB_PORT=5432 -e DB_USERNAME=postgres -e DB_PASSWORD=postgres -e DB_DATABASE=postgres example/electric-vehicles.jv -dg peek" + "example:vehicles": "nx run interpreter:run -d -e DB_HOST=localhost -e DB_PORT=5432 -e DB_USERNAME=postgres -e DB_PASSWORD=postgres -e DB_DATABASE=postgres example/electric-vehicles.jv -dg peek", + "clean": "nx reset && rm -r dist/ tmp/ apps/vs-code-extension/assets/jayvee.tmLanguage.json apps/docs/docs/user/block-types/**/*.md apps/docs/docs/user/value-types/built-in-value-types.md apps/docs/docs/user/examples/*.md apps/docs/src/theme/prism-jayvee.js libs/language-server/src/lib/*/generated libs/monaco-editor/src/lib/{language-configuration,jayvee.tmLanguage}.json" }, "private": true, "dependencies": { From 64436b197adc7129478421086f61ba7186baf653 Mon Sep 17 00:00:00 2001 From: Jonas Zeltner Date: Mon, 2 Mar 2026 17:14:55 +0100 Subject: [PATCH 2/5] fix: abort document generation on error Problem: If there is an error during document generation, the error is printed, but document generation continues, failing later in the pipeline. Solution: Throw the error, making node exit with a non-zero error code, making nx abort the pipeline with a failure at the right location --- apps/docs-generator/src/main.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/apps/docs-generator/src/main.ts b/apps/docs-generator/src/main.ts index 4126bcfd..ae8a8e38 100644 --- a/apps/docs-generator/src/main.ts +++ b/apps/docs-generator/src/main.ts @@ -131,4 +131,6 @@ ${exampleModel.toString()} main() .then(() => console.log('Finished generating docs!')) - .catch((e) => console.error(e)); + .catch((e) => { + throw e; + }); From b5082fa67edf5d92a155e0d53d0658af776cd520 Mon Sep 17 00:00:00 2001 From: Jonas Zeltner Date: Wed, 4 Mar 2026 13:55:55 +0100 Subject: [PATCH 3/5] fix: replace `@nx/js:node` executor with `nx:run-commands` Problem: For some reason, the `@nx/js:node` SILENTLY ABORTS the exectution after a timeout, WHITHOUT an error code. See https://github.com/nrwl/nx/blob/4377c8b00d2343058f7d4ebd572d18b559682b43/packages/js/src/executors/node/node.impl.ts#L109-L132 Solution: Use the `nx:run-commands` executor instead --- apps/docs-generator/project.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/apps/docs-generator/project.json b/apps/docs-generator/project.json index 45085706..a8beaaf6 100644 --- a/apps/docs-generator/project.json +++ b/apps/docs-generator/project.json @@ -13,11 +13,11 @@ } }, "start": { - "executor": "@nx/js:node", - "dependsOn": ["generate-language-server"], + "executor": "nx:run-commands", + "dependsOn": ["generate-language-server", "build"], "options": { - "watch": false, - "buildTarget": "docs-generator:build" + "commands": ["node dist/apps/docs-generator/main.js"], + "parallel": false } }, "generate-language-server": { From 9d7ba11de3bb617ddaf459cd86245aa49af1d224 Mon Sep 17 00:00:00 2001 From: Jonas Zeltner Date: Thu, 5 Mar 2026 09:13:25 +0100 Subject: [PATCH 4/5] feat(docs-generator): allow pimitive value types to have their own examles Problem: The docs-generator uses an (outdated) example for all referencable valuetypes. Solution: Get the example from an overridable valuetype method and update the default --- apps/docs-generator/src/user-doc-generator.ts | 25 +++------------ .../primitive/boolean-value-type.ts | 2 +- .../primitive/decimal-value-type.ts | 2 +- .../primitive/integer-value-type.ts | 2 +- .../primitive/primitive-value-type.ts | 32 ++++++++++++++++++- .../value-type/primitive/text-value-type.ts | 4 +-- .../src/lib/workspace/stdlib.ts | 2 +- 7 files changed, 42 insertions(+), 27 deletions(-) diff --git a/apps/docs-generator/src/user-doc-generator.ts b/apps/docs-generator/src/user-doc-generator.ts index 0263d851..a7dcaddc 100644 --- a/apps/docs-generator/src/user-doc-generator.ts +++ b/apps/docs-generator/src/user-doc-generator.ts @@ -38,30 +38,15 @@ that fullfil [_constraints_](./primitive-value-types#constraints).`.trim(), valueTypes .filter((valueType) => valueType.isReferenceableByUser()) .forEach((valueType) => { + const description = valueType.getUserDocDescription(); assert( - valueType.getUserDoc() !== undefined, + description !== undefined, `Documentation is missing for user extendable value type: ${valueType.getName()}`, ); builder .heading(valueType.getName(), 2) - .description(valueType.getUserDoc() ?? '', 3) - .examples( - [ - { - code: ` -block ExampleTableInterpreter oftype TableInterpreter { - header: true; - columns: [ - "columnName" oftype ${valueType.getName()} - ]; -}`.trim(), - description: `A block of type \`TableInterpreter\` that - interprets data in the column \`columnName\` as \`${valueType.getName()}\`. - `.trim(), - }, - ], - 3, - ); + .description(description, 3) + .examples(valueType.getUserDocExamples(), 3); }); return builder.build(); @@ -109,7 +94,7 @@ block ExampleTableInterpreter oftype TableInterpreter { return builder.build(); } - private extractDocsFromComment(comment?: string | undefined): + private extractDocsFromComment(comment?: string): | { description: string | undefined; examples: ExampleDoc[]; diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/boolean-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/boolean-value-type.ts index 911b2c40..66cb0067 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/boolean-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/boolean-value-type.ts @@ -36,7 +36,7 @@ export class BooleanValuetype extends PrimitiveValueType { return true; } - override getUserDoc(): string { + override getUserDocDescription(): string { return ` A boolean value. Examples: true, false diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/decimal-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/decimal-value-type.ts index 05090e70..68d3f269 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/decimal-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/decimal-value-type.ts @@ -43,7 +43,7 @@ export class DecimalValuetype extends PrimitiveValueType { return true; } - override getUserDoc(): string { + override getUserDocDescription(): string { return ` A decimal value. Example: 3.14 diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/integer-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/integer-value-type.ts index 531b1760..53ddd0cd 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/integer-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/integer-value-type.ts @@ -39,7 +39,7 @@ export class IntegerValuetype extends PrimitiveValueType { return true; } - override getUserDoc(): string { + override getUserDocDescription(): string { return ` An integer value. Example: 3 diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/primitive-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/primitive-value-type.ts index 818dc657..0b0c57ff 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/primitive-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/primitive-value-type.ts @@ -8,6 +8,7 @@ import { } from '../../../expressions/internal-value-representation'; import { AbstractValueType } from '../abstract-value-type'; import { type ValueType } from '../value-type'; +import { type ExampleDoc } from '../../typed-object/typed-object-wrapper'; export abstract class PrimitiveValueType< I extends InternalValidValueRepresentation = InternalValidValueRepresentation, @@ -33,10 +34,39 @@ export abstract class PrimitiveValueType< * Text only, no comment characters. * Should be given for all user-referenceable value types {@link isReferenceableByUser} */ - getUserDoc(): string | undefined { + getUserDocDescription(): string | undefined { return undefined; } + getUserDocExamples(): ExampleDoc[] { + const name = this.getName(); + const capitalizedName = name.charAt(0).toUpperCase() + name.slice(1); + return [ + { + code: ` +valuetype TableSchema { + tableColumn: ${name}; +} +transfrom tableRowParser { + from r oftype SheetRow; + to tableRow oftye TableSchema; + + tableRow: { + tableColumn: as${capitalizedName} (r . "tableColumn"); + }; +} +block ExampleTableInterpreter oftype TableInterpreter { + header: true; + columns: TableSchema; + parseWith: tableRowParser; +}`.trim(), + description: + `A block of type \`TableInterpreter\` that interprets data in the column "columnName" as \`${name}\`. + `.trim(), + }, + ]; + } + // eslint-disable-next-line @typescript-eslint/no-unused-vars fromString(_s: string): I | InvalidValue { return new InvalidValue(`Cannot parse ${this.getName()}`); diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/text-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/text-value-type.ts index e7010c75..c80896f1 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/text-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/text-value-type.ts @@ -30,9 +30,9 @@ export class TextValuetype extends PrimitiveValueType { return true; } - override getUserDoc(): string { + override getUserDocDescription(): string { return ` -A text value. +A text value. Example: "Hello World" `.trim(); } diff --git a/libs/language-server/src/lib/workspace/stdlib.ts b/libs/language-server/src/lib/workspace/stdlib.ts index 375259d0..14fd518f 100644 --- a/libs/language-server/src/lib/workspace/stdlib.ts +++ b/libs/language-server/src/lib/workspace/stdlib.ts @@ -39,7 +39,7 @@ export function getStdLib() { function parseBuiltinValuetypeToJayvee(valueType: PrimitiveValueType): string { const lines: string[] = []; - const userDoc = valueType.getUserDoc(); + const userDoc = valueType.getUserDocDescription(); if (userDoc !== undefined) { lines.push(parseAsComment(userDoc)); } From d32d6d94d01ca8c5abd9e9baf77e0431cf2df34b Mon Sep 17 00:00:00 2001 From: Jonas Zeltner Date: Thu, 5 Mar 2026 09:14:24 +0100 Subject: [PATCH 5/5] fix(docs): add documentation for `SheetRow` Problem: Document generation crashes because `SheetRow` does not provide required documentation Solution: Override the required method and provide a custom example The previous commits make sure the pipeline actually crashes at the correct location, instead of failing silently or too late. This commit actually fixes the pipeline --- .../primitive/sheetrow-value-type.ts | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/sheetrow-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/sheetrow-value-type.ts index 84cdee0b..e89c5085 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/sheetrow-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/sheetrow-value-type.ts @@ -5,6 +5,7 @@ import { PrimitiveValueType } from './primitive-value-type'; import { type ValueTypeVisitor } from '../value-type'; import { type InternalValidValueRepresentation } from '../../../expressions'; +import { type ExampleDoc } from '../../typed-object/typed-object-wrapper'; export class SheetRowValueType extends PrimitiveValueType { acceptVisitor(visitor: ValueTypeVisitor): R { @@ -19,6 +20,41 @@ export class SheetRowValueType extends PrimitiveValueType { return 'SheetRow'; } + override getUserDocDescription(): string { + return ` +The values of a row inside a sheet. Only usable inside a transform that parses SheetRows into a value type. +Accessible via the dot operator (see example). +`.trim(); + } + + override getUserDocExamples(): ExampleDoc[] { + return [ + { + code: ` +valuetype Coordinate { + x: decimal; + y: decimal; +} +transfrom coordinateParser { + from r oftype SheetRow; + to coord oftye Coordinate; + + coord: { + x: asDecimal (r . "x"); + y: asDecimal (r . 1); + }; +} +block ExampleTableInterpreter oftype TableInterpreter { + header: true; + columns: Coordinate; + parseWith: CoordinateParser; +}`.trim(), + description: + 'A transform, used in a block of type `TableInterpreter`, that interprets a `SheetRow` into a table row with columns `x` and `y`.', + }, + ]; + } + override isInternalValidValueRepresentation( operandValue: InternalValidValueRepresentation, ): operandValue is string[] {