Add API reference generation tooling

Author: SandroMaglione

.changeset/api-reference-generator.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": patch
+---
+
+Add Effect-compatible TypeDoc API reference generation tooling.

.gitignore

@@ -1,6 +1,7 @@
 node_modules/
 dist/
 references/
+.data/
 *.tgz
 .DS_Store
 .pnpm-store

CONTRIBUTING.md

@@ -55,3 +55,15 @@ understands imports, re-exports, and dynamic imports, and enforces:
 
 The checker has executable fixture tests and runs as part of `pnpm check`. Add
 new rules only with a failing fixture that demonstrates the boundary.
+
+## API reference data
+
+`pnpm docs:api` generates an Effect-compatible TypeDoc dataset under
+`.data/api-reference/v4`. The dataset contains a top-level manifest, a package
+manifest, and one checksummed reflection JSON file per module configured in
+`api-reference.config.json`. Generated data is not committed.
+
+`pnpm docs:api:check` runs the API reference unit tests, generates the complete
+dataset in a temporary directory, validates its manifests and checksums, and
+ensures every reflection can be consumed by the site-facing normalizer. It runs
+as part of `pnpm check`.

api-reference.config.json

@@ -0,0 +1,45 @@
+{
+  "channel": "v4",
+  "output": ".data/api-reference/v4",
+  "tsconfig": "tsconfig.json",
+  "barrels": [
+    {
+      "export": ".",
+      "source": "src/index.ts"
+    },
+    {
+      "export": "./testing",
+      "source": "src/testing/index.ts"
+    },
+    {
+      "export": "./reactivity",
+      "source": "src/unstable/reactivity/index.ts"
+    },
+    {
+      "export": "./cluster",
+      "source": "src/unstable/cluster/index.ts"
+    }
+  ],
+  "modules": [
+    {
+      "export": "./Machine",
+      "source": "src/Machine.ts",
+      "barrel": "."
+    },
+    {
+      "export": "./testing/MachineTest",
+      "source": "src/testing/MachineTest.ts",
+      "barrel": "./testing"
+    },
+    {
+      "export": "./unstable/reactivity/AtomMachine",
+      "source": "src/unstable/reactivity/AtomMachine.ts",
+      "barrel": "./reactivity"
+    },
+    {
+      "export": "./unstable/cluster/ClusterMachine",
+      "source": "src/unstable/cluster/ClusterMachine.ts",
+      "barrel": "./cluster"
+    }
+  ]
+}

package.json

@@ -54,9 +54,12 @@
     "perf:runtime": "pnpm build && node --expose-gc scripts/runtime-performance.mjs",
     "format": "dprint fmt",
     "format:check": "dprint check",
+    "docs:api": "node scripts/api-reference/generate.mjs",
+    "docs:api:test": "node --test scripts/api-reference/*.test.mjs",
+    "docs:api:check": "pnpm docs:api:test && node scripts/api-reference/generate.mjs --check",
     "test:consumer": "node scripts/test-consumer.mjs",
     "pack:check": "node scripts/pack-check.mjs",
-    "check": "pnpm format:check && pnpm check:architecture && pnpm typecheck && pnpm build && pnpm test && pnpm test:types && pnpm test:consumer && pnpm pack:check",
+    "check": "pnpm format:check && pnpm check:architecture && pnpm docs:api:check && pnpm typecheck && pnpm build && pnpm test && pnpm test:types && pnpm test:consumer && pnpm pack:check",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "pnpm build && changeset publish"
@@ -72,6 +75,7 @@
     "effect": "4.0.0-beta.107",
     "tinybench": "2.9.0",
     "tstyche": "7.2.1",
+    "typedoc": "0.28.20",
     "typescript": "6.0.3",
     "vitest": "4.1.10",
     "xstate-v5": "npm:xstate@5.32.5",