docs: add Docusaurus website

Also refactor Yarn buildscripts.

13 files changed, 418 insertions, 40 deletions

diff --git a/subprojects/docs/.gitignore b/subprojects/docs/.gitignore
new file mode 100644
index 00000000..2d94aa21
--- /dev/null
+++ b/subprojects/docs/.gitignore
@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2024 The Refinery Authors
+#
+# SPDX-License-Identifier: CC0-1.0
+
+.docusaurus
+.yarn
diff --git a/subprojects/docs/babel.config.cts b/subprojects/docs/babel.config.cts
new file mode 100644
index 00000000..b1bc1281
--- /dev/null
+++ b/subprojects/docs/babel.config.cts
@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ * Copyright (c) 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: MIT AND EPL-2.0
+ */
+
+import type { TransformOptions } from '@babel/core';
+
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+} satisfies TransformOptions;
diff --git a/subprojects/docs/build.gradle.kts b/subprojects/docs/build.gradle.kts
new file mode 100644
index 00000000..9226ffe0
--- /dev/null
+++ b/subprojects/docs/build.gradle.kts
@@ -0,0 +1,91 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+import org.siouan.frontendgradleplugin.infrastructure.gradle.RunYarn
+import tools.refinery.gradle.utils.SonarPropertiesUtils
+
+plugins {
+        id("tools.refinery.gradle.frontend-workspace")
+        id("tools.refinery.gradle.sonarqube")
+}
+
+frontend {
+        assembleScript.set("run build")
+}
+
+val srcDir = "src"
+
+val docusaurusOutputDir = layout.buildDirectory.dir("docusaurus")
+
+val configFiles: FileCollection = files(
+        rootProject.file("yarn.lock"),
+        rootProject.file("package.json"),
+        "package.json",
+        rootProject.file("tsconfig.base.json"),
+        "tsconfig.json",
+        "babel.config.config.ts",
+        "docusaurus.config.ts",
+)
+
+val lintConfigFiles: FileCollection = configFiles + files(
+        rootProject.file(".eslintrc.cjs"),
+        rootProject.file("prettier.config.cjs")
+)
+
+tasks {
+        assembleFrontend {
+                inputs.dir("src")
+                inputs.files(configFiles)
+                outputs.dir(docusaurusOutputDir)
+        }
+
+        val typeCheckFrontend by registering(RunYarn::class) {
+                dependsOn(installFrontend)
+                inputs.dir(srcDir)
+                inputs.files(configFiles)
+                outputs.dir(layout.buildDirectory.dir("typescript"))
+                script.set("run typecheck")
+                group = "verification"
+                description = "Check for TypeScript type errors."
+        }
+
+        val lintFrontend by registering(RunYarn::class) {
+                dependsOn(installFrontend)
+                dependsOn(typeCheckFrontend)
+                inputs.dir(srcDir)
+                inputs.files(lintConfigFiles)
+                outputs.file(layout.buildDirectory.file("eslint.json"))
+                script.set("run lint")
+                group = "verification"
+                description = "Check for TypeScript lint errors and warnings."
+        }
+
+        register<RunYarn>("fixFrontend") {
+                dependsOn(installFrontend)
+                dependsOn(typeCheckFrontend)
+                inputs.dir(srcDir)
+                inputs.files(lintConfigFiles)
+                script.set("run lint:fix")
+                group = "verification"
+                description = "Check for TypeScript lint errors and warnings."
+        }
+
+        check {
+                dependsOn(typeCheckFrontend)
+                dependsOn(lintFrontend)
+        }
+
+        clean {
+                delete(".docusaurus")
+                delete(".yarn")
+        }
+}
+
+sonarqube.properties {
+        SonarPropertiesUtils.addToList(properties, "sonar.sources", srcDir)
+        property("sonar.nodejs.executable", "${frontend.nodeInstallDirectory.get()}/bin/node")
+        property("sonar.eslint.reportPaths", "${layout.buildDirectory.get()}/eslint.json")
+}
diff --git a/subprojects/docs/docusaurus.config.ts b/subprojects/docs/docusaurus.config.ts
new file mode 100644
index 00000000..d0f1b33a
--- /dev/null
+++ b/subprojects/docs/docusaurus.config.ts
@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ * Copyright (c) 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: MIT AND EPL-2.0
+ */
+
+import type { Options as PagesOptions } from '@docusaurus/plugin-content-pages';
+import type { Options as ClassicThemeOptions } from '@docusaurus/theme-classic';
+import type { UserThemeConfig } from '@docusaurus/theme-common';
+import type { Config } from '@docusaurus/types';
+import { Config as SwcConfig } from '@swc/core';
+import smartypants from 'remark-smartypants';
+
+const markdownOptions = {
+  remarkPlugins: [[smartypants, { dashes: 'oldschool' }]],
+};
+
+export default {
+  title: 'Refinery',
+  url: 'https://refinery.tools',
+  baseUrl: '/',
+  baseUrlIssueBanner: false,
+  trailingSlash: true,
+  staticDirectories: ['static'],
+  plugins: [
+    [
+      '@docusaurus/plugin-content-pages',
+      markdownOptions satisfies PagesOptions,
+    ],
+    '@docusaurus/plugin-sitemap',
+    './src/plugins/swcMinifyPlugin.ts',
+  ],
+  themes: [
+    [
+      '@docusaurus/theme-classic',
+      {
+        customCss: [require.resolve('./src/css/custom.css')],
+      } satisfies ClassicThemeOptions,
+    ],
+  ],
+  themeConfig: {
+    colorMode: {
+      respectPrefersColorScheme: true,
+    },
+    navbar: {
+      title: 'Refinery',
+      hideOnScroll: true,
+    },
+    footer: {
+      copyright: `
+        Copyright &copy; 2021-2024
+        <a href="https://github.com/graphs4value/refinery/blob/main/CONTRIBUTORS.md" target="_blank">The Refinery Authors</a>.
+        Available under the
+        <a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">Eclipse Public License - v 2.0</a>.
+      `,
+    },
+  } satisfies UserThemeConfig,
+  webpack: {
+    // Speed up builds by using a native Javascript loader.
+    // See: https://github.com/facebook/docusaurus/issues/4765#issuecomment-841135926
+    // But we follow the Docusaurus upstream from
+    // https://github.com/facebook/docusaurus/blob/791da2e4a1a53aa6309887059e3f112fcb35bec4/website/docusaurus.config.ts#L152-L171
+    // and use swc instead of esbuild.
+    jsLoader: (isServer) => ({
+      loader: require.resolve('swc-loader'),
+      options: {
+        jsc: {
+          parser: {
+            syntax: 'typescript',
+            tsx: true,
+          },
+          transform: {
+            react: {
+              runtime: 'automatic',
+            },
+          },
+          target: 'es2022',
+        },
+        module: {
+          type: isServer ? 'commonjs' : 'es6',
+        },
+      } satisfies SwcConfig,
+    }),
+  },
+} satisfies Config;
diff --git a/subprojects/docs/package.json b/subprojects/docs/package.json
new file mode 100644
index 00000000..bdf95a70
--- /dev/null
+++ b/subprojects/docs/package.json
@@ -0,0 +1,59 @@
+{
+  "//": [
+    "SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/>",
+    "",
+    "SPDX-License-Identifier: EPL-2.0"
+  ],
+  "name": "@refinery/docs",
+  "version": "0.0.0",
+  "description": "Documentation for Refinery",
+  "private": true,
+  "scripts": {
+    "build": "WEBPACK_URL_LOADER_LIMIT=0 docusaurus build --out-dir build/docusaurus",
+    "serve": "docusaurus serve --dir build/docusaurus --port 1313 --no-open",
+    "dev": "WEBPACK_URL_LOADER_LIMIT=0 docusaurus start --port 1313 --no-open",
+    "docusaurus": "docusaurus",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "typecheck": "yarn run g:tsc -p subprojects/docs/tsconfig.json",
+    "lint": "yarn run g:lint subprojects/docs",
+    "lint:fix": "yarn run lint --fix"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graphs4value/refinery.git"
+  },
+  "author": "The Refinery Authors <https://refinery.tools/>",
+  "license": "EPL-2.0",
+  "bugs": {
+    "url": "https://github.com/graphs4value/refinery/issues"
+  },
+  "homepage": "https://refinery.tools",
+  "dependencies": {
+    "@docusaurus/core": "^3.2.1",
+    "@docusaurus/plugin-content-docs": "^3.2.1",
+    "@docusaurus/plugin-content-pages": "^3.2.1",
+    "@docusaurus/plugin-sitemap": "^3.2.1",
+    "@docusaurus/theme-classic": "^3.2.1",
+    "@docusaurus/theme-common": "^3.2.1",
+    "@fontsource-variable/jetbrains-mono": "^5.0.20",
+    "@fontsource-variable/open-sans": "^5.0.28",
+    "@fontsource/open-sans": "^5.0.27",
+    "@mdx-js/react": "^3.0.1",
+    "@swc/core": "^1.4.12",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "remark-smartypants": "^2.1.0",
+    "swc-loader": "^0.2.6",
+    "terser-webpack-plugin": "^5.3.10",
+    "webpack": "^5.91.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^3.2.1",
+    "@docusaurus/types": "^3.2.1",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^20.12.5",
+    "@types/react": "^18.2.74",
+    "@types/react-dom": "^18.2.24"
+  }
+}
diff --git a/subprojects/docs/src/css/custom.css b/subprojects/docs/src/css/custom.css
new file mode 100644
index 00000000..115d7ac9
--- /dev/null
+++ b/subprojects/docs/src/css/custom.css
@@ -0,0 +1,40 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+@import '@fontsource-variable/open-sans/wdth.css';
+@import '@fontsource-variable/open-sans/wdth-italic.css';
+@import '@fontsource-variable/jetbrains-mono/wght.css';
+@import '@fontsource-variable/jetbrains-mono/wght-italic.css';
+
+:root {
+  --ifm-font-family-base: 'Open Sans Variable',
+    'Open Sans',
+    'Roboto',
+    'Helvetica',
+    'Arial',
+    sans-serif;
+  --ifm-fony-family-monospace: 'JetBrains Mono Variable',
+    'JetBrains Mono',
+    'Cascadia Code',
+    'Fira Code',
+    monospace;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+[data-theme='dark'] {
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}
+
+code,
+kbd {
+  font-feature-settings: 'liga', 'calt';
+}
+
+.navbar__title {
+  font-weight: 500;
+  font-size: 1.25rem;
+}
diff --git a/subprojects/docs/src/pages/index.tsx b/subprojects/docs/src/pages/index.tsx
new file mode 100644
index 00000000..256d12ac
--- /dev/null
+++ b/subprojects/docs/src/pages/index.tsx
@@ -0,0 +1,19 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+import Layout from '@theme/Layout';
+
+export default function Home() {
+  return (
+    <Layout>
+      <div className="hero hero--dark">
+        <div className="container">
+          <h1 className="hero__title">Refinery</h1>
+        </div>
+      </div>
+    </Layout>
+  );
+}
diff --git a/subprojects/docs/src/plugins/swcMinifyPlugin.ts b/subprojects/docs/src/plugins/swcMinifyPlugin.ts
new file mode 100644
index 00000000..ecac654b
--- /dev/null
+++ b/subprojects/docs/src/plugins/swcMinifyPlugin.ts
@@ -0,0 +1,41 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+import type { Plugin } from '@docusaurus/types';
+import TerserPlugin from 'terser-webpack-plugin';
+
+/**
+ * A Docusarus plugin that replaces the built-in Javascript minifier with swc.
+ *
+ * See
+ * https://github.com/facebook/docusaurus/issues/4765#issuecomment-1679863984
+ * but we use swc instead of esbuild.
+ *
+ * @returns The Docusarus plugin.
+ */
+export default function swcMinifyPlugin(): Plugin {
+  return {
+    name: 'refinery-swc-minify-plugin',
+    configureWebpack: (config) => ({
+      mergeStrategy: {
+        'optimization.minimizer': 'replace',
+      },
+      optimization: {
+        minimizer:
+          config.optimization?.minimizer?.map((plugin) => {
+            // `instanceof` seems to be broken, because a different version of
+            // `TerserPlguin` is coming from Docusaurus than the one we import.
+            if (plugin?.constructor.name === TerserPlugin.name) {
+              return new TerserPlugin({
+                minify: TerserPlugin.swcMinify,
+              });
+            }
+            return plugin;
+          }) ?? [],
+      },
+    }),
+  };
+}
diff --git a/subprojects/docs/tsconfig.json b/subprojects/docs/tsconfig.json
new file mode 100644
index 00000000..5b32bb0e
--- /dev/null
+++ b/subprojects/docs/tsconfig.json
@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ * Copyright (c) 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: MIT AND EPL-2.0
+ *
+ * FIle based on
+ * https://github.com/facebook/docusaurus/blob/73016d4936164ba38d4b86ec2aa8c168b5904a21/packages/docusaurus-tsconfig/tsconfig.json
+ * but copied instead of adding an `extends` declaration to let SonarQube see its contents.
+ */
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "types": [
+      "node",
+      "@docusaurus/module-type-aliases",
+      "@docusaurus/theme-classic"
+    ],
+    "baseUrl": ".",
+    "paths": {
+      "@site/*": ["./*"]
+    }
+  },
+  "include": ["."],
+  "exclude": [
+    ".docusaurus",
+    ".yarn",
+    "build"
+  ]
+}
diff --git a/subprojects/frontend/.gitignore b/subprojects/frontend/.gitignore
new file mode 100644
index 00000000..52a177c5
--- /dev/null
+++ b/subprojects/frontend/.gitignore
@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2021-2023 The Refinery Authors
+#
+# SPDX-License-Identifier: CC0-1.0
+
+dev-dist/
+*.typegen.ts
diff --git a/subprojects/frontend/build.gradle.kts b/subprojects/frontend/build.gradle.kts
index ac2c1817..10a138b1 100644
--- a/subprojects/frontend/build.gradle.kts
+++ b/subprojects/frontend/build.gradle.kts
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 The Refinery Authors <https://refinery.tools/>
+ * SPDX-FileCopyrightText: 2021-2024 The Refinery Authors <https://refinery.tools/>
  *
  * SPDX-License-Identifier: EPL-2.0
  */
@@ -25,40 +25,34 @@ val productionAssets: Configuration by configurations.creating {
         isCanBeResolved = false
 }
 
-val sourcesWithoutTypes = fileTree("src") {
+val sourcesWithoutTypes: FileCollection = fileTree("src") {
         exclude("**/*.typegen.ts")
 }
 
 val sourcesWithTypes: FileCollection = fileTree("src") + fileTree("types")
 
-val buildScripts: FileCollection = fileTree("config") + files(
-                rootProject.file(".eslintrc.cjs"),
-                rootProject.file("prettier.config.cjs"),
-                "vite.config.ts",
+val installationState: FileCollection = files(
+        rootProject.file("yarn.lock"),
+        rootProject.file("package.json"),
+        "package.json",
 )
 
-val installationState = files(
-                rootProject.file("yarn.lock"),
-                rootProject.file("package.json"),
-                "package.json",
-)
-
-val sharedConfigFiles: FileCollection = installationState + files(
-                rootProject.file("tsconfig.base.json"),
-                "tsconfig.json",
-                "tsconfig.node.json",
-                "tsconfig.shared.json",
-)
+val assembleConfigFiles: FileCollection = installationState + files(
+        rootProject.file("tsconfig.base.json"),
+        "tsconfig.json",
+        "tsconfig.node.json",
+        "tsconfig.shared.json",
+        "vite.config.ts",
+) + fileTree("config")
 
-val assembleConfigFiles = sharedConfigFiles + file("vite.config.ts") + fileTree("config") {
-        include("**/*.ts")
-}
-
-val assembleSources = sourcesWithTypes + fileTree("public") + file("index.html")
+val assembleSources: FileCollection = sourcesWithTypes + fileTree("public") + files("index.html")
 
-val assembleFiles = assembleSources + assembleConfigFiles
+val assembleFiles: FileCollection = assembleSources + assembleConfigFiles
 
-val lintingFiles: FileCollection = sourcesWithTypes + buildScripts + sharedConfigFiles
+val lintingFiles: FileCollection = sourcesWithTypes + assembleConfigFiles + files(
+        rootProject.file(".eslintrc.cjs"),
+        rootProject.file("prettier.config.cjs"),
+)
 
 tasks {
         val generateXStateTypes by registering(RunYarn::class) {
@@ -112,16 +106,6 @@ tasks {
                 dependsOn(lintFrontend)
         }
 
-        register<RunYarn>("serveFrontend") {
-                dependsOn(installFrontend)
-                dependsOn(generateXStateTypes)
-                inputs.files(assembleFiles)
-                outputs.dir(viteOutputDir.map { it.dir("development") })
-                script.set("run serve")
-                group = "run"
-                description = "Start a Vite dev server with hot module replacement."
-        }
-
         clean {
                 delete("dev-dist")
                 delete(fileTree("src") {
diff --git a/subprojects/frontend/package.json b/subprojects/frontend/package.json
index b133e762..d5bad0c2 100644
--- a/subprojects/frontend/package.json
+++ b/subprojects/frontend/package.json
@@ -11,7 +11,7 @@
   "private": true,
   "scripts": {
     "build": "MODE=production vite build",
-    "serve": "MODE=development vite serve",
+    "dev": "MODE=development vite serve",
     "typegen": "xstate typegen \"src/**/*.ts?(x)\"",
     "typecheck": "yarn run g:tsc -p subprojects/frontend/tsconfig.shared.json && yarn run g:tsc -p subprojects/frontend/tsconfig.node.json && yarn run g:tsc -p subprojects/frontend/tsconfig.json",
     "lint": "yarn run g:lint subprojects/frontend",
@@ -67,7 +67,7 @@
     "mobx": "^6.12.3",
     "mobx-react-lite": "^4.0.7",
     "ms": "^2.1.3",
-    "nanoid": "^5.0.6",
+    "nanoid": "^5.0.7",
     "notistack": "^3.0.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
diff --git a/subprojects/language-web/build.gradle.kts b/subprojects/language-web/build.gradle.kts
index c3a0b7e9..02e4ff17 100644
--- a/subprojects/language-web/build.gradle.kts
+++ b/subprojects/language-web/build.gradle.kts
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 The Refinery Authors <https://refinery.tools/>
+ * SPDX-FileCopyrightText: 2021-2024 The Refinery Authors <https://refinery.tools/>
  *
  * SPDX-License-Identifier: EPL-2.0
  */
@@ -55,7 +55,7 @@ tasks {
                 }
         }
 
-        register<JavaExec>("serveBackend") {
+        register<JavaExec>("serve") {
                 dependsOn(webapp)
                 val mainRuntimeClasspath = sourceSets.main.map { it.runtimeClasspath }
                 dependsOn(mainRuntimeClasspath)
@@ -67,7 +67,7 @@ tasks {
                 description = "Start a Jetty web server serving the Xtext API and assets."
         }
 
-        register<JavaExec>("serveBackendOnly") {
+        register<JavaExec>("serveBackend") {
                 val mainRuntimeClasspath = sourceSets.main.map { it.runtimeClasspath }
                 dependsOn(mainRuntimeClasspath)
                 classpath(mainRuntimeClasspath)