From a4164c8266c547b53b3a46540cb0ce9bfd41de2b Mon Sep 17 00:00:00 2001 From: Cristian Sotomayor Date: Sat, 24 Oct 2026 23:26:12 -0500 Subject: [PATCH 1/2] test(docs): compare the architecture page's package graph with the manifests Refs NIW2-340 Co-Authored-By: Claude Sonnet 5.5 --- scripts/docs/architecture-graph.test.ts | 105 ++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 scripts/docs/architecture-graph.test.ts 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, []) + }) +}) From 9bbcf708a7ed78575b13663d9d041aa134ca3d9c Mon Sep 17 00:00:00 2001 From: Cristian Sotomayor Date: Sat, 24 Oct 2026 23:29:01 -0500 Subject: [PATCH 2/2] docs(architecture): draw the real package graph and date-note ADR-0005 The page said generate depends on no workspace package and that nothing reaches sideways. generate depends on core and schema, editor depends on generate, schema, tokens and core, and mcp depends on generate. The page now carries the edge list the new test checks, and ADR-0005 notes that core is Node-bound today and that apps/relay does not exist yet. Refs NIW2-340 Co-Authored-By: Claude Sonnet 5.5 --- .../src/content/docs/architecture/index.md | 120 ++++++++++++------ .../content/docs/decisions/0005-monorepo.md | 18 +++ 2 files changed, 97 insertions(+), 41 deletions(-) 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