module-spec 0.0.0-stage → 0.2.0

package/lib/languages/typescript/read.js

@@ -0,0 +1,220 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import ts from "typescript";
+import { toPosix } from "../../files.js";
+import { kitPackageDir } from "../../tools.js";
+
+const NOT_A_PACKAGE = /^(\.|\/|#)/;
+const OUTPUT_LIMIT = 512 * 1024 * 1024;
+
+function packageNameOf(specifier) {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
+function cruiseConfig(root) {
+  const options = {
+    doNotFollow: { path: "node_modules" },
+    exclude: { path: "(^|/)(node_modules|dist|build|coverage)/" },
+    tsPreCompilationDeps: true,
+    enhancedResolveOptions: {
+      exportsFields: ["exports"],
+      conditionNames: ["import", "require", "node", "default", "types"],
+      extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json"],
+    },
+  };
+  if (fs.existsSync(path.join(root, "tsconfig.json"))) options.tsConfig = { fileName: "tsconfig.json" };
+  return { options };
+}
+
+/**
+ * The specifiers a file names only in `import type` or `export type` statements. Those leave no import behind
+ * when the code runs. `import { type T }` is not among them: Node still loads that module, only empty.
+ */
+function erasedSpecifiers(root, file) {
+  const source = ts.createSourceFile(file, fs.readFileSync(path.join(root, file), "utf8"), ts.ScriptTarget.Latest);
+  const erased = new Set();
+  const loaded = new Set();
+  for (const statement of source.statements) {
+    const isImport = ts.isImportDeclaration(statement);
+    if ((!isImport && !ts.isExportDeclaration(statement)) || !statement.moduleSpecifier) continue;
+    const typeOnly = isImport ? statement.importClause?.isTypeOnly : statement.isTypeOnly;
+    (typeOnly ? erased : loaded).add(statement.moduleSpecifier.text);
+  }
+  return new Set([...erased].filter((specifier) => !loaded.has(specifier)));
+}
+
+/** Import edges, read by the kit's own dependency-cruiser. */
+function readEdges(root, dirs) {
+  const dir = kitPackageDir("dependency-cruiser");
+  const bin = path.join(dir, JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")).bin.depcruise);
+  const configFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "module-spec-")), "cruise.json");
+  fs.writeFileSync(configFile, JSON.stringify(cruiseConfig(root)));
+  const run = spawnSync(process.execPath, [bin, ...dirs, "--config", configFile, "--output-type", "json"], {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: OUTPUT_LIMIT,
+  });
+  fs.rmSync(path.dirname(configFile), { recursive: true, force: true });
+  if (run.status !== 0) throw new Error(`dependency-cruiser failed:\n${run.stderr || run.stdout}`);
+  const edges = [];
+  for (const file of JSON.parse(run.stdout).modules) {
+    if (file.source.includes("node_modules/")) continue;
+    let erased = null;
+    for (const dependency of file.dependencies) {
+      const from = toPosix(file.source);
+      if (dependency.coreModule) {
+        edges.push({ from, external: dependency.module.replace(/^node:/, ""), std: true });
+      } else if (dependency.couldNotResolve || dependency.resolved.includes("node_modules/")) {
+        if (!NOT_A_PACKAGE.test(dependency.module)) edges.push({ from, external: packageNameOf(dependency.module), std: false });
+      } else {
+        const typeOnly = (erased ??= erasedSpecifiers(root, from)).has(dependency.module);
+        edges.push({ from, to: toPosix(dependency.resolved), ...(typeOnly && { typeOnly }) });
+      }
+    }
+  }
+  return edges;
+}
+
+/** The syntax each scan in the plan looks for. Each message names one scan, so a sighting maps back to it. */
+const SYNTAX = {
+  wait: [
+    "FunctionDeclaration[async=true]",
+    "FunctionExpression[async=true]",
+    "ArrowFunctionExpression[async=true]",
+    "AwaitExpression",
+    "ForOfStatement[await=true]",
+  ].map((selector) => ({ selector, message: "waits" })),
+  // Globals that reach the outside without an import, so the import check cannot see them.
+  io: [
+    ...["fetch", "WebSocket", "XMLHttpRequest", "EventSource"].map((name) => ({
+      selector: `:matches(CallExpression, NewExpression)[callee.type='Identifier'][callee.name='${name}']`,
+      message: `uses ${name}`,
+    })),
+    ...["localStorage", "sessionStorage", "indexedDB"].map((name) => ({
+      selector: `MemberExpression[object.type='Identifier'][object.name='${name}']`,
+      message: `uses ${name}`,
+    })),
+  ],
+  env: [{ selector: "MemberExpression[object.type='MetaProperty'][property.name='env']", message: "reads import.meta.env" }],
+  // JSX needs no import of the UI framework under the automatic runtime, so the import check cannot see it.
+  ui: [{ selector: ":matches(JSXElement, JSXFragment)", message: "draws JSX outside view/" }],
+  // Calls that patch what a module imports or holds, instead of passing a fake in: vitest, jest and node:test.
+  patch: [
+    ...["vi", "jest"].flatMap((runner) =>
+      ["mock", "doMock", "unstable_mockModule", "spyOn", "stubGlobal"].map((call) => ({
+        selector: `CallExpression[callee.object.name='${runner}'][callee.property.name='${call}']`,
+        message: `patches with ${runner}.${call}`,
+      })),
+    ),
+    ...["method", "module", "getter", "setter", "property"].flatMap((call) => [
+      { selector: `CallExpression[callee.object.name='mock'][callee.property.name='${call}']`, message: `patches with mock.${call}` },
+      { selector: `CallExpression[callee.object.property.name='mock'][callee.property.name='${call}']`, message: `patches with mock.${call}` },
+    ]),
+  ],
+};
+
+const SCAN_OF_MESSAGE = new Map(Object.entries(SYNTAX).flatMap(([scan, selectors]) => selectors.map(({ message }) => [message, scan])));
+
+const GLOB_SPECIAL = /[[\]{}()*?!+@]/g;
+const asGlob = (file) => file.replace(GLOB_SPECIAL, "\\$&");
+
+/** One no-restricted-syntax entry per set of scans, since a later entry for the same rule replaces an earlier one's options. */
+function syntaxEntries(plan) {
+  const scansOf = new Map();
+  for (const scan of Object.keys(SYNTAX)) {
+    for (const file of plan[scan]) scansOf.set(file, [...(scansOf.get(file) ?? []), scan]);
+  }
+  return [...Map.groupBy(scansOf, ([, scans]) => scans.join(" "))].map(([scans, entries]) => ({
+    files: entries.map(([file]) => asGlob(file)),
+    rules: { "no-restricted-syntax": ["error", ...scans.split(" ").flatMap((scan) => SYNTAX[scan])] },
+  }));
+}
+
+/** What ESLint sees for each scan in the plan. */
+async function lintSightings(root, plan) {
+  const all = [...new Set([...Object.keys(SYNTAX).flatMap((scan) => plan[scan]), ...plan.complexity])];
+  if (all.length === 0) return [];
+  const { ESLint } = await import("eslint");
+  const parser = await import("@typescript-eslint/parser");
+  const configs = [
+    { files: ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"], languageOptions: { parser } },
+    ...syntaxEntries(plan),
+    { files: plan.complexity.map(asGlob), rules: { complexity: ["error", { max: plan.maxComplexity }] } },
+    {
+      files: plan.env.map(asGlob),
+      rules: { "no-restricted-properties": ["error", { object: "process", property: "env", message: "reads process.env" }] },
+    },
+  ].filter((entry) => entry.files.length > 0);
+  const linter = new ESLint({ cwd: root, overrideConfigFile: true, overrideConfig: configs, ignore: false });
+  const results = await linter.lintFiles(all);
+  const unreadable = results.filter((result) => result.messages.some((message) => message.fatal));
+  if (unreadable.length > 0) {
+    throw new Error(`ESLint could not parse ${unreadable.map((result) => path.relative(root, result.filePath)).join(", ")}`);
+  }
+  const seen = {
+    "no-restricted-syntax": (message) => ({ scan: SCAN_OF_MESSAGE.get(message.message), detail: message.message }),
+    complexity: (message) => ({ scan: "complexity", detail: message.message }),
+    "no-restricted-properties": () => ({ scan: "env", detail: "reads process.env" }),
+  };
+  return results.flatMap((result) => {
+    const file = toPosix(path.relative(root, result.filePath));
+    return result.messages
+      .filter((message) => seen[message.ruleId])
+      .map((message) => ({ ...seen[message.ruleId](message), file, line: message.line }));
+  });
+}
+
+function compilerOptions(ts, root) {
+  const tsconfig = path.join(root, "tsconfig.json");
+  if (fs.existsSync(tsconfig)) {
+    const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
+    return ts.parseJsonConfigFileContent(read.config, ts.sys, root).options;
+  }
+  return {
+    allowImportingTsExtensions: true,
+    noEmit: true,
+    module: ts.ModuleKind.NodeNext,
+    moduleResolution: ts.ModuleResolutionKind.NodeNext,
+    target: ts.ScriptTarget.ESNext,
+    jsx: ts.JsxEmit.ReactJSX,
+    strict: true,
+    skipLibCheck: true,
+  };
+}
+
+function exportLine(ts, checker, sourceFile, exported) {
+  const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+  if (!(symbol.flags & ts.SymbolFlags.Value)) return `type ${exported.name}`;
+  const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0] ?? sourceFile;
+  const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+  return `${exported.name}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`;
+}
+
+/** Each door's exports with their types, one line each, read by the TypeScript compiler. */
+async function doorExports(root, modules) {
+  const { default: ts } = await import("typescript");
+  const doorOf = (module) => path.join(root, module.dir, module.language.door);
+  const program = ts.createProgram(modules.map(doorOf), compilerOptions(ts, root));
+  const checker = program.getTypeChecker();
+  const api = new Map();
+  for (const module of modules) {
+    const sourceFile = program.getSourceFile(doorOf(module));
+    const symbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
+    const lines = symbol ? checker.getExportsOfModule(symbol).map((exported) => exportLine(ts, checker, sourceFile, exported)) : [];
+    api.set(module.name, lines.sort());
+  }
+  return api;
+}
+
+/** @type {import("../index.js").Language["analyze"]} */
+export async function analyze({ root, config, modules, plan }) {
+  return {
+    edges: readEdges(root, config.roots),
+    sightings: await lintSightings(root, plan),
+    findings: [],
+    api: await doorExports(root, modules),
+  };
+}

package/lib/languages/typescript/scaffold.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readIfExists } from "../../files.js";
+import { copyTemplates, fill, writeNew } from "../../templating.js";
+import { dependenciesOf, testRunnerOf } from "./project.js";
+
+const TEMPLATES = path.join(path.dirname(fileURLToPath(import.meta.url)), "templates");
+
+function testTemplate(root, kind) {
+  return fs.readFileSync(path.join(TEMPLATES, `${kind}-test.${testRunnerOf(root)}.ts`), "utf8");
+}
+
+/** A sibling module's package.json, when the modules beside this one are workspace packages. */
+function siblingPackage(root, dir) {
+  const parent = path.join(root, path.dirname(dir));
+  if (!fs.existsSync(parent)) return null;
+  for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+    const text = entry.isDirectory() && readIfExists(path.join(parent, entry.name, "package.json"));
+    if (text) return JSON.parse(text);
+  }
+  return null;
+}
+
+/** A package.json for the new module, when the modules beside it are workspace packages. */
+function writeWorkspacePackage(root, dir, values, written) {
+  const sibling = siblingPackage(root, dir);
+  if (!sibling) return;
+  const scope = sibling.name?.startsWith("@") ? `${sibling.name.split("/")[0]}/` : "";
+  const packageJson = { name: `${scope}${values.name}`, private: true, type: "module", exports: { ".": "./index.ts" } };
+  writeNew(root, path.join(dir, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`, written);
+}
+
+export function newModule(root, dir, values) {
+  const written = [];
+  copyTemplates(root, path.join(TEMPLATES, "module"), dir, values, written);
+  writeNew(root, path.join(dir, "__tests__", `${values.name}.test.ts`), fill(testTemplate(root, "module"), values), written);
+  writeWorkspacePackage(root, dir, values, written);
+  return written;
+}
+
+/** A module with a React view/ and a vitest test, in the shape of spec/frontend.md. */
+export function newViewModule(root, dir, values) {
+  const dependencies = dependenciesOf(root);
+  const missing = ["react", "react-dom", "vitest"].filter((name) => !dependencies[name]);
+  if (missing.length > 0) {
+    throw new Error(`new-module --view writes a React view with a vitest test: add ${missing.join(", ")} to package.json first`);
+  }
+  const written = [];
+  copyTemplates(root, path.join(TEMPLATES, "view-module"), dir, values, written);
+  writeWorkspacePackage(root, dir, values, written);
+  return written;
+}
+
+export function newPort(root, dir, values) {
+  const written = [];
+  copyTemplates(root, path.join(TEMPLATES, "port"), dir, values, written);
+  writeNew(root, path.join(dir, "__tests__", `${values.Port}.contract.test.ts`), fill(testTemplate(root, "port"), values), written);
+  return written;
+}

package/lib/languages/typescript/templates/module/index.ts

@@ -0,0 +1,2 @@
+export { create{{Name}} } from "./shell/create{{Name}}.ts";
+export type { {{Name}}, {{Name}}Deps } from "./shell/create{{Name}}.ts";

package/lib/languages/typescript/templates/module/shell/create{{Name}}.ts

@@ -0,0 +1,8 @@
+export type {{Name}}Deps = Record<string, never>;
+
+export type {{Name}} = Record<string, never>;
+
+export function create{{Name}}(deps: {{Name}}Deps): {{Name}} {
+  void deps;
+  return {};
+}

package/lib/languages/typescript/templates/module-test.node.ts

@@ -0,0 +1,7 @@
+import { deepStrictEqual } from "node:assert";
+import { test } from "node:test";
+import { create{{Name}} } from "../index.ts";
+
+test("create{{Name}} builds {{name}} from its deps", () => {
+  deepStrictEqual(create{{Name}}({}), {});
+});

package/lib/languages/typescript/templates/module-test.vitest.ts

@@ -0,0 +1,6 @@
+import { expect, test } from "vitest";
+import { create{{Name}} } from "../index.ts";
+
+test("create{{Name}} builds {{name}} from its deps", () => {
+  expect(create{{Name}}({})).toEqual({});
+});

package/lib/languages/typescript/templates/port/adapters/inMemory{{Port}}.ts

@@ -0,0 +1,5 @@
+import type { {{Port}} } from "../ports/{{Port}}.ts";
+
+export function inMemory{{Port}}(): {{Port}} {
+  return {};
+}

package/lib/languages/typescript/templates/port/ports/{{Port}}.ts

@@ -0,0 +1 @@
+export interface {{Port}} {}

package/lib/languages/typescript/templates/port-test.node.ts

@@ -0,0 +1,12 @@
+import { describe } from "node:test";
+import { inMemory{{Port}} } from "../adapters/inMemory{{Port}}.ts";
+import type { {{Port}} } from "../ports/{{Port}}.ts";
+
+/** One test per promise {{Port}} makes. Every adapter runs this same suite, so the fake cannot drift from the real one. */
+export function {{portCamel}}Contract(make: () => {{Port}}): void {
+  void make;
+}
+
+describe("{{Port}} contract: in-memory fake", () => {
+  {{portCamel}}Contract(inMemory{{Port}});
+});

package/lib/languages/typescript/templates/port-test.vitest.ts

@@ -0,0 +1,12 @@
+import { describe } from "vitest";
+import { inMemory{{Port}} } from "../adapters/inMemory{{Port}}.ts";
+import type { {{Port}} } from "../ports/{{Port}}.ts";
+
+/** One test per promise {{Port}} makes. Every adapter runs this same suite, so the fake cannot drift from the real one. */
+export function {{portCamel}}Contract(make: () => {{Port}}): void {
+  void make;
+}
+
+describe("{{Port}} contract: in-memory fake", () => {
+  {{portCamel}}Contract(inMemory{{Port}});
+});

package/lib/languages/typescript/templates/view-module/__tests__/{{name}}.test.tsx

@@ -0,0 +1,9 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, test } from "vitest";
+import { create{{Name}}Model, {{Name}}Page } from "../index.ts";
+
+test("{{name}} shows it is ready once started", () => {
+  const model = create{{Name}}Model({});
+  model.send({ type: "started" });
+  expect(renderToStaticMarkup(<{{Name}}Page model={model} />)).toContain("Ready");
+});

package/lib/languages/typescript/templates/view-module/core/model.ts

@@ -0,0 +1,25 @@
+/** What {{name}} shows. The view draws it, and only update() changes it. */
+export interface {{Name}}State {
+  readonly ready: boolean;
+}
+
+/** What can happen on the screen. */
+export type {{Name}}Event = { type: "started" };
+
+/** What the view reads and sends events to. The shell builds it, and the view knows only this type. */
+export interface {{Name}}Model {
+  state(): {{Name}}State;
+  subscribe(listener: () => void): () => void;
+  send(event: {{Name}}Event): void;
+}
+
+export const initial{{Name}}State: {{Name}}State = { ready: false };
+
+export function update(state: {{Name}}State, event: {{Name}}Event): {{Name}}State {
+  switch (event.type) {
+    case "started":
+      return { ...state, ready: true };
+  }
+}
+
+export const statusOf = (state: {{Name}}State): string => (state.ready ? "Ready" : "Not started");

package/lib/languages/typescript/templates/view-module/index.ts

@@ -0,0 +1,4 @@
+export { create{{Name}}Model } from "./shell/create{{Name}}Model.ts";
+export type { {{Name}}Deps } from "./shell/create{{Name}}Model.ts";
+export { {{Name}}Page } from "./view/{{Name}}Page.tsx";
+export type { {{Name}}Model } from "./core/model.ts";

package/lib/languages/typescript/templates/view-module/shell/create{{Name}}Model.ts

@@ -0,0 +1,20 @@
+import { type {{Name}}Model, type {{Name}}State, initial{{Name}}State, update } from "../core/model.ts";
+
+export type {{Name}}Deps = Record<string, never>;
+
+export function create{{Name}}Model(deps: {{Name}}Deps): {{Name}}Model {
+  void deps;
+  let state: {{Name}}State = initial{{Name}}State;
+  const listeners = new Set<() => void>();
+  return {
+    state: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+    send(event) {
+      state = update(state, event);
+      for (const listener of listeners) listener();
+    },
+  };
+}

package/lib/languages/typescript/templates/view-module/view/{{Name}}Page.tsx

@@ -0,0 +1,14 @@
+import { useSyncExternalStore } from "react";
+import { type {{Name}}Model, statusOf } from "../core/model.ts";
+
+export function {{Name}}Page({ model }: { model: {{Name}}Model }) {
+  const state = useSyncExternalStore(model.subscribe, model.state, model.state);
+  return (
+    <section>
+      <p>{statusOf(state)}</p>
+      <button type="button" onClick={() => model.send({ type: "started" })}>
+        Start
+      </button>
+    </section>
+  );
+}

package/lib/modules.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import YAML from "yaml";
+import { readIfExists, walkFiles } from "./files.js";
+import { doorNames, languageOfDir } from "./languages/index.js";
+import { PARTS } from "./place.js";
+
+const require = createRequire(import.meta.url);
+const Ajv2020 = require("ajv/dist/2020.js");
+const SCHEMA = require("../manifest.schema.json");
+
+export const MANIFEST_FILE = "module.yaml";
+
+const validateManifest = new Ajv2020({ allErrors: true }).compile(SCHEMA);
+
+function describeSchemaError(error, data) {
+  if (error.instancePath !== "/owns") return `${error.instancePath || "module.yaml"} ${error.message}`;
+  if (error.keyword === "not") return `owns "${data.owns}" names an activity, not a decision`;
+  if (error.keyword === "pattern") return "owns spans more than one line";
+  return `owns ${error.message}`;
+}
+
+function schemaProblems(manifestPath, data) {
+  if (validateManifest(data)) return [];
+  return validateManifest.errors.map((error) => ({
+    id: error.instancePath === "/owns" ? "C2" : "C1",
+    file: manifestPath,
+    detail: describeSchemaError(error, data),
+  }));
+}
+
+function readModule(root, manifestPath, problems) {
+  const dir = path.posix.dirname(manifestPath);
+  let data;
+  try {
+    data = YAML.parse(fs.readFileSync(path.join(root, manifestPath), "utf8")) ?? {};
+  } catch (error) {
+    problems.push({ id: "C1", file: manifestPath, detail: `is not valid YAML: ${error.message.split("\n")[0]}` });
+    return null;
+  }
+  const found = schemaProblems(manifestPath, data);
+  problems.push(...found);
+  if (found.some((problem) => problem.id === "C1")) return null;
+
+  const language = languageOfDir(path.join(root, dir));
+  if (!language) {
+    problems.push({ id: "C1", file: manifestPath, detail: `has no door: add ${doorNames()}` });
+    return null;
+  }
+  const packageText = readIfExists(path.join(root, dir, "package.json"));
+  const packageJson = packageText ? JSON.parse(packageText) : null;
+  if (packageJson && data.depends_on) {
+    problems.push({
+      id: "C5",
+      file: manifestPath,
+      detail: "lists depends_on, but package.json already lists this module's dependencies: keep them only in package.json",
+    });
+  }
+  const files = walkFiles(root, dir).filter((file) => language.isSource(file));
+  return {
+    name: packageJson?.name ?? path.posix.basename(dir),
+    dir,
+    role: data.role,
+    owns: data.owns,
+    language,
+    manifestPath,
+    depsFile: packageJson ? `${dir}/package.json` : manifestPath,
+    declared: packageJson
+      ? Object.keys({ ...packageJson.dependencies, ...packageJson.devDependencies, ...packageJson.peerDependencies })
+      : (data.depends_on ?? []),
+    ownsTables: data.owns_tables ?? [],
+    parts: new Set(PARTS.filter((part) => fs.existsSync(path.join(root, dir, language.partsDir, part)))),
+    files,
+  };
+}
+
+/** Every module under the configured roots, and every problem found reading their manifests. */
+export function discoverModules(root, config) {
+  const problems = [];
+  const manifests = [...new Set(config.roots.flatMap((dir) => walkFiles(root, dir)))]
+    .filter((file) => path.posix.basename(file) === MANIFEST_FILE)
+    .sort();
+  const read = manifests.map((manifestPath) => readModule(root, manifestPath, problems)).filter(Boolean);
+
+  const byName = new Map();
+  for (const module of read) {
+    const twin = byName.get(module.name);
+    if (twin) problems.push({ id: "C1", file: module.manifestPath, detail: `has the same name as ${twin.manifestPath}: ${module.name}` });
+    else byName.set(module.name, module);
+  }
+  const modules = [...byName.values()];
+  for (const module of modules) {
+    const outer = modules.find((other) => other !== module && module.dir.startsWith(`${other.dir}/`));
+    if (outer) problems.push({ id: "C1", file: module.manifestPath, detail: `sits inside module ${outer.name}: modules do not nest` });
+    module.dependsOn = module.declared.filter((name) => byName.has(name));
+    if (module.depsFile === module.manifestPath) {
+      for (const name of module.declared.filter((declared) => !byName.has(declared))) {
+        problems.push({ id: "C5", file: module.manifestPath, detail: `depends_on lists ${name}, which is no module` });
+      }
+    }
+  }
+  return { modules, problems };
+}

package/lib/mutation.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import path from "node:path";
+import { affectedModules, changedFiles } from "./affected.js";
+import { loadConfig } from "./config.js";
+import { readIfExists } from "./files.js";
+import { discoverModules } from "./modules.js";
+import { placeOf } from "./place.js";
+
+export const MUTATION_REPORT = "mutation-report.txt";
+
+/**
+ * The parts whose code is mutated, beside the door. Never ports, which hold only types, adapters, which contract
+ * tests prove against the real service, which may not run here, a view, which holds no rules (F3), or a file in
+ * no part, such as an app's composition root or a tool's config.
+ */
+const MUTATED = new Set(["core", "shell"]);
+
+/**
+ * The files mutation testing changes in a module, and the module's own tests, which must notice. An adapter's test
+ * proves the adapter against the outside and is slow, while the code it reaches is proven through the door, so it
+ * does not count.
+ */
+export function mutationTargets(module) {
+  const files = [];
+  const tests = [];
+  for (const file of module.files) {
+    const place = placeOf(module, file);
+    if (place.test) {
+      if (place.part !== "adapters" && !place.contractTest) tests.push(file);
+    }
+    else if (place.door || MUTATED.has(place.part)) files.push(file);
+  }
+  return { files, tests };
+}
+
+const lineOf = (survivor) => `${survivor.file}:${survivor.line} ${survivor.detail}`;
+/** A survivor's identity, without its line, so code that moves keeps its entry. */
+const keyOf = (survivor) => `${survivor.file} ${survivor.detail}`;
+const SURVIVOR_LINE = /^(\S+):(\d+) (.*)$/;
+
+/** The live mutants a module's report accepts, none when it has no report. */
+function acceptedSurvivors(root, module) {
+  const text = readIfExists(path.join(root, module.dir, MUTATION_REPORT));
+  return (text ?? "")
+    .split("\n")
+    .map((line) => SURVIVOR_LINE.exec(line))
+    .filter(Boolean)
+    .map(([, file, line, detail]) => ({ file, line: Number(line), detail }));
+}
+
+function reportText(module, accepted) {
+  return [
+    `# ${module.name}: live mutants accepted because no test can tell them apart from the code. Review each one.`,
+    "# `module-spec mutate --accept` rewrites this file.",
+    "",
+    ...accepted.map(lineOf),
+    "",
+  ].join("\n");
+}
+
+/**
+ * Whether a run stands: every live mutant must be one the report accepts, unless this run accepts them all.
+ * `fresh` names the live mutants the report does not accept, each accepted entry matching one mutant.
+ */
+export function judge(accepted, survivors, accept) {
+  if (accept) return { failed: false, fresh: [] };
+  const left = new Map();
+  for (const entry of accepted) left.set(keyOf(entry), (left.get(keyOf(entry)) ?? 0) + 1);
+  const fresh = survivors.filter((survivor) => {
+    const count = left.get(keyOf(survivor)) ?? 0;
+    left.set(keyOf(survivor), count - 1);
+    return count === 0;
+  });
+  return { failed: fresh.length > 0, fresh };
+}
+
+/** Rewrites the report to the mutants that live now, all of them accepted, or removes it when none live. */
+function writeReport(root, module, survivors) {
+  const report = path.join(root, module.dir, MUTATION_REPORT);
+  const before = readIfExists(report);
+  if (survivors.length === 0) {
+    if (before !== null) fs.rmSync(report);
+    return before !== null;
+  }
+  const text = reportText(module, survivors);
+  if (before === text) return false;
+  fs.writeFileSync(report, text);
+  return true;
+}
+
+async function mutateOne(root, config, module, accept) {
+  const { files, tests } = mutationTargets(module);
+  if (files.length === 0) return { module, reason: "nothing to mutate" };
+  if (tests.length === 0) return { module, failed: true, reason: "has code to mutate but no tests" };
+  const run = await module.language.mutate({ root, config, module, files, tests });
+  const inModule = (file) => file.slice(module.dir.length + 1);
+  const survivors = run.survivors
+    .map((survivor) => ({ ...survivor, file: inModule(survivor.file) }))
+    .sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.detail.localeCompare(b.detail));
+  const verdict = judge(acceptedSurvivors(root, module), survivors, accept);
+  const wrote = !verdict.failed && writeReport(root, module, survivors);
+  return { module, killed: run.killed, survivors, wrote, ...verdict };
+}
+
+function moduleAt(byDir, dir) {
+  const module = byDir.get(dir.replace(/\/+$/, ""));
+  if (!module) throw new Error(`${dir} is not a module folder`);
+  return module;
+}
+
+/**
+ * Mutation testing, one module at a time with only its own tests: the modules in `dirs`, or else the modules
+ * a change since `since` touched. Not their dependents: a dependent's code and tests are unchanged, so its
+ * live mutants are too. A module passes with no live mutant its mutation-report.txt does not accept.
+ */
+export async function mutateModules(root, { dirs = [], since, accept = false }) {
+  const config = loadConfig(root);
+  const { modules } = discoverModules(root, config);
+  const byDir = new Map(modules.map((module) => [module.dir, module]));
+  const chosen = dirs.length > 0 ? dirs.map((dir) => moduleAt(byDir, dir)) : affectedModules(modules, changedFiles(root, since)).changed;
+  const results = [];
+  for (const module of chosen) results.push(await mutateOne(root, config, module, accept));
+  return results;
+}