feat(build-docs): generate script API

_regroup/package.json

@@ -48,9 +48,7 @@
     "lorem-ipsum": "2.0.8",    
     "rcedit": "4.0.1",
     "rimraf": "6.0.1",    
-    "tslib": "2.8.1",    
+    "tslib": "2.8.1"    
-    "typedoc": "0.28.14",
-    "typedoc-plugin-missing-exports": "4.1.2"
   },
   "optionalDependencies": {
     "appdmg": "0.6.6"

_regroup/typedoc.json

@@ -1,15 +0,0 @@
-{
-  "entryPoints": [
-    "src/services/backend_script_entrypoint.ts",
-    "src/public/app/services/frontend_script_entrypoint.ts"
-  ],
-  "plugin": [
-    "typedoc-plugin-missing-exports"
-  ],
-  "outputs": [
-    {
-      "name": "html",
-      "path": "./docs/Script API"
-    }
-  ]
-}

apps/build-docs/package.json

@@ -15,6 +15,8 @@
     "archiver": "7.0.1",
     "fs-extra": "11.3.2",
     "react": "19.2.0",
-    "react-dom": "19.2.0"
+    "react-dom": "19.2.0",
+    "typedoc": "0.28.14",
+    "typedoc-plugin-missing-exports": "4.1.2"
   }
 }

apps/build-docs/src/backend_script_entrypoint.ts

@@ -0,0 +1,36 @@
+/**
+ * The backend script API is accessible to code notes with the "JS (backend)" language.
+ *
+ * The entire API is exposed as a single global: {@link api}
+ *
+ * @module Backend Script API
+ */
+
+/**
+ * This file creates the entrypoint for TypeDoc that simulates the context from within a
+ * script note on the server side.
+ *
+ * Make sure to keep in line with backend's `script_context.ts`.
+ */
+
+export type { default as AbstractBeccaEntity } from "../../server/src/becca/entities/abstract_becca_entity.js";
+export type { default as BAttachment } from "../../server/src/becca/entities/battachment.js";
+export type { default as BAttribute } from "../../server/src/becca/entities/battribute.js";
+export type { default as BBranch } from "../../server/src/becca/entities/bbranch.js";
+export type { default as BEtapiToken } from "../../server/src/becca/entities/betapi_token.js";
+export type { BNote };
+export type { default as BOption } from "../../server/src/becca/entities/boption.js";
+export type { default as BRecentNote } from "../../server/src/becca/entities/brecent_note.js";
+export type { default as BRevision } from "../../server/src/becca/entities/brevision.js";
+
+import BNote from "../../server/src/becca/entities/bnote.js";
+import BackendScriptApi, { type Api } from "../../server/src/services/backend_script_api.js";
+
+export type { Api };
+
+const fakeNote = new BNote();
+
+/**
+ * The `code` api global variable allows access to the backend script API, which is documented in {@link Api}.
+ */
+export const api: Api = new BackendScriptApi(fakeNote, {});

apps/build-docs/src/frontend_script_entrypoint.ts

@@ -0,0 +1,28 @@
+/**
+ * The front script API is accessible to code notes with the "JS (frontend)" language.
+ *
+ * The entire API is exposed as a single global: {@link api}
+ *
+ * @module Frontend Script API
+ */
+
+/**
+ * This file creates the entrypoint for TypeDoc that simulates the context from within a
+ * script note.
+ *
+ * Make sure to keep in line with frontend's `script_context.ts`.
+ */
+
+export type { default as BasicWidget } from "../../client/src/widgets/basic_widget.js";
+export type { default as FAttachment } from "../../client/src/entities/fattachment.js";
+export type { default as FAttribute } from "../../client/src/entities/fattribute.js";
+export type { default as FBranch } from "../../client/src/entities/fbranch.js";
+export type { default as FNote } from "../../client/src/entities/fnote.js";
+export type { Api } from "../../client/src/services/frontend_script_api.js";
+export type { default as NoteContextAwareWidget } from "../../client/src/widgets/note_context_aware_widget.js";
+export type { default as RightPanelWidget } from "../../client/src/widgets/right_panel_widget.js";
+
+import FrontendScriptApi, { type Api } from "../../client/src/services/frontend_script_api.js";
+
+//@ts-expect-error
+export const api: Api = new FrontendScriptApi();

apps/build-docs/src/main.ts

@@ -3,6 +3,7 @@ import BuildContext from "./context";
 import buildSwagger from "./swagger";
 import { existsSync, mkdirSync, rmSync } from "fs";
 import buildDocs from "./build-docs";
+import buildScriptApi from "./script-api";
 
 const context: BuildContext = {
     gitRootDir: join(__dirname, "../../../"),
@@ -19,6 +20,7 @@ async function main() {
     // Start building.
     await buildDocs(context);
     buildSwagger(context);
+    buildScriptApi(context);
 }
 
 main();

apps/build-docs/src/script-api.ts

@@ -0,0 +1,9 @@
+import { execSync } from "child_process";
+import BuildContext from "./context";
+
+export default function buildScriptApi({ }: BuildContext) {
+    execSync(`pnpm typedoc`, {
+        stdio: "inherit"
+        // * Output dir is set in typedoc.json.
+    });
+}

apps/build-docs/tsconfig.app.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ES2020",
+    "outDir": "dist",
+    "strict": false,
+    "types": [
+      "node",
+      "express"
+    ],
+    "rootDir": "src",
+    "tsBuildInfoFile": "dist/tsconfig.app.tsbuildinfo"
+  },
+  "include": [
+    "src/**/*.ts",
+    "../server/src/*.d.ts"
+  ],
+  "exclude": [
+    "eslint.config.js",
+    "eslint.config.cjs",
+    "eslint.config.mjs"
+  ],
+  "references": [
+    {
+      "path": "../server/tsconfig.app.json"
+    },
+    {
+      "path": "../desktop/tsconfig.app.json"
+    },
+    {
+      "path": "../client/tsconfig.app.json"
+    }
+  ]
+}

apps/build-docs/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": [],
+  "references": [
+    {
+      "path": "../server"
+    },
+    {
+      "path": "../client"
+    },
+    {
+      "path": "./tsconfig.app.json"
+    }
+  ]
+}

apps/build-docs/typedoc.json

@@ -0,0 +1,15 @@
+{
+  "entryPoints": [
+    "src/backend_script_entrypoint.ts",
+    "src/frontend_script_entrypoint.ts"
+  ],
+  "plugin": [
+    "typedoc-plugin-missing-exports"
+  ],
+  "outputs": [
+    {
+      "name": "html",
+      "path": "../../site/script-api"
+    }
+  ]
+}

apps/client/src/services/frontend_script_entrypoint.ts

@@ -1,28 +0,0 @@
-/**
- * The front script API is accessible to code notes with the "JS (frontend)" language.
- *
- * The entire API is exposed as a single global: {@link api}
- *
- * @module Frontend Script API
- */
-
-/**
- * This file creates the entrypoint for TypeDoc that simulates the context from within a
- * script note.
- *
- * Make sure to keep in line with frontend's `script_context.ts`.
- */
-
-export type { default as BasicWidget } from "../widgets/basic_widget.js";
-export type { default as FAttachment } from "../entities/fattachment.js";
-export type { default as FAttribute } from "../entities/fattribute.js";
-export type { default as FBranch } from "../entities/fbranch.js";
-export type { default as FNote } from "../entities/fnote.js";
-export type { Api } from "./frontend_script_api.js";
-export type { default as NoteContextAwareWidget } from "../widgets/note_context_aware_widget.js";
-export type { default as RightPanelWidget } from "../widgets/right_panel_widget.js";
-
-import FrontendScriptApi, { type Api } from "./frontend_script_api.js";
-
-//@ts-expect-error
-export const api: Api = new FrontendScriptApi();

apps/server/src/services/backend_script_entrypoint.ts

@@ -1,37 +0,0 @@
-/**
- * The backend script API is accessible to code notes with the "JS (backend)" language.
- *
- * The entire API is exposed as a single global: {@link api}
- *
- * @module Backend Script API
- */
-
-/**
- * This file creates the entrypoint for TypeDoc that simulates the context from within a
- * script note on the server side.
- *
- * Make sure to keep in line with backend's `script_context.ts`.
- */
-
-export type { default as AbstractBeccaEntity } from "../becca/entities/abstract_becca_entity.js";
-export type { default as BAttachment } from "../becca/entities/battachment.js";
-export type { default as BAttribute } from "../becca/entities/battribute.js";
-export type { default as BBranch } from "../becca/entities/bbranch.js";
-export type { default as BEtapiToken } from "../becca/entities/betapi_token.js";
-export type { BNote };
-export type { default as BOption } from "../becca/entities/boption.js";
-export type { default as BRecentNote } from "../becca/entities/brecent_note.js";
-export type { default as BRevision } from "../becca/entities/brevision.js";
-
-import BNote from "../becca/entities/bnote.js";
-import type { Api } from "./backend_script_api.js";
-import BackendScriptApi from "./backend_script_api.js";
-
-export type { Api };
-
-const fakeNote = new BNote();
-
-/**
- * The `code` api global variable allows access to the backend script API, which is documented in {@link Api}.
- */
-export const api: Api = new BackendScriptApi(fakeNote, {});

pnpm-lock.yaml

@@ -142,6 +142,12 @@ importers:
       react-dom:
         specifier: 19.2.0
         version: 19.2.0(react@19.2.0)
+      typedoc:
+        specifier: 0.28.14
+        version: 0.28.14(typescript@5.9.3)
+      typedoc-plugin-missing-exports:
+        specifier: 4.1.2
+        version: 4.1.2(typedoc@0.28.14(typescript@5.9.3))
 
   apps/client:
     dependencies:
@@ -2971,6 +2977,9 @@ packages:
   '@gar/promisify@1.1.3':
     resolution: {integrity: sha512-k2Ty1JcVojjJFwrg/ThKi2ujJ7XNLYaFGNB/bWT9wGR+oSMJHMa5w+CUq6p/pVrKeNNgA7pCqEcjSnHVoqJQFw==}
 
+  '@gerrit0/mini-shiki@3.14.0':
+    resolution: {integrity: sha512-c5X8fwPLOtUS8TVdqhynz9iV0GlOtFUT1ppXYzUUlEXe4kbZ/mvMT8wXoT8kCwUka+zsiloq7sD3pZ3+QVTuNQ==}
+
   '@hapi/hoek@9.3.0':
     resolution: {integrity: sha512-/c6rf4UJlmHlC9b5BaNvzAcFv7HZ2QHaV0D4/HNlBdvFnvQq8RI4kYdhyPCl7Xj+oWvTWQ8ujhqS53LIgAe6KQ==}
 
@@ -4502,6 +4511,21 @@ packages:
   '@selderee/plugin-htmlparser2@0.11.0':
     resolution: {integrity: sha512-P33hHGdldxGabLFjPPpaTxVolMrzrcegejx+0GxjrIb9Zv48D8yAIA/QTDR2dFl7Uz7urX8aX6+5bCZslr+gWQ==}
 
+  '@shikijs/engine-oniguruma@3.14.0':
+    resolution: {integrity: sha512-TNcYTYMbJyy+ZjzWtt0bG5y4YyMIWC2nyePz+CFMWqm+HnZZyy9SWMgo8Z6KBJVIZnx8XUXS8U2afO6Y0g1Oug==}
+
+  '@shikijs/langs@3.14.0':
+    resolution: {integrity: sha512-DIB2EQY7yPX1/ZH7lMcwrK5pl+ZkP/xoSpUzg9YC8R+evRCCiSQ7yyrvEyBsMnfZq4eBzLzBlugMyTAf13+pzg==}
+
+  '@shikijs/themes@3.14.0':
+    resolution: {integrity: sha512-fAo/OnfWckNmv4uBoUu6dSlkcBc+SA1xzj5oUSaz5z3KqHtEbUypg/9xxgJARtM6+7RVm0Q6Xnty41xA1ma1IA==}
+
+  '@shikijs/types@3.14.0':
+    resolution: {integrity: sha512-bQGgC6vrY8U/9ObG1Z/vTro+uclbjjD/uG58RvfxKZVD5p9Yc1ka3tVyEFy7BNJLzxuWyHH5NWynP9zZZS59eQ==}
+
+  '@shikijs/vscode-textmate@10.0.2':
+    resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
+
   '@sideway/address@4.1.5':
     resolution: {integrity: sha512-IqO/DUQHUkPeixNQ8n0JA6102hT9CmaljNTPmQ1u8MEhBo/R4Q8eKLN/vGZxuebwOroDB4cbpjheD4+/sKFK4Q==}
 
@@ -9655,6 +9679,9 @@ packages:
   lines-and-columns@1.2.4:
     resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
 
+  linkify-it@5.0.0:
+    resolution: {integrity: sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==}
+
   lint-staged@16.2.6:
     resolution: {integrity: sha512-s1gphtDbV4bmW1eylXpVMk2u7is7YsrLl8hzrtvC70h4ByhcMLZFY01Fx05ZUDNuv1H8HO4E+e2zgejV1jVwNw==}
     engines: {node: '>=20.17'}
@@ -9890,6 +9917,10 @@ packages:
   mark.js@8.11.1:
     resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==}
 
+  markdown-it@14.1.0:
+    resolution: {integrity: sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==}
+    hasBin: true
+
   markdown-table@3.0.4:
     resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
 
@@ -9968,6 +9999,9 @@ packages:
   mdn-data@2.12.2:
     resolution: {integrity: sha512-IEn+pegP1aManZuckezWCO+XZQDplx1366JoVhTpMpBB1sPey/SbveZQUosKiKiGYjg1wH4pMlNgXbCiYgihQA==}
 
+  mdurl@2.0.0:
+    resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==}
+
   media-typer@0.3.0:
     resolution: {integrity: sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==}
     engines: {node: '>= 0.6'}
@@ -11974,6 +12008,10 @@ packages:
   pump@3.0.3:
     resolution: {integrity: sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA==}
 
+  punycode.js@2.3.1:
+    resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==}
+    engines: {node: '>=6'}
+
   punycode@1.4.1:
     resolution: {integrity: sha512-jmYNElW7yvO7TV33CjSmvSiE2yco3bV2czu/OzDKdMNVZQWfxCblURLhf+47syQRBntjfLdd/H0egrzIG+oaFQ==}
 
@@ -13743,6 +13781,18 @@ packages:
   typedarray@0.0.6:
     resolution: {integrity: sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==}
 
+  typedoc-plugin-missing-exports@4.1.2:
+    resolution: {integrity: sha512-WNoeWX9+8X3E3riuYPduilUTFefl1K+Z+5bmYqNeH5qcWjtnTRMbRzGdEQ4XXn1WEO4WCIlU0vf46Ca2y/mspg==}
+    peerDependencies:
+      typedoc: ^0.28.1
+
+  typedoc@0.28.14:
+    resolution: {integrity: sha512-ftJYPvpVfQvFzpkoSfHLkJybdA/geDJ8BGQt/ZnkkhnBYoYW6lBgPQXu6vqLxO4X75dA55hX8Af847H5KXlEFA==}
+    engines: {node: '>= 18', pnpm: '>= 10'}
+    hasBin: true
+    peerDependencies:
+      typescript: 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x
+
   typescript-eslint@8.46.2:
     resolution: {integrity: sha512-vbw8bOmiuYNdzzV3lsiWv6sRwjyuKJMQqWulBOU7M0RrxedXledX8G8kBbQeiOYDnTfiXz0Y4081E1QMNB6iQg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -13774,6 +13824,9 @@ packages:
     resolution: {integrity: sha512-O3oYyCMPYgNNHuO7Jjk3uacJWZF8loBgwrfd/5LE/HyZ3lUIOdniQ7DNXJcIgZbwioZxk0fLfI4EVnetdiX5jg==}
     hasBin: true
 
+  uc.micro@2.1.0:
+    resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==}
+
   ufo@1.6.1:
     resolution: {integrity: sha512-9a4/uxlTWJ4+a5i0ooc1rU7C7YOw3wT+UGqdeNNHWnOF9qcMBgLRS+4IYUqbczewFx4mLEig6gawh7X6mFlEkA==}
 
@@ -15501,6 +15554,8 @@ snapshots:
       '@ckeditor/ckeditor5-utils': 47.1.0
       '@ckeditor/ckeditor5-watchdog': 47.1.0
       es-toolkit: 1.39.5
+    transitivePeerDependencies:
+      - supports-color
 
   '@ckeditor/ckeditor5-dev-build-tools@43.1.0(@swc/helpers@0.5.17)(tslib@2.8.1)(typescript@5.9.3)':
     dependencies:
@@ -15665,6 +15720,8 @@ snapshots:
       '@ckeditor/ckeditor5-utils': 47.1.0
       ckeditor5: 47.1.0(patch_hash=8331a09d41443b39ea1c784daaccfeb0da4f9065ed556e7de92e9c77edd9eb41)
       es-toolkit: 1.39.5
+    transitivePeerDependencies:
+      - supports-color
 
   '@ckeditor/ckeditor5-editor-classic@47.1.0':
     dependencies:
@@ -17612,6 +17669,14 @@ snapshots:
 
   '@gar/promisify@1.1.3': {}
 
+  '@gerrit0/mini-shiki@3.14.0':
+    dependencies:
+      '@shikijs/engine-oniguruma': 3.14.0
+      '@shikijs/langs': 3.14.0
+      '@shikijs/themes': 3.14.0
+      '@shikijs/types': 3.14.0
+      '@shikijs/vscode-textmate': 10.0.2
+
   '@hapi/hoek@9.3.0': {}
 
   '@hapi/topo@5.1.0':
@@ -19321,6 +19386,26 @@ snapshots:
       domhandler: 5.0.3
       selderee: 0.11.0
 
+  '@shikijs/engine-oniguruma@3.14.0':
+    dependencies:
+      '@shikijs/types': 3.14.0
+      '@shikijs/vscode-textmate': 10.0.2
+
+  '@shikijs/langs@3.14.0':
+    dependencies:
+      '@shikijs/types': 3.14.0
+
+  '@shikijs/themes@3.14.0':
+    dependencies:
+      '@shikijs/types': 3.14.0
+
+  '@shikijs/types@3.14.0':
+    dependencies:
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
+  '@shikijs/vscode-textmate@10.0.2': {}
+
   '@sideway/address@4.1.5':
     dependencies:
       '@hapi/hoek': 9.3.0
@@ -25839,6 +25924,10 @@ snapshots:
 
   lines-and-columns@1.2.4: {}
 
+  linkify-it@5.0.0:
+    dependencies:
+      uc.micro: 2.1.0
+
   lint-staged@16.2.6:
     dependencies:
       commander: 14.0.1
@@ -26170,6 +26259,15 @@ snapshots:
 
   mark.js@8.11.1: {}
 
+  markdown-it@14.1.0:
+    dependencies:
+      argparse: 2.0.1
+      entities: 4.5.0
+      linkify-it: 5.0.0
+      mdurl: 2.0.0
+      punycode.js: 2.3.1
+      uc.micro: 2.1.0
+
   markdown-table@3.0.4: {}
 
   marked@16.4.1: {}
@@ -26323,6 +26421,8 @@ snapshots:
 
   mdn-data@2.12.2: {}
 
+  mdurl@2.0.0: {}
+
   media-typer@0.3.0: {}
 
   media-typer@1.1.0: {}
@@ -28527,6 +28627,8 @@ snapshots:
       end-of-stream: 1.4.5
       once: 1.4.0
 
+  punycode.js@2.3.1: {}
+
   punycode@1.4.1: {}
 
   punycode@2.3.1: {}
@@ -30818,6 +30920,19 @@ snapshots:
 
   typedarray@0.0.6: {}
 
+  typedoc-plugin-missing-exports@4.1.2(typedoc@0.28.14(typescript@5.9.3)):
+    dependencies:
+      typedoc: 0.28.14(typescript@5.9.3)
+
+  typedoc@0.28.14(typescript@5.9.3):
+    dependencies:
+      '@gerrit0/mini-shiki': 3.14.0
+      lunr: 2.3.9
+      markdown-it: 14.1.0
+      minimatch: 9.0.5
+      typescript: 5.9.3
+      yaml: 2.8.1
+
   typescript-eslint@8.46.2(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3):
     dependencies:
       '@typescript-eslint/eslint-plugin': 8.46.2(@typescript-eslint/parser@8.46.2(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3))(eslint@9.38.0(jiti@2.6.1))(typescript@5.9.3)
@@ -30839,6 +30954,8 @@ snapshots:
 
   ua-parser-js@0.7.41: {}
 
+  uc.micro@2.1.0: {}
+
   ufo@1.6.1: {}
 
   uglify-js@3.19.3: