module-spec 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+## 0.2.0
+
+- `mutate` counts only the module's core, shell and door tests. An adapter's test and a
+  contract test prove the adapter against the outside and are slow, so a mutant that only
+  they catch now lives until a test through the door catches it. On factory's chat module
+  those tests were 39 of 40 seconds of test time, rerun for every core mutant.
+- Under vitest, `mutate` keeps each module's verdicts in
+  `node_modules/.cache/module-spec/mutate/`, and a rerun tests again only the mutants whose
+  code or covering tests changed.
+- `mutate` changes only `core/`, `shell/` and the door, as the spec says. Before,
+  it also changed files in no part, such as an app's `main.ts` or a
+  `vitest.config.ts`.
+- `mutate` runs a vitest project through Stryker's vitest runner, limited to the
+  module's own tests by `testFiles`, instead of starting vitest once per mutant.
+  It also no longer crashes on TypeScript 7, which has no JS API.
+- A module has exactly one door. The optional pure door `core/index.ts` is gone.
+- B1 is one rule for every language: a core uses no input/output module and no
+  input/output global (`fetch`, `open`). A TypeScript core may now use pure
+  Node builtins.
+- Fewer terms: "platform module" folds into the shared role.
+- The spec no longer lists tools per language. The kit picks them.
+- Each language is one folder, `lib/languages/<name>/`, and the rules never
+  name a language. A shared conformance suite proves every language finds the
+  same violations in the same project.
+- `new-module` without `--lang` fails on a project whose language is unclear,
+  instead of guessing Python.
+- Test rules have their own page, spec/tests.md. C7 is now T1, and B5 is now
+  T3. T1 drops the exception for tests inside `adapters/`: only a port's
+  contract test reaches behind the door. New T2: tests pass fakes in and never
+  patch.
+- T3 also fails when an adapter that imports a port is missing from that
+  port's contract test, so the real adapter cannot be left out.
+- Go support: the door is the package at the module root, parts sit under
+  `internal/`, and tests use the `_test` package. A Go program built on
+  `go/parser` reads the code, so no Go tool beyond the toolchain is needed.
+- `api-report.txt` drops its door heading: a module has one door.
+- Frontend modules, spec/frontend.md: the backend's shape plus `view/`. New
+  F1: only `view/` imports the UI framework. New F2: a view only renders, with
+  no input/output and no import of its own shell, ports or adapters. New F3:
+  a view holds no rules, under the same complexity cap as the shell. Each
+  language lists its UI packages, and a project adds its own through `ui`.
+- `new-module --view` writes a React module in that shape, with a vitest test.
+- **Breaking:** `shellComplexity` in `module-spec.json` is now `maxComplexity`,
+  since it caps `view/` too. The old key fails with a message naming the new one.
+- C8 also catches `import.meta.env` in TypeScript.
+- B1 and F2 also catch `EventSource`, `localStorage`, `sessionStorage` and
+  `indexedDB` in TypeScript.
+- The kit decides once, in `lib/scans.js`, which files each scan reads and
+  which rule a finding breaks. Each language only runs its tools over the list.
+- `new-module` writes `module.yaml` itself, quoted safely, instead of one
+  template per language.
+- `module-spec affected` prints the modules a change since `main` can break:
+  the changed ones, and every module that depends on them.
+- `module-spec mutate` mutation-tests each module a change touched with only
+  its own tests, by each language's own tool. It fails on any live mutant.
+  `--accept` lists mutants no test can tell apart from the code in the
+  module's `mutation-report.txt`.
+- Zero where you work: `check` fails on any violation or cross-module clone in
+  a module the branch changes, even one in the baseline. Untouched modules
+  keep their baseline, which may only shrink.
+- New W1 check: a branch changes one module besides apps.
+- The branch that first adds `module.yaml` files skips W1 and zero where you
+  work, so adopting the spec on a branch passes with its baseline.
+- Trends are now called a map. They never fail CI.
+- **Breaking:** the kit names no third-party package. Any package a project
+  has not listed under `pure` in `module-spec.json` counts as input/output, so
+  a new driver nobody named still fails B1, B3 or F2. UI packages go under
+  `ui`, and `new-module --view` adds its own. Each language names only its
+  standard library's input/output and UI modules, and its toolchain says what
+  is standard. The `impure` key fails with a message.
+- An agent skill, `skills/module-spec/`, installed as a Claude Code plugin from
+  this repo. A test keeps its commands and flags in step with the CLI.
+- B1 and F2 let a core or view name the types of a module that carries
+  adapters through an import erased before the code runs: TypeScript's
+  `import type`, or Python's `if TYPE_CHECKING:`. `import { type T }` still
+  counts, because Node loads the module.
+- W2 says how a door change that breaks callers lands one module per branch:
+  expand, migrate, contract.
+- pnpm replaces npm: the repo pins it in `packageManager`, and the skill, its
+  CI template and the README install with it.
+- Invoked with no words, the skill sets up what a project lacks: the kit, its
+  config, adopted modules and a CI step, read from `scripts/state.sh`.
+- `new-module` and `new-port` also write the module's `api-report.txt`, so a
+  fresh module passes `check` with no extra step.
+- The scaffold tests now see a failing TypeScript test. Run inside
+  `node --test`, a nested `node --test` always exited 0.
+
+## 0.1.0
+
+First version.
+
+- The spec: common rules C1–C11, roles R1–R3, the backend inside B1–B7,
+  adopting existing code, and working on modules in parallel.
+- `module-spec check`, `baseline`, `api`, `new-module`, `new-port`, `report`
+  and `init`, for TypeScript and Python modules.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# module-spec
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+How every project splits its code into modules, so many agents can work on it
+at once without the code rotting, and the checks that hold it there.
+
+## Why
+
+Agents copy whatever the code around them makes easy, and they lose context
+between chats. A rule written only in prose is read once and then forgotten.
+So every rule here ends in a check, and every check's error names the rule,
+the fix and the heading that explains why. The spec says why. The checks
+enforce. The templates make the right shape the cheapest one to write.
+
+## Read in this order
+
+1. [spec/common.md](spec/common.md): rules for every module.
+2. [spec/roles.md](spec/roles.md): app, feature and shared modules.
+3. [spec/backend.md](spec/backend.md): the inside of a backend module.
+4. [spec/tests.md](spec/tests.md): how a module is tested, and why good design deletes tests.
+5. [spec/frontend.md](spec/frontend.md): the inside of a frontend module.
+6. [spec/adopting.md](spec/adopting.md): bringing existing code under the spec.
+7. [spec/workflow.md](spec/workflow.md): agents working on modules in parallel.
+
+## Install
+
+Node 24 or later and pnpm. In the project:
+
+```sh
+pnpm add -D "git+ssh://gitea/aleburrascano/module-spec.git"
+```
+
+A Go project needs the `go` toolchain on the PATH and `go.mod` at the project
+root. Its first `mutate` downloads the mutation tool through `go run`. A Python
+project also installs `import-linter`, `ruff` and, for `mutate`, `mutmut` in its
+own environment. The kit runs `.venv/bin/python` when it exists, or the
+interpreter named in `module-spec.json`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `module-spec check [--since <ref>]` | Runs every check. Fails on a violation that is not in the baseline, a baseline entry that no longer happens, any violation or clone in a module the branch changes, and a branch that changes two modules besides apps. |
+| `module-spec baseline [--accept-new]` | Records today's violations in `module-spec.baseline.json`. Refuses to add new ones unless `--accept-new`. |
+| `module-spec api` | Rewrites each module's `api-report.txt` from what its door exports. |
+| `module-spec new-module <dir> --role <role> --owns "<decision>" [--lang ts\|py\|go] [--view]` | Writes a module that already passes every check. Without `--lang`, the project's files decide, and an unclear project is an error. `--view` writes a frontend module with a React `view/` and a vitest test (TypeScript only). |
+| `module-spec new-port <module dir> <PortName>` | Writes a port, an in-memory fake and its contract test. |
+| `module-spec affected [--since <ref>]` | Prints the modules a change since `<ref>` (default: `main`) can break: the changed ones and every module that depends on them. One folder per line. |
+| `module-spec mutate [<module dir>...] [--since <ref>] [--accept]` | Mutation-tests each module with only its own tests, by default the modules changed since `<ref>`. Fails on any live mutant its `mutation-report.txt` does not accept. `--accept` records mutants no test can tell apart from the code. |
+| `module-spec report` | A map, never enforced: commits that stay in one module, modules that change together, fan-in. |
+| `module-spec init` | Writes a default `module-spec.json`. |
+
+Every command takes `--root <dir>`. An error looks like this:
+
+```
+B1 billing/core/settle.ts imports fs
+    Core is pure. Fix: Move the input/output into adapters/ and pass the data into the core. ...
+    See .../module-spec/spec/backend.md#b1-core-is-pure
+```
+
+## How a rule is enforced
+
+| Kind | Meaning | Examples |
+|---|---|---|
+| Rule | stays at zero, CI fails | cycles, imports past a door, live mutants no one accepted, a branch that changes two modules |
+| Zero where you work | a module a branch changes holds none, baselined or not | violations, cross-module clones |
+| Ratchet | may only go down, in modules no branch has touched yet | violations left in the baseline, cross-module clones |
+| Map | read by people, never fails CI | fan-in, modules that changed together |
+
+Agents copy the code they read, and behind one door per module that is the
+inside of the module they change. So a branch clears every violation in that
+module, even one in the baseline: debt there stops the work until it is gone
+(stop the line, Taiichi Ohno, *Toyota Production System*). Debt in a module no
+branch touches waits for the next branch that does, so one module's debt never
+blocks every chat. A map has no right value: a shared module many features use
+is the design working, and failing on fan-in would push agents to copy code
+instead of importing it. Each language's own tools read the code, and the kit applies
+each rule once for every language; see [backend.md](spec/backend.md#languages).
+
+## Agent skill
+
+`skills/module-spec/` tells an agent which command to run at each step of a
+change. The repo is its own Claude Code plugin marketplace. On the machine with
+a clone of this repo, from the clone:
+
+```sh
+claude plugin marketplace add "$PWD"
+claude plugin install module-spec@module-spec
+```
+
+The plugin reads the clone in place, so a pull updates the skill.
+`__tests__/skill.test.js` fails when the skill runs a command or flag the CLI
+does not have.
+
+## module-spec.json
+
+Every key is optional.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `roots` | `["."]` | Folders searched for `module.yaml`. |
+| `maxComplexity` | `5` | The highest complexity a `shell/` or `view/` function may have (B2, F3). Was `shellComplexity`. |
+| `pure.<language>` | `[]` | Third-party packages that touch nothing outside, such as `"pure": { "typescript": ["zod"] }`. Any other third-party package counts as input/output, so only `adapters/` and apps may import it (B1, B3, F2). An entry ending in `/` matches a scope. Replaces `impure`, which now fails. |
+| `ui.<language>` | `[]` | Packages that draw the user interface, which only `view/` may import (F1), such as `react` or a component library. `new-module --view` adds the ones its template uses. `/` works as in `pure`. |
+| `python.executable` | `.venv/bin/python`, else `python3` | The interpreter that has import-linter and ruff. |
+| `clones.minLines` | `6` | The shortest clone C11 counts. |
+
+## Layout
+
+```
+spec/                  the why, one rule per heading, each with an ID
+manifest.schema.json   the shape of module.yaml
+bin/module-spec.js     the CLI
+skills/module-spec/    the agent skill: which command to run when
+.claude-plugin/        the plugin and marketplace that install the skill
+lib/                   the rules, which never name a language
+lib/languages/<name>/  one folder per language: its door, its tools, its templates
+__tests__/conformance/ the projects every language must pass
+```
+
+`pnpm test` runs the suite. The Python tests need `.venv` with import-linter,
+ruff and pytest: `python3 -m venv .venv && .venv/bin/pip install import-linter ruff pytest mutmut`.
+
+## Adding a language
+
+1. Add `lib/languages/<name>/`. Its `index.js` exports the `Language` shape
+   described in [lib/languages/index.js](lib/languages/index.js): the door, what
+   counts as a test, which standard library modules touch the outside or draw,
+   how its own tools read the code, and its templates. Add it to `LANGUAGES` there.
+2. Add `__tests__/conformance/<name>.js`. It writes that language's code for
+   the modules in [cases.js](__tests__/conformance/cases.js), whose `code`
+   field says what each module holds.
+3. The language is supported when `pnpm test` passes: the clean project finds
+   nothing, and the broken one finds exactly what cases.js lists.

package/bin/module-spec.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { affectedModules, changedFiles } from "../lib/affected.js";
+import { BASELINE_FILE, compareWithBaseline, keyOf, loadBaseline, writeBaseline } from "../lib/baseline.js";
+import { checkBranch } from "../lib/branch.js";
+import { runChecks } from "../lib/check.js";
+import { writeApiReports } from "../lib/checks/api.js";
+import { loadConfig } from "../lib/config.js";
+import { LANGUAGES } from "../lib/languages/index.js";
+import { discoverModules } from "../lib/modules.js";
+import { MUTATION_REPORT, mutateModules } from "../lib/mutation.js";
+import { moduleMap } from "../lib/report.js";
+import { RULES, specLink } from "../lib/rules.js";
+import { initProject, newModule, newPort } from "../lib/scaffold.js";
+
+const USAGE = `usage: module-spec <command> [--root <dir>]
+
+  check [--since <ref>]       run every check; fails on a violation not in ${BASELINE_FILE}, a stale entry there,
+                              any violation in a module this branch changes, or a branch that changes two modules
+  baseline [--accept-new]     record today's violations; refuses to add new ones unless --accept-new
+  api                         rewrite each module's api-report.txt from what its door exports
+  new-module <dir> --role app|feature|shared --owns "<decision>" [--lang ${LANGUAGES.flatMap((language) => language.aliases).join("|")}] [--view]
+  new-port <module dir> <PortName>
+  affected [--since <ref>]    the modules a change since <ref> (default: main) can break, one folder per line
+  mutate [<module dir>...] [--since <ref>] [--accept]
+                              mutation-test each module with its own tests (default: the modules changed since <ref>); fails on any live mutant not accepted
+  report                      a map, never enforced: commits that stay in one module, pairs that change together, fan-in
+  init                        write a default module-spec.json`;
+
+/** Flags that take no value. */
+const SWITCHES = { "--accept-new": "acceptNew", "--view": "view", "--accept": "accept" };
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) positional.push(arg);
+    else if (SWITCHES[arg]) flags[SWITCHES[arg]] = true;
+    else flags[arg.slice(2)] = argv[(index += 1)];
+  }
+  return { positional, flags };
+}
+
+function describe(violation) {
+  const rule = RULES[violation.id];
+  const where = violation.line ? `${violation.file}:${violation.line}` : violation.file;
+  return `${violation.id} ${where} ${violation.detail}\n    ${rule.title}. Fix: ${rule.fix}\n    See ${specLink(violation.id)}`;
+}
+
+function describeClones(clones) {
+  return clones.map((clone) => `    ${clone.lines} lines: ${clone.a.file}:${clone.a.line} = ${clone.b.file}:${clone.b.line}`).join("\n");
+}
+
+async function check(root, since) {
+  const { modules, violations, clones } = await runChecks(root);
+  const diff = compareWithBaseline(loadBaseline(root), violations, clones.length);
+  const branch = checkBranch(root, { modules, violations, clones, since });
+  const fresh = new Set(diff.fresh.map(keyOf));
+  const baselinedHere = (branch?.violations ?? []).filter((violation) => !fresh.has(keyOf(violation)));
+  for (const violation of diff.fresh) console.log(describe(violation));
+  for (const violation of baselinedHere) console.log(`${describe(violation)}\n    In the baseline, but this branch changes its module, so it goes now.`);
+  for (const violation of branch?.spans ?? []) console.log(describe(violation));
+  if (branch?.clones.length > 0) {
+    console.log(`C11 ${branch.clones.length} cross-module clones reach a module this branch changes\n    ${RULES.C11.title}. Fix: ${RULES.C11.fix}\n    See ${specLink("C11")}`);
+    console.log(describeClones(branch.clones));
+  }
+  for (const key of diff.stale) console.log(`stale ${key}\n    Fixed, so remove it: run module-spec baseline.`);
+  if (diff.clonesNow > diff.clonesBefore) {
+    console.log(`C11 ${diff.clonesNow} cross-module clones, up from ${diff.clonesBefore}\n    ${RULES.C11.title}. Fix: ${RULES.C11.fix}\n    See ${specLink("C11")}`);
+    console.log(describeClones(clones));
+  } else if (diff.clonesNow < diff.clonesBefore) {
+    console.log(`C11 cross-module clones fell to ${diff.clonesNow} from ${diff.clonesBefore}: run module-spec baseline to lock it in.`);
+  }
+  const branchFailed = baselinedHere.length > 0 || (branch?.spans.length ?? 0) > 0 || (branch?.clones.length ?? 0) > 0;
+  const failed = branchFailed || diff.fresh.length > 0 || diff.stale.length > 0 || diff.clonesNow !== diff.clonesBefore;
+  const changed = branch ? `, branch changes ${branch.changed.map((module) => module.name).join(", ") || "no module"}` : "";
+  console.log(
+    `module-spec: ${modules.length} modules, ${diff.fresh.length} new, ${diff.stale.length} stale, ${diff.known} known, ${diff.clonesNow} cross-module clones${changed}`,
+  );
+  return failed ? 1 : 0;
+}
+
+async function baseline(root, acceptNew) {
+  const { violations, clones } = await runChecks(root);
+  const before = loadBaseline(root);
+  const added = violations.filter((violation) => !before.violations.has(keyOf(violation)));
+  const clonesUp = clones.length > before.clones;
+  if ((added.length > 0 || clonesUp) && !acceptNew) {
+    for (const violation of added) console.log(describe(violation));
+    if (clonesUp) console.log(`C11 cross-module clones rose to ${clones.length} from ${before.clones}`);
+    console.log("module-spec: refusing to add new violations to the baseline. Fix them, or rerun with --accept-new.");
+    return 1;
+  }
+  writeBaseline(root, violations, clones.length);
+  console.log(`module-spec: wrote ${BASELINE_FILE}: ${violations.length} violations, ${clones.length} cross-module clones`);
+  return 0;
+}
+
+async function api(root) {
+  const { modules, api: exportsByModule } = await runChecks(root);
+  const written = writeApiReports(root, modules, exportsByModule);
+  console.log(written.length > 0 ? `module-spec: rewrote ${written.join(", ")}` : "module-spec: every api-report.txt is current");
+  return 0;
+}
+
+function report(root) {
+  const { modules } = discoverModules(root, loadConfig(root));
+  const found = moduleMap(root, modules);
+  const share = found.commits === 0 ? 0 : Math.round((100 * found.singleModule) / found.commits);
+  console.log(`commits that touch modules: ${found.commits}, ${share}% stay in one module, ${found.sweeps} sweep 6 or more`);
+  console.log("modules that change together most:");
+  for (const [pair, count] of found.topPairs) console.log(`  ${count}  ${pair}`);
+  console.log("fan-in (modules that declare each one):");
+  for (const [name, count] of found.fanIn) console.log(`  ${count}  ${name}`);
+  return 0;
+}
+
+function affected(root, since) {
+  const { modules } = discoverModules(root, loadConfig(root));
+  const found = affectedModules(modules, changedFiles(root, since));
+  for (const module of found.modules) console.log(module.dir);
+  if (found.outside.length > 0) {
+    console.error(`module-spec: ${found.outside.length} changed files belong to no module, so only the full suite covers them: ${found.outside.join(", ")}`);
+  }
+  return 0;
+}
+
+function describeMutation(result) {
+  const { module } = result;
+  if (result.reason) return `${module.dir}: ${result.reason}`;
+  const head = `${module.dir}: killed ${result.killed} of ${result.killed + result.survivors.length}, ${result.survivors.length} live`;
+  if (!result.failed) {
+    const accepted = result.survivors.length > 0 ? `, all accepted in ${MUTATION_REPORT}` : "";
+    return `${head}${accepted}${result.wrote ? `. Rewrote ${module.dir}/${MUTATION_REPORT}` : ""}`;
+  }
+  return [
+    `${head}. Live mutants no test catches:`,
+    ...result.fresh.map((survivor) => `    ${module.dir}/${survivor.file}:${survivor.line} ${survivor.detail}`),
+    "    Add a test through the door that fails for each one. Only if no test can tell one apart from the real code, rerun with --accept.",
+  ].join("\n");
+}
+
+async function mutate(root, dirs, flags) {
+  const results = await mutateModules(root, { dirs, since: flags.since, accept: flags.accept });
+  if (results.length === 0) console.log("module-spec: no module changed, so nothing to mutate");
+  for (const result of results) console.log(describeMutation(result));
+  return results.some((result) => result.failed) ? 1 : 0;
+}
+
+function printWritten(written) {
+  console.log(written.length > 0 ? `module-spec: wrote ${written.join(", ")}` : "module-spec: nothing to write");
+  return 0;
+}
+
+async function main(argv) {
+  const { positional, flags } = parseArgs(argv);
+  const root = path.resolve(flags.root ?? ".");
+  const [command, ...rest] = positional;
+  switch (command) {
+    case "check":
+      return check(root, flags.since);
+    case "baseline":
+      return baseline(root, flags.acceptNew);
+    case "api":
+      return api(root);
+    case "new-module":
+      return printWritten(await newModule(root, { dir: rest[0], role: flags.role, owns: flags.owns, lang: flags.lang, view: flags.view }));
+    case "new-port":
+      return printWritten(await newPort(root, { dir: rest[0], port: rest[1] }));
+    case "affected":
+      return affected(root, flags.since);
+    case "mutate":
+      return mutate(root, rest, flags);
+    case "report":
+      return report(root);
+    case "init":
+      return printWritten(initProject(root));
+    default:
+      console.log(USAGE);
+      return command ? 1 : 0;
+  }
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    console.error(`module-spec: ${error.message}`);
+    process.exitCode = 2;
+  },
+);

package/lib/affected.js

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { MANIFEST_FILE } from "./modules.js";
+import { moduleLookup } from "./place.js";
+
+/** Branches a change is measured from when no --since names one, in the order tried: the remote's default first. */
+const MAIN_BRANCHES = ["origin/HEAD", "main", "master"];
+
+function git(root, args) {
+  const run = spawnSync("git", args, { cwd: root, encoding: "utf8" });
+  if (run.error || run.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${(run.stderr ?? String(run.error)).trim()}`);
+  return run.stdout.split("\n").filter(Boolean);
+}
+
+/** The commit a change starts from: where HEAD left `since`, or the remote's default branch, main or master. */
+function baseOf(root, since) {
+  const ref = since ?? MAIN_BRANCHES.find((branch) => spawnSync("git", ["rev-parse", "--verify", "--quiet", branch], { cwd: root }).status === 0);
+  if (!ref) throw new Error(`no ${MAIN_BRANCHES.join(" or ")} branch to compare with: pass --since <ref>`);
+  return git(root, ["merge-base", "HEAD", ref])[0];
+}
+
+/** Every file changed since `since`, committed or not, new files included, as paths relative to root. */
+export function changedFiles(root, since) {
+  const base = baseOf(root, since);
+  const changed = [...git(root, ["diff", "--name-only", "--relative", base]), ...git(root, ["ls-files", "--others", "--exclude-standard"])];
+  return [...new Set(changed)].sort();
+}
+
+/**
+ * The modules a change can break: `changed` holds a changed file, and `modules` adds every module that
+ * depends on one of them, directly or through others. A dependent counts even when no door changed, because
+ * behaviour can change behind an unchanged door. `outside` lists the changed files that belong to no module.
+ */
+export function affectedModules(modules, files) {
+  const moduleOf = moduleLookup(modules);
+  const dependents = new Map(modules.map((module) => [module.name, []]));
+  for (const module of modules) for (const name of module.dependsOn) dependents.get(name).push(module);
+  const changed = new Set(files.map(moduleOf).filter(Boolean));
+  const affected = new Set(changed);
+  // A Set visits what is added while it is walked, so this reaches dependents of dependents.
+  for (const module of affected) for (const dependent of dependents.get(module.name)) affected.add(dependent);
+  const byDir = (a, b) => a.dir.localeCompare(b.dir);
+  return { changed: [...changed].sort(byDir), modules: [...affected].sort(byDir), outside: files.filter((file) => !moduleOf(file)) };
+}
+
+/** Whether the commit a change starts from holds a module.yaml. It does not on the branch that first adopts the spec. */
+export function adoptedAtBase(root, since) {
+  return git(root, ["ls-tree", "-r", "--name-only", baseOf(root, since)]).some((file) => path.posix.basename(file) === MANIFEST_FILE);
+}
+
+/** Whether root sits in a git work tree with a first commit, so a change can be measured at all. */
+export function hasHistory(root) {
+  return spawnSync("git", ["rev-parse", "--verify", "--quiet", "HEAD"], { cwd: root }).status === 0;
+}

package/lib/baseline.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const BASELINE_FILE = "module-spec.baseline.json";
+
+/** A violation's identity in the baseline. No line number, so moving code does not churn the file. */
+export function keyOf(violation) {
+  return `${violation.id} ${violation.file} ${violation.detail}`;
+}
+
+export function loadBaseline(root) {
+  const file = path.join(root, BASELINE_FILE);
+  if (!fs.existsSync(file)) return { violations: new Set(), clones: 0 };
+  const saved = JSON.parse(fs.readFileSync(file, "utf8"));
+  return { violations: new Set(saved.violations), clones: saved.clones };
+}
+
+export function writeBaseline(root, violations, clones) {
+  const saved = { violations: [...new Set(violations.map(keyOf))].sort(), clones };
+  fs.writeFileSync(path.join(root, BASELINE_FILE), `${JSON.stringify(saved, null, 2)}\n`);
+}
+
+/** What changed since the baseline. Both new and stale entries fail, so the baseline only shrinks. */
+export function compareWithBaseline(baseline, violations, clones) {
+  const current = new Set(violations.map(keyOf));
+  const fresh = violations.filter((violation) => !baseline.violations.has(keyOf(violation)));
+  return {
+    fresh,
+    stale: [...baseline.violations].filter((key) => !current.has(key)),
+    known: violations.length - fresh.length,
+    clonesBefore: baseline.clones,
+    clonesNow: clones,
+  };
+}

package/lib/branch.js

@@ -0,0 +1,26 @@
+import { adoptedAtBase, affectedModules, changedFiles, hasHistory } from "./affected.js";
+import { moduleLookup } from "./place.js";
+
+/**
+ * What a branch must leave at zero. Agents copy the code they read, and behind one door per module the code a
+ * branch reads is the inside of the module it changes. So that module carries no violation, baselined or not,
+ * and no cross-module clone. A branch changes one module besides apps, which only wire (W1).
+ * Before a repository's first commit there is no branch, so nothing is returned. Nor on the branch that first adopts the
+ * spec: every module is new there, and the baseline it writes holds today's debt.
+ */
+export function checkBranch(root, { modules, violations, clones, since }) {
+  if (!hasHistory(root) || !adoptedAtBase(root, since)) return null;
+  const { changed } = affectedModules(modules, changedFiles(root, since));
+  const touched = new Set(changed);
+  const moduleOf = moduleLookup(modules);
+  const changedWork = changed.filter((module) => module.role !== "app");
+  return {
+    changed,
+    violations: violations.filter((violation) => touched.has(moduleOf(violation.file))),
+    clones: clones.filter((clone) => touched.has(moduleOf(clone.a.file)) || touched.has(moduleOf(clone.b.file))),
+    spans:
+      changedWork.length > 1
+        ? [{ id: "W1", file: changedWork[1].manifestPath, line: null, detail: `changes ${changedWork.map((module) => module.name).join(", ")}: one module per branch` }]
+        : [],
+  };
+}

package/lib/check.js

@@ -0,0 +1,53 @@
+import { keyOf } from "./baseline.js";
+import { loadConfig } from "./config.js";
+import { checkApiReports } from "./checks/api.js";
+import { findCrossModuleClones } from "./checks/clones.js";
+import { checkImports } from "./checks/imports.js";
+import { checkManifests } from "./checks/manifests.js";
+import { checkPorts } from "./checks/ports.js";
+import { checkTables } from "./checks/tables.js";
+import { LANGUAGES } from "./languages/index.js";
+import { discoverModules } from "./modules.js";
+import { findingsOf, scanPlan } from "./scans.js";
+
+/** Runs each language's own tools over that language's modules and merges what they read. */
+async function analyzeLanguages(root, config, modules) {
+  const merged = { edges: [], findings: [], api: new Map(), languages: new Set() };
+  for (const language of LANGUAGES) {
+    const own = modules.filter((module) => module.language === language);
+    if (own.length === 0) continue;
+    const read = await language.analyze({ root, config, modules: own, plan: scanPlan(own, config) });
+    merged.edges.push(...read.edges);
+    merged.findings.push(...read.findings, ...findingsOf(read.sightings, own));
+    for (const [name, lines] of read.api) merged.api.set(name, lines);
+    merged.languages.add(language);
+  }
+  return merged;
+}
+
+function unique(violations) {
+  const seen = new Map();
+  for (const violation of violations) {
+    const normalized = { line: null, ...violation };
+    if (!seen.has(keyOf(normalized))) seen.set(keyOf(normalized), normalized);
+  }
+  return [...seen.values()].sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0));
+}
+
+/** Every rule over the project at `root`: its violations, its cross-module clones and what the doors export. */
+export async function runChecks(root) {
+  const config = loadConfig(root);
+  const { modules, problems } = discoverModules(root, config);
+  const read = await analyzeLanguages(root, config, modules);
+  const violations = unique([
+    ...problems,
+    ...checkManifests(modules),
+    ...read.findings,
+    ...checkImports({ modules, edges: read.edges, config, analyzedLanguages: read.languages }),
+    ...checkTables(root, modules),
+    ...checkPorts(modules, read.edges),
+    ...checkApiReports(root, modules, read.api),
+  ]);
+  const clones = await findCrossModuleClones(root, modules, config);
+  return { config, modules, violations, clones, api: read.api };
+}

package/lib/checks/api.js

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readIfExists } from "../files.js";
+
+export const API_REPORT = "api-report.txt";
+
+/** The api-report.txt a module's door exports should produce. */
+function apiReportOf(module, lines) {
+  return [`# ${module.name}: what its door exports. Rewrite with \`module-spec api\`.`, "", ...lines].join("\n") + "\n";
+}
+
+/** C4: each module's committed api-report.txt matches what its door exports. */
+export function checkApiReports(root, modules, api) {
+  const problems = [];
+  for (const module of modules.filter((candidate) => api.has(candidate.name))) {
+    const file = `${module.dir}/${API_REPORT}`;
+    const expected = apiReportOf(module, api.get(module.name));
+    const committed = readIfExists(path.join(root, file));
+    if (committed === null) problems.push({ id: "C4", file, line: null, detail: "is missing: run module-spec api" });
+    else if (committed !== expected) problems.push({ id: "C4", file, line: null, detail: "differs from what the door exports: run module-spec api and review the diff" });
+  }
+  return problems;
+}
+
+export function writeApiReports(root, modules, api) {
+  const written = [];
+  for (const module of modules.filter((candidate) => api.has(candidate.name))) {
+    const expected = apiReportOf(module, api.get(module.name));
+    const file = path.join(root, module.dir, API_REPORT);
+    if (readIfExists(file) !== expected) {
+      fs.writeFileSync(file, expected);
+      written.push(`${module.dir}/${API_REPORT}`);
+    }
+  }
+  return written;
+}