module-spec 0.0.0-stage → 0.2.0

package/lib/checks/clones.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { toPosix } from "../files.js";
+import { moduleLookup, placeOf } from "../place.js";
+
+const require = createRequire(import.meta.url);
+
+/** C11: clones whose two copies sit in different modules, found by jscpd over every module's source, tests left out. */
+export async function findCrossModuleClones(root, modules, config) {
+  if (modules.length < 2) return [];
+  const counted = modules.flatMap((module) => module.files.filter((file) => !placeOf(module, file).test));
+  if (counted.length === 0) return [];
+  const { detectClones } = require("jscpd");
+  const clones = await detectClones({
+    path: counted.map((file) => path.join(root, file)),
+    minLines: config.clones.minLines,
+    silent: true,
+    reporters: [],
+  });
+  const moduleOf = moduleLookup(modules);
+  const where = (duplication) => toPosix(path.relative(root, duplication.sourceId));
+  return clones
+    .map((clone) => ({
+      a: { file: where(clone.duplicationA), line: clone.duplicationA.start.line },
+      b: { file: where(clone.duplicationB), line: clone.duplicationB.start.line },
+      lines: clone.duplicationA.end.line - clone.duplicationA.start.line + 1,
+    }))
+    .filter((clone) => {
+      const first = moduleOf(clone.a.file);
+      const second = moduleOf(clone.b.file);
+      return first && second && first !== second;
+    });
+}

package/lib/checks/imports.js

@@ -0,0 +1,101 @@
+import { CONFIG_FILE } from "../config.js";
+import { moduleLookup, PURE_PARTS, placeOf } from "../place.js";
+import { roleRuleBroken } from "./manifests.js";
+
+/** Whether `name` is on `list`, where an entry ending in "/" matches a whole scope. */
+function matches(list, name) {
+  return list.some((entry) => (entry.endsWith("/") ? name.startsWith(entry) : name === entry));
+}
+
+/**
+ * "ui", "io", "pure" or "unlisted". The standard library is a fixed set, so each language names the part of
+ * it that touches the outside or draws. Third-party packages are an open set, so the project lists the ones
+ * it trusts, and any other counts as input/output: a new driver nobody listed still fails.
+ */
+function kindOf(edge, language, config) {
+  if (edge.std) {
+    if (matches(language.stdlib.ui, edge.external)) return "ui";
+    return matches(language.stdlib.io, edge.external) ? "io" : "pure";
+  }
+  if (matches(config.ui[language.name] ?? [], edge.external)) return "ui";
+  return matches(config.pure[language.name] ?? [], edge.external) ? "pure" : "unlisted";
+}
+
+function checkExternal(edge, source, place, config) {
+  if (!source || place.test || source.role === "app") return null;
+  const kind = kindOf(edge, source.language, config);
+  if (kind === "ui") return place.part === "view" ? null : { id: "F1", detail: `imports ${edge.external}` };
+  if (kind === "pure" || place.part === "adapters") return null;
+  const lists = place.part === "view" ? "pure or ui" : "pure";
+  const why = kind === "unlisted" ? `, which ${CONFIG_FILE} does not list under ${lists}` : "";
+  return { id: PURE_PARTS[place.part] ?? "B3", detail: `imports ${edge.external}${why}` };
+}
+
+/** What each pure part may not import from its own module. */
+const BEHIND_PURE_PART = { core: ["shell", "adapters"], view: ["shell", "ports", "adapters"] };
+
+function checkInside(module, place, targetPlace) {
+  if (place.test) {
+    const allowed = targetPlace.door || targetPlace.test || (place.contractTest && ["ports", "adapters"].includes(targetPlace.part));
+    return allowed ? null : { id: "T1", detail: `imports ${targetPlace.inner}, behind ${module.name}'s door` };
+  }
+  if (BEHIND_PURE_PART[place.part]?.includes(targetPlace.part)) {
+    return { id: PURE_PARTS[place.part], detail: `imports ${targetPlace.inner}` };
+  }
+  return null;
+}
+
+function checkAcross(edge, source, place, target, targetPlace) {
+  const found = [];
+  if (!targetPlace.door) found.push({ id: "C3", detail: `imports ${edge.to}, behind ${target.name}'s door` });
+  if (!source) return found;
+  const roleRule = roleRuleBroken(source, target);
+  if (roleRule) found.push({ id: roleRule, detail: `imports ${target.name}, a ${target.role} module` });
+  else if (!source.dependsOn.includes(target.name)) {
+    found.push({ id: "C5", detail: `imports ${target.name}, which ${source.name} does not declare` });
+  }
+  // An import erased before the code runs names the module's types but loads none of its adapters.
+  if (PURE_PARTS[place.part] && !place.test && !edge.typeOnly && target.parts.has("adapters")) {
+    found.push({ id: PURE_PARTS[place.part], detail: `imports ${target.name}, which carries its adapters` });
+  }
+  return found;
+}
+
+/**
+ * C3, C5, R1–R3, B1, B3, F1, F2 and T1 over the import edges the language tools read.
+ * An edge is { from, line, to, typeOnly } for a project file, or { from, line, external, std } for a package.
+ */
+export function checkImports({ modules, edges, config, analyzedLanguages }) {
+  const moduleOf = moduleLookup(modules);
+  const used = new Map(modules.map((module) => [module.name, new Set()]));
+  const problems = [];
+  for (const edge of edges) {
+    const source = moduleOf(edge.from);
+    const place = source ? placeOf(source, edge.from) : null;
+    const at = (found) => ({ ...found, file: edge.from, line: edge.line ?? null });
+    if (edge.external) {
+      const found = checkExternal(edge, source, place, config);
+      if (found) problems.push(at(found));
+      continue;
+    }
+    const target = moduleOf(edge.to);
+    if (!target) {
+      if (source && !place.test) problems.push(at({ id: "C5", detail: `imports ${edge.to}, which belongs to no module` }));
+      continue;
+    }
+    const targetPlace = placeOf(target, edge.to);
+    if (source === target) {
+      const found = checkInside(source, place, targetPlace);
+      if (found) problems.push(at(found));
+      continue;
+    }
+    if (source) used.get(source.name).add(target.name);
+    problems.push(...checkAcross(edge, source, place, target, targetPlace).map(at));
+  }
+  for (const module of modules.filter((candidate) => analyzedLanguages.has(candidate.language))) {
+    for (const name of module.dependsOn.filter((declared) => !used.get(module.name).has(declared))) {
+      problems.push({ id: "C5", file: module.depsFile, line: null, detail: `declares ${name}, which nothing in ${module.name} imports` });
+    }
+  }
+  return problems;
+}

package/lib/checks/manifests.js

@@ -0,0 +1,52 @@
+const MAY_IMPORT = { app: ["feature", "shared"], feature: ["shared"], shared: ["shared"] };
+const ROLE_RULE = { app: "R3", feature: "R1", shared: "R2" };
+
+/** The role rule `from` breaks by depending on `to`, or null. */
+export function roleRuleBroken(from, to) {
+  return MAY_IMPORT[from.role].includes(to.role) ? null : ROLE_RULE[from.role];
+}
+
+function declaredCycles(modules, byName) {
+  const cycles = [];
+  const state = new Map();
+  const stack = [];
+  const visit = (module) => {
+    state.set(module.name, "open");
+    stack.push(module.name);
+    for (const name of module.dependsOn) {
+      if (state.get(name) === "open") cycles.push([...stack.slice(stack.indexOf(name)), name]);
+      else if (!state.has(name)) visit(byName.get(name));
+    }
+    stack.pop();
+    state.set(module.name, "done");
+  };
+  for (const module of modules) if (!state.has(module.name)) visit(module);
+  return cycles;
+}
+
+/** R1–R3, C6 and C10 on what the manifests declare, before any import is read. */
+export function checkManifests(modules) {
+  const byName = new Map(modules.map((module) => [module.name, module]));
+  const problems = [];
+  for (const module of modules) {
+    for (const name of module.dependsOn) {
+      const rule = roleRuleBroken(module, byName.get(name));
+      if (rule) problems.push({ id: rule, file: module.depsFile, detail: `declares ${name}, a ${byName.get(name).role} module` });
+    }
+  }
+  for (const cycle of declaredCycles(modules, byName)) {
+    problems.push({ id: "C6", file: byName.get(cycle[0]).depsFile, detail: `declares a cycle: ${cycle.join(" -> ")}` });
+  }
+  const owners = new Map();
+  for (const module of modules) {
+    for (const table of module.ownsTables) owners.set(table, [...(owners.get(table) ?? []), module]);
+  }
+  for (const [table, tableOwners] of owners) {
+    if (tableOwners.length < 2) continue;
+    for (const owner of tableOwners) {
+      const others = tableOwners.filter((other) => other !== owner).map((other) => other.name);
+      problems.push({ id: "C10", file: owner.manifestPath, detail: `owns table ${table}, which ${others.join(", ")} also owns` });
+    }
+  }
+  return problems;
+}

package/lib/checks/ports.js

@@ -0,0 +1,32 @@
+import path from "node:path";
+import { placeOf } from "../place.js";
+
+/** T3: every port in ports/ has a contract test, and that test runs every adapter that implements the port. */
+export function checkPorts(modules, edges) {
+  const importsOf = new Map();
+  for (const edge of edges.filter((candidate) => candidate.to)) {
+    importsOf.set(edge.from, (importsOf.get(edge.from) ?? new Set()).add(edge.to));
+  }
+  const imports = (from, to) => importsOf.get(from)?.has(to) ?? false;
+  const problems = [];
+  for (const module of modules.filter((candidate) => candidate.parts.has("ports"))) {
+    const places = module.files.map((file) => ({ file, place: placeOf(module, file) }));
+    const adapters = places.filter(({ place }) => place.part === "adapters" && !place.test).map(({ file }) => file);
+    for (const { file, place } of places) {
+      if (place.part !== "ports" || place.test) continue;
+      const port = path.posix.basename(file);
+      const expected = module.language.contractTestFor(port);
+      if (!expected) continue;
+      const contractTest = places.find((candidate) => candidate.place.contractTest && path.posix.basename(candidate.file) === expected)?.file;
+      if (!contractTest) {
+        problems.push({ id: "T3", file, line: null, detail: `port ${port} has no contract test ${expected}` });
+        continue;
+      }
+      // An adapter implements a port by importing it. The contract test must then run that adapter too.
+      for (const adapter of adapters.filter((candidate) => imports(candidate, file) && !imports(contractTest, candidate))) {
+        problems.push({ id: "T3", file: adapter, line: null, detail: `implements ${port}, but ${expected} never runs it` });
+      }
+    }
+  }
+  return problems;
+}

package/lib/checks/tables.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { placeOf } from "../place.js";
+
+/**
+ * Upper-case SQL that writes a table. Upper case only, so an `update()` call or the word in prose never
+ * matches. An upsert's `DO UPDATE SET` and `ON DUPLICATE KEY UPDATE` name columns, not tables.
+ */
+const SQL_WRITE =
+  /\b(?:INSERT\s+(?:OR\s+[A-Z]+\s+)?INTO|(?<!KEY\s)(?<!DO\s)UPDATE|DELETE\s+FROM|REPLACE\s+INTO|MERGE\s+INTO)\s+(?!SET\b)[`"[]?([A-Za-z_][\w.]*)/g;
+
+function lineAt(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+
+/** C10: every table a module writes is one it owns. */
+export function checkTables(root, modules) {
+  const ownerOf = new Map(modules.flatMap((module) => module.ownsTables.map((table) => [table, module])));
+  const problems = [];
+  for (const module of modules) {
+    for (const file of module.files.filter((candidate) => !placeOf(module, candidate).test)) {
+      const text = fs.readFileSync(path.join(root, file), "utf8");
+      for (const match of text.matchAll(SQL_WRITE)) {
+        const table = match[1].split(".").at(-1);
+        const owner = ownerOf.get(table);
+        if (owner === module) continue;
+        problems.push({
+          id: "C10",
+          file,
+          line: lineAt(text, match.index),
+          detail: owner ? `writes table ${table}, which ${owner.name} owns` : `writes table ${table}, which no module owns`,
+        });
+      }
+    }
+  }
+  return problems;
+}

package/lib/config.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+import { LANGUAGES } from "./languages/index.js";
+
+export const CONFIG_FILE = "module-spec.json";
+
+const DEFAULTS = {
+  roots: ["."],
+  maxComplexity: 5,
+  pure: Object.fromEntries(LANGUAGES.map((language) => [language.name, []])),
+  ui: Object.fromEntries(LANGUAGES.map((language) => [language.name, []])),
+  clones: { minLines: 6 },
+  ...Object.fromEntries(
+    LANGUAGES.filter((language) => Object.keys(language.configDefaults).length > 0).map((language) => [language.name, language.configDefaults]),
+  ),
+};
+
+/** Keys whose value merges key by key with the default, instead of replacing it. */
+const MERGED = ["pure", "ui", "clones", ...LANGUAGES.map((language) => language.name)];
+
+/** Keys a release retired, so an old module-spec.json fails loudly instead of being ignored. */
+const RETIRED = {
+  shellComplexity: "shellComplexity is now maxComplexity, and it caps view/ functions too. Rename the key.",
+  impure: "impure is gone. Every package not listed under pure counts as input/output, so delete the key.",
+};
+
+function ownConfig(root) {
+  const file = path.join(root, CONFIG_FILE);
+  return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
+}
+
+/** The project's module-spec.json merged over the defaults. Every key is optional. */
+export function loadConfig(root) {
+  const own = ownConfig(root);
+  for (const [key, message] of Object.entries(RETIRED)) {
+    if (key in own) throw new Error(`${CONFIG_FILE}: ${message}`);
+  }
+  const merged = { ...DEFAULTS, ...own };
+  for (const key of MERGED) merged[key] = { ...DEFAULTS[key], ...own[key] };
+  return merged;
+}
+
+/** Adds `names` to the project's `key` list for `language` ("pure" or "ui"), creating the file when needed. Returns whether it wrote. */
+export function listPackages(root, key, language, names) {
+  const own = ownConfig(root);
+  const listed = own[key]?.[language] ?? [];
+  const missing = names.filter((name) => !listed.includes(name));
+  if (missing.length === 0) return false;
+  own[key] = { ...own[key], [language]: [...listed, ...missing] };
+  fs.writeFileSync(path.join(root, CONFIG_FILE), `${JSON.stringify(own, null, 2)}\n`);
+  return true;
+}
+
+export function defaultConfig() {
+  return structuredClone(DEFAULTS);
+}

package/lib/files.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const NEVER_WALKED = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  "vendor",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".mypy_cache",
+  ".ruff_cache",
+  ".pytest_cache",
+]);
+
+export function toPosix(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+/** Every file under `dir`, as a posix path relative to `root`, skipping dependency and build folders. */
+export function walkFiles(root, dir = ".") {
+  const found = [];
+  const visit = (relativeDir) => {
+    for (const entry of fs.readdirSync(path.join(root, relativeDir), { withFileTypes: true })) {
+      const relativePath = relativeDir === "." ? entry.name : `${relativeDir}/${entry.name}`;
+      if (entry.isDirectory()) {
+        if (!NEVER_WALKED.has(entry.name)) visit(relativePath);
+      } else if (entry.isFile()) {
+        found.push(relativePath);
+      }
+    }
+  };
+  visit(toPosix(dir));
+  return found;
+}
+
+export function readIfExists(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
+}
+
+/**
+ * A throwaway copy of the project, for a tool that writes beside the code it reads. Only the files `keep`
+ * accepts are copied, and dependency and build folders never are. The caller removes it.
+ */
+export function scratchCopy(root, keep = () => true) {
+  const copy = fs.mkdtempSync(path.join(os.tmpdir(), "module-spec-scratch-"));
+  for (const file of walkFiles(root).filter(keep)) {
+    fs.mkdirSync(path.dirname(path.join(copy, file)), { recursive: true });
+    fs.copyFileSync(path.join(root, file), path.join(copy, file));
+  }
+  return copy;
+}

package/lib/languages/go/go.mod

@@ -0,0 +1,5 @@
+// The kit's own Go files: the reader and the templates. Being their own module keeps them out of
+// a Go project's ./... when the kit is installed in its node_modules.
+module module-spec/go
+
+go 1.22

package/lib/languages/go/index.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { mutate } from "./mutate.js";
+import { analyze } from "./read.js";
+import { newModule, newPort } from "./scaffold.js";
+
+const isGo = (name) => name.endsWith(".go");
+const isGoTest = (name) => name.endsWith("_test.go");
+
+/**
+ * Go's door is the package at the module root, and its parts sit under internal/, so the compiler
+ * refuses a deep import as well as the kit. Tests sit at the module root in the external _test package.
+ *
+ * @type {import("../index.js").Language}
+ */
+export default {
+  name: "go",
+  aliases: ["go"],
+  door: "a .go file at the module root",
+  isDoor: (inner) => !inner.includes("/") && isGo(inner) && !isGoTest(inner),
+  partsDir: "internal",
+  isSource: isGo,
+  isTest: (segments) => isGoTest(segments.at(-1)),
+  isContractTest: (name) => name.endsWith("_contract_test.go"),
+  contractTestFor: (file) => (file === "doc.go" ? null : `${file.replace(/\.go$/, "")}_contract_test.go`),
+  stdlib: {
+    io: ["os", "os/", "net", "net/", "syscall", "database/sql", "io/ioutil", "log/syslog", "plugin"],
+    ui: [],
+  },
+  viewUi: [],
+  configDefaults: {},
+  detect: (root) => fs.existsSync(path.join(root, "go.mod")),
+  analyze,
+  mutate,
+  newModule,
+  newPort,
+};

package/lib/languages/go/mutate.js

@@ -0,0 +1,56 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { scratchCopy } from "../../files.js";
+
+/** Gremlins, pinned, run through `go run` so the go toolchain is the only install. */
+const GREMLINS = "github.com/go-gremlins/gremlins/cmd/gremlins@v0.6.0";
+const OUTPUT_LIMIT = 512 * 1024 * 1024;
+/** Gremlins' statuses: a timeout counts as caught, and a mutant no test reaches counts as live. */
+const CAUGHT = new Set(["KILLED", "TIMED OUT"]);
+const LIVE = new Set(["LIVED", "NOT COVERED"]);
+
+const escaped = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Mutation testing by gremlins, in a scratch copy that keeps only this module's tests. Gremlins runs
+ * `go test ./...` for each mutant (its integration mode), because a module's tests sit at its door, not
+ * beside the internal package a mutant changes. With other tests gone, only this module's tests judge it.
+ */
+export async function mutate({ root, module, files, tests }) {
+  const own = new Set(tests);
+  const copy = scratchCopy(root, (file) => !file.endsWith("_test.go") || own.has(file));
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "module-spec-gremlins-"));
+  try {
+    const targets = new Set(files);
+    const excluded = module.files.filter((file) => !targets.has(file) && !own.has(file));
+    const report = path.join(work, "report.json");
+    const run = spawnSync(
+      "go",
+      [
+        "run", GREMLINS, "unleash", "--integration", "--invert-logical", "--silent",
+        "--coverpkg", `./${module.dir}/...`, "--output", report,
+        ...excluded.flatMap((file) => ["--exclude-files", `(^|/)${escaped(file.slice(module.dir.length + 1))}$`]),
+        `./${module.dir}`,
+      ],
+      { cwd: copy, encoding: "utf8", maxBuffer: OUTPUT_LIMIT },
+    );
+    if (run.error || run.status !== 0 || !fs.existsSync(report)) {
+      throw new Error(`gremlins failed; Go modules need the go toolchain on the PATH:\n${run.stderr || run.stdout || run.error}`);
+    }
+    const mutations = JSON.parse(fs.readFileSync(report, "utf8")).files.flatMap((file) =>
+      file.mutations.map((mutation) => ({ ...mutation, file: `${module.dir}/${file.file_name}` })),
+    );
+    const sourceLine = (file, line) => fs.readFileSync(path.join(root, file), "utf8").split("\n")[line - 1].trim();
+    return {
+      killed: mutations.filter((mutation) => CAUGHT.has(mutation.status)).length,
+      survivors: mutations
+        .filter((mutation) => LIVE.has(mutation.status))
+        .map((mutation) => ({ file: mutation.file, line: mutation.line, detail: `${mutation.type}: ${sourceLine(mutation.file, mutation.line)}` })),
+    };
+  } finally {
+    fs.rmSync(copy, { recursive: true, force: true });
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}

package/lib/languages/go/read.js

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const READ_PROJECT = path.join(path.dirname(fileURLToPath(import.meta.url)), "read_project.go");
+const OUTPUT_LIMIT = 512 * 1024 * 1024;
+
+/** Libraries that patch functions or variables in place: Go's form of a mock that patches (T2). */
+const PATCHERS = ["github.com/agiledragon/gomonkey", "github.com/agiledragon/gomonkey/", "bou.ke/monkey", "github.com/undefinedlabs/go-mpatch", "github.com/prashantv/gostub"];
+const patches = (name) => PATCHERS.some((entry) => (entry.endsWith("/") ? name.startsWith(entry) : name === entry));
+
+/** @type {import("../index.js").Language["analyze"]} */
+export async function analyze({ modules, root, plan }) {
+  const request = {
+    projectRoot: root,
+    files: modules.flatMap((module) => module.files),
+    testFiles: plan.patch,
+    doorDirs: modules.map((module) => module.dir),
+    plan,
+  };
+  // Run outside the project, so its go.mod and toolchain line never apply to the kit's own reader.
+  const run = spawnSync("go", ["run", READ_PROJECT], {
+    cwd: os.tmpdir(),
+    input: JSON.stringify(request),
+    encoding: "utf8",
+    maxBuffer: OUTPUT_LIMIT,
+  });
+  if (run.error || run.status !== 0) throw new Error(`reading the Go modules failed; Go modules need the go toolchain on the PATH:\n${run.stderr ?? run.error}`);
+  const read = JSON.parse(run.stdout);
+  const tests = new Set(plan.patch);
+  const sightings = [
+    ...read.sightings,
+    ...read.edges
+      .filter((edge) => edge.external && tests.has(edge.from) && patches(edge.external))
+      .map((edge) => ({ scan: "patch", file: edge.from, line: edge.line, detail: `patches with ${edge.external}` })),
+  ];
+  const api = new Map(modules.map((module) => [module.name, read.exports[module.dir] ?? []]));
+  return { edges: read.edges, sightings, findings: read.whiteBox.map((found) => ({ ...found, id: "T1" })), api };
+}