@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/lint/no-module-side-effects.ts

@@ -0,0 +1,94 @@
+import type { Context, ESTree, CreateRule } from "@oxlint/plugins";
+
+/*
+ * `"sideEffects": false` is only true when importing a module runs nothing. A bundler keeps any top-level code it
+ * cannot prove pure, so module scope only declares; a call it needs is marked pure or moved into a function.
+ */
+const MESSAGE = "module scope runs no code; move this into a function, or mark a pure call /* @__PURE__ */";
+/** Statements that only declare. A class is walked instead: its decorators, heritage and static parts run. */
+const DECLARATIONS = [
+  "EmptyStatement",
+  "ExportAllDeclaration",
+  "FunctionDeclaration",
+  "ImportDeclaration",
+  "TSDeclareFunction",
+  "TSEnumDeclaration",
+  "TSExportAssignment",
+  "TSImportEqualsDeclaration",
+  "TSInterfaceDeclaration",
+  "TSModuleDeclaration",
+  "TSTypeAliasDeclaration",
+];
+const EFFECTS = [
+  "AssignmentExpression",
+  "AwaitExpression",
+  "CallExpression",
+  "NewExpression",
+  "TaggedTemplateExpression",
+  "UpdateExpression",
+  "YieldExpression",
+];
+/** Code inside a function runs when it is called, not at import. */
+const FUNCTIONS = ["ArrowFunctionExpression", "FunctionDeclaration", "FunctionExpression"];
+const PURE = /[@#]__PURE__/;
+
+type Node = ESTree.Node;
+type Field = ESTree.PropertyDefinition | ESTree.AccessorProperty;
+
+const isNode = (value: unknown): value is Node =>
+  typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+const isField = (node: Node): node is Field =>
+  node.type.endsWith("PropertyDefinition") || node.type.endsWith("AccessorProperty");
+
+function children(node: Node): Node[] {
+  const entries: [string, unknown][] = Object.entries(node);
+  return entries.flatMap(([key, value]) => (key === "parent" ? [] : [value].flat().filter(isNode)));
+}
+
+function firstOf<T>(items: readonly T[], find: (item: T) => Node | null): Node | null {
+  for (const item of items) {
+    const found = find(item);
+    if (found !== null) return found;
+  }
+  return null;
+}
+
+const pure = (context: Context, node: Node): boolean =>
+  context.sourceCode.getCommentsBefore(node).some((comment) => PURE.test(comment.value));
+
+/** The first node under `node` that runs at import: a non-pure effect, a decorator, or a static part's code. */
+function firstEffect(context: Context, node: Node | null): Node | null {
+  if (node === null || FUNCTIONS.includes(node.type)) return null;
+  if (node.type === "Decorator") return node;
+  if (node.type === "StaticBlock") return firstOf(node.body, (statement) => statementEffect(context, statement));
+  // An instance field's value runs per construction; its decorators and computed key run with the class.
+  const parts = isField(node) && !node.static ? [...node.decorators, node.key] : children(node);
+  if (EFFECTS.includes(node.type) && !pure(context, node)) return node;
+  return firstOf(parts, (child) => firstEffect(context, child));
+}
+
+/** What a module-scope statement runs at import, or null when it only declares. */
+function statementEffect(context: Context, statement: Node): Node | null {
+  const inner = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+  if (inner === null || DECLARATIONS.includes(inner.type)) return null;
+  if (inner.type === "ExpressionStatement" && typeof inner.directive === "string") return null;
+  if (inner.type === "VariableDeclaration")
+    return firstOf(inner.declarations, (item) => firstEffect(context, item.init));
+  if (inner.type === "ExportDefaultDeclaration" || inner.type === "ClassDeclaration")
+    return firstEffect(context, inner);
+  return inner;
+}
+
+/** Fails module-scope code that runs at import, reported on the first such node of each statement. */
+export const noModuleSideEffects: CreateRule = {
+  create(context) {
+    return {
+      Program(program) {
+        for (const statement of program.body) {
+          const effect = statementEffect(context, statement);
+          if (effect !== null) context.report({ message: MESSAGE, node: effect });
+        }
+      },
+    };
+  },
+};

package/cli/lint/no-module-state.ts

@@ -0,0 +1,58 @@
+import type { ESTree, CreateRule } from "@oxlint/plugins";
+
+const MESSAGE =
+  "module-scope state outlives every caller; move it into a function, or make it a const with a Readonly type";
+/** Wrappers that change a value's type, never the value: `(x)`, `x as T`, `x satisfies T`, `x!` and `<T>x`. */
+const WRAPPERS = [
+  "ParenthesizedExpression",
+  "TSAsExpression",
+  "TSSatisfiesExpression",
+  "TSNonNullExpression",
+  "TSTypeAssertion",
+];
+/** A const annotated with one of these is read-only to every caller, so it holds no state they can change. */
+const READONLY = ["ReadonlySet", "ReadonlyMap", "Readonly"];
+
+type Expression = ESTree.Expression;
+type Wrapper =
+  | ESTree.ParenthesizedExpression
+  | ESTree.TSAsExpression
+  | ESTree.TSSatisfiesExpression
+  | ESTree.TSNonNullExpression
+  | ESTree.TSTypeAssertion;
+
+const isWrapper = (node: Expression): node is Wrapper => WRAPPERS.includes(node.type);
+
+function unwrap(node: Expression | null): Expression | null {
+  let current = node;
+  while (current !== null && isWrapper(current)) current = current.expression;
+  return current;
+}
+
+function readonlyAnnotated(declarator: ESTree.VariableDeclarator): boolean {
+  const annotation = declarator.id.typeAnnotation?.typeAnnotation;
+  if (annotation?.type !== "TSTypeReference" || annotation.typeName.type !== "Identifier") return false;
+  return READONLY.includes(annotation.typeName.name);
+}
+
+/** A declarator whose value is constructed once at import and shared by every caller. */
+function constructed(declarator: ESTree.VariableDeclarator): boolean {
+  return unwrap(declarator.init)?.type === "NewExpression" && !readonlyAnnotated(declarator);
+}
+
+function isState(node: ESTree.VariableDeclaration): boolean {
+  if (node.declare === true) return false;
+  return node.kind !== "const" || node.declarations.some(constructed);
+}
+
+/** Fails a module-scope `let`, `var` or `using`, and a `const` holding a `new` object, exported or not. */
+export const noModuleState: CreateRule = {
+  create(context) {
+    return {
+      VariableDeclaration(node) {
+        const statement = node.parent.type === "ExportNamedDeclaration" ? node.parent : node;
+        if (statement.parent.type === "Program" && isState(node)) context.report({ message: MESSAGE, node });
+      },
+    };
+  },
+};

package/cli/lint/no-side-effect-import.ts

@@ -0,0 +1,17 @@
+import type { CreateRule } from "@oxlint/plugins";
+
+/**
+ * Fails an import that binds nothing: it is there only to run the module, so importing it has an effect no caller
+ * chose. `import type` is erased and passes.
+ */
+export const noSideEffectImport: CreateRule = {
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        if (node.specifiers.length > 0 || node.importKind === "type") return;
+        const message = `import "${node.source.value}" runs a module for its effects; import a function from it and call that`;
+        context.report({ message, node });
+      },
+    };
+  },
+};

package/cli/lint/no-v8-ignore.ts

@@ -0,0 +1,18 @@
+import type { CreateRule } from "@oxlint/plugins";
+
+/** The v8 coverage provider honors all three tools' hints; each hides uncovered code behind a full score. */
+const HINT = /\b(?:v8|c8|istanbul)\s+ignore\b/i;
+const MESSAGE = "coverage ignore comments hide untested code; delete the code or add a test that runs it";
+
+/** Fails every coverage ignore comment, reported on the comment. */
+export const noV8Ignore: CreateRule = {
+  create(context) {
+    return {
+      Program() {
+        for (const comment of context.sourceCode.getAllComments()) {
+          if (HINT.test(comment.value)) context.report({ message: MESSAGE, node: comment });
+        }
+      },
+    };
+  },
+};

package/cli/lint/script-rules.ts

@@ -0,0 +1,9 @@
+/**
+ * The checks `repo check`, `repo turn` and `repo lint --baseline` run beside oxlint as scripts on the TypeScript
+ * compiler API, by the names `lint.skip` takes. Kept apart from the checks so the oxlint config can accept the names
+ * without loading typescript.
+ */
+export const MAGIC_NUMBER = "repo/magic-number";
+export const MAGIC_STRING = "repo/magic-string";
+export const GUARD_REJECTS = "repo/guard-rejects";
+export const SCRIPT_RULES: readonly string[] = [MAGIC_NUMBER, MAGIC_STRING, GUARD_REJECTS];

package/cli/lint/skip-on-platform.constants.ts

@@ -0,0 +1,8 @@
+export const SKIP = "skip";
+export const GLOBAL_OBJECT = "globalThis";
+export const PROCESS = "process";
+export const VERSIONS = "versions";
+export const TYPEOF = "typeof";
+export const UNDEFINED = "undefined";
+/** Typed `string` so a node type compares to it without narrowing. */
+export const PAREN: string = "ParenthesizedExpression";

package/cli/lint/skip-on-platform.ts

@@ -0,0 +1,118 @@
+import type { CreateRule, ESTree } from "@oxlint/plugins";
+import { GLOBAL_OBJECT, PAREN, PROCESS, SKIP, TYPEOF, UNDEFINED, VERSIONS } from "./skip-on-platform.constants.ts";
+
+type Node = ESTree.Node;
+
+/** The test functions whose `skipIf` and `runIf` take a skip condition. */
+const TEST_FUNCTIONS = ["it", "test", "describe"];
+/** Chains that keep a test function a test function: `it.concurrent.skipIf`. */
+const CHAINS = ["concurrent", "sequential"];
+const CONDITIONAL = ["skipIf", "runIf"];
+const PLATFORM_READS = ["platform", "arch"];
+const COMPARISONS = ["===", "!==", "==", "!=", "<", ">", "<=", ">="];
+const JOINS = ["&&", "||"];
+const UNARY = ["!", "-"];
+const NOTHING = "no condition";
+const tail =
+  "a test may skip only on process.platform, process.arch, process.versions or a runtime global, so make it hermetic instead";
+
+const nameOf = (node: Node | null | undefined): string | undefined =>
+  node?.type === "Identifier" ? node.name : undefined;
+
+/** The plain name of `.name` on a member read, or undefined for `[expr]` and private names. */
+const memberName = (node: ESTree.MemberExpression): string | undefined =>
+  node.computed ? undefined : nameOf(node.property);
+
+/** `it`, `test` or `describe`, bare or through `.concurrent` and `.sequential`. */
+function isTestFunction(node: Node): boolean {
+  if (node.type === "Identifier") return TEST_FUNCTIONS.includes(node.name);
+  return node.type === "MemberExpression" && CHAINS.includes(memberName(node) ?? "") && isTestFunction(node.object);
+}
+
+/** `it.skipIf` or `describe.concurrent.runIf`: the name of the conditional call, or undefined. */
+function conditionalName(callee: Node): string | undefined {
+  if (callee.type !== "MemberExpression") return undefined;
+  const name = memberName(callee);
+  return name !== undefined && CONDITIONAL.includes(name) && isTestFunction(callee.object) ? name : undefined;
+}
+
+/** `process.platform`, `process.arch`, `process.versions.<name>` or `globalThis.<name>`. */
+function isRuntimeRead(node: ESTree.MemberExpression): boolean {
+  const name = memberName(node);
+  const { object } = node;
+  if (name === undefined) return false;
+  if (nameOf(object) === GLOBAL_OBJECT) return true;
+  if (nameOf(object) === PROCESS) return PLATFORM_READS.includes(name);
+  return object.type === "MemberExpression" && nameOf(object.object) === PROCESS && memberName(object) === VERSIONS;
+}
+
+type Parenthesized = { type: typeof PAREN; expression: Node };
+
+/** `(x)`: oxlint drops the parentheses, but a parser that keeps them (as the test harness's does) yields this node. */
+const isParenthesized = (node: Node): node is Node & Parenthesized => node.type === PAREN;
+
+/** The operand a unary read passes through: `!x` and `-x` read what `x` reads, `typeof <identifier>` reads nothing. */
+function unaryLeaf(node: ESTree.UnaryExpression): Node | undefined {
+  if (node.operator === TYPEOF) return node.argument.type === "Identifier" ? undefined : node;
+  return UNARY.includes(node.operator) ? firstLeaf(node.argument) : node;
+}
+
+/** The first leaf of `a <op> b`, when `op` is a comparison or a join. */
+function binaryLeaf(
+  node: ESTree.BinaryExpression | ESTree.LogicalExpression | ESTree.PrivateInExpression,
+): Node | undefined {
+  if (!COMPARISONS.includes(node.operator) && !JOINS.includes(node.operator)) return node;
+  return firstLeaf(node.left) ?? firstLeaf(node.right);
+}
+
+/** The part of a condition that reads anything but the platform or runtime, as the node to name; undefined if none. */
+function firstLeaf(node: Node): Node | undefined {
+  if (isParenthesized(node)) return firstLeaf(node.expression);
+  if (node.type === "Literal") return undefined;
+  if (node.type === "Identifier") return node.name === UNDEFINED ? undefined : node;
+  if (node.type === "MemberExpression") return isRuntimeRead(node) ? undefined : node;
+  if (node.type === "UnaryExpression") return unaryLeaf(node);
+  if (node.type === "BinaryExpression" || node.type === "LogicalExpression") return binaryLeaf(node);
+  return node;
+}
+
+/** The function a test hands its context to, when `node` is one: `(ctx) => {}` or `function (ctx) {}`. */
+function contextParam(node: Node): string | undefined {
+  if (node.type !== "ArrowFunctionExpression" && node.type !== "FunctionExpression") return undefined;
+  const callee = node.parent.type === "CallExpression" ? node.parent.callee : undefined;
+  if (callee === undefined || !(isTestFunction(callee) || conditionalName(callee) !== undefined)) return undefined;
+  return nameOf(node.params[0]);
+}
+
+/** Whether `name` is the context parameter of a test callback around `node`: `it("x", (ctx) => { ctx.skip(...) })`. */
+function isTestContext(node: Node, name: string): boolean {
+  for (let at: Node | null | undefined = node.parent; at; at = at.parent) {
+    if (contextParam(at) === name) return true;
+  }
+  return false;
+}
+
+/** Fails a `skipIf`, `runIf` or `ctx.skip` whose condition reads anything but the platform or the runtime. */
+export const skipOnPlatform: CreateRule = {
+  create(context) {
+    const { text } = context.sourceCode;
+    const render = (node: Node): string => text.slice(node.start, node.end).replaceAll(/\s+/g, " ");
+    const check = (node: ESTree.CallExpression, who: string) => {
+      const [condition] = node.arguments;
+      const leaf = condition === undefined ? undefined : firstLeaf(condition);
+      if (condition !== undefined && leaf === undefined) return;
+      const what = leaf === undefined ? NOTHING : render(leaf.type === "CallExpression" ? leaf.callee : leaf);
+      context.report({ message: `${who} reads ${what}; ${tail}`, node });
+    };
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+        const conditional = conditionalName(callee);
+        if (conditional !== undefined) return check(node, conditional);
+        const isSkip = callee.type === "MemberExpression" && memberName(callee) === SKIP;
+        const owner = isSkip ? nameOf(callee.object) : undefined;
+        if (owner !== undefined && isTestContext(node, owner)) check(node, SKIP);
+      },
+    };
+  },
+};

package/cli/lint/todo-needs-id.ts

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { CreateRule } from "@oxlint/plugins";
+
+/** A comment line, past its `//`, `/*` or JSDoc `*`, that starts with the marker, and the `(…)` right after it. */
+const MARKER = /^[\s*]*(TODO|FIXME)\b(?:\(([^)]*)\))?/;
+const ISSUE = /^(?:#\d+|[A-Z][A-Z\d]*-\d+|https?:\/\/\S+)$/;
+const SLUG = /^[a-z\d]+(?:-[a-z\d]+)*$/;
+/** `path.join` reads `/` as the separator on every OS. */
+const LESSONS = ".repo/lessons";
+
+/** The nearest `.repo/lessons` dir at or above `start`, or null when none is. */
+function nearestLessons(start: string): string | null {
+  let dir = start;
+  while (!fs.existsSync(path.join(dir, LESSONS))) {
+    if (path.dirname(dir) === dir) return null;
+    dir = path.dirname(dir);
+  }
+  return path.join(dir, LESSONS);
+}
+
+const shown = (cwd: string, to: string): string => path.relative(cwd, to).replaceAll("\\", "/");
+
+/** Where the linted file is, and the dir paths in messages are relative to. */
+type Where = { cwd: string; filename: string };
+
+/** The message for a slug that names no lesson file in the nearest lessons dir, or null when one is there. */
+function lessonProblem(where: Where, slug: string): string | null {
+  const dir = nearestLessons(path.dirname(where.filename)) ?? path.join(where.cwd, LESSONS);
+  if (fs.existsSync(path.join(dir, `${slug}.md`))) return null;
+  return `"${slug}" names no lesson: add ${shown(where.cwd, dir)}/${slug}.md, or use an issue ID like TODO(#123)`;
+}
+
+/** The message for one comment line, or null when it starts with no marker or carries a good ID. */
+function problemOf(where: Where, line: string): string | null {
+  const match = MARKER.exec(line);
+  if (match === null) return null;
+  const word = String(match[1]);
+  const id = match[2] ?? "";
+  if (ISSUE.test(id)) return null;
+  if (SLUG.test(id)) return lessonProblem(where, id);
+  return `${word} needs an issue or lesson ID: ${word}(#123), ${word}(ABC-123) or ${word}(<lesson slug>)`;
+}
+
+/**
+ * Fails a `TODO` or `FIXME` that starts a comment or a JSDoc line without an ID someone can look up: `#12`, `ABC-12`,
+ * an issue URL, or the slug of a lesson in the nearest `.repo/lessons/`. A mention mid-sentence is prose and passes.
+ */
+export const todoNeedsId: CreateRule = {
+  create(context) {
+    const where: Where = { cwd: context.cwd, filename: context.filename };
+    return {
+      Program() {
+        for (const comment of context.sourceCode.getAllComments()) {
+          for (const line of comment.value.split("\n")) {
+            const message = problemOf(where, line);
+            if (message !== null) context.report({ message, node: comment });
+          }
+        }
+      },
+    };
+  },
+};

package/cli/lint/types-file.ts

@@ -0,0 +1,28 @@
+import type { CreateRule } from "@oxlint/plugins";
+import type { Statement } from "./names.ts";
+
+const MESSAGE = "a .types.ts file holds only exported types and interfaces; move this into a module";
+const TYPES = ["TSTypeAliasDeclaration", "TSInterfaceDeclaration"];
+
+/** `import type`, an exported type alias or interface, or `export type … from`. */
+function typeOnly(statement: Statement): boolean {
+  if (statement.type === "ImportDeclaration") return statement.importKind === "type";
+  if (statement.type === "ExportAllDeclaration") return statement.exportKind === "type";
+  if (statement.type !== "ExportNamedDeclaration") return false;
+  if (statement.declaration !== null) return TYPES.includes(statement.declaration.type);
+  return statement.source !== null && statement.exportKind === "type";
+}
+
+/** Fails every statement of a `*.types.ts` file that is not a type: such a file is erased whole at build. */
+export const typesFile: CreateRule = {
+  create(context) {
+    if (!context.filename.endsWith(".types.ts")) return {};
+    return {
+      Program(program) {
+        for (const statement of program.body) {
+          if (!typeOnly(statement)) context.report({ message: MESSAGE, node: statement });
+        }
+      },
+    };
+  },
+};

package/cli/lint-schema.ts

@@ -0,0 +1,32 @@
+/** The `lint` section of workerstack.config.ts: the sanctioned rule skips. */
+import { z } from "zod";
+import { isReason } from "./lint/is-reason.ts";
+
+const REASON_ERROR = "say why the rules are off, in three words or more";
+const SKIP_LIST = "must be a list of { files, rules, reason } entries";
+
+/** One sanctioned exception: oxlint rule keys turned off for the files the globs match, and why. */
+function skipSchema(): SkipSchema {
+  const list = (error: string, empty: string): ListSchema =>
+    z.array(z.string({ error }), { error }).min(1, { error: empty }).readonly();
+  return z.strictObject(
+    {
+      files: list("must be a list of file globs", "list at least one file glob"),
+      rules: list("must be a list of rule names", 'list at least one rule, like "repo/no-module-state"'),
+      reason: z.string({ error: REASON_ERROR }).refine(isReason, { error: REASON_ERROR }),
+    },
+    { error: 'must be an object like { files: ["src/a.ts"], rules: ["repo/no-module-state"], reason: "why" }' },
+  );
+}
+
+type ListSchema = z.ZodReadonly<z.ZodArray<z.ZodString>>;
+type SkipSchema = z.ZodObject<{ files: ListSchema; rules: ListSchema; reason: z.ZodString }, z.core.$strict>;
+type LintSchema = z.ZodObject<{ skip: z.ZodOptional<z.ZodReadonly<z.ZodArray<SkipSchema>>> }, z.core.$strict>;
+
+/** `lint`: the skips, built when the config schema is. */
+export function lintSchema(): LintSchema {
+  return z.strictObject(
+    { skip: z.array(skipSchema(), { error: SKIP_LIST }).readonly().optional() },
+    { error: "must be an object like { skip: [{ files, rules, reason }] }" },
+  );
+}

package/cli/magic/fixtures/magic-repo.ts

@@ -0,0 +1,64 @@
+/** Temp repos for the magic literal tests, the messages they expect, and a schema type to bound. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { scriptDiagnostics } from "../../script-diagnostics.ts";
+import type { Diagnostic } from "../../scripts/lint-baseline.ts";
+
+export const SLOW = 60_000;
+export const NUMBER = "repo(magic-number)";
+export const STRING = "repo(magic-string)";
+export const NAMES_NOTHING = (text: string) => `${text} names nothing; give it a named const`;
+export const BOUND = (call: string) =>
+  `${call} is a schema bound; import it from a *.constants.ts file or a constants package`;
+export const COMPARED = (text: string) =>
+  `"${text}" is compared to a plain string; type the value as a literal union or brand, or import the string from a *.constants.ts file`;
+export const COPIES = (name: string, text: string) =>
+  `${name} copies "${text}" locally to compare to a plain string; move it to a *.constants.ts file`;
+
+const temps: string[] = [];
+
+export function cleanTemps(): void {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/** A temp root holding `files`, removed by `cleanTemps`. */
+export function plant(files: Record<string, string>): string {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-magic-")));
+  temps.push(root);
+  for (const [rel, text] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), text);
+  }
+  return root;
+}
+
+/** The diagnostic of a hit at `at`, `<file>:<line>:<column>`. */
+export const hit = (at: string, rule: string, message: string): Diagnostic => ({
+  file: at.slice(0, at.indexOf(":")),
+  rule,
+  line: `${at}: error ${rule}: ${message}`,
+});
+
+/** Every hit of the planted `files`, all of them checked. */
+export function magicOf(files: Record<string, string>): Diagnostic[] {
+  const found = scriptDiagnostics(plant(files), Object.keys(files));
+  if (!found.ok) throw new Error(found.errors.join("\n"));
+  return found.value;
+}
+
+/** A schema type: the receiver of a bound has a `parse` method. */
+export const SCHEMA = [
+  "export class Schema {",
+  "  parse(value: unknown): unknown {",
+  "    return value;",
+  "  }",
+  "  max(_bound: number): Schema {",
+  "    return this;",
+  "  }",
+  "  min(_bound: number): Schema {",
+  "    return this;",
+  "  }",
+  "}",
+  "",
+].join("\n");

package/cli/magic/magic-hit.ts

@@ -0,0 +1,2 @@
+/** One magic literal: the file, offset and one-based line and column it is reported at, its rule and the fix. */
+export type MagicHit = { fileName: string; at: number; line: number; column: number; rule: string; message: string };

package/cli/magic/magic-nodes.ts

@@ -0,0 +1,44 @@
+/** What both magic checks ask of a syntax node: a const's string, where a hit sits, and the constants homes. */
+import ts from "typescript";
+import type { MagicHit } from "./magic-hit.ts";
+
+/** A `*.constants.ts` file (or its `.js`, `.mts`… spelling), as a path or an import specifier with or without one. */
+export const CONSTANTS_FILE: RegExp = /\.constants(?:\.[cm]?[jt]sx?)?$/;
+/** A package, scoped or not, whose name ends in `constants`, or a subpath of one. */
+const CONSTANTS_PACKAGE = /^(?:@[^/]+\/)?[^/]*constants(?:\/|$)/;
+/** A string with a letter or digit in it; one of punctuation or nothing says nothing a name could. */
+const MEANINGFUL = /[\p{L}\p{N}]/u;
+
+/** Whether an import of `specifier` reaches a constants file or a constants package. */
+export const isConstantsModule = (specifier: string): boolean =>
+  CONSTANTS_FILE.test(specifier) || CONSTANTS_PACKAGE.test(specifier);
+
+export const isConstDeclaration = (declaration: ts.VariableDeclaration): boolean =>
+  (ts.getCombinedNodeFlags(declaration) & ts.NodeFlags.Const) !== 0;
+
+/** `node` without the parentheses, `as` and `satisfies` around it, which change a type and never a value. */
+function unwrapped(node: ts.Expression): ts.Expression {
+  let bare = node;
+  while (ts.isParenthesizedExpression(bare) || ts.isAsExpression(bare) || ts.isSatisfiesExpression(bare))
+    bare = bare.expression;
+  return bare;
+}
+
+/** A string literal that says something: not empty and not punctuation alone. */
+export const isMeaningful = (node: ts.Expression): node is ts.StringLiteralLike =>
+  ts.isStringLiteralLike(node) && MEANINGFUL.test(node.text);
+
+/** The string a `const` holds, when its initializer is a literal that says something; null for any other. */
+export function constString(declaration: ts.VariableDeclaration): string | null {
+  if (declaration.initializer === undefined || !isConstDeclaration(declaration)) return null;
+  const value = unwrapped(declaration.initializer);
+  return isMeaningful(value) ? value.text : null;
+}
+
+/** A hit reported at the start of `node`, with its one-based line and column. */
+export function hitAt(node: ts.Node, rule: string, message: string): MagicHit {
+  const file = node.getSourceFile();
+  const at = node.getStart(file);
+  const { line, character } = file.getLineAndCharacterOfPosition(at);
+  return { fileName: file.fileName, at, line: line + 1, column: character + 1, rule, message };
+}

package/cli/magic/magic-numbers.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, expect, it } from "vitest";
+import {
+  BOUND,
+  cleanTemps,
+  hit,
+  magicOf,
+  NAMES_NOTHING,
+  NUMBER,
+  SCHEMA,
+  STRING,
+  COMPARED,
+} from "./fixtures/magic-repo.ts";
+
+afterEach(cleanTemps);
+
+const PASS = [
+  "export const RETRIES = 3;",
+  "export const LIMITS = { name: 64, list: [8, 16] } as const;",
+  "export const SIZES = [32, -64] satisfies number[];",
+  "export const MINUTE = (60 * 1000) as number;",
+  "export enum Level {",
+  "  Low = 5,",
+  "  High = 10,",
+  "}",
+  "export class Pool {",
+  "  static readonly MAX = 9;",
+  "  readonly size = 4;",
+  "}",
+  "export type Port = 8080;",
+  "export type Pair = [3, -4];",
+  "type Id = string & { __brand: 'Id' };",
+  "export function f(x: number, mode: 'fast' | 'slow', at: `/${string}`, id: Id, s: string): number {",
+  "  if (mode === 'fast' || at === '/a' || id !== 'abc') return 0;",
+  "  switch (mode) {",
+  "    case 'slow':",
+  "      return -0;",
+  "  }",
+  "  if (s === '' || s === '/' || s.split(', ').length === 1) return -0;",
+  "  return x * 2 + x / 2 + (x % 2) + 2 ** x + 1;",
+  "}",
+  "",
+].join("\n");
+
+it("passes identity values, scaling 2, named numbers, literal types and typed or punctuation strings", () => {
+  expect(magicOf({ "src/pass.ts": PASS })).toEqual([]);
+});
+
+const REFUSED = [
+  'import { Schema } from "./schema.ts";',
+  'import { NAME_MAX } from "./limits.constants.ts";',
+  'import { WIDTH } from "@acme/constants";',
+  'import * as limits from "./limits.constants.ts";',
+  "const LOCAL_MAX = 64;",
+  "let loose = 1;",
+  "export function g(x: number, s: Schema, kind: string): number {",
+  "  void s.max(LOCAL_MAX).max(NAME_MAX).max(WIDTH).min(1).max(x).max(limits.NAME_MAX).max(loose).max(missing);",
+  "  switch (kind) {",
+  '    case "deep":',
+  "      return x + 2;",
+  "    default:",
+  "      return Math.max(x, 3) - -1;",
+  "  }",
+  "}",
+  "",
+].join("\n");
+
+it("refuses -1, a 2 that does not scale, a local const bound, a string case and a bound off a schema", () => {
+  expect(
+    magicOf({
+      "src/refused.ts": REFUSED,
+      "src/schema.ts": SCHEMA,
+      "src/limits.constants.ts": "export const NAME_MAX = 2048;\n",
+    }),
+  ).toEqual([
+    hit("src/refused.ts:8:14", NUMBER, BOUND(".max(LOCAL_MAX)")),
+    hit("src/refused.ts:10:10", STRING, COMPARED("deep")),
+    hit("src/refused.ts:11:18", NUMBER, NAMES_NOTHING("2")),
+    hit("src/refused.ts:13:26", NUMBER, NAMES_NOTHING("3")),
+    hit("src/refused.ts:13:31", NUMBER, NAMES_NOTHING("-1")),
+  ]);
+});
+
+it("refuses a bound imported from a module that is not a constants file or package", () => {
+  const files = {
+    "src/a.ts": [
+      'import { Schema } from "./schema.ts";',
+      'import { MAX } from "./limits.ts";',
+      'import { TOP } from "@acme/limits";',
+      "export const a = (s: Schema) => s.max(MAX).max(TOP);",
+      "",
+    ].join("\n"),
+    "src/limits.ts": "export const MAX = 64;\n",
+    "src/schema.ts": SCHEMA,
+  };
+  expect(magicOf(files)).toEqual([
+    hit("src/a.ts:4:39", NUMBER, BOUND(".max(MAX)")),
+    hit("src/a.ts:4:48", NUMBER, BOUND(".max(TOP)")),
+  ]);
+});