module-spec 0.0.0-stage → 0.1.0

package/lib/place.js

@@ -0,0 +1,25 @@
+export const PARTS = ["core", "shell", "view", "adapters", "ports"];
+
+/** The parts that never touch the outside, with the rule each breaks when it does. */
+export const PURE_PARTS = { core: "B1", view: "F2" };
+
+/** A function that finds the module a file belongs to, or null. */
+export function moduleLookup(modules) {
+  const deepestFirst = [...modules].sort((a, b) => b.dir.length - a.dir.length);
+  return (file) => deepestFirst.find((module) => file.startsWith(`${module.dir}/`)) ?? null;
+}
+
+/** Where a file sits inside its module: its part, whether it is a test, a contract test or the door. */
+export function placeOf(module, file) {
+  const inner = file.slice(module.dir.length + 1);
+  const segments = inner.split("/");
+  const { partsDir } = module.language;
+  const underParts = !partsDir ? segments : segments[0] === partsDir ? segments.slice(1) : [];
+  return {
+    inner,
+    part: underParts.length > 1 && PARTS.includes(underParts[0]) ? underParts[0] : null,
+    test: module.language.isTest(segments),
+    contractTest: module.language.isContractTest(segments.at(-1)),
+    door: module.language.isDoor(inner),
+  };
+}

package/lib/report.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { moduleLookup } from "./place.js";
+
+const COMMITS_READ = 500;
+const SWEEP = 6;
+const TOP_PAIRS = 5;
+
+/** Which modules each recent commit touched, from git history. */
+function commitsByModule(root, modules) {
+  const log = spawnSync("git", ["log", `-n${COMMITS_READ}`, "--name-only", "--format=@@%H"], { cwd: root, encoding: "utf8" });
+  if (log.status !== 0) return [];
+  const moduleOf = moduleLookup(modules);
+  return log.stdout
+    .split("@@")
+    .slice(1)
+    .map((commit) => new Set(commit.split("\n").slice(1).filter(Boolean).map(moduleOf).filter(Boolean).map((module) => module.name)))
+    .filter((touched) => touched.size > 0);
+}
+
+/** A map for people, never enforced: how often a commit stays in one module, which modules change together, and fan-in. */
+export function moduleMap(root, modules) {
+  const commits = commitsByModule(root, modules);
+  const pairs = new Map();
+  for (const touched of commits.filter((names) => names.size > 1 && names.size < SWEEP)) {
+    const names = [...touched].sort();
+    for (let first = 0; first < names.length; first += 1) {
+      for (let second = first + 1; second < names.length; second += 1) {
+        const pair = `${names[first]} + ${names[second]}`;
+        pairs.set(pair, (pairs.get(pair) ?? 0) + 1);
+      }
+    }
+  }
+  const fanIn = new Map(modules.map((module) => [module.name, 0]));
+  for (const module of modules) for (const name of module.dependsOn) fanIn.set(name, fanIn.get(name) + 1);
+  return {
+    commits: commits.length,
+    singleModule: commits.filter((touched) => touched.size === 1).length,
+    sweeps: commits.filter((touched) => touched.size >= SWEEP).length,
+    topPairs: [...pairs].sort((a, b) => b[1] - a[1]).slice(0, TOP_PAIRS),
+    fanIn: [...fanIn].filter(([, count]) => count > 0).sort((a, b) => b[1] - a[1]),
+  };
+}

package/lib/rules.js

@@ -0,0 +1,145 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SPEC_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "spec");
+
+/** Every rule a check can report. The heading named by `anchor` in `spec/<doc>` holds the why. */
+export const RULES = {
+  C1: {
+    doc: "common.md",
+    anchor: "c1-every-module-has-a-manifest",
+    title: "Every module has a valid manifest and a door",
+    fix: "Make module.yaml match manifest.schema.json, and give the module the door its language expects.",
+  },
+  C2: {
+    doc: "common.md",
+    anchor: "c2-owns-names-a-decision-not-an-activity",
+    title: "`owns` names a decision, not an activity",
+    fix: "Rewrite owns as the one decision only this module makes, in one line, such as 'how an engagement's fee is computed'.",
+  },
+  C3: {
+    doc: "common.md",
+    anchor: "c3-one-door",
+    title: "Other code reaches a module only through its door",
+    fix: "Import the module's door, and export what you need from there.",
+  },
+  C4: {
+    doc: "common.md",
+    anchor: "c4-the-door-stays-small",
+    title: "The door's exports match api-report.txt",
+    fix: "Run `module-spec api`, then review the diff of api-report.txt: export only what callers need.",
+  },
+  C5: {
+    doc: "common.md",
+    anchor: "c5-dependencies-are-declared",
+    title: "A module imports exactly the modules it declares",
+    fix: "Declare the module (depends_on, or package.json dependencies when the module has a package.json), or remove the import. Remove declared modules nothing imports.",
+  },
+  C6: {
+    doc: "common.md",
+    anchor: "c6-no-cycles",
+    title: "No cycles between modules",
+    fix: "Move what both sides need into a shared module, or let the app pass one side in through createX(deps).",
+  },
+  C8: {
+    doc: "common.md",
+    anchor: "c8-one-composition-root-wires-everything",
+    title: "Only an app reads the environment",
+    fix: "Read the value in the app's composition root and pass it in through createX(deps).",
+  },
+  C10: {
+    doc: "common.md",
+    anchor: "c10-only-the-owner-writes-its-tables",
+    title: "Only the owning module writes a table",
+    fix: "Write the table through its owner's door. If this module owns it, list it in owns_tables, and in no other module's.",
+  },
+  C11: {
+    doc: "common.md",
+    anchor: "c11-cross-module-clones-only-go-down",
+    title: "Cross-module clones only go down",
+    fix: "Give the copied code one owner: move it into a shared module, or let the app pass one module's door to the other.",
+  },
+  R1: {
+    doc: "roles.md",
+    anchor: "r1-a-feature-imports-only-shared-modules",
+    title: "A feature imports only shared modules",
+    fix: "Declare the port you need as a type in this feature's core, and let the app pass the other feature's door in through createX(deps).",
+  },
+  R2: {
+    doc: "roles.md",
+    anchor: "r2-a-shared-module-imports-only-shared-modules",
+    title: "A shared module imports only shared modules",
+    fix: "Move the code this module needs into a shared module, or let the caller pass it in as an argument.",
+  },
+  R3: {
+    doc: "roles.md",
+    anchor: "r3-an-app-imports-no-other-app",
+    title: "An app imports no other app",
+    fix: "Move the code both apps need into a shared module and import it from both.",
+  },
+  B1: {
+    doc: "backend.md",
+    anchor: "b1-core-is-pure",
+    title: "Core is pure",
+    fix: "Move the input/output into adapters/ and pass the data into the core. If the core needs data partway through a decision, run `module-spec new-port`. A third-party package that touches nothing outside goes under pure in module-spec.json.",
+  },
+  B2: {
+    doc: "backend.md",
+    anchor: "b2-shell-is-thin",
+    title: "Shell is thin",
+    fix: "Move the decisions into core/ as a pure function. If the core needs data partway through a decision, run `module-spec new-port`.",
+  },
+  B3: {
+    doc: "backend.md",
+    anchor: "b3-only-adapters-touch-the-outside",
+    title: "Only adapters touch the outside",
+    fix: "Move the code that touches the database, network, files or framework into adapters/. A third-party package that touches nothing outside goes under pure in module-spec.json.",
+  },
+  F1: {
+    doc: "frontend.md",
+    anchor: "f1-only-view-knows-the-ui-framework",
+    title: "Only view/ knows the UI framework",
+    fix: "Move the code that draws into view/. Keep core/ and shell/ plain code, so a new framework or a mobile app rewrites only view/.",
+  },
+  F2: {
+    doc: "frontend.md",
+    anchor: "f2-a-view-only-renders",
+    title: "A view only renders",
+    fix: "Give the view its state and a send function as props, from a model the shell builds. Move loading, saving and fetching into the shell and its adapters. A package that draws goes under ui in module-spec.json, one that touches nothing outside under pure.",
+  },
+  F3: {
+    doc: "frontend.md",
+    anchor: "f3-a-view-holds-no-rules",
+    title: "A view holds no rules",
+    fix: "Move the decision into core/ as a pure function, such as a selector the view calls, and test it through the door.",
+  },
+  W1: {
+    doc: "workflow.md",
+    anchor: "w1-one-module-per-chat",
+    title: "A branch changes one module",
+    fix: "Split the branch: land one module's change, then the next, each against a door that already works (W2). An app only wires, so it may change beside one other module.",
+  },
+  T1: {
+    doc: "tests.md",
+    anchor: "t1-tests-reach-a-module-only-through-its-door",
+    title: "Tests reach a module only through its door",
+    fix: "Test through the module's door, with fakes passed in. Only a port's contract test may import its ports/ and adapters/.",
+  },
+  T2: {
+    doc: "tests.md",
+    anchor: "t2-tests-pass-fakes-in-never-patch",
+    title: "Tests pass fakes in, never patch",
+    fix: "Pass a fake in through createX(deps). If there is no way to pass it in, the module needs a port: run `module-spec new-port`.",
+  },
+  T3: {
+    doc: "tests.md",
+    anchor: "t3-every-port-has-one-contract-test",
+    title: "Every port has one contract test",
+    fix: "Add the contract test the message names: one suite that runs against the fake and the real adapter. `module-spec new-port` writes it.",
+  },
+};
+
+export function specLink(id) {
+  const rule = RULES[id];
+  return `${path.join(SPEC_DIR, rule.doc)}#${rule.anchor}`;
+}

package/lib/scaffold.js

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { runChecks } from "./check.js";
+import { writeApiReports } from "./checks/api.js";
+import { CONFIG_FILE, defaultConfig, listPackages } from "./config.js";
+import { LANGUAGES, languageNamed, languageOfDir } from "./languages/index.js";
+import { MANIFEST_FILE } from "./modules.js";
+import { writeNew } from "./templating.js";
+
+const words = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean);
+const pascal = (name) => words(name).map((word) => word[0].toUpperCase() + word.slice(1)).join("");
+const camel = (name) => pascal(name).replace(/^./, (first) => first.toLowerCase());
+const snake = (name) => words(name).map((word) => word.toLowerCase()).join("_");
+
+/** The language asked for, else the one the project's files show. Never a guess. */
+function languageFor(root, requested) {
+  if (requested) return languageNamed(requested);
+  const found = LANGUAGES.find((language) => language.detect(root));
+  if (!found) throw new Error(`cannot tell this project's language: pass --lang ${LANGUAGES.flatMap((language) => language.aliases).join("|")}`);
+  return found;
+}
+
+/** Writes the api-report.txt of the module at dir, so what a scaffold wrote passes C4 with no extra step. */
+async function reportOn(root, dir, written) {
+  const { modules, api } = await runChecks(root);
+  const at = path.relative(root, path.resolve(root, dir)).split(path.sep).join("/");
+  return [...written, ...writeApiReports(root, modules.filter((module) => module.dir === at), api)];
+}
+
+/** Writes a module: the manifest here, since it is the same in every language, and the code from the language's templates. */
+export async function newModule(root, { dir, role, owns, lang, view = false }) {
+  if (!dir || !role || !owns) throw new Error('usage: module-spec new-module <dir> --role app|feature|shared --owns "the decision it owns" [--view]');
+  if (fs.existsSync(path.join(root, dir, MANIFEST_FILE))) throw new Error(`${dir} already has a ${MANIFEST_FILE}`);
+  const language = languageFor(root, lang);
+  const write = view ? language.newViewModule : language.newModule;
+  if (!write) throw new Error(`${language.name} has no view template yet: write view/ by hand, as spec/frontend.md shows`);
+  const name = path.basename(dir);
+  const written = write(root, dir, { role, owns, name, Name: pascal(name), snake: snake(name) });
+  writeNew(root, path.join(dir, MANIFEST_FILE), YAML.stringify({ role, owns }), written);
+  if (view && listPackages(root, "ui", language.name, language.viewUi)) written.push(CONFIG_FILE);
+  return reportOn(root, dir, written);
+}
+
+export async function newPort(root, { dir, port }) {
+  if (!dir || !port) throw new Error("usage: module-spec new-port <module dir> <PortName>");
+  if (!fs.existsSync(path.join(root, dir, MANIFEST_FILE))) throw new Error(`${dir} has no ${MANIFEST_FILE}: run module-spec new-module first`);
+  const language = languageOfDir(path.join(root, dir));
+  if (!language) throw new Error(`${dir} has no door, so its language is unknown`);
+  return reportOn(root, dir, language.newPort(root, dir, { Port: pascal(port), portCamel: camel(port), portSnake: snake(port) }));
+}
+
+export function initProject(root) {
+  const written = [];
+  writeNew(root, CONFIG_FILE, `${JSON.stringify(defaultConfig(), null, 2)}\n`, written);
+  return written;
+}

package/lib/scans.js

@@ -0,0 +1,62 @@
+import { moduleLookup, PURE_PARTS, placeOf } from "./place.js";
+
+/** The detail of a wait in a core, the same in every language so a baseline entry survives a port to another. */
+const WAITS = "async code: a core with no ports never waits";
+
+/** The parts whose functions have a complexity cap, with the rule each breaks over it. */
+const CAPPED_PARTS = { shell: "B2", view: "F3" };
+
+/** The rule a sighting breaks, from the scan that saw it and the part its file sits in. */
+const RULE_OF = {
+  wait: () => "B1",
+  io: (part) => PURE_PARTS[part],
+  complexity: (part) => CAPPED_PARTS[part],
+  env: () => "C8",
+  ui: () => "F1",
+  patch: () => "T2",
+};
+
+/**
+ * Which files each scan searches. The kit decides it here, once, so a language only runs its own tools
+ * over these lists and reports what it saw. A language skips a scan its tools have nothing for.
+ *
+ * @typedef {object} ScanPlan
+ * @property {string[]} wait         search for waiting (async, await): the core of a module with no ports/
+ * @property {string[]} io           search for input/output globals (fetch, open): every core/ and view/
+ * @property {string[]} complexity   search for functions over maxComplexity: every shell/ and view/
+ * @property {number} maxComplexity
+ * @property {string[]} env          search for environment reads: every module but an app
+ * @property {string[]} ui           search for UI syntax (JSX): outside view/, in every module but an app
+ * @property {string[]} patch        search for patching: every test
+ *
+ * @typedef {object} Sighting   what one scan saw: { scan: a ScanPlan key, file, line, detail }
+ */
+export function scanPlan(modules, config) {
+  const plan = { wait: [], io: [], complexity: [], maxComplexity: config.maxComplexity, env: [], ui: [], patch: [] };
+  for (const module of modules) {
+    for (const file of module.files) {
+      const { part, test } = placeOf(module, file);
+      if (test) {
+        plan.patch.push(file);
+        continue;
+      }
+      if (part === "core" && !module.parts.has("ports")) plan.wait.push(file);
+      if (part in PURE_PARTS) plan.io.push(file);
+      if (part in CAPPED_PARTS) plan.complexity.push(file);
+      if (module.role !== "app") plan.env.push(file);
+      if (module.role !== "app" && part !== "view") plan.ui.push(file);
+    }
+  }
+  return plan;
+}
+
+/** Each sighting as a violation of the rule it breaks. */
+export function findingsOf(sightings, modules) {
+  const moduleOf = moduleLookup(modules);
+  return sightings.map(({ scan, file, line, detail }) => ({
+    id: RULE_OF[scan](placeOf(moduleOf(file), file).part),
+    file,
+    line: line ?? null,
+    detail: scan === "wait" ? WAITS : detail,
+  }));
+}

package/lib/templating.js

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import { toPosix, walkFiles } from "./files.js";
+
+/** `text` with each {{key}} replaced by values[key]. A key with no value is an error, never a blank. */
+export function fill(text, values) {
+  return text.replace(/\{\{(\w+)\}\}/g, (placeholder, key) => {
+    if (!(key in values)) throw new Error(`template placeholder ${placeholder} has no value`);
+    return values[key];
+  });
+}
+
+/** Writes `file` under root unless it exists, and records it in `written`. Never overwrites. */
+export function writeNew(root, file, text, written) {
+  const target = path.join(root, file);
+  if (fs.existsSync(target)) return;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, text);
+  written.push(toPosix(file));
+}
+
+/** Copies every file in templateDir into targetDir, filling placeholders in names and text. */
+export function copyTemplates(root, templateDir, targetDir, values, written) {
+  for (const file of walkFiles(templateDir)) {
+    const text = fs.readFileSync(path.join(templateDir, file), "utf8");
+    writeNew(root, path.join(targetDir, fill(file, values)), fill(text, values), written);
+  }
+}

package/lib/tools.js

@@ -0,0 +1,17 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KIT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * The folder of one of this kit's own dependencies. The kit pins its TypeScript tools rather than borrowing
+ * the project's: a project on TypeScript 7 has no compiler API, and one pinned set behaves the same everywhere.
+ */
+export function kitPackageDir(name) {
+  for (let dir = KIT_ROOT; ; dir = path.dirname(dir)) {
+    const candidate = path.join(dir, "node_modules", name);
+    if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
+    if (dir === path.dirname(dir)) throw new Error(`module-spec cannot find its dependency ${name}: reinstall module-spec`);
+  }
+}

package/manifest.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "module-spec/manifest.schema.json",
+  "title": "module.yaml",
+  "description": "The manifest every module carries. See spec/common.md#c1-every-module-has-a-manifest.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["role", "owns"],
+  "properties": {
+    "role": {
+      "enum": ["app", "feature", "shared"],
+      "description": "Which modules this one may import. See spec/roles.md."
+    },
+    "owns": {
+      "type": "string",
+      "description": "The one decision only this module makes, in one line. Names a decision, not an activity. See spec/common.md#c2-owns-names-a-decision-not-an-activity.",
+      "pattern": "^[^\\n]+$",
+      "not": {
+        "pattern": "\\b([Hh]andles?|[Mm]anages?|[Uu]tils?|[Hh]elpers?|[Mm]isc|TODO)\\b"
+      }
+    },
+    "depends_on": {
+      "type": "array",
+      "description": "The modules this module may import. Leave it out when the module has a package.json: its dependencies say the same. See spec/common.md#c5-dependencies-are-declared.",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "owns_tables": {
+      "type": "array",
+      "description": "Tables only this module writes. Leave it out where there is no SQL. See spec/common.md#c10-only-the-owner-writes-its-tables.",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  }
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "module-spec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "How every project splits its code into modules, with the checks that enforce it. The why behind each rule: spec/.",
+  "type": "module",
+  "packageManager": "pnpm@12.10.1",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "module-spec": "bin/module-spec.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "spec",
+    "manifest.schema.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@stryker-mutator/core": "^10.1.1",
+    "@stryker-mutator/vitest-runner": "^10.1.1",
+    "@typescript-eslint/parser": "^8.71.1",
+    "ajv": "^8.20.0",
+    "dependency-cruiser": "^18.7.0",
+    "eslint": "^10.12.0",
+    "jscpd": "^4.3.0",
+    "typescript": "~6.0.3",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "vitest": "^5.0.5"
+  }
+}

package/spec/adopting.md

@@ -0,0 +1,70 @@
+# Bringing existing code under the spec
+
+Existing code adopts the spec door first. Code that is not a module yet starts
+at the first step. A module that does not follow the spec starts at the door.
+
+```mermaid
+---
+config:
+  look: handDrawn
+---
+flowchart LR
+  find["🔍 find the cluster<br/>co-change, name owns"]:::loose --> door["🚪 add the door<br/>re-export what callers use"]:::step
+  door --> callers["➡️ point callers<br/>at the door"]:::step
+  callers --> gate["🚦 turn on checks<br/>baseline today's violations"]:::gate
+  gate --> pin["🧪 characterization tests<br/>through the door"]:::step
+  pin --> inside["🧠 refactor inside<br/>core / shell, one ticket each"]:::step
+  inside -- "baseline shrinks" --> inside
+  mod["📦 existing module<br/>starts here"]:::start -.-> door
+  classDef loose fill:#5c3d0e,stroke:#f59e0b,color:#fef3c7
+  classDef step fill:#1b4332,stroke:#52b788,color:#d8f3dc
+  classDef gate fill:#1e3a5f,stroke:#60a5fa,color:#dbeafe
+  classDef start fill:#2d2d2d,stroke:#9ca3af,color:#e5e7eb
+```
+
+## Find the cluster
+
+Files that change in the same commits belong together (change coupling, Adam
+Tornhill, *Your Code as a Crime Scene*, 2015). Name the decision they share.
+That line becomes `owns`. `module-spec report` lists the modules that change
+together most, and the share of commits that stay in one module.
+
+## Add the door
+
+`module-spec new-module <dir> --role <role> --owns "<decision>"` writes the
+manifest, the door, a `createX(deps)` shell and a test through the door. For
+existing code, write `module.yaml` by hand and turn the file callers import
+into the door.
+
+## Why the door comes first
+
+Once every caller uses the door, the inside can be rebuilt without touching
+them. Every later step depends on that.
+
+## The baseline
+
+`module-spec.baseline.json` lists every violation that exists on the day the
+checks turn on, and the count of cross-module clones. It is committed.
+
+```sh
+module-spec baseline --accept-new   # once, the day the checks turn on
+module-spec check                   # in CI and before every push
+module-spec baseline                # after a fix, to drop its line
+```
+
+`check` fails on a violation that is not in the baseline, and on a baseline
+line that no longer happens, so a fix also deletes its line and the file only
+shrinks. A branch that changes a module also clears every one of that
+module's lines: `check` fails on any violation in it, baselined or not. So the
+baseline empties module by module, as work reaches each one. The one
+exception is the branch that first adds `module.yaml` files: every module is
+new there, so that branch skips the branch rules and its baseline holds.
+`baseline` refuses to add a new violation unless you pass
+`--accept-new`, so growing the baseline is a choice that shows in the diff.
+An entry has no line number, so moving code does not churn the file.
+
+## Characterization tests
+
+Before an agent refactors the inside, tests pin what the code does today, good
+or bad (Michael Feathers, *Working Effectively with Legacy Code*, 2004). A
+refactor that changes behaviour then fails a test instead of shipping.