@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/lint/class-file.ts

@@ -0,0 +1,39 @@
+import type { ESTree, CreateRule } from "@oxlint/plugins";
+import { declarationOf, movedOf, type Statement } from "./names.ts";
+
+const MESSAGE = "a class file holds one class, its imports and its export";
+
+/** The class a top-level statement declares, bare or exported, or null when it declares none. */
+function classOf(statement: Statement): ESTree.Class | null {
+  const declaration = declarationOf(statement);
+  return declaration?.type === "ClassDeclaration" ? declaration : null;
+}
+
+/** `export { C }` or `export default C`: the export of a class declared bare. */
+function exportsClass(statement: Statement, name: string | null): boolean {
+  if (statement.type === "ExportDefaultDeclaration")
+    return statement.declaration.type === "Identifier" && statement.declaration.name === name;
+  if (statement.type !== "ExportNamedDeclaration" || statement.source !== null) return false;
+  const [only, ...rest] = statement.specifiers;
+  return only !== undefined && rest.length === 0 && only.local.type === "Identifier" && only.local.name === name;
+}
+
+/**
+ * Fails, in a file with a top-level class, every top-level statement but its imports, that class and its export: a
+ * helper, a type or a second class goes to its own file, so a file declares functions or a class, never both.
+ */
+export const classFile: CreateRule = {
+  create(context) {
+    return {
+      Program(program) {
+        const owner = program.body.find((statement) => classOf(statement) !== null);
+        if (owner === undefined) return;
+        const name = classOf(owner)?.id?.name ?? null;
+        for (const statement of program.body) {
+          if (statement === owner || statement.type === "ImportDeclaration" || exportsClass(statement, name)) continue;
+          context.report({ message: `${MESSAGE}; move ${movedOf(statement)} to its own file`, node: statement });
+        }
+      },
+    };
+  },
+};

package/cli/lint/config-file.ts

@@ -0,0 +1,32 @@
+import path from "node:path";
+import type { CreateRule } from "@oxlint/plugins";
+import { movedOf, type Statement } from "./names.ts";
+
+/** `vite.config.ts`, `workerstack.config.ts`, `eslint.config.mjs`. */
+const CONFIG = /\.config\.(?:ts|mts|js|mjs)$/;
+const MESSAGE = "a config file holds only imports and exports";
+
+/** An import, `export default`, or an export that declares nothing: `export { a }`, `export … from`. */
+const allowed = (statement: Statement): boolean =>
+  statement.type === "ImportDeclaration" ||
+  statement.type === "ExportDefaultDeclaration" ||
+  statement.type === "ExportAllDeclaration" ||
+  (statement.type === "ExportNamedDeclaration" && statement.declaration === null);
+
+/** Fails any other statement in a config file: what a config builds lives in a module it imports. */
+export const configFile: CreateRule = {
+  create(context) {
+    if (!CONFIG.test(path.basename(context.filename))) return {};
+    return {
+      Program(program) {
+        for (const statement of program.body) {
+          if (allowed(statement)) continue;
+          context.report({
+            message: `${MESSAGE}; move ${movedOf(statement)} into a module it imports`,
+            node: statement,
+          });
+        }
+      },
+    };
+  },
+};

package/cli/lint/entry-file.ts

@@ -0,0 +1,54 @@
+import path from "node:path";
+import type { ESTree, CreateRule } from "@oxlint/plugins";
+import { nearestManifest, readManifest } from "./manifest.ts";
+import type { Statement } from "./names.ts";
+
+const SHAPE = "a bin file holds only imports and one main() call";
+const MESSAGE = `${SHAPE}; move this into the module main comes from`;
+const MISSING = `${SHAPE}; import main and call it once`;
+
+/** Whether `filename` is a `bin` of its nearest package.json, both resolved from the manifest's dir. */
+function isBin(filename: string): boolean {
+  const file = nearestManifest(path.dirname(filename));
+  const manifest = file === null ? null : readManifest(file);
+  if (manifest === null) return false;
+  const self = path.resolve(filename);
+  return manifest.bins.some((bin) => path.resolve(path.dirname(manifest.file), bin) === self);
+}
+
+const importsMain = (program: ESTree.Program): boolean =>
+  program.body.some(
+    (statement) =>
+      statement.type === "ImportDeclaration" && statement.specifiers.some((item) => item.local.name === "main"),
+  );
+
+/** `main(…)`, `await main(…)` or `void main(…)` as a statement. */
+function callsMain(statement: Statement): boolean {
+  if (statement.type !== "ExpressionStatement") return false;
+  let call = statement.expression;
+  if (call.type === "AwaitExpression" || (call.type === "UnaryExpression" && call.operator === "void"))
+    call = call.argument;
+  return call.type === "CallExpression" && call.callee.type === "Identifier" && call.callee.name === "main";
+}
+
+/**
+ * Fails a file its nearest package.json lists as a `bin` unless it holds only imports and one call of an imported
+ * `main`, so what the program does lives in a module a test can import. A file whose manifest is unreadable is skipped.
+ */
+export const entryFile: CreateRule = {
+  create(context) {
+    if (!isBin(context.filename)) return {};
+    return {
+      Program(program) {
+        const imported = importsMain(program);
+        let called = false;
+        for (const statement of program.body) {
+          if (statement.type === "ImportDeclaration") continue;
+          if (imported && !called && callsMain(statement)) called = true;
+          else context.report({ message: MESSAGE, node: statement });
+        }
+        if (!called) context.report({ message: MISSING, node: program });
+      },
+    };
+  },
+};

package/cli/lint/env-in-config.ts

@@ -0,0 +1,66 @@
+import path from "node:path";
+import type { CreateRule, ESTree } from "@oxlint/plugins";
+import { ENV_FILE, ENV_PROPERTY, IMPORT_KEYWORD } from "../env.constants.ts";
+
+/** Modules whose `env` export is the process environment. */
+const ENV_MODULES = ["process", "node:process", "cloudflare:workers"];
+/** Globals that carry the environment as `.env`. */
+const GLOBALS = ["process", "Bun"];
+const tail = "is read outside env.ts; add the variable to this package's env.ts schema and read it through that module";
+const messageOf = (what: string) => `${what} ${tail}`;
+
+/** The property name of `.name` or `["name"]`, when it is a plain name. */
+function propertyName(node: ESTree.MemberExpression): string | undefined {
+  if (!node.computed) return node.property.type === "Identifier" ? node.property.name : undefined;
+  return node.property.type === "Literal" && typeof node.property.value === "string" ? node.property.value : undefined;
+}
+
+/** `process.env` or `Bun.env`, or `import.meta.env`: what the member read is of, or undefined. */
+function envOwner(node: ESTree.MemberExpression): string | undefined {
+  if (propertyName(node) !== ENV_PROPERTY) return undefined;
+  const { object } = node;
+  if (object.type === "Identifier" && GLOBALS.includes(object.name)) return `${object.name}.env`;
+  return object.type === "MetaProperty" && object.meta.name === IMPORT_KEYWORD ? "import.meta.env" : undefined;
+}
+
+/** `const { env } = process`: a destructuring that pulls `env` off a global. */
+function destructured(node: ESTree.VariableDeclarator): string | undefined {
+  const { id, init } = node;
+  if (id.type !== "ObjectPattern" || init?.type !== "Identifier" || !GLOBALS.includes(init.name)) return undefined;
+  const pulls = id.properties.some(
+    (property) =>
+      property.type === "Property" &&
+      (property.key.type === "Identifier"
+        ? property.key.name
+        : property.key.type === "Literal" && property.key.value) === ENV_PROPERTY,
+  );
+  return pulls ? `${init.name}.env` : undefined;
+}
+
+/** The name an import specifier takes from its module, quoted or not. */
+const importedName = (imported: ESTree.ModuleExportName): string =>
+  imported.type === "Identifier" ? imported.name : String(imported.value);
+
+/** Fails a read of the process environment in any file not named `env.ts`; tests are not exempt. */
+export const envInConfig: CreateRule = {
+  create(context) {
+    if (path.basename(context.filename) === ENV_FILE) return {};
+    return {
+      MemberExpression(node) {
+        const what = envOwner(node);
+        if (what !== undefined) context.report({ message: messageOf(what), node });
+      },
+      VariableDeclarator(node) {
+        const what = destructured(node);
+        if (what !== undefined) context.report({ message: messageOf(what), node });
+      },
+      ImportDeclaration(node) {
+        if (!ENV_MODULES.includes(node.source.value)) return;
+        for (const specifier of node.specifiers) {
+          if (specifier.type === "ImportSpecifier" && importedName(specifier.imported) === ENV_PROPERTY)
+            context.report({ message: messageOf(ENV_PROPERTY), node: specifier });
+        }
+      },
+    };
+  },
+};

package/cli/lint/filename-matches-export.ts

@@ -0,0 +1,63 @@
+import path from "node:path";
+import type { ESTree, CreateRule } from "@oxlint/plugins";
+import { declaredNames } from "./names.ts";
+
+/** Index files collect, declaration files describe, and test files test: none is named after one export. */
+const SKIPPED = /^index\.|\.d\.[cm]?ts$|\.(?:test|spec|e2e)\./;
+
+/** An entry or bin file's `main` is named by its role, not its file; the entry rule governs those. */
+const ENTRY_EXPORT = "main";
+
+type Node = ESTree.Node;
+
+const exportedName = (name: ESTree.ModuleExportName): string =>
+  name.type === "Identifier" ? name.name : String(name.value);
+
+/** The names a statement exports, or null when it re-exports a module's every name; `export default` adds none. */
+function exportsOf(statement: Node): string[] | null {
+  if (statement.type === "ExportAllDeclaration")
+    return statement.exported === null ? null : [exportedName(statement.exported)];
+  if (statement.type !== "ExportNamedDeclaration") return [];
+  if (statement.declaration !== null) return declaredNames(statement.declaration);
+  return statement.specifiers.map((specifier) => exportedName(specifier.exported));
+}
+
+const letters = (name: string): string => name.toLowerCase().replaceAll(/[^a-z\d]/g, "");
+const kebab = (name: string): string =>
+  name
+    .replaceAll(/([a-z\d])([A-Z])/g, "$1-$2")
+    .replaceAll(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replaceAll(/[^A-Za-z\d]+/g, "-")
+    .toLowerCase();
+
+/** The one name `program` exports, or null when it exports none, several, or an unknown set. */
+function soleExport(program: ESTree.Program): string | null {
+  const names = new Set<string>();
+  for (const statement of program.body) {
+    const found = exportsOf(statement);
+    if (found === null) return null;
+    for (const name of found) names.add(name);
+  }
+  return names.size === 1 ? [...names].join("") : null;
+}
+
+/**
+ * Fails a file with exactly one exported name that is not named after it, compared on letters and digits so
+ * `read-workspace.ts`, `readWorkspace.ts` and `read_workspace.ts` all match `readWorkspace`.
+ */
+export const filenameMatchesExport: CreateRule = {
+  create(context) {
+    const base = path.basename(context.filename);
+    if (SKIPPED.test(base)) return {};
+    // oxlint lints only files with an extension, so the name has a dot.
+    const stem = base.slice(0, base.indexOf("."));
+    return {
+      Program(program) {
+        const name = soleExport(program);
+        if (name === null || name === ENTRY_EXPORT || letters(name) === letters(stem)) return;
+        const message = `${base} exports only "${name}"; rename the file ${kebab(name)}${base.slice(stem.length)}`;
+        context.report({ message, node: program });
+      },
+    };
+  },
+};

package/cli/lint/index-file.ts

@@ -0,0 +1,22 @@
+import path from "node:path";
+import type { CreateRule } from "@oxlint/plugins";
+
+const INDEX = /^index\.(?:ts|tsx|mts|js)$/;
+const MESSAGE = "an index file only re-exports; move this into its own module and re-export it";
+
+/** Fails every statement of an index file but `export … from` and `export * from`, type-only forms included. */
+export const indexFile: CreateRule = {
+  create(context) {
+    if (!INDEX.test(path.basename(context.filename))) return {};
+    return {
+      Program(program) {
+        for (const statement of program.body) {
+          const reexport =
+            statement.type === "ExportAllDeclaration" ||
+            (statement.type === "ExportNamedDeclaration" && statement.source !== null);
+          if (!reexport) context.report({ message: MESSAGE, node: statement });
+        }
+      },
+    };
+  },
+};

package/cli/lint/index.ts

@@ -0,0 +1,47 @@
+/**
+ * `@workerstack/repo/lint`: the oxlint JS plugin `repo`, which the standards pack's generated `.oxlintrc.json` loads
+ * with every rule on. oxlint reads a plugin from its default export.
+ */
+import type { Plugin } from "@oxlint/plugins";
+import { asNeedsReason } from "./as-needs-reason.ts";
+import { boundaries } from "./boundaries.ts";
+import { classFile } from "./class-file.ts";
+import { configFile } from "./config-file.ts";
+import { entryFile } from "./entry-file.ts";
+import { envInConfig } from "./env-in-config.ts";
+import { filenameMatchesExport } from "./filename-matches-export.ts";
+import { indexFile } from "./index-file.ts";
+import { noCommentedOutCode } from "./no-commented-out-code.ts";
+import { noMockOfSubject } from "./no-mock-of-subject.ts";
+import { noModuleSideEffects } from "./no-module-side-effects.ts";
+import { noModuleState } from "./no-module-state.ts";
+import { noSideEffectImport } from "./no-side-effect-import.ts";
+import { noV8Ignore } from "./no-v8-ignore.ts";
+import { skipOnPlatform } from "./skip-on-platform.ts";
+import { todoNeedsId } from "./todo-needs-id.ts";
+import { typesFile } from "./types-file.ts";
+
+const plugin: Plugin & { meta: { name: string } } = {
+  meta: { name: "repo" },
+  rules: {
+    "as-needs-reason": asNeedsReason,
+    boundaries,
+    "class-file": classFile,
+    "config-file": configFile,
+    "entry-file": entryFile,
+    "env-in-config": envInConfig,
+    "filename-matches-export": filenameMatchesExport,
+    "index-file": indexFile,
+    "no-commented-out-code": noCommentedOutCode,
+    "no-mock-of-subject": noMockOfSubject,
+    "no-module-side-effects": noModuleSideEffects,
+    "no-module-state": noModuleState,
+    "no-side-effect-import": noSideEffectImport,
+    "no-v8-ignore": noV8Ignore,
+    "skip-on-platform": skipOnPlatform,
+    "todo-needs-id": todoNeedsId,
+    "types-file": typesFile,
+  },
+};
+
+export default plugin;

package/cli/lint/is-reason.ts

@@ -0,0 +1,6 @@
+/** A reason is at least this many words of letters; fewer is a marker like `ok` or `safe`. */
+const MIN_WORDS = 3;
+const WORD = /\p{L}+(?:['’-]\p{L}+)*/gu;
+
+/** Whether `text` holds a written reason: at least three words of letters. */
+export const isReason = (text: string): boolean => (text.match(WORD) ?? []).length >= MIN_WORDS;

package/cli/lint/manifest.ts

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * What a package.json declares, parsed from untrusted JSON: a field of the wrong shape counts as absent. `bins` are
+ * the `bin` paths as written, relative to the manifest's dir.
+ */
+export type Manifest = { file: string; name: string | null; declared: string[]; bins: string[] };
+
+const DEPENDENCY_MAPS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** The nearest package.json at or above `start`, or null when none is. */
+export function nearestManifest(start: string): string | null {
+  let dir = start;
+  while (!fs.existsSync(path.join(dir, "package.json"))) {
+    if (path.dirname(dir) === dir) return null;
+    dir = path.dirname(dir);
+  }
+  return path.join(dir, "package.json");
+}
+
+/** A manifest's bin scripts: `bin` as one path or a map of them; anything else names none. */
+export function binsOf(bin: unknown): string[] {
+  const all = isRecord(bin) ? Object.values(bin) : [bin];
+  return all.filter((file) => typeof file === "string");
+}
+
+/** The manifest at `file`, or null when it cannot be read as a JSON object. */
+export function readManifest(file: string): Manifest | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!isRecord(raw)) return null;
+  const name = typeof raw.name === "string" ? raw.name : null;
+  const declared = DEPENDENCY_MAPS.flatMap((key) => {
+    const map = raw[key];
+    return isRecord(map) ? Object.keys(map) : [];
+  });
+  return { file, name, declared, bins: binsOf(raw.bin) };
+}

package/cli/lint/names.ts

@@ -0,0 +1,59 @@
+import type { ESTree } from "@oxlint/plugins";
+
+/** A top-level statement of a module. */
+export type Statement = ESTree.Program["body"][number];
+type Binding = ESTree.BindingPattern | ESTree.BindingRestElement;
+type Declaration = NonNullable<ESTree.ExportNamedDeclaration["declaration"]>;
+
+/** The names a binding pattern declares: `{ a, b: [c] }` → a, c. */
+function boundNames(pattern: Binding | null): string[] {
+  if (pattern === null) return [];
+  switch (pattern.type) {
+    case "Identifier":
+      return [pattern.name];
+    case "ObjectPattern":
+      return pattern.properties.flatMap((property) =>
+        boundNames(property.type === "RestElement" ? property : property.value),
+      );
+    case "ArrayPattern":
+      return pattern.elements.flatMap(boundNames);
+    case "AssignmentPattern":
+      return boundNames(pattern.left);
+    case "RestElement":
+      return boundNames(pattern.argument);
+  }
+}
+
+/** The names a declaration binds, as after `export`. */
+export function declaredNames(declaration: Declaration): string[] {
+  if (declaration.type === "VariableDeclaration")
+    return declaration.declarations.flatMap((item) => boundNames(item.id));
+  return declaration.id !== null && declaration.id.type === "Identifier" ? [declaration.id.name] : [];
+}
+
+const DECLARATIONS = [
+  "ClassDeclaration",
+  "FunctionDeclaration",
+  "TSDeclareFunction",
+  "TSEnumDeclaration",
+  "TSInterfaceDeclaration",
+  "TSModuleDeclaration",
+  "TSTypeAliasDeclaration",
+  "VariableDeclaration",
+];
+
+const isDeclaration = (node: { type: string }): node is Declaration => DECLARATIONS.includes(node.type);
+
+/** The declaration a statement makes, bare, after `export` or after `export default`, or null when it makes none. */
+export function declarationOf(statement: Statement): Declaration | null {
+  if (statement.type === "ExportNamedDeclaration") return statement.declaration;
+  const inner = statement.type === "ExportDefaultDeclaration" ? statement.declaration : statement;
+  return isDeclaration(inner) ? inner : null;
+}
+
+/** What a message asks to move: the names `statement` declares, quoted, or "this" when it declares none. */
+export function movedOf(statement: Statement): string {
+  const declaration = declarationOf(statement);
+  const names = declaration === null ? [] : declaredNames(declaration);
+  return names.length === 0 ? "this" : names.map((name) => `"${name}"`).join(", ");
+}

package/cli/lint/no-commented-out-code.ts

@@ -0,0 +1,105 @@
+import type { Comment, CreateRule } from "@oxlint/plugins";
+import { parseSync } from "oxc-parser";
+
+const MESSAGE = "this comment is code; delete it, git keeps the old version";
+/** Comments a tool reads: type and lint directives, pure marks, and coverage hints. */
+const TOOL = /^\s*(?:@ts-|oxlint-|eslint-|[@#]__PURE__|(?:v8|c8|istanbul)\s+ignore\b)/;
+/** Two line comments on adjacent lines, with nothing but spaces between them. */
+const ADJACENT = /^[ \t]*\r?\n[ \t]*$/;
+const BLOCK_STAR = /^[ \t]*\*[ \t]?/gm;
+/** What only code holds: a parsed expression or a label alone can be prose like `workspace` or `note: see a.b`. */
+const CODE = [
+  "AssignmentExpression",
+  "CallExpression",
+  "ClassDeclaration",
+  "DoWhileStatement",
+  "ExportAllDeclaration",
+  "ExportDefaultDeclaration",
+  "ExportNamedDeclaration",
+  "ForInStatement",
+  "ForOfStatement",
+  "ForStatement",
+  "FunctionDeclaration",
+  "IfStatement",
+  "ImportDeclaration",
+  "NewExpression",
+  "ReturnStatement",
+  "SwitchStatement",
+  "TSEnumDeclaration",
+  "TSInterfaceDeclaration",
+  "TSTypeAliasDeclaration",
+  "ThrowStatement",
+  "TryStatement",
+  "VariableDeclaration",
+  "WhileStatement",
+];
+
+/** JSDoc documents, a triple-slash comment directs the compiler, and a tool comment is read by its tool. */
+function skipped(comment: Comment): boolean {
+  if (comment.type === "Block" && comment.value.startsWith("*")) return true;
+  if (comment.type === "Line" && comment.value.startsWith("/")) return true;
+  return TOOL.test(comment.value);
+}
+
+const joins = (text: string, previous: Comment, comment: Comment): boolean =>
+  previous.type === "Line" && comment.type === "Line" && ADJACENT.test(text.slice(previous.end, comment.start));
+
+type Group = [Comment, ...Comment[]];
+
+/** The comments to read as one text each: a run of line comments on adjacent lines, or one block comment. */
+function groupsOf(text: string, comments: readonly Comment[]): Group[] {
+  const groups: Group[] = [];
+  let open: { group: Group; last: Comment } | null = null;
+  for (const comment of comments) {
+    if (skipped(comment)) {
+      open = null;
+    } else if (open !== null && joins(text, open.last, comment)) {
+      open.group.push(comment);
+      open.last = comment;
+    } else {
+      open = { group: [comment], last: comment };
+      groups.push(open.group);
+    }
+  }
+  return groups;
+}
+
+function holdsCode(node: unknown): boolean {
+  if (typeof node !== "object" || node === null) return false;
+  if (Array.isArray(node)) return node.some(holdsCode);
+  if ("type" in node && typeof node.type === "string" && CODE.includes(node.type)) return true;
+  return Object.values(node).some(holdsCode);
+}
+
+/** Whether `source` parses as TypeScript with no error, at module scope or in a function body, and holds code. */
+function isCode(source: string): boolean {
+  for (const text of [source, `async function* comment() {\n${source}\n}`]) {
+    const parsed = parseSync("comment.ts", text, { sourceType: "module" });
+    if (parsed.errors.length === 0) return holdsCode(parsed.program.body);
+  }
+  return false;
+}
+
+const textOf = (group: readonly Comment[]): string =>
+  group
+    .map((comment) => (comment.type === "Block" ? comment.value.replaceAll(BLOCK_STAR, "") : comment.value))
+    .join("\n");
+
+/** Code as a whole, like a multi-line `if`, or on any one line, like a commented call under a prose line. */
+const isCodeGroup = (text: string): boolean => isCode(text) || text.split("\n").some(isCode);
+
+/**
+ * Fails a comment that parses as code: git keeps the old version, so code left in a comment only rots. Consecutive
+ * line comments are read as one; JSDoc, triple-slash and tool comments are skipped.
+ */
+export const noCommentedOutCode: CreateRule = {
+  create(context) {
+    return {
+      Program() {
+        for (const group of groupsOf(context.sourceCode.text, context.sourceCode.getAllComments())) {
+          if (isCodeGroup(textOf(group))) context.report({ message: MESSAGE, node: group[0] });
+        }
+      },
+    };
+  },
+};

package/cli/lint/no-mock-of-subject.ts

@@ -0,0 +1,64 @@
+import path from "node:path";
+import type { ESTree, CreateRule } from "@oxlint/plugins";
+
+const TEST_FILE = /\.(?:test|spec)(\.[cm]?[jt]sx?)$/;
+const EXTENSION = /\.[cm]?[jt]sx?$/;
+/** `vi.mock`, `vi.doMock` and `jest.mock` replace a module for the whole test file. */
+const MOCKS: Readonly<Record<string, readonly string[]>> = { vi: ["mock", "doMock"], jest: ["mock"] };
+
+type Node = ESTree.Node;
+
+const stringOf = (node: Node | undefined): string | null =>
+  node?.type === "Literal" && typeof node.value === "string" ? node.value : null;
+
+const isImportMetaUrl = (node: Node | undefined): boolean =>
+  node?.type === "MemberExpression" &&
+  node.object.type === "MetaProperty" &&
+  node.object.meta.name === "import" &&
+  node.property.type === "Identifier" &&
+  node.property.name === "url";
+
+/** The relative path of `new URL("<rel>", import.meta.url).href`, or null for any other node. */
+function urlPath(node: Node): string | null {
+  if (node.type !== "MemberExpression" || node.property.type !== "Identifier" || node.property.name !== "href")
+    return null;
+  const { object } = node;
+  if (object.type !== "NewExpression" || object.callee.type !== "Identifier" || object.callee.name !== "URL")
+    return null;
+  return isImportMetaUrl(object.arguments[1]) ? stringOf(object.arguments[0]) : null;
+}
+
+const isMock = (callee: Node): boolean =>
+  callee.type === "MemberExpression" &&
+  callee.object.type === "Identifier" &&
+  callee.property.type === "Identifier" &&
+  (MOCKS[callee.object.name] ?? []).includes(callee.property.name);
+
+/** The relative specifier a mock call names, as a literal or the `import.meta.url` form, or null. */
+function mockedPath(node: ESTree.CallExpression): string | null {
+  const [first] = node.arguments;
+  if (!isMock(node.callee) || first === undefined) return null;
+  const specifier = stringOf(first) ?? urlPath(first);
+  return specifier?.startsWith(".") ? specifier : null;
+}
+
+/**
+ * Fails a test that mocks the module it tests: `parse.test.ts` mocking `./parse.ts` checks the mock, not the code.
+ * The subject is the test's path minus `.test` or `.spec`, compared without extensions.
+ */
+export const noMockOfSubject: CreateRule = {
+  create(context) {
+    const { filename } = context;
+    if (!TEST_FILE.test(filename)) return {};
+    const subject = filename.replace(TEST_FILE, "");
+    return {
+      CallExpression(node) {
+        const specifier = mockedPath(node);
+        if (specifier === null) return;
+        if (path.resolve(path.dirname(filename), specifier).replace(EXTENSION, "") !== subject) return;
+        const message = `"${specifier}" is the module this test covers; test it for real and mock what it calls`;
+        context.report({ message, node });
+      },
+    };
+  },
+};