@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

package/guides/configuration.md

@@ -0,0 +1,556 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Configuration Reference
+
+This document describes every configuration file used by the `@xmachines/xmachines-js` monorepo — TypeScript build settings, linting, formatting, testing, and CI/CD. All configuration is file-based; the project uses no environment variables for build or test execution.
+
+---
+
+## Table of Contents
+
+- [Environment Variables](#environment-variables)
+- [TypeScript Configuration](#typescript-configuration)
+    - [Shared Base Config (`@xmachines/shared/tsconfig`)](#shared-base-config-xmachinessharedtsconfig)
+    - [Root Workspace Coordinator (`tsconfig.json`)](#root-workspace-coordinator-tsconfigjson)
+    - [Per-Package Config Pattern](#per-package-config-pattern)
+    - [Test TypeScript Config](#test-typescript-config)
+- [Linting Configuration (oxlint)](#linting-configuration-oxlint)
+    - [Shared Linting Rules (`@xmachines/shared/oxlint`)](#shared-linting-rules-xmachinessharedoxlint)
+    - [Root Linting Config (`oxlint.config.ts`)](#root-linting-config-oxlintconfigts)
+- [Formatting Configuration (oxfmt)](#formatting-configuration-oxfmt)
+    - [Shared Formatting Rules (`@xmachines/shared/oxfmt`)](#shared-formatting-rules-xmachinessharedoxfmt)
+    - [Root Formatting Config (`oxfmt.config.ts`)](#root-formatting-config-oxfmtconfigts)
+- [Editor Configuration (`.editorconfig`)](#editor-configuration-editorconfig)
+- [Vitest Configuration](#vitest-configuration)
+    - [Root Node Test Config (`vitest.config.ts`)](#root-node-test-config-vitestconfigts)
+    - [Root Browser Test Config (`vitest.browser.config.ts`)](#root-browser-test-config-vitestbrowserconfigts)
+    - [Shared Vitest Helper (`@xmachines/shared/vitest`)](#shared-vitest-helper-xmachinessharedvitest)
+    - [Per-Package Vitest Config Pattern](#per-package-vitest-config-pattern)
+    - [Coverage Thresholds](#coverage-thresholds)
+- [Release Configuration (`.releaserc.json`)](#release-configuration-releaserc-json)
+- [CI/CD Configuration (`.gitlab-ci.yml`)](#cicd-configuration-gitlab-ciyml)
+- [npm Overrides and Patches](#npm-overrides-and-patches)
+- [Per-Environment Overrides](#per-environment-overrides)
+
+---
+
+## Environment Variables
+
+This project does **not** require environment variables to build, test, or develop. All configuration is expressed through config files checked into the repository.
+
+The only environment variable that affects runtime behaviour is `NODE_ENV`, which is managed automatically by Vitest and the CI pipeline.
+
+> The `.env` file pattern is in `.gitignore` but no `.env.example` exists — no user-facing environment variables are consumed by this project.
+
+---
+
+## TypeScript Configuration
+
+The monorepo uses a **TypeScript composite build system** with project references. A single root `tsconfig.json` coordinates all packages; each package extends a shared base config from [`@xmachines/shared`](../api/@xmachines/shared/README.md).
+
+### Shared Base Config (`@xmachines/shared/tsconfig`)
+
+**Source:** `packages/shared/config/tsconfig.json`  
+**Exported as:** `@xmachines/shared/tsconfig`
+
+This is the authoritative base config inherited by every package. Key settings:
+
+| Category      | Option                       | Value        | Purpose                                                      |
+| ------------- | ---------------------------- | ------------ | ------------------------------------------------------------ |
+| Language      | `target`                     | `ESNext`     | Compile to modern JavaScript                                 |
+| Language      | `lib`                        | `["ESNext"]` | ESNext globals only (no DOM)                                 |
+| Language      | `types`                      | `["node"]`   | Node.js type declarations                                    |
+| Modules       | `module`                     | `NodeNext`   | Native ESM, respects `exports` field                         |
+| Modules       | `moduleResolution`           | `NodeNext`   | Node12+ resolution algorithm                                 |
+| Modules       | `customConditions`           | `["source"]` | Resolves `@xmachines/*` to TypeScript source during dev/test |
+| Type checking | `strict`                     | `true`       | Full strict mode                                             |
+| Type checking | `noUnusedLocals`             | `true`       | Error on unused local variables                              |
+| Type checking | `noUnusedParameters`         | `true`       | Error on unused function parameters                          |
+| Type checking | `noFallthroughCasesInSwitch` | `true`       | Error on switch fallthrough                                  |
+| Type checking | `noImplicitReturns`          | `true`       | All code paths must return                                   |
+| Type checking | `noImplicitOverride`         | `true`       | `override` keyword required                                  |
+| Type checking | `exactOptionalPropertyTypes` | `true`       | Optional props cannot be `undefined` unless explicitly typed |
+| Emit          | `declaration`                | `true`       | Generate `.d.ts` files                                       |
+| Emit          | `declarationMap`             | `true`       | Generate `.d.ts.map` for IDE "go to definition"              |
+| Emit          | `sourceMap`                  | `true`       | Generate `.js.map` files                                     |
+| Emit          | `removeComments`             | `false`      | Preserve JSDoc in output                                     |
+| Interop       | `verbatimModuleSyntax`       | `true`       | Enforce `import type` for type-only imports                  |
+| Interop       | `isolatedModules`            | `true`       | Each file compilable independently                           |
+
+**Include/exclude defaults:**
+
+```json
+{
+	"include": ["src/**/*"],
+	"exclude": ["dist", "node_modules", "**/*.spec.ts", "**/*.test.ts"]
+}
+```
+
+### Root Workspace Coordinator (`tsconfig.json`)
+
+**Source:** `tsconfig.json`
+
+The root config does **not compile anything itself**. It contains only `references` to all packages, listed in dependency order (leaves first, dependents last). TypeScript uses this to build the full graph in the correct sequence.
+
+```
+Layer 0 (no internal deps): play-signals, play, docs
+Layer 1 (depends on Layer 0): play-actor
+Layer 2 (depends on Layers 0–1): play-router, play-dom-router, play-sveltekit-router,
+                                  play-xstate, play-react, play-vue, play-solid, play-svelte,
+                                  play-dom, play-tanstack-react-router, play-vue-router,
+                                  play-solid-router, play-svelte-spa-router,
+                                  play-tanstack-solid-router
+Layer 3 (top-level / examples): play-react-router, all examples/demo packages
+```
+
+Run the full build with:
+
+```bash
+npm run build          # tsc --build (incremental, correct order)
+npm run build -w <pkg> # Build one package and its dependencies
+```
+
+### Per-Package Config Pattern
+
+Every package uses two `tsconfig` files:
+
+**`packages/<name>/tsconfig.base.json`** — points to the shared base:
+
+```json
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "@xmachines/shared/tsconfig"
+}
+```
+
+**`packages/<name>/tsconfig.json`** — the build config with composite enabled:
+
+```json
+{
+	"$schema": "https://json.schemastore.org/tsconfig",
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"include": ["src/**/*"]
+}
+```
+
+Packages that depend on other `@xmachines/*` packages also declare `references` (see [`@xmachines/shared`](../api/@xmachines/shared/README.md) for the base config):
+
+```json
+{
+	"references": [{ "path": "../play" }]
+}
+```
+
+### Test TypeScript Config
+
+**Source:** `packages/shared/config/tsconfig.test.json`  
+**Exported as:** `@xmachines/shared/tsconfig-test`
+
+Per-package test configs extend both the package base and this shared test config:
+
+```json
+{
+	"extends": ["./tsconfig.base.json", "@xmachines/shared/tsconfig-test"],
+	"include": ["src/**/*", "test/**/*"]
+}
+```
+
+Key test-specific settings:
+
+| Option                       | Value                        | Purpose                                               |
+| ---------------------------- | ---------------------------- | ----------------------------------------------------- |
+| `noEmit`                     | `true`                       | Type-check only; Vitest transpiles at runtime         |
+| `allowImportingTsExtensions` | `true`                       | Import `.ts` files directly in test code              |
+| `customConditions`           | `["source"]`                 | Resolves packages to source, not dist                 |
+| `types`                      | `["node", "vitest/globals"]` | Adds Vitest global types (`describe`, `it`, `expect`) |
+
+The root `tsconfig.test.json` coordinates all per-package test configs (used by `npm run test:build`).
+
+---
+
+## Linting Configuration (oxlint)
+
+The project uses **oxlint** (`^1.60.0`) — a fast Rust-based linter with ESLint-compatible rules.
+
+### Shared Linting Rules (`@xmachines/shared/oxlint`)
+
+**Source:** `packages/shared/config/oxlint.config.ts`  
+**Exported as:** `@xmachines/shared/oxlint`
+
+| Setting       | Value                             |
+| ------------- | --------------------------------- |
+| Plugins       | `typescript`, `unicorn`, `import` |
+| `correctness` | `"error"`                         |
+| `suspicious`  | `"warn"`                          |
+| `pedantic`    | `"off"`                           |
+| `perf`        | `"warn"`                          |
+| `style`       | `"off"`                           |
+
+Custom rule overrides:
+
+| Rule                         | Level     | Reason                                      |
+| ---------------------------- | --------- | ------------------------------------------- |
+| `unicorn/filename-case`      | `"off"`   | Not enforced project-wide                   |
+| `import/no-cycle`            | `"error"` | Circular imports are forbidden              |
+| `typescript/no-explicit-any` | `"error"` | `any` is prohibited                         |
+| `typescript/no-unused-vars`  | `"error"` | Unused vars are errors; `_` prefix exempted |
+
+### Root Linting Config (`oxlint.config.ts`)
+
+**Source:** `oxlint.config.ts`
+
+Extends the shared config and adds monorepo-level ignore patterns:
+
+| Ignored Path      | Reason                       |
+| ----------------- | ---------------------------- |
+| `.planning`       | Auto-generated planning docs |
+| `.opencode`       | AI tooling cache             |
+| `node_modules`    | Third-party dependencies     |
+| `dist`            | Build output                 |
+| `build`           | Build output                 |
+| `coverage`        | Test coverage output         |
+| `docs/api/_media` | Auto-generated TypeDoc media |
+| `*.min.js`        | Minified files               |
+| `CHANGELOG.md`    | Managed by semantic-release  |
+
+**Run commands:**
+
+```bash
+npm run lint        # oxlint .
+npm run lint:fix    # oxlint --fix .
+```
+
+Per-package linting can be run with:
+
+```bash
+npm run lint -w packages/<name>
+```
+
+---
+
+## Formatting Configuration (oxfmt)
+
+The project uses **oxfmt** (`^0.45.0`) — an opinionated formatter compatible with Prettier's output.
+
+### Shared Formatting Rules (`@xmachines/shared/oxfmt`)
+
+**Source:** `packages/shared/config/oxfmt.config.ts`  
+**Exported as:** `@xmachines/shared/oxfmt`
+
+| Option               | Value                         |
+| -------------------- | ----------------------------- |
+| `printWidth`         | `100`                         |
+| `tabWidth`           | `4`                           |
+| `useTabs`            | `true` (tabs for indentation) |
+| `semi`               | `true`                        |
+| `singleQuote`        | `false` (double quotes)       |
+| `trailingComma`      | `"all"`                       |
+| `insertFinalNewline` | `true`                        |
+
+**JSON and YAML override** (via `overrides`):
+
+| Option     | Value            |
+| ---------- | ---------------- |
+| `useTabs`  | `false` (spaces) |
+| `tabWidth` | `2`              |
+
+Default ignored paths include: `**/node_modules`, `**/dist`, `**/build`, `**/coverage`, `**/*.tsbuildinfo`, `**/*.log`, `**/*.min.js`, `**/.git`, `**/.svelte-kit`, `**/.nyc_output`, IDE directories, and test artifact directories.
+
+### Root Formatting Config (`oxfmt.config.ts`)
+
+**Source:** `oxfmt.config.ts`
+
+Extends the shared config and adds additional monorepo-level ignore patterns:
+
+| Ignored Path    |
+| --------------- |
+| `.planning`     |
+| `.opencode`     |
+| `.agents`       |
+| `.githuman`     |
+| `.devcontainer` |
+| `CHANGELOG.md`  |
+| `Thumbs.db`     |
+
+**Run commands:**
+
+```bash
+npm run format        # oxfmt .   (format in place)
+npm run format:check  # oxfmt --check .   (CI mode, no writes)
+```
+
+---
+
+## Editor Configuration (`.editorconfig`)
+
+**Source:** `.editorconfig`
+
+Enforces consistent whitespace across all editors:
+
+| File Pattern        | `indent_style` | `indent_size` | Notes                                                             |
+| ------------------- | -------------- | ------------- | ----------------------------------------------------------------- |
+| `*` (default)       | `tab`          | `4`           | UTF-8, LF line endings, trim trailing whitespace, final newline   |
+| `*.{json,yml,yaml}` | `space`        | `2`           | Matches oxfmt JSON/YAML override                                  |
+| `*.md`              | (inherited)    | (inherited)   | Trailing whitespace **not** trimmed (allows Markdown line breaks) |
+
+---
+
+## Vitest Configuration
+
+The project uses **Vitest** (`^4.1.4`) with two distinct test modes — Node.js (unit/integration) and Browser (Playwright Chromium).
+
+### Root Node Test Config (`vitest.config.ts`)
+
+**Source:** `vitest.config.ts`
+
+| Option            | Value                                                                            | Notes                                     |
+| ----------------- | -------------------------------------------------------------------------------- | ----------------------------------------- |
+| `pool`            | `"forks"`                                                                        | Isolated Node.js process per file         |
+| `maxWorkers`      | `4`                                                                              | Parallel worker cap                       |
+| `isolate`         | `true`                                                                           | Full module isolation between tests       |
+| `fileParallelism` | `false`                                                                          | Files run sequentially within each worker |
+| `testTimeout`     | `10000` ms                                                                       | Per-test timeout                          |
+| `hookTimeout`     | `30000` ms                                                                       | `beforeAll`/`afterAll` timeout            |
+| `teardownTimeout` | `30000` ms                                                                       | Teardown timeout                          |
+| `resolve.alias`   | [`xmAliases(...)`](../api/@xmachines/shared/vite-aliases/functions/xmAliases.md) | `@xmachines/*` → TypeScript source        |
+
+The config enumerates all per-package `vitest.config.ts` files explicitly via the `projects` array. 29 project configs are currently registered.
+
+**Run commands:**
+
+```bash
+npm test                    # vitest run (all packages, node mode)
+npm run test:watch          # vitest (watch mode)
+npm run test:coverage       # vitest run --coverage
+npm run coverage:report     # vitest run --coverage --coverage.reporter=html
+npm run coverage:summary    # vitest run --coverage --coverage.reporter=json-summary
+```
+
+### Root Browser Test Config (`vitest.browser.config.ts`)
+
+**Source:** `vitest.browser.config.ts`
+
+Browser tests run via **Playwright Chromium** in headless mode.
+
+| Option            | Value                            | Notes                                              |
+| ----------------- | -------------------------------- | -------------------------------------------------- |
+| `pool`            | `"forks"`                        | Isolated process per browser project               |
+| `maxWorkers`      | `2`                              | Capped lower than Node tests (Playwright overhead) |
+| `isolate`         | `true`                           | Full isolation                                     |
+| `fileParallelism` | `false`                          | Sequential file execution                          |
+| `testTimeout`     | `20000` ms                       | Higher than Node (UI rendering overhead)           |
+| `hookTimeout`     | `30000` ms                       | Same as Node                                       |
+| `teardownTimeout` | `30000` ms                       | Same as Node                                       |
+| `globalSetup`     | `vitest.browser.global-setup.ts` | Raises `process.setMaxListeners` to `32`           |
+| `resolve`         | `xmResolve(...)`                 | Source aliases + `conditions: ["source"]`          |
+
+The `projects` array lists 24 browser test configs (package-level unit browser tests and demo app integration flows).
+
+**Run command:**
+
+```bash
+npm run test:browser    # vitest run --config vitest.browser.config.ts
+```
+
+### Shared Vitest Helper ([`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md))
+
+**Source:** `packages/shared/config/vitest.ts`  
+**Exported as:** [`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md)
+
+All packages call [`defineXmVitestConfig(import.meta.url, overrides)`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md) instead of `defineConfig` directly. This helper automatically:
+
+1. Injects `resolve.alias: xmAliases(import.meta.url)` so `@xmachines/*` packages resolve to TypeScript source.
+2. Prepends `vitest.node.setup.ts` for non-browser projects (enforces Node.js >= 22.0.0 at runtime).
+3. Prepends `vitest.setup.ts` (extends matchers with `@testing-library/jest-dom`).
+
+Setup injection is additive — caller-provided `setupFiles` are appended after the shared ones.
+
+### Per-Package Vitest Config Pattern
+
+Packages use one of two environment patterns:
+
+**Node environment (core packages):**
+
+```typescript
+// packages/<name>/vitest.config.ts
+import { defineXmVitestConfig } from "@xmachines/shared/vitest";
+
+export default defineXmVitestConfig(import.meta.url, {
+	test: {
+		environment: "node",
+		include: ["test/**/*.spec.ts", "test/**/*.test.ts"],
+		exclude: ["node_modules/**"],
+		coverage: {
+			/* package-specific thresholds */
+		},
+	},
+});
+```
+
+**Browser environment (packages with DOM interaction):**
+
+```typescript
+// packages/<name>/vitest.browser.config.ts
+import { defineConfig } from "vitest/config";
+import { playwright } from "@vitest/browser-playwright";
+import { xmResolve, xmCacheDir, xmOptimizeDeps } from "@xmachines/shared/vite-aliases";
+
+export default defineConfig({
+	cacheDir: xmCacheDir(import.meta.url, "<project-name>"),
+	resolve: xmResolve(import.meta.url),
+	optimizeDeps: xmOptimizeDeps([
+		/* framework packages */
+	]),
+	test: {
+		name: "<project-name>",
+		browser: {
+			enabled: true,
+			provider: playwright(),
+			headless: true,
+			instances: [{ browser: "chromium" }],
+		},
+		include: ["test/browser/**/*.browser.test.ts"],
+	},
+});
+```
+
+### Coverage Thresholds
+
+Coverage is enforced by `@vitest/coverage-v8`. Thresholds apply at two levels:
+
+**Root (regression gate) — `vitest.config.ts`:**
+
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 75%       |
+| Statements | 80%       |
+
+**Core packages** (`play`, `play-actor`, `play-signals` and others with highest standards):
+
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 90%       |
+| Functions  | 90%       |
+| Branches   | 85%       |
+| Statements | 90%       |
+
+**Integration/renderer packages** (e.g., `play-react`, `play-vue`, `play-solid`):
+
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 80%       |
+| Statements | 80%       |
+
+Coverage reports are produced in `text`, `html`, and `json-summary` formats, written to `coverage/` (gitignored).
+
+---
+
+## Release Configuration (`.releaserc.json`)
+
+**Source:** `.releaserc.json`  
+**Tool:** `semantic-release`
+
+| Setting            | Value                                                  |
+| ------------------ | ------------------------------------------------------ |
+| Tag format         | `v${version}`                                          |
+| Stable branch      | `main`                                                 |
+| Pre-release branch | `beta` (channel: `beta`, prerelease: auto-incremented) |
+| RC branch          | `pre/rc` (channel: `pre/rc`, prerelease: `rc`)         |
+
+**Release plugins in order:**
+
+1. `@semantic-release/commit-analyzer` — determines version bump from conventional commits
+2. `@semantic-release/release-notes-generator` — generates changelog entries
+3. `@semantic-release/changelog` — writes `CHANGELOG.md`
+4. `@semantic-release/exec` — runs `set-workspace-versions.mjs`, builds all packages, regenerates TypeDoc API docs
+5. `@semantic-release/npm` — publishes each public package to npm (18 packages total)
+6. `@semantic-release/git` — commits updated `CHANGELOG.md`, `package.json`, `package-lock.json`, all per-package `package.json` files, and generated API docs
+7. `@semantic-release/gitlab` — creates a GitLab release with tarball assets
+
+Packages with `npmPublish: false` (all `examples/demo` packages) are packed as tarballs but not published to npm.
+
+The `NPM_ID_TOKEN` GitLab CI token is used for authenticated npm publishing via OIDC. <!-- VERIFY: NPM_OIDC_token configuration details are managed in GitLab CI/CD secrets -->
+
+---
+
+## CI/CD Configuration (`.gitlab-ci.yml`)
+
+**Source:** `.gitlab-ci.yml`
+
+**Pipeline trigger conditions:**
+
+| Condition                                 | Trigger                       |
+| ----------------------------------------- | ----------------------------- |
+| `$CI_COMMIT_TAG`                          | Tag push                      |
+| `$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH` | Push to default branch (main) |
+| `$CI_MERGE_REQUEST_IID`                   | Merge request                 |
+
+**Included components:**
+
+| Component                                            | Version | Purpose                                   |
+| ---------------------------------------------------- | ------- | ----------------------------------------- |
+| `to-be-continuous/node/gitlab-ci-node`               | `5.1.2` | Node.js build, test, lint, and audit jobs |
+| `to-be-continuous/semantic-release/gitlab-ci-semrel` | `4.1.0` | Automated versioning and release          |
+
+**node-build job** (the primary test job):
+
+| Setting             | Value                                                                                                                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------- |
+| Test command        | `npm run test:coverage -- --coverage.reporter=text --coverage.reporter=cobertura --coverage.reportsDirectory=reports/coverage --reporter=default --reporter=junit --outputFile.junit=reports/junit.xml` |
+| Coverage extraction | Regex: `/All files[^                                                                                                                                                                                    | ]\*\|[^ | ]\*\s+([\d\.]+)/` |
+| JUnit report        | `reports/junit.xml`                                                                                                                                                                                     |
+| Coverage report     | `reports/coverage/cobertura-coverage.xml` (Cobertura format)                                                                                                                                            |
+| Audit level         | `--audit-level=high`                                                                                                                                                                                    |
+
+**semantic-release job:**
+
+| Setting            | Value                    |
+| ------------------ | ------------------------ |
+| Release branches   | `main`, `beta`, `pre/rc` |
+| Artifact path      | `dist/releases/*.tgz`    |
+| Artifact retention | 1 week                   |
+
+Jobs tagged as `rules: *auto-or-manual` run automatically on tag/main-branch pushes and are available as manual triggers on MRs.
+
+---
+
+## npm Overrides and Patches
+
+**Source:** `package.json` `overrides` section and `patches/` directory
+
+The root `package.json` declares two npm overrides to pin transitive dependency versions:
+
+| Package           | Override                    | Reason                              |
+| ----------------- | --------------------------- | ----------------------------------- |
+| `glob`            | `^13.0.6`                   | Pin to compatible major             |
+| `whatwg-encoding` | `npm:@exodus/bytes@^1.15.0` | Replace with compatible alternative |
+
+Patches are applied automatically on `npm install` via the `postinstall` script:
+
+```bash
+# Applied via postinstall → patch-package
+npm ci   # patches applied automatically after install
+```
+
+To re-apply patches manually:
+
+```bash
+npm run apply-patches    # runs patch-package
+```
+
+---
+
+## Per-Environment Overrides
+
+This project does not use `.env.development`, `.env.production`, or `.env.test` files. There are no per-environment configuration overrides — the same config files apply in all contexts.
+
+The one environment-aware distinction is in Vitest: the `source` custom condition in `tsconfig` / Vite resolve config causes `@xmachines/*` imports to resolve to TypeScript source during development and testing, while production builds use the compiled `dist/` output via the standard `exports` field in each package's `package.json`.