feat(build-docs): generate 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"
+    }
+  ]
+}