Jayvee goes ESM (Langium Upgrade)

.eslintrc.json

@@ -3,9 +3,6 @@
   "extends": "@jvalue/eslint-config-jvalue",
   "ignorePatterns": ["**/*"],
   "plugins": ["@nx"],
-  "parserOptions": {
-    "project": ["./tsconfig.base.json"]
-  },
   "overrides": [
     {
       "files": ["*.ts", ".tsx"],
@@ -37,6 +34,25 @@
         ]
       }
     },
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "plugins": ["unicorn"],
+      "rules": {
+        "unicorn/prefer-node-protocol": "warn",
+        "unicorn/import-style": "warn",
+        "no-restricted-imports": [
+          "error",
+          {
+            "paths": [
+              {
+                "name": "node:assert",
+                "message": "Please use the library `assert` instead to keep browser compatibility. You might need to disable rule `unicorn/prefer-node-protocol` to do so."
+              }
+            ]
+          }
+        ]
+      }
+    },
     {
       "files": ["*.ts", "*.tsx"],
       "extends": ["plugin:@nx/typescript"],
@@ -49,14 +65,10 @@
     },
     {
       "files": ["*.spec.ts", "*.spec.tsx", "*.spec.js", "*.spec.jsx"],
-      "plugins": ["jest"],
-      "env": {
-        "jest": true
-      },
+      "plugins": ["vitest"],
       "rules": {
         // you should turn the original rule off *only* for test files
-        "@typescript-eslint/unbound-method": "off",
-        "jest/unbound-method": "error"
+        "@typescript-eslint/unbound-method": "off"
       }
     }
   ]

.vscode/extensions.json

@@ -2,6 +2,7 @@
   "recommendations": [
     "nrwl.angular-console",
     "langium.langium-vscode",
-    "firsttris.vscode-jest-runner"
+    "esbenp.prettier-vscode",
+    "vitest.explorer"
   ]
 }

apps/docs-generator/.eslintrc.json

@@ -0,0 +1,21 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "parserOptions": {
+    "project": ["apps/docs-generator/tsconfig.app.json"]
+  },
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

apps/docs-generator/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

apps/docs-generator/project.json

@@ -0,0 +1,30 @@
+{
+  "name": "docs-generator",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/docs-generator/src",
+  "projectType": "application",
+  "targets": {
+    "build": {
+      "dependsOn": ["generate-language-server"],
+      "options": {
+        "main": "{projectRoot}/src/main.ts",
+        "tsConfig": "{projectRoot}/tsconfig.app.json"
+      }
+    },
+    "start": {
+      "executor": "@nx/js:node",
+      "options": {
+        "watch": false,
+        "buildTarget": "docs-generator:build"
+      }
+    },
+    "generate-language-server": {
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": ["nx run language-server:generate"],
+        "parallel": false
+      }
+    }
+  },
+  "tags": []
+}

apps/docs/generator/src/main.ts → apps/docs-generator/src/main.ts

@@ -2,8 +2,9 @@
 //
 // SPDX-License-Identifier: AGPL-3.0-only
 
-import { readFileSync, readdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path, { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import {
   type JayveeServices,
@@ -16,35 +17,33 @@ import { NodeFileSystem } from 'langium/node';
 
 import { UserDocGenerator } from './user-doc-generator';
 
+/** ESM does not know __filename and __dirname, so defined here */
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
 async function main(): Promise<void> {
-  const rootPath = join(__dirname, '..', '..', '..', '..');
+  const docsAppPath = join(__dirname, '..', '..', '..', 'apps', 'docs');
+  const jayveeExamplesPath = join(__dirname, '..', '..', '..', 'example');
 
   const services = createJayveeServices(NodeFileSystem).Jayvee;
   await initializeWorkspace(services);
 
-  generateBlockTypeDocs(services, rootPath);
-  generateConstraintTypeDocs(services, rootPath);
-  generateValueTypeDocs(services, rootPath);
-  generateExampleDocs(rootPath);
+  generateBlockTypeDocs(services, docsAppPath);
+  generateConstraintTypeDocs(services, docsAppPath);
+  generateValueTypeDocs(services, docsAppPath);
+  generateExampleDocs(jayveeExamplesPath, docsAppPath);
 }
 
 function generateBlockTypeDocs(
   services: JayveeServices,
-  rootPath: string,
+  docsAppPath: string,
 ): void {
   const blockTypes = getAllBuiltinBlockTypes(
     services.shared.workspace.LangiumDocuments,
     services.WrapperFactories,
   );
 
-  const docsPath = join(
-    rootPath,
-    'apps',
-    'docs',
-    'docs',
-    'user',
-    'block-types',
-  );
+  const docsPath = join(docsAppPath, 'docs', 'user', 'block-types');
 
   for (const blockType of blockTypes) {
     const userDocBuilder = new UserDocGenerator(services);
@@ -60,16 +59,9 @@ function generateBlockTypeDocs(
 
 function generateConstraintTypeDocs(
   services: JayveeServices,
-  rootPath: string,
+  docsAppPath: string,
 ): void {
-  const docsPath = join(
-    rootPath,
-    'apps',
-    'docs',
-    'docs',
-    'user',
-    'constraint-types',
-  );
+  const docsPath = join(docsAppPath, 'docs', 'user', 'constraint-types');
   const constraintTypes = getAllBuiltinConstraintTypes(
     services.shared.workspace.LangiumDocuments,
     services.WrapperFactories,
@@ -90,16 +82,9 @@ function generateConstraintTypeDocs(
 
 function generateValueTypeDocs(
   services: JayveeServices,
-  rootPath: string,
+  docsAppPath: string,
 ): void {
-  const docsPath = join(
-    rootPath,
-    'apps',
-    'docs',
-    'docs',
-    'user',
-    'value-types',
-  );
+  const docsPath = join(docsAppPath, 'docs', 'user', 'value-types');
   const userDocBuilder = new UserDocGenerator(services);
   const valueTypeDoc = userDocBuilder.generateValueTypesDoc(
     services.ValueTypeProvider.Primitives.getAll(),
@@ -112,9 +97,8 @@ function generateValueTypeDocs(
   console.info(`Generated file ${fileName}`);
 }
 
-function generateExampleDocs(rootPath: string): void {
-  const docsPath = join(rootPath, 'apps', 'docs', 'docs', 'user', 'examples');
-  const examplesPath = join(rootPath, 'example');
+function generateExampleDocs(examplesPath: string, docsAppPath: string): void {
+  const docsPath = join(docsAppPath, 'docs', 'user', 'examples');
 
   for (const file of readdirSync(examplesPath)) {
     if (file.endsWith('.jv')) {

apps/docs/generator/src/user-doc-generator.ts → apps/docs-generator/src/user-doc-generator.ts

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: AGPL-3.0-only
 
+// eslint-disable-next-line unicorn/prefer-node-protocol
 import { strict as assert } from 'assert';
 
 import {

apps/docs-generator/tsconfig.app.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"],
+  "include": ["src/**/*.ts"]
+}

apps/docs-generator/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    }
+  ],
+  "compilerOptions": {
+    "esModuleInterop": true
+  }
+}

apps/docs-generator/tsconfig.json.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only

apps/docs/.eslintrc.json

@@ -1,6 +1,16 @@
 {
   "extends": ["../../.eslintrc.json"],
-  "ignorePatterns": ["!**/*", "**/.docusaurus/**", "**/theme/prism-jayvee.js"],
+  "ignorePatterns": [
+    "!**/*",
+    "**/.docusaurus/**",
+    "**/theme/prism-jayvee.js",
+    "*.config.js",
+    "**/prism-include-languages.js",
+    "**/sidebars.js"
+  ],
+  "parserOptions": {
+    "project": ["apps/docs/tsconfig.app.json"]
+  },
   "overrides": [
     {
       "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],

apps/docs/docs/dev/04-guides/02-working-with-the-ast.md

@@ -124,7 +124,9 @@ After calling `assert`, the type system of TypeScript assumes the condition to b
 Here is an example of how to use it in practice:
 
 ```typescript
-// Import the `assert` function like this:
+// We use the `assert` function from the `assert` library, not `node:assert` (to preserve browser compatibility)
+
+// eslint-disable-next-line unicorn/prefer-node-protocol
 import { strict as assert } from 'assert';
 
 import { A, B, isB } from './ast';