diff --git a/apps/documentation/src/content/docs/architecture/index.md b/apps/documentation/src/content/docs/architecture/index.md index 2a898df..de33ba2 100644 --- a/apps/documentation/src/content/docs/architecture/index.md +++ b/apps/documentation/src/content/docs/architecture/index.md @@ -18,49 +18,85 @@ today, and what must stay true_. ## The package graph Nine packages and three apps. Dependencies point in one direction only — no -package imports something that imports it back. +package imports something that imports it back. Each box depends only on boxes +above it; the annotations next to each box say which ones. ``` - ┌────────────┐ - │ schema │ Zod contracts. Depends on nothing. - └─────┬──────┘ - │ - ┌─────▼──────┐ - │ core │ Project logic: load, resolve, write. - └─────┬──────┘ Fully synchronous. - ┌───────────────┼───────────────┐ - │ │ │ - ┌─────▼────┐ ┌─────▼────┐ ┌─────▼────┐ - │ server │ │ mcp │ │ editor │ - │ (Hono) │ │ (agents) │ │ (React) │ - └─────┬────┘ └─────┬────┘ └─────┬────┘ - │ │ │ - └───────────────┼───────────────┘ - │ - ┌─────▼──────┐ - │ apps/cli │ The composition root. The only thing - └────────────┘ that knows every other piece exists. - - ┌────────────┐ Consumed by mcp and cli. Depends on no workspace - │ generate │ package at all — which is why it could be migrated - └────────────┘ to Effect in isolation. - - tokens · tui · config Leaves. CSS tokens, terminal rendering, - shared tsconfig. + ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ + │ schema │ │ tokens │ │ tui │ │ config │ + │ (Zod) │ │ (CSS) │ │ │ │ │ + └────┬─────┘ └──────────┘ └────────┘ └──────────┘ + │ Leaves: none of these four depends on a workspace package. + ┌────▼─────┐ + │ core │ core → schema + └────┬─────┘ Fully synchronous. Node-bound today: it imports node:fs, + │ node:path and node:crypto. + ┌─────┴─────────────┐ + │ │ +┌──▼───────┐ ┌────▼─────┐ +│ server │ │ generate │ server → core, schema (no node: imports) +│ (Hono) │ │ (Effect) │ generate → core, schema +└──┬───────┘ └────┬─────┘ + │ ┌────┴──────────┐ + │ ┌────▼────┐ ┌────▼────┐ + │ │ mcp │ │ editor │ mcp → core, generate, schema + │ │ (agents)│ │ (React) │ editor → core (events), generate + │ └────┬────┘ └────┬────┘ (examples), schema, tokens + │ │ │ +┌──▼──────────────▼───────────────▼──┐ +│ apps/cli │ cli → core, schema, server, generate, +└────────────────────────────────────┘ mcp, editor, tui ``` -| Package | Source lines | Role | -| ---------------- | ------------ | ----------------------------------------------------------------------------------------------------- | -| `@laqi/schema` | 149 | Zod contracts for mock files, config and state. The vocabulary everything else speaks | -| `@laqi/core` | 1,314 | Loading, state resolution, atomic writes. Fully synchronous, `ProjectResult` as its error channel | -| `@laqi/generate` | 1,290 | Types ⇄ data: parse TypeScript, infer from JSON, generate mocks, print types. Effect-first internally | -| `@laqi/server` | 754 | The mock server, the control plane and the public app, on Hono | -| `@laqi/mcp` | 679 | The agent-facing tool surface | -| `@laqi/editor` | 2,236 | The control panel — a plain React SPA | -| `@laqi/tui` | 341 | Terminal rendering: layout, palette, screens | -| `@laqi/tokens` | — | Design tokens as CSS, shared by the panel and the site | -| `@laqi/config` | — | Shared tsconfig base | -| `apps/cli` | 2,831 | The `laqi` binary. Owns the process and composes everything | +Lines show the layering; the annotations and the edge list below give the exact +dependencies. `apps/cli` loads `generate` and `mcp` with dynamic `import()`. + +`apps/site` depends on `tokens`, and `examples/todo-app` depends on the `laqi` +binary (`apps/cli`). `apps/documentation` depends on no workspace package. + +The list below is the same graph as data, one `dependent -> dependency` edge per +line, named by directory. `scripts/docs/architecture-graph.test.ts` derives the +real edges from every workspace `package.json` and fails when this list +differs, in either direction. When a dependency changes, change one line here. + + + +``` +cli -> core +cli -> editor +cli -> generate +cli -> mcp +cli -> schema +cli -> server +cli -> tui +core -> schema +editor -> core +editor -> generate +editor -> schema +editor -> tokens +generate -> core +generate -> schema +mcp -> core +mcp -> generate +mcp -> schema +server -> core +server -> schema +site -> tokens +todo-app -> cli +``` + +| Package | Source lines | Role | +| ---------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `@laqi/schema` | 149 | Zod contracts for mock files, config and state. The vocabulary everything else speaks | +| `@laqi/core` | 1,314 | Loading, state resolution, atomic writes. Fully synchronous, `ProjectResult` as its error channel. Imports `node:fs`, `node:path` and `node:crypto`, so it runs on Node and Bun only | +| `@laqi/generate` | 1,290 | Types ⇄ data: parse TypeScript, infer from JSON, generate mocks, print types. Effect-first internally | +| `@laqi/server` | 754 | The mock server, the control plane and the public app, on Hono | +| `@laqi/mcp` | 679 | The agent-facing tool surface | +| `@laqi/editor` | 2,236 | The control panel — a plain React SPA | +| `@laqi/tui` | 341 | Terminal rendering: layout, palette, screens | +| `@laqi/tokens` | — | Design tokens as CSS, shared by the panel and the site | +| `@laqi/config` | — | Shared tsconfig base | +| `apps/cli` | 2,831 | The `laqi` binary. Owns the process and composes everything | ## What actually ships @@ -86,8 +122,10 @@ Two consequences worth holding on to: Rules that hold across packages. Breaking one is a bug, not a style choice. **The composition root is `apps/cli`.** It is the only place that knows about -every package. Nothing below it reaches sideways: `@laqi/server` does not import -`@laqi/mcp`, and neither imports the other's internals. +every package. Between the packages below it, only the edges in the list above +exist: `@laqi/server` does not import `@laqi/mcp` or `@laqi/editor`, and no +package imports `apps/cli`. `@laqi/generate` is shared on purpose — `mcp` and +`editor` both build on it — so it sits below them rather than beside them. **Heavy dependencies load lazily.** `typescript` (23 MB), `quicktype-core` and `@faker-js/faker` are behind dynamic `import()`, so starting a mock server never diff --git a/apps/documentation/src/content/docs/decisions/0005-monorepo.md b/apps/documentation/src/content/docs/decisions/0005-monorepo.md index b7554b5..d40c85b 100644 --- a/apps/documentation/src/content/docs/decisions/0005-monorepo.md +++ b/apps/documentation/src/content/docs/decisions/0005-monorepo.md @@ -7,6 +7,24 @@ title: ADR-0005 — Monorepo aligned with rakoi **Status:** Accepted **Date:** 2026-08-24 +> **Note, 2026-10-24.** The decision below is unchanged; this records where the +> code stands against it. +> +> - **`core` is Node-bound today.** Its loader, writer, project, state store, +> revision, canonical-JSON and atomic-file modules import `node:fs`, +> `node:path` or `node:crypto`. Only `server` is free of `node:` imports. +> "`core` + `server` run the same on Node and on the edge" is therefore not +> true yet: `server` could run on a Worker, `core` cannot. +> - **`apps/relay` does not exist.** [ADR-0007](/decisions/0007-public-url/) +> defers the relay to phase 2, so the diagram's `relay` entry is planned, not +> built. +> - **The relay needs a storage port in `core` first.** `core` would have to +> take its file and hash access through an interface that a Worker can +> implement before the relay can reuse it. That port is not implemented. +> +> The package graph as it is now lives in +> [Architecture](/architecture/#the-package-graph). + ## Context v1 was a flat npm package of four files. v2 has at least four distinct diff --git a/scripts/docs/architecture-graph.test.ts b/scripts/docs/architecture-graph.test.ts new file mode 100644 index 0000000..85de651 --- /dev/null +++ b/scripts/docs/architecture-graph.test.ts @@ -0,0 +1,105 @@ +import { existsSync, readFileSync, readdirSync } from 'node:fs' +import { join } from 'node:path' +import { describe, expect, it } from 'vitest' + +// The architecture page drew a package graph by hand and then claimed things +// about it that the manifests disprove: "generate depends on no workspace +// package at all" while it depends on core and schema, and "nothing below the +// CLI reaches sideways" while editor and mcp both import generate. Nothing +// compared the page with the code, so the drawing aged on its own. +// +// The page keeps its edge list in one machine-readable block, introduced by +// the marker below. This test derives the real list from every workspace +// package.json and fails when the two differ, in either direction. + +const ROOT = join(import.meta.dirname, '..', '..') +const PAGE = join(ROOT, 'apps/documentation/src/content/docs/architecture/index.md') +const MARKER = '' +const DEPENDENCY_FIELDS = [ + 'dependencies', + 'devDependencies', + 'peerDependencies', + 'optionalDependencies', +] as const + +interface Manifest { + name: string + dependencies?: Record + devDependencies?: Record + peerDependencies?: Record + optionalDependencies?: Record +} + +/** `apps/cli` is `cli`, `packages/core` is `core`: the directory names the node. */ +function workspaceManifests(): Map { + const rootManifest = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')) as { + workspaces: { packages: string[] } + } + const manifests = new Map() + for (const pattern of rootManifest.workspaces.packages) { + const parent = pattern.replace(/\/\*$/, '') + for (const entry of readdirSync(join(ROOT, parent), { withFileTypes: true })) { + const manifestPath = join(ROOT, parent, entry.name, 'package.json') + if (!entry.isDirectory() || !existsSync(manifestPath)) continue + manifests.set(entry.name, JSON.parse(readFileSync(manifestPath, 'utf8')) as Manifest) + } + } + return manifests +} + +function realEdges(manifests: Map): string[] { + const nodeOf = new Map([...manifests].map(([node, manifest]) => [manifest.name, node])) + const edges = new Set() + for (const [from, manifest] of manifests) { + for (const field of DEPENDENCY_FIELDS) { + for (const dependency of Object.keys(manifest[field] ?? {})) { + const to = nodeOf.get(dependency) + if (to) edges.add(`${from} -> ${to}`) + } + } + } + return [...edges].sort() +} + +function documentedEdges(): string[] { + const page = readFileSync(PAGE, 'utf8') + const start = page.indexOf(MARKER) + if (start === -1) return [] + const block = /```[^\n]*\n([\s\S]*?)```/.exec(page.slice(start + MARKER.length)) + if (!block) return [] + return (block[1] ?? '') + .split('\n') + .map((line) => line.trim()) + .filter(Boolean) + .sort() +} + +describe('architecture page package graph', () => { + const manifests = workspaceManifests() + const real = realEdges(manifests) + + it('reads the workspace it claims to describe', () => { + expect(real).toContain('cli -> core') + expect(real).toContain('core -> schema') + }) + + it('lists exactly the workspace dependencies the manifests declare', () => { + expect(documentedEdges()).toEqual(real) + }) + + it('has no dependency cycle, as the page promises', () => { + const targets = new Map() + for (const edge of real) { + const [from = '', to = ''] = edge.split(' -> ') + targets.set(from, [...(targets.get(from) ?? []), to]) + } + const finished = new Set() + const visit = (node: string, path: string[]): void => { + expect(path, `cycle: ${[...path, node].join(' -> ')}`).not.toContain(node) + if (finished.has(node)) return + for (const next of targets.get(node) ?? []) visit(next, [...path, node]) + finished.add(node) + } + for (const node of manifests.keys()) visit(node, []) + }) +})