superdev-cli 0.1.0

package/scripts/validate/manifests.mjs

@@ -0,0 +1,173 @@
+// Plugin manifests and the hook table. These are the files a host reads before
+// any Superdev code runs, so a broken one fails at install time on someone
+// else's machine rather than here.
+//
+// Absolute paths are the recurring defect: a manifest written on the author's
+// machine points nowhere once installed, and it leaks a home directory.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { ERROR, WARNING, finding, isKebab, readJson, rel } from "./common.mjs";
+
+export const name = "manifests";
+
+const ABSOLUTE_HOME = /(?:\/(?:Users|home)\/[A-Za-z0-9._-]+|[A-Z]:\\Users\\[A-Za-z0-9._-]+)/;
+// A command may reference the plugin root, never a rooted filesystem path.
+const ROOTED_COMMAND = /(?:^|\s)"?\/(?!\/)[A-Za-z0-9._-]+\//;
+
+const CLAUDE_REQUIRED = ["name", "version", "description"];
+const CODEX_INTERFACE_REQUIRED = [
+  "displayName", "shortDescription", "longDescription", "developerName", "category",
+];
+
+function portability(path, text, findings) {
+  if (ABSOLUTE_HOME.test(text)) {
+    findings.push(finding("MF-010", ERROR, path,
+      "contains an absolute home path, which points nowhere once the plugin is installed elsewhere"));
+  }
+  if (text.includes("../")) {
+    findings.push(finding("MF-011", ERROR, path,
+      "contains a path escape (../), which resolves outside the plugin root"));
+  }
+}
+
+export async function run(root) {
+  const findings = [];
+
+  const claudeManifest = join(root, ".claude-plugin", "plugin.json");
+  if (!existsSync(claudeManifest)) {
+    findings.push(finding("MF-001", ERROR, ".claude-plugin/plugin.json",
+      "the Claude plugin manifest is missing; there is nothing to validate"));
+  } else {
+    const path = rel(root, claudeManifest);
+    const { value, error } = readJson(claudeManifest);
+    if (error) {
+      findings.push(finding("MF-002", ERROR, path, `manifest is not valid JSON: ${error}`));
+    } else {
+      for (const field of CLAUDE_REQUIRED) {
+        if (typeof value[field] !== "string" || !value[field].trim()) {
+          findings.push(finding("MF-003", ERROR, path, `required field "${field}" is missing or empty`));
+        }
+      }
+      if (!isKebab(value.name)) {
+        findings.push(finding("MF-004", ERROR, path,
+          `name "${value.name ?? ""}" is not kebab-case; a host derives directory and command names from it`));
+      }
+      portability(path, JSON.stringify(value), findings);
+    }
+  }
+
+  const marketplace = join(root, ".claude-plugin", "marketplace.json");
+  if (existsSync(marketplace)) {
+    const path = rel(root, marketplace);
+    const { value, error } = readJson(marketplace);
+    if (error) findings.push(finding("MF-002", ERROR, path, `marketplace manifest is not valid JSON: ${error}`));
+    else portability(path, JSON.stringify(value), findings);
+  }
+
+  const codexManifest = join(root, ".codex-plugin", "plugin.json");
+  if (!existsSync(codexManifest)) {
+    findings.push(finding("MF-005", ERROR, ".codex-plugin/plugin.json",
+      "the Codex plugin manifest is missing; Codex distribution is a supported surface"));
+  } else {
+    const path = rel(root, codexManifest);
+    const { value, error } = readJson(codexManifest);
+    if (error) {
+      findings.push(finding("MF-002", ERROR, path, `manifest is not valid JSON: ${error}`));
+    } else {
+      if (!value.author || typeof value.author !== "object" || typeof value.author.name !== "string" || !value.author.name.trim()) {
+        findings.push(finding("MF-006", ERROR, path, "author must be an object carrying a non-empty name"));
+      }
+      const iface = value.interface;
+      if (!iface || typeof iface !== "object") {
+        findings.push(finding("MF-007", ERROR, path, "interface object is missing"));
+      } else {
+        for (const field of CODEX_INTERFACE_REQUIRED) {
+          if (typeof iface[field] !== "string" || !iface[field].trim()) {
+            findings.push(finding("MF-007", ERROR, path, `interface.${field} must be a non-empty string`));
+          }
+        }
+        if (!("defaultPrompt" in iface) && !("default_prompt" in iface)) {
+          findings.push(finding("MF-007", ERROR, path, "interface.defaultPrompt is missing"));
+        }
+        if (!Array.isArray(iface.capabilities) || !iface.capabilities.every((c) => typeof c === "string" && c.trim())) {
+          findings.push(finding("MF-007", ERROR, path, "interface.capabilities must be an array of non-empty strings"));
+        }
+      }
+      portability(path, JSON.stringify(value), findings);
+    }
+  }
+
+  const hooksFile = join(root, "hooks", "hooks.json");
+  if (!existsSync(hooksFile)) {
+    findings.push(finding("MF-008", ERROR, "hooks/hooks.json",
+      "hooks.json is missing; the agent lifecycle hooks have no declaration"));
+  } else {
+    const path = rel(root, hooksFile);
+    const { value, error } = readJson(hooksFile);
+    if (error) {
+      findings.push(finding("MF-002", ERROR, path, `hooks.json is not valid JSON: ${error}`));
+    } else if (!value.hooks || typeof value.hooks !== "object") {
+      findings.push(finding("MF-009", ERROR, path, "hooks.json must carry a hooks object"));
+    } else {
+      for (const [event, groups] of Object.entries(value.hooks)) {
+        if (!Array.isArray(groups)) {
+          findings.push(finding("MF-009", ERROR, path, `hooks.${event} must be an array`));
+          continue;
+        }
+        for (const group of groups) {
+          for (const hook of group?.hooks ?? []) {
+            if (hook.type !== "command" || typeof hook.command !== "string" || !hook.command.trim()) {
+              findings.push(finding("MF-009", ERROR, path, `hooks.${event} carries a hook without a command`));
+              continue;
+            }
+            if (ROOTED_COMMAND.test(hook.command)) {
+              findings.push(finding("MF-010", ERROR, path,
+                `hooks.${event} runs an absolute path; use \${CLAUDE_PLUGIN_ROOT}`));
+            }
+            if (!hook.command.includes("${CLAUDE_PLUGIN_ROOT}")) {
+              findings.push(finding("MF-012", WARNING, path,
+                `hooks.${event} does not anchor its command to \${CLAUDE_PLUGIN_ROOT}, so it depends on the working directory`));
+            }
+          }
+        }
+      }
+      portability(path, JSON.stringify(value).replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ""), findings);
+    }
+  }
+
+  // Every manifest that carries a version must carry the SAME version. Three
+  // manifests sat at 0.1.1 while package.json said 0.2.0, and nothing noticed,
+  // because this validator only checked that a version field was present. A
+  // version that disagrees with itself across distribution surfaces means an
+  // install instruction is wrong for at least one of them.
+  const pkg = readJson(join(root, "package.json")).value;
+  if (pkg?.version) {
+    const declared = [
+      [".claude-plugin/plugin.json", readJson(join(root, ".claude-plugin", "plugin.json")).value?.version],
+      [".codex-plugin/plugin.json", readJson(join(root, ".codex-plugin", "plugin.json")).value?.version],
+      [".claude-plugin/marketplace.json metadata",
+        readJson(join(root, ".claude-plugin", "marketplace.json")).value?.metadata?.version],
+      ...(readJson(join(root, ".claude-plugin", "marketplace.json")).value?.plugins ?? [])
+        .map((plugin, i) => [`.claude-plugin/marketplace.json plugins[${i}]`, plugin?.version]),
+      // The CLI the plugin says it needs. The two ship separately now, so this
+      // is the one number that could sensibly lag, and it is also the one that
+      // would silently warn every user that their tools are mismatched if it
+      // were left behind a release. One version for both halves means this
+      // field moves with the rest.
+      [".claude-plugin/plugin.json requires.cli",
+        readJson(join(root, ".claude-plugin", "plugin.json")).value?.requires?.cli],
+      [".codex-plugin/plugin.json requires.cli",
+        readJson(join(root, ".codex-plugin", "plugin.json")).value?.requires?.cli],
+    ];
+    for (const [where, version] of declared) {
+      if (version === undefined || version === null) continue;
+      if (version !== pkg.version) {
+        findings.push(finding("MF-013", ERROR, where,
+          `declares version "${version}" while package.json declares "${pkg.version}"`));
+      }
+    }
+  }
+
+  return { name, findings };
+}

package/scripts/validate/markdown.mjs

@@ -0,0 +1,123 @@
+// Generated Markdown under talks/.
+//
+// Markdown here is a projection of accepted database content, never a second
+// writable source of truth. Three things make that claim checkable: the marker
+// says which record and revision produced the file, the hash says the body is
+// still the body that was generated, and a relative link that resolves says the
+// projection is internally consistent rather than merely well formed.
+//
+// A file whose hash no longer matches is not a defect in this validator: it is
+// a pending edit proposal, and it is reported so that it gets reviewed rather
+// than silently overwritten.
+
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { dirname, extname, join, resolve } from "node:path";
+import { ERROR, finding, isDirectory, readText, rel, walk } from "./common.mjs";
+
+export const name = "markdown";
+
+// <!-- superdev:generated source=FEAT-0007 revision=42 hash=<sha256-of-body> -->
+const MARKER = /^<!--\s*superdev:generated\s+source=(\S+)\s+revision=(\d+)\s+hash=([0-9a-f]{64})\s*-->\s*$/;
+
+const INLINE_LINK = /!?\[[^\]]*\]\(\s*<?([^)<>\s]+)(?:\s+"[^"]*")?\s*>?\s*\)/g;
+const REFERENCE_LINK = /^\s{0,3}\[[^\]]+\]:\s*<?([^\s<>]+)>?/gm;
+
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+
+/**
+ * The body the hash covers: everything after the marker line, LF line endings,
+ * no trailing whitespace on any line, exactly one terminal newline. Stated in
+ * the module contract, restated here because a renderer and a validator that
+ * disagree about normalization produce a permanent false proposal.
+ */
+export function normalizeBody(body) {
+  const normalized = String(body)
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map((line) => line.replace(/[ \t]+$/, ""))
+    .join("\n");
+  return normalized.replace(/\n+$/, "") + "\n";
+}
+
+export const bodyHash = (body) => createHash("sha256").update(normalizeBody(body)).digest("hex");
+
+/** Every relative link target in a document, deduplicated, anchors removed. */
+export function linkTargets(text) {
+  const targets = new Set();
+  for (const pattern of [INLINE_LINK, REFERENCE_LINK]) {
+    pattern.lastIndex = 0;
+    for (const match of text.matchAll(pattern)) {
+      const raw = match[1];
+      if (!raw || EXTERNAL.test(raw)) continue;
+      const target = raw.split("#")[0].split("?")[0];
+      if (target) targets.add(target);
+    }
+  }
+  return [...targets].sort();
+}
+
+export async function run(root) {
+  const findings = [];
+  const talks = join(root, "talks");
+
+  // A repository that has never been initialized as a Superdev project has no
+  // generated Markdown, and that is not a defect: there is no database, so
+  // nothing has been generated and nothing is missing. This is distinct from the
+  // absent-input case ADR-0019 requires a validator to fail on, which is when a
+  // project DOES exist and its documents are gone. Superdev's own repository is
+  // exactly this case: its documentation is docs/ and README, and it is not
+  // itself managed as a Superdev project.
+  const initialized = existsSync(join(root, ".superdev", "superdev.db"));
+
+  if (!isDirectory(talks)) {
+    if (!initialized) return { name, findings, note: "no project here, so no generated Markdown to inspect" };
+    findings.push(finding("MD-000", ERROR, "talks",
+      "this project has a database but no talks directory; run superdev docs generate"));
+    return { name, findings };
+  }
+
+  const files = walk(talks).filter((file) => extname(file) === ".md");
+  if (!files.length) {
+    if (!initialized) return { name, findings, note: "no project here, so no generated Markdown to inspect" };
+    findings.push(finding("MD-000", ERROR, "talks",
+      "this project has a database but talks/ holds no documents; run superdev docs generate"));
+    return { name, findings };
+  }
+
+  for (const file of files) {
+    const path = rel(root, file);
+    const text = readText(file);
+    if (text === null) {
+      findings.push(finding("MD-005", ERROR, path, "document is unreadable"));
+      continue;
+    }
+
+    const newline = text.indexOf("\n");
+    const firstLine = newline === -1 ? text : text.slice(0, newline);
+    const marker = firstLine.match(MARKER);
+    if (!marker) {
+      findings.push(finding("MD-001", ERROR, path,
+        "carries no superdev:generated marker, so nothing records which record and revision produced it"));
+    } else {
+      const [, source, , recordedHash] = marker;
+      if (!/^[A-Z]{1,5}-\d{4,}$/.test(source)) {
+        findings.push(finding("MD-002", ERROR, path, `marker source "${source}" is not a Superdev identifier`));
+      }
+      const actual = bodyHash(newline === -1 ? "" : text.slice(newline + 1));
+      if (actual !== recordedHash) {
+        findings.push(finding("MD-003", ERROR, path,
+          "body does not match the hash in its marker; this is a pending edit proposal, not a file to overwrite"));
+      }
+    }
+
+    for (const target of linkTargets(text)) {
+      const resolved = resolve(dirname(file), target);
+      if (!existsSync(resolved)) {
+        findings.push(finding("MD-004", ERROR, path, `relative link "${target}" does not resolve`));
+      }
+    }
+  }
+
+  return { name, findings };
+}

package/scripts/validate/migrations.mjs

@@ -0,0 +1,187 @@
+// Migration validator.
+//
+// This one builds its artifact rather than reading one: it applies the whole
+// ordered migration set forward into a throwaway database in a temp directory,
+// proves the schema is intact and the guard triggers actually fire, and deletes
+// it. Nothing is committed, nothing is simulated, and a passing run means the
+// SQL in the repository really does produce the schema it claims to.
+//
+// It fails when there are no migrations. A migration validator that skips
+// itself when the input is missing is how a broken schema ships.
+
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { availableMigrations, migrate } from "../../src/db/migrate.mjs";
+import { create, mutate, paths, query, setStatus } from "../../src/db/store.mjs";
+import { ERROR, finding } from "./common.mjs";
+
+export const name = "migrations";
+
+const MIGRATIONS_PATH = "src/db/migrations";
+
+/** Run a probe that must be refused, and say what the refusal proved. */
+async function mustRefuse(tmpRoot, code, path, expectedCode, description, action) {
+  try {
+    await mutate(tmpRoot, action);
+  } catch (err) {
+    const message = String(err?.message ?? err);
+    if (message.includes(expectedCode)) return null;
+    return finding(code, ERROR, path,
+      `${description} was refused with "${message}" rather than ${expectedCode}`);
+  }
+  return finding(code, ERROR, path, `${description} was allowed; ${expectedCode} did not fire`);
+}
+
+export async function run(root) {
+  const findings = [];
+  const dir = join(root, "src", "db", "migrations");
+  const available = availableMigrations(dir);
+
+  if (!available.length) {
+    findings.push(finding("MG-000", ERROR, MIGRATIONS_PATH,
+      "no migration files found; the schema cannot be applied or proven"));
+    return { name, findings };
+  }
+
+  const tmpRoot = mkdtempSync(join(tmpdir(), "superdev-validate-migrations-"));
+  try {
+    const dbFile = paths(tmpRoot).db;
+
+    // ------------------------------------------------- apply the full set forward
+    let applied;
+    try {
+      applied = await migrate(dbFile, { apply: true, dir });
+    } catch (err) {
+      findings.push(finding("MG-001", ERROR, MIGRATIONS_PATH,
+        `applying the migration set forward failed: ${String(err?.message ?? err)}`));
+      return { name, findings };
+    }
+
+    if (applied.applied.length !== available.length) {
+      findings.push(finding("MG-002", ERROR, MIGRATIONS_PATH,
+        `${available.length} migration file(s) on disk but ${applied.applied.length} applied`));
+    }
+
+    // ------------------------------------------------------ integrity and keys
+    const health = await query(tmpRoot, async (db) => {
+      const out = {};
+      try {
+        out.integrity = await db.all("PRAGMA integrity_check");
+      } catch (err) {
+        out.integrityError = String(err?.message ?? err);
+      }
+      try {
+        out.foreignKeys = await db.all("PRAGMA foreign_key_check");
+      } catch (err) {
+        out.foreignKeyError = String(err?.message ?? err);
+      }
+      out.bookkeeping = await db.all("SELECT version, name, checksum FROM applied_migrations ORDER BY version");
+      return out;
+    });
+
+    if (health.integrityError) {
+      findings.push(finding("MG-003", ERROR, MIGRATIONS_PATH, `integrity check could not run: ${health.integrityError}`));
+    } else {
+      const verdicts = (health.integrity ?? []).map((row) => String(Object.values(row)[0] ?? "")).filter(Boolean);
+      const bad = verdicts.filter((v) => v.toLowerCase() !== "ok");
+      if (!verdicts.length) findings.push(finding("MG-003", ERROR, MIGRATIONS_PATH, "integrity check returned nothing"));
+      else if (bad.length) findings.push(finding("MG-003", ERROR, MIGRATIONS_PATH, `integrity check reported: ${bad.join("; ")}`));
+    }
+
+    if (health.foreignKeyError) {
+      findings.push(finding("MG-004", ERROR, MIGRATIONS_PATH, `foreign key check could not run: ${health.foreignKeyError}`));
+    } else if ((health.foreignKeys ?? []).length) {
+      findings.push(finding("MG-004", ERROR, MIGRATIONS_PATH,
+        `foreign key check reported ${health.foreignKeys.length} violation(s) in a freshly migrated database`));
+    }
+
+    // -------------------------------- applied list equals the checked-in files
+    const onDisk = available.map((m) => `${m.version} ${m.name} ${m.checksum}`);
+    const recorded = (health.bookkeeping ?? []).map((row) => `${row.version} ${row.name} ${row.checksum}`);
+    if (onDisk.join("\n") !== recorded.join("\n")) {
+      const missing = onDisk.filter((entry) => !recorded.includes(entry)).map((e) => e.split(" ")[1]);
+      const extra = recorded.filter((entry) => !onDisk.includes(entry)).map((e) => e.split(" ")[1]);
+      findings.push(finding("MG-005", ERROR, MIGRATIONS_PATH,
+        `the applied migration list does not equal the migration files${missing.length ? `; not applied or altered: ${missing.join(", ")}` : ""}${extra.length ? `; applied but not on disk: ${extra.join(", ")}` : ""}`));
+    }
+
+    // ------------------------------------------------------- prove the triggers
+    let taskId = null;
+    try {
+      taskId = await mutate(tmpRoot, async (db) => {
+        const project = await create(db, "project", { name: "Validator probe", slug: "validator-probe" });
+        const module = await create(db, "module", {
+          project_id: project.id, name: "Probe module", slug: "probe-module",
+        }, { projectId: project.id });
+        const feature = await create(db, "feature", {
+          project_id: project.id, module_id: module.id, name: "Probe feature", slug: "probe-feature",
+        }, { projectId: project.id });
+        const task = await create(db, "task", {
+          project_id: project.id, feature_id: feature.id, name: "Probe task",
+        }, { projectId: project.id });
+        return task.id;
+      });
+    } catch (err) {
+      findings.push(finding("MG-006", ERROR, MIGRATIONS_PATH,
+        `the schema could not hold a minimal project, module, feature and task: ${String(err?.message ?? err)}`));
+      return { name, findings };
+    }
+
+    // The append-only probes need a real row: a statement that matches nothing
+    // never reaches the trigger and would pass without proving anything.
+    const eventId = await query(tmpRoot, (db) =>
+      db.value("SELECT id FROM activity_events ORDER BY sequence LIMIT 1"));
+    if (!eventId) {
+      findings.push(finding("MG-006", ERROR, MIGRATIONS_PATH,
+        "creating records recorded no activity event, so the append-only triggers cannot be proven"));
+      return { name, findings };
+    }
+
+    const refusals = [
+      await mustRefuse(tmpRoot, "MG-007", MIGRATIONS_PATH, "E_TASK_WITHOUT_CONTRACT",
+        "moving a task out of draft with no contract link",
+        (db) => setStatus(db, "task", taskId, "ready")),
+      await mustRefuse(tmpRoot, "MG-008", MIGRATIONS_PATH, "E_APPEND_ONLY",
+        "updating an activity event",
+        (db) => db.run("UPDATE activity_events SET summary = ? WHERE id = ?", "rewritten", eventId)),
+      await mustRefuse(tmpRoot, "MG-009", MIGRATIONS_PATH, "E_APPEND_ONLY",
+        "deleting an activity event",
+        (db) => db.run("DELETE FROM activity_events WHERE id = ?", eventId)),
+    ];
+    findings.push(...refusals.filter(Boolean));
+
+    // The constraint has to permit the mapped case too, or "always refuses" would
+    // read as "correctly refuses".
+    try {
+      await mutate(tmpRoot, async (db) => {
+        await db.run(
+          "INSERT INTO task_contract_links (task_id, target_type, target_id, relationship) VALUES (?,?,?,?)",
+          taskId, "acceptance_criterion", "AC-0001", "implements",
+        );
+        await setStatus(db, "task", taskId, "ready");
+      });
+    } catch (err) {
+      findings.push(finding("MG-010", ERROR, MIGRATIONS_PATH,
+        `a task with a contract link could not leave draft: ${String(err?.message ?? err)}`));
+    }
+
+    // Only meaningful once a transition exists; a missing one is already MG-010.
+    const historyId = await query(tmpRoot, (db) =>
+      db.value("SELECT id FROM status_history ORDER BY id LIMIT 1"));
+    if (historyId) {
+      const historyRefusal = await mustRefuse(tmpRoot, "MG-011", MIGRATIONS_PATH, "E_APPEND_ONLY",
+        "deleting a status transition",
+        (db) => db.run("DELETE FROM status_history WHERE id = ?", historyId));
+      if (historyRefusal) findings.push(historyRefusal);
+    }
+  } finally {
+    rmSync(tmpRoot, { recursive: true, force: true });
+    if (existsSync(tmpRoot)) {
+      findings.push(finding("MG-012", ERROR, MIGRATIONS_PATH,
+        "the throwaway database directory could not be removed"));
+    }
+  }
+
+  return { name, findings };
+}

package/scripts/validate/no-tests.mjs

@@ -0,0 +1,136 @@
+// What kind of testing this repository permits, and what it still refuses.
+//
+// The rule used to be absolute: no test file of any kind. Its reason was sound
+// and is worth restating, because it is the thing this validator still protects.
+// Every earlier attempt to keep "just a few" tests grew a fixture project, then
+// phase gates over that fixture, then completion claims measured in test counts.
+// A simulated product passing its own gates says nothing about the real one, and
+// it is worse than saying nothing, because it feels like proof.
+//
+// What the absolute version also refused was cheap and valuable: an assertion
+// that a pure function returns the right answer. The cost of that refusal was
+// measured rather than guessed. Of thirteen defects found in one session, seven
+// were in pure functions and would each have been caught by two or three lines:
+// a paragraph joiner that split a wrapped sentence and produced a feature named
+// after half a clause; a backup restore that resolved a bare filename against
+// the wrong directory, so the name the product printed could not be handed back
+// to it; a version comparison that told nobody on a pre-release that the release
+// existed. None of them could fail a validator, because none of them is a
+// structural claim. They are arithmetic, and arithmetic is what an assertion is
+// for.
+//
+// So the line moved to where the original reasoning actually pointed:
+//
+//   Allowed: a `.test.mjs` file beside the source it tests, run by node's own
+//   test runner, asserting on functions called directly.
+//
+//   Still refused: a test directory, a fixture project, any third-party
+//   framework, and anything that stands a simulated product up to pass its own
+//   gates.
+//
+// The completion rule is untouched, and it is the part that matters most. A task
+// completes on recorded evidence about the real product. A green suite is not
+// evidence, a coverage figure is not progress, and neither may ever be offered
+// as either.
+
+import { join } from "node:path";
+import { ERROR, WARNING, finding, isDirectory, readJson, rel, walk } from "./common.mjs";
+
+export const name = "no-tests";
+
+/** A tree of tests is the shape that grew a fixture project last time. */
+const TEST_DIRECTORIES = new Set(["tests", "test", "__tests__", "spec", "fixtures"]);
+
+/** Allowed: beside the source, named for it. Refused: every other shape. */
+const COLOCATED_TEST = /^[a-z0-9-]+\.test\.mjs$/;
+const OTHER_TEST_FILE = /\.(?:test|spec)\.(?:cjs|js|ts|tsx|jsx)$|\.spec\.mjs$/;
+
+/**
+ * Frameworks and their runners. Node's own runner is deliberately absent: it
+ * needs no dependency, so it cannot grow one.
+ */
+const TEST_RUNNER = /\b(?:jest|vitest|mocha|ava|tap|jasmine|karma|cypress|playwright test)\b/;
+
+/** Where a colocated test may live: beside source, not anywhere in the tree. */
+const TESTABLE_ROOTS = ["src/", "scripts/"];
+
+export async function run(root) {
+  const findings = [];
+  if (!isDirectory(root)) {
+    findings.push(finding("NT-000", ERROR, ".", "the project root does not exist"));
+    return { name, findings };
+  }
+
+  // Read the tree once. walk() is a generator over the whole repository and
+  // calling it per file turned this validator quadratic.
+  const paths = new Set();
+  for (const file of walk(root)) paths.add(rel(root, file));
+
+  const trees = new Map();
+  let colocated = 0;
+
+  for (const path of paths) {
+    const segments = path.split("/");
+    const name_ = segments.at(-1);
+    const at = segments.findIndex((segment) => TEST_DIRECTORIES.has(segment));
+
+    if (at !== -1 && at < segments.length - 1) {
+      const tree = segments.slice(0, at + 1).join("/");
+      trees.set(tree, (trees.get(tree) ?? 0) + 1);
+      continue;
+    }
+
+    if (COLOCATED_TEST.test(name_)) {
+      if (!TESTABLE_ROOTS.some((prefix) => path.startsWith(prefix))) {
+        findings.push(finding("NT-005", ERROR, path,
+          `a unit test belongs beside the source it tests, under ${TESTABLE_ROOTS.join(" or ")}`));
+        continue;
+      }
+      // The source it names has to exist, or it tests nothing and will keep
+      // passing after that source is deleted.
+      const subject = path.replace(/\.test\.mjs$/, ".mjs");
+      if (!paths.has(subject)) {
+        findings.push(finding("NT-006", ERROR, path,
+          `there is no ${subject} for this to test, so it asserts on nothing that ships`));
+        continue;
+      }
+      colocated += 1;
+      continue;
+    }
+
+    if (OTHER_TEST_FILE.test(name_)) {
+      findings.push(finding("NT-001", ERROR, path,
+        "test file; a unit test is named <source>.test.mjs and sits beside its source"));
+    }
+  }
+
+  for (const [tree, count] of [...trees].sort()) {
+    findings.push(finding("NT-002", ERROR, tree,
+      `test or fixture tree holding ${count} file(s); a unit test sits beside the source it tests, and this repository keeps no fixture project`));
+  }
+
+  const { value: pkg } = readJson(join(root, "package.json"));
+
+  // `npm test` is allowed now, and only for node's own runner. A script that
+  // reaches for a framework is the first step back toward the tree this refuses.
+  for (const [script, command] of Object.entries(pkg?.scripts ?? {})) {
+    if (TEST_RUNNER.test(String(command))) {
+      findings.push(finding("NT-003", ERROR, "package.json",
+        `script "${script}" runs a third-party test runner; unit tests use node --test, which needs no dependency`));
+    }
+  }
+  for (const dependency of Object.keys({ ...pkg?.devDependencies, ...pkg?.dependencies })) {
+    if (TEST_RUNNER.test(dependency)) {
+      findings.push(finding("NT-004", ERROR, "package.json",
+        `dependency "${dependency}" is a test framework; unit tests use node --test`));
+    }
+  }
+
+  // Tests that nothing runs are the same as no tests, with more upkeep.
+  if (colocated > 0 && !pkg?.scripts?.test) {
+    findings.push(finding("NT-007", WARNING, "package.json",
+      `${colocated} unit test file(s) exist and no "test" script runs them`));
+  }
+
+  return { name, findings };
+}