module-spec 0.0.0-stage → 0.1.0

package/spec/backend.md

@@ -0,0 +1,176 @@
+# The inside of a backend module
+
+The shape is hexagonal (Ports and Adapters, Alistair Cockburn, 2005) with a
+functional core (Gary Bernhardt, "Boundaries", 2012): rules in the middle,
+input and output at the edge, one door in.
+
+```mermaid
+---
+config:
+  look: handDrawn
+---
+flowchart LR
+  caller["📞 caller<br/>an app or a test"]
+  subgraph pkg["📦 billing"]
+    door["🚪 door<br/>index.ts"]:::always
+    shell["🔁 shell<br/>load, call core, save"]:::always
+    core["🧠 core<br/>the rules, no input or output"]:::always
+    adapters["🔧 adapters<br/>Postgres, HTTP routes"]:::io
+    port["🔌 port<br/>InvoiceStore"]:::rare
+  end
+  outside["🌍 outside<br/>database, network, files"]
+  caller --> door --> shell
+  shell --> core
+  shell --> adapters
+  adapters --> outside
+  core -. "asks halfway" .-> port
+  adapters -. "implements" .-> port
+  classDef always fill:#1b4332,stroke:#52b788,color:#d8f3dc
+  classDef io fill:#5c3d0e,stroke:#f59e0b,color:#fef3c7
+  classDef rare fill:#3b1f5c,stroke:#c084fc,color:#f3e8ff
+```
+
+Green parts every module with rules has. Amber appears when the module touches
+the outside. Purple only when the core needs data halfway through a decision,
+see [B4](#b4-ports-only-when-needed). `InvoiceStore` is an example.
+
+## Layout
+
+Each folder exists so one check can find it.
+
+```
+billing/
+  module.yaml      manifest                                 C1
+  index.ts         the door: re-exports only                C3, C4
+  api-report.txt   what the door exports                    C4
+  shell/           door functions: load, call core, save    B2
+  core/            the rules, with no input or output       B1
+  ports/           driven ports, only when needed           B4, T3
+  adapters/        database, HTTP routes, files             B3
+  __tests__/       tests through the door                   T1, T2
+```
+
+In Python the door is `__init__.py` and the tests folder is `tests/`. In Go the
+door is the package at the module root, the parts sit under `internal/` so the
+compiler refuses a deep import too, and tests sit at the module root in the
+`_test` package. The rest is the same.
+
+`ports/` and `adapters/` exist only when needed. A pure calculation module may
+be only `module.yaml`, the door, `core/` and the tests. A module that only moves
+data between HTTP and a table has no rules, so it has no `core/` and no ports.
+Tests may also sit in a `__tests__/` folder inside a part. They still reach the
+module only through its door ([T1](tests.md#t1-tests-reach-a-module-only-through-its-door)).
+
+## B1. Core is pure
+
+`core/` takes data and returns data. It reaches the outside only through its
+own module's ports, so it uses:
+
+- no input/output code: none of the standard library's input/output modules
+  (files, network, processes, such as `fs`, `os` or `socket`), no global that
+  does input/output (`fetch`, `open`), and no third-party package the project
+  has not listed as pure. The rule is the same in every language;
+- nothing from its own `shell/` or `adapters/`;
+- no other module that carries adapters. Ask for it through a port instead.
+  An import the language erases before the code runs may name that module's
+  types, because it loads nothing: TypeScript's `import type`, or Python's
+  `if TYPE_CHECKING:`. TypeScript's `import { type T }` does not count, since
+  Node still loads the module. Go has no such import.
+
+A core with no `ports/` folder also never waits: no `async`, no `await`. A
+core that has to wait on something is calling out, so it needs a port. Once
+the module has `ports/`, its core may await them.
+
+**Why:** a pure core is tested in one line with no mocks. "Imports nothing
+impure" is a check a machine can run. "Is this the right port" is not.
+**Check:** the import checker, plus a scan of each core for input/output
+globals and, when it has no ports, for `async`. A third-party package counts
+as input/output until the project lists it under `pure` in `module-spec.json`,
+so a new database driver fails though nobody named it (fail-safe defaults,
+Jerome Saltzer and Michael Schroeder, "The Protection of Information in
+Computer Systems", 1975). The kit names no third-party package. Each language
+names only the input/output modules of its own standard library, a fixed set.
+
+## B2. Shell is thin
+
+A door function loads what the core needs, calls the core, and saves what the
+core returns.
+
+```ts
+// shell
+const invoice = await db.loadInvoice(id)
+await db.saveInvoice(settle(invoice, payment))   // settle() is the core
+```
+
+**Why:** rules that leak into the shell escape B1.
+**Check:** a complexity cap on `shell/`. Leaked rules add branches and trip
+it. The cap is a proxy: an agent can split a function to slip under it, so the
+clone ratchet and review cover the rest.
+
+## B3. Only adapters touch the outside
+
+Only `adapters/` imports database drivers, HTTP frameworks, and file or
+network libraries. HTTP routes live in `adapters/`, because a route changes
+when its feature changes. An app module is exempt: its composition root opens
+the connections.
+
+**Check:** the import checker, with the same lists as
+[B1](#b1-core-is-pure): outside `adapters/`, a third-party package must be
+listed under `pure`.
+
+## B4. Ports only when needed
+
+Start every module as a functional core with no driven ports. Add a driven
+port only when the core cannot know what data it needs until it has decided
+part of the way, for example "if overdue, fetch the client's payment plan".
+
+A port is defined in `ports/`, named after the core's need (`InvoiceStore`),
+not the technology (`PostgresInvoiceRepo`). Adapters implement it (dependency
+inversion, Robert C. Martin).
+
+`new-port` writes the port, an in-memory fake and the contract test in one
+step, so the right fix is cheaper than any workaround.
+
+**Why:** when a needed port is missing, an agent either imports input/output
+code into the core (B1 fails) or moves rules into the shell (B2 fails). Both
+errors point to `new-port`. That leaves the port as the only path.
+
+## B6. Two kinds of error
+
+- **Expected outcomes** are return values. The door's types list them.
+- **Bugs and outages** are thrown and caught once, at the top of the app.
+
+```ts
+type PayResult =
+  | { ok: true; invoice: Invoice }
+  | { ok: false; error: 'already-paid' | 'amount-mismatch' }
+```
+
+Adapters translate driver errors into the module's own errors. A Postgres
+error code that reaches a caller leaks the decision "billing uses Postgres".
+Where possible, design errors out of existence: deleting a missing item can
+simply do nothing (Ousterhout, *A Philosophy of Software Design*).
+
+**Check:** the API report ([C4](common.md#c4-the-door-stays-small)) lists
+every error type at the door, so a leaked driver error shows in the diff.
+
+## B7. Parse inputs at the edge
+
+Adapters turn raw input into the module's own types: HTTP bodies, and database
+rows too. The door and the core accept only those types, so a raw `string`
+cannot pass as an `InvoiceId` (Alexis King, "Parse, don't validate", 2019).
+What a value is goes in a type. What to do with it goes in a test.
+
+**Check:** the project's own type checker, not this kit. A distinct type per
+kind of value turns the mix-up into a type error.
+
+## Languages
+
+Each rule is written once, for every language. The kit reads each language
+with that language's own tools, then applies every rule the same way, so a
+rule has one wording and one error message everywhere. Supported today:
+TypeScript, Python and Go.
+
+Where a language's compiler can enforce a rule, prefer it, as Go's `internal/`
+does for the door. In Rust, the core would be its own crate with no database
+or async runtime in its `Cargo.toml`.

package/spec/common.md

@@ -0,0 +1,163 @@
+# Rules for every module
+
+These rules hold for every module, backend or frontend, whatever its role.
+Each rule has an ID, and `module-spec check` prints it with a link to the
+rule's heading here.
+
+A module is a folder with one door. Everything behind the door is private. The
+goal is a deep module: a small door over a lot of hidden work (John Ousterhout,
+*A Philosophy of Software Design*). Each module hides one decision, so a change
+to that decision touches one module (David Parnas, "On the Criteria To Be Used
+in Decomposing Systems into Modules", 1972).
+
+A project with one module needs none of this. Turn the checks on at the second
+module.
+
+## C1. Every module has a manifest
+
+`module.yaml` sits at the module root. Its shape is
+[manifest.schema.json](../manifest.schema.json).
+
+```yaml
+role: feature
+owns: how an engagement's fee is computed
+depends_on: [db, money]
+owns_tables: [invoice, invoice_line]
+```
+
+`role` is one of [the roles](roles.md). A module that has its own
+`package.json` lists its dependencies there, not in `depends_on`, so the two
+never disagree. Modules do not nest.
+
+**Why:** the checks read the manifest. Without it, "who may import whom" is a
+guess.
+**Check:** schema validation, a door, a unique name, no module inside another.
+
+## C2. `owns` names a decision, not an activity
+
+`owns` says in one line what this module alone decides. "How fees are computed"
+passes. "Handles invoices" fails.
+
+**Why:** a module split by activity (validate, save, notify) makes one change
+touch every module. A module split by decision keeps the change in one place.
+This is the single responsibility principle read as "one reason to change"
+(Robert C. Martin, *Clean Architecture*, 2017), not "does one thing".
+**Check:** the schema rejects the activity words "handles", "manages",
+"utils", "helpers" and "misc", the word "TODO", and more than one line.
+
+## C3. One door
+
+Other code reaches a module only through its door, and a module has exactly
+one. The door's place is fixed per language, so the manifest has no field for
+it: `index.ts` in TypeScript, `__init__.py` in Python, the package at the module
+root in Go. In a workspace package,
+`package.json` `exports` maps only `.` to the door.
+
+**Why:** once callers use only the door, everything behind it can be rebuilt
+without touching them. A second door is a second surface for agents to widen.
+**Check:** the import checker.
+
+## C4. The door stays small
+
+Export only what callers need. `module-spec api` writes `api-report.txt` in the
+module: every export of every door, with its type (TypeScript) or its
+`__all__` list (Python). The report is committed, so any change to the door
+shows in the diff.
+
+**Why:** agents tend to export whatever they touch. A wide door is a shallow
+module.
+**Check:** `api-report.txt` matches the door, and a Python door declares
+`__all__`.
+
+## C5. Dependencies are declared
+
+A module imports exactly the modules it declares, in `depends_on` or in its
+`package.json`. Every declared module is imported somewhere in it.
+
+**Why:** an undeclared dependency is an edge nobody decided on. A declared one
+nothing uses is a lie about the design.
+**Check:** the import checker compares imports with the declaration.
+
+## C6. No cycles
+
+No module depends on itself through other modules.
+
+**Check:** the declared dependencies form no cycle, and C5 keeps the imports
+inside the declarations.
+
+## C8. One composition root wires everything
+
+Each app module holds one composition root, such as `app/main.ts` (Mark
+Seemann, *Dependency Injection in .NET*, 2011). It is the only place that
+reads the environment or opens connections. Each module's door exports one
+`createX(deps)` function. The module builds its own adapters from the handles
+in `deps`, so its adapters stay private.
+
+```ts
+// app/main.ts
+const db = openPool(env.DATABASE_URL)
+const billing = createBilling({ db, clock: systemClock })
+```
+
+**Why:** one file shows how the whole app is built. A module never builds
+itself in secret, so a test can pass in fakes.
+**Check:** only app modules read the environment.
+
+## C9. Modules talk through the app
+
+```ts
+// billing declares nothing about reports, and reports imports nothing from billing.
+const reports = createReports({ fees: billing })   // reports asks; billing fits its Fees port
+billing.onInvoicePaid(notifications.sendReceipt)   // billing tells, unaware of who listens
+```
+
+- **To ask**, a feature declares the port it needs as a type in its own core,
+  such as `Fees`. The app passes the other feature's door, which fits the port.
+  The two features never import each other ([R1](roles.md#r1-a-feature-imports-only-shared-modules)).
+- **To tell**, a module exposes an `onX` hook, and the app attaches the
+  listeners. The module never imports its listeners.
+- **No global event bus.** It hides who listens, and agents cannot see what
+  they cannot search for.
+
+**Why:** every wire is in one file, and features stay independent.
+**Check:** R1 and C5.
+
+## C10. Only the owner writes its tables
+
+Where there is SQL, each table has one owning module, listed in `owns_tables`.
+Only the owner writes it. Others read through the owner's door, or read the
+table but never write it. The services form of this rule is "database per
+service" (Chris Richardson, *Microservices Patterns*, 2018).
+
+**Why:** a table's notion of a valid row is a decision. Two writers means two
+versions of that decision.
+**Check:** upper-case SQL that writes a table (`INSERT INTO`, `UPDATE`,
+`DELETE FROM`, `REPLACE INTO`, `MERGE INTO`) appears only in its owner, and no
+two manifests own one table.
+
+## C11. Cross-module clones only go down
+
+**Why:** zero imports between two modules does not mean zero coupling. A rule
+copied into two modules is coupling that no import checker sees, and the
+copies drift apart.
+**Check:** a clone detector counts clones of at least six lines whose copies
+sit in different modules, tests left out. The count is a ratchet, kept in the
+[baseline](adopting.md#the-baseline): it may stay or fall, never rise. A
+module a branch changes may sit in no clone at all.
+
+## When to split or merge
+
+These are a map, not checks. They raise a flag. A person decides where the
+edge goes.
+`module-spec report` shows them.
+
+- **Split** when a module's rules form two clusters that never import each
+  other and never change in the same commit. That is two decisions in one
+  folder.
+- **Split** when `owns` no longer fits in one line.
+- **Merge** when two modules always change in the same commits. The split was
+  shallow.
+
+Start a new project with a few large modules, one per business capability (a
+bounded context, Eric Evans, *Domain-Driven Design*, 2003). An early wrong
+split costs more than a late right one.

package/spec/frontend.md

@@ -0,0 +1,181 @@
+# The inside of a frontend module
+
+A frontend module has the backend's shape plus one part, `view/`. State and the
+rules that change it sit in the core, the shell runs effects, and the view
+draws. This is Model-View-Update, also called The Elm Architecture (Evan
+Czaplicki). The view is a Humble Object (Gerard Meszaros, *xUnit Test
+Patterns*, 2007): code so simple it needs no tests of its own.
+
+```mermaid
+---
+config:
+  look: handDrawn
+---
+flowchart LR
+  user["👤 user"]:::outside
+  app["🚀 web app<br/>router, wiring"]:::part
+  subgraph checkout["📦 checkout (feature)"]
+    door["🚪 index.ts"]:::part
+    view["🖼️ view/<br/>state in, events out"]:::new
+    shell["🔁 shell/<br/>holds state, runs effects"]:::part
+    core["🧠 core/<br/>update(state, event)<br/>selectors"]:::part
+    port["🔌 ports/CheckoutApi"]:::part
+    adapter["🔧 adapters/httpCheckoutApi"]:::part
+  end
+  api["🌐 server API"]:::outside
+  app --> door
+  user -- click --> view
+  view -- "send(event)" --> shell
+  shell --> core
+  shell -- "new state" --> view
+  shell --> port
+  adapter -. implements .-> port
+  adapter --> api
+  classDef new fill:#1b4332,stroke:#52b788,color:#d8f3dc
+  classDef part fill:#2b2b2b,stroke:#9ca3af,color:#e5e7eb
+  classDef outside fill:#1e3a5f,stroke:#60a5fa,color:#dbeafe
+```
+
+Green: the one part a frontend adds. Grey: the same parts as a backend module.
+Blue: outside the module.
+
+## Layout
+
+```
+checkout/
+  module.yaml      manifest                                    C1
+  index.ts         the door: re-exports only                   C3, C4
+  core/            state, update(state, event), selectors      B1
+  shell/           the model: holds state, runs effects        B2
+  view/            components: state in, events out            F1, F2, F3
+  ports/           CheckoutApi, only when needed               B4, T3
+  adapters/        the fetch client                            B3
+  __tests__/       tests through the door                      T1, T2
+```
+
+Every rule in [common.md](common.md), [roles.md](roles.md) and
+[tests.md](tests.md) holds here too, and B1 to B4 in
+[backend.md](backend.md) hold for the parts they name.
+
+The door exports two things: the shell's `createCheckoutModel(deps)` and the
+view's `CheckoutPage`. The model's type lives in the core, so the view and the
+shell never import each other. The app joins them:
+
+```ts
+// core/checkout.ts
+export interface CheckoutModel {
+  state(): CheckoutState
+  subscribe(listener: () => void): () => void
+  send(event: CheckoutEvent): void
+}
+
+// view/CheckoutPage.tsx
+export function CheckoutPage({ model }: { model: CheckoutModel }) {
+  const state = useSyncExternalStore(model.subscribe, model.state, model.state)
+  return <button onClick={() => model.send({ type: "paid" })}>{payLabel(state)}</button>
+}
+
+// the web app's composition root
+const model = createCheckoutModel({ api: httpCheckoutApi(env.API_URL) })
+root.render(<CheckoutPage model={model} />)
+```
+
+## F1. Only view/ knows the UI framework
+
+Only `view/` imports the UI framework: React, Vue, Svelte, a GUI or a terminal
+UI toolkit. The core, shell, ports and adapters are plain code. An app module
+is exempt, because its composition root starts the framework. Tests are exempt,
+because they render the view.
+
+**Why:** the UI framework is the decision most likely to change, and a mobile
+app needs other views over the same model. With the framework in one part,
+either change rewrites `view/` and nothing else (information hiding, David
+Parnas, 1972).
+**Check:** the import checker. The project lists its UI packages, such as
+`react` or a component library, under `ui` in `module-spec.json`, and
+`new-module --view` lists the ones its template uses. A UI module in the
+standard library, such as Python's tkinter, needs no entry. In TypeScript, JSX
+outside `view/` counts too, because JSX needs no import of the framework.
+
+## F2. A view only renders
+
+A view gets its state and a `send` function from the model, and draws. It
+imports only the core, other files in `view/`, the UI framework, and other
+modules that carry no adapters. It never imports the shell, ports or adapters,
+and never touches the outside: no `fetch`, no storage, no file or network
+module.
+
+A view may still use the framework's own tools for the screen, such as an
+effect that focuses an input. With no way to reach the outside, that is all
+such an effect can do.
+
+**Why:** data moves one way: event, shell, core, new state, view. A view that
+fetches breaks that loop, and its test needs a network mock, which
+[T2](tests.md#t2-tests-pass-fakes-in-never-patch) bans.
+**Check:** the import checker, plus the same input/output scan as a core
+([B1](backend.md#b1-core-is-pure)).
+
+## F3. A view holds no rules
+
+A view decides only how things look. A business decision, such as "is shipping
+free for this cart", is a selector in the core that the view calls.
+
+**Why:** a rule in a view escapes B1, and it can be tested only by drawing the
+page.
+**Check:** the same complexity cap as the shell
+([B2](backend.md#b2-shell-is-thin)), `maxComplexity` in `module-spec.json`.
+Rules add branches and trip it. Like B2's cap, it is a proxy, so the clone
+ratchet and review cover the rest.
+
+## Tests
+
+A test builds the model through the door with a fake passed in, draws the
+page, acts like the user and reads the screen. "The more your tests resemble
+the way your software is used, the more confidence they can give you" (Kent C.
+Dodds, Testing Library's guiding principle).
+
+```tsx
+test("paying shows the receipt", async () => {
+  const model = createCheckoutModel({ api: inMemoryCheckoutApi({ due: 300 }) })
+  render(<CheckoutPage model={model} />)
+  await user.click(screen.getByRole("button", { name: "Pay $3.00" }))
+  await screen.findByText("Paid")
+})
+```
+
+[T1](tests.md#t1-tests-reach-a-module-only-through-its-door) and
+[T2](tests.md#t2-tests-pass-fakes-in-never-patch) hold as they are: the test
+imports only the door, and it never mocks `fetch`, because the fake API comes
+in through `createCheckoutModel`.
+
+## Across features
+
+- **Routing lives in the app.** A feature never imports another feature's
+  page ([R1](roles.md#r1-a-feature-imports-only-shared-modules)). To link to
+  one, it takes a URL or a `navigate` function from the app through its deps.
+- **No global store.** State that several features read, such as the
+  signed-in user, is a shared module the app creates once and passes in
+  ([C9](common.md#c9-modules-talk-through-the-app)).
+- **A design system is a shared module.** Its components live in its own
+  `view/`.
+
+## Why not Feature-Sliced Design
+
+Feature-Sliced Design is the best-known frontend folder standard. It has six
+layers (app, pages, widgets, features, entities, shared) against this spec's
+three roles, so a project would have two vocabularies. Its `model` segment
+mixes rules with data fetching, and it has no ports, so its tests mock the
+`api` segment, which T2 bans. This shape is the backend's, plus `view/`, so
+every check already in place keeps working.
+
+## Languages
+
+TypeScript reads `.ts` and `.tsx`, so React, Preact, Solid and any JSX
+framework work. Vue and Svelte single-file components (`.vue`, `.svelte`) are
+not read yet. Python and Go apply the same rules to any GUI or terminal UI
+toolkit the project lists under `ui`, such as Qt or Bubble Tea, and Python to
+tkinter with no entry.
+
+`module-spec new-module <dir> --view` writes a React module in this shape,
+with a test. It needs `react` and `vitest` in the project, and is TypeScript
+only for now.

package/spec/roles.md

@@ -0,0 +1,93 @@
+# Roles: app, feature, shared
+
+Every module has a `role` in its manifest. The role decides which modules it may
+import, on the backend and the frontend alike. The inside layout is a separate
+matter, see [backend.md](backend.md) and [frontend.md](frontend.md).
+
+```mermaid
+---
+config:
+  look: handDrawn
+---
+flowchart TB
+  subgraph apps["🚀 apps: one per thing you run"]
+    direction LR
+    server["🖥️ server"]:::app
+    web["🌐 web"]:::app
+    mobile["📱 mobile"]:::app
+    cli["⌨️ cli"]:::app
+  end
+  subgraph features["🏢 features: what the project does"]
+    direction LR
+    billing["billing"]:::feature
+    reports["reports"]:::feature
+  end
+  subgraph shared["🔧 shared: what features build on"]
+    direction LR
+    money["money<br/>how amounts round"]:::shared
+    db["db<br/>how we talk to Postgres"]:::shared
+  end
+  apps -- "may import" --> features
+  features -- "may import" --> shared
+  apps -- "may import" --> shared
+  server -. "❌ never" .-> web
+  billing -. "❌ never" .-> reports
+  classDef app fill:#1b4332,stroke:#52b788,color:#d8f3dc
+  classDef feature fill:#3b1f5c,stroke:#c084fc,color:#f3e8ff
+  classDef shared fill:#1e3a5f,stroke:#60a5fa,color:#dbeafe
+```
+
+The module names are examples. Imports point only downward.
+
+| Role      | What it is                                                     | May import                  |
+|-----------|----------------------------------------------------------------|-----------------------------|
+| `app`     | one thing you run: a server, a web app, a CLI. Holds the composition root | features and shared modules |
+| `feature` | something the project does: a page, a job, a command           | shared modules              |
+| `shared`  | what two or more features build on                             | shared modules              |
+
+The roles follow Ports and Adapters (Alistair Cockburn, 2005), the bounded
+context and shared kernel (Eric Evans, *Domain-Driven Design*, 2003) and the
+acyclic dependencies principle (Robert C. Martin).
+
+## R1. A feature imports only shared modules
+
+A feature never imports another feature, not even through its door. When one
+feature needs another, it declares the port it needs as a type in its own core,
+and the app passes the other feature's door in through `createX(deps)`. See
+[C9](common.md#c9-modules-talk-through-the-app).
+
+**Why:** features that import each other are one tangle with folders drawn on
+it. A change inside one breaks the other, and neither can be tested or removed
+alone. A door does not fix this: it grows to re-export whatever the next
+caller needs.
+**Check:** the import checker, and the manifest check on what each module
+declares.
+
+## R2. A shared module imports only shared modules
+
+**Why:** dependencies point toward what changes least (the stable dependencies
+principle, Robert C. Martin, *Agile Software Development*, 2002). A shared
+module that imports a feature changes whenever that feature does, and so does
+every feature built on it.
+**Check:** the import checker.
+
+## R3. An app imports no other app
+
+**Why:** two apps that share code through each other deploy as one.
+**Check:** the import checker.
+
+## When code moves between roles
+
+Code a second feature needs moves to a shared module when that second user
+arrives, and back into its feature when only one user is left.
+
+## What a shared module holds
+
+Either rules that several features use, such as how money rounds, or plumbing
+any business could use, such as a database pool, a clock or a logger. For
+plumbing, `owns` names the technical decision: "how we talk to Postgres".
+
+Many modules build on a shared module, so a change to its door ripples
+everywhere. `module-spec report` lists each module's fan-in, so the most
+depended-on doors are easy to watch. Plumbing often has no rules, so it may be
+only a door and adapters, with no `core/`.