@zgeoff/oxlint-config 0.2.12 → 0.2.13

package/README.md

@@ -10,8 +10,9 @@ that loosens either comment rule. `zgeoff/function-verb` enforces the function-n
 the shared agent guidelines, `zgeoff/test-beside-module` keeps each test file beside the module it
 tests, `zgeoff/import-zones` fails an import that crosses a module boundary the repo declares,
 `zgeoff/no-restricted-words` keeps the words in its `words` option out of a path's text,
-`zgeoff/no-abbreviated-names` reports each abbreviated value name it lists with its full word, and
-`zgeoff/no-file-snapshot` bans file snapshots.
+`zgeoff/no-abbreviated-names` reports each abbreviated value name it lists with its full word,
+`zgeoff/no-file-snapshot` bans file snapshots, and `zgeoff/setup-test-only` keeps a test file's
+module level to `setupTest()` and its tests.
 
 ## Usage
 
@@ -88,6 +89,29 @@ first statement, so put the comment above it:
 A second test file for a module (`<name>.host.test.ts`) needs its own `<name>.host.<ext>`, so the
 rule reports it beside only `<name>.ts`.
 
+## `zgeoff/setup-test-only`
+
+A `<name>.test.ts` or `<name>.test.tsx` file declares one function, `setupTest()`, and nothing else,
+as the testing skill requires. At module level the rule allows imports, `type` and `interface`
+declarations, one `setupTest` function declaration, and statements that call `test`, `test.each`,
+`test.skipIf` or `test.if`, or a chain of them, with `test` under its local alias when the
+`bun:test` import renames it. It reports every other statement: a `let`, a `var`, a class, an enum,
+a second function, an export, and a call such as `beforeEach(...)`. The message holds the three ways
+out of a helper: inline it, swap it for a registered matcher, or move it to the shared test utils
+with tests of its own.
+
+A module-level `const` passes only as a skip gate: a declarator that binds at least one name, each
+binding read, and read only at collection time, inside an argument of the test runner's `skipIf` or
+inside the initializer of another gate. The runner is `test` as `bun:test` exports it, under its
+local alias if the import renames it, or a chain of its modifiers, so `matrix.skipIf(rows)` is not a
+gate read. A file that imports no `test` uses the global one, unless an import or a module-level
+declaration of its own takes the name `test`. A read inside a function never counts, so a `skipIf`
+in `setupTest()` or a test body leaves its `const` reported. A gate derived from an awaited probe
+passes beside the probe, in the same declaration or its own, but consts that only read each other
+never reach a `skipIf` and report. A `const` that nothing reads reports too, and so does a
+declarator that binds nothing, such as `const {} = registerHooks()`. The rule does not check the
+comment that the skill asks a gate to carry.
+
 ## `zgeoff/no-restricted-words`
 
 Off unless a repo configures it. The `words` option lists the words to keep out of the text of a

package/oxlintrc.json

@@ -32,6 +32,7 @@
     "zgeoff/function-verb": "error",
     "zgeoff/test-beside-module": "error",
     "zgeoff/no-file-snapshot": "error",
+    "zgeoff/setup-test-only": "error",
 
     // name a value for what it holds, in full words: one letter only for a
     // coordinate, zod's `z`, Bun's shell `$` or an unread `_` placeholder, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/oxlint-config",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Shareable oxlint config: strict categories, house-style rules, and a custom JS plugin",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
     "no-comment-rule-override.js",
     "test-beside-module.js",
     "no-file-snapshot.js",
+    "setup-test-only.js",
     "import-zones.js",
     "import-zones-schema.js",
     "find-repo-root.js",

package/plugin.js

@@ -6,6 +6,7 @@ import noCommentRuleOverride from './no-comment-rule-override.js';
 import noFileSnapshot from './no-file-snapshot.js';
 import noJSDoc from './no-jsdoc.js';
 import noRestrictedWords from './no-restricted-words.js';
+import setupTestOnly from './setup-test-only.js';
 import testBesideModule from './test-beside-module.js';
 
 // custom rules loaded through oxlint's jsPlugins (ESLint v9 rule API): each
@@ -111,6 +112,7 @@ const plugin = {
     'no-abbreviated-names': noAbbreviatedNames,
     'test-beside-module': testBesideModule,
     'no-file-snapshot': noFileSnapshot,
+    'setup-test-only': setupTestOnly,
     'import-zones': importZones,
   },
 };

package/setup-test-only.js

@@ -0,0 +1,269 @@
+import { basename } from 'node:path';
+
+const testFilePattern = /\.test\.tsx?$/u;
+
+// the statements a test file holds besides its tests and `setupTest()`:
+// imports and type-only declarations, which run nothing at module level
+const allowedStatementTypes = new Set([
+  'ImportDeclaration',
+  'TSTypeAliasDeclaration',
+  'TSInterfaceDeclaration',
+]);
+
+// the members a `test` call may chain: `test.each(rows)(…)`,
+// `test.skipIf(gate)(…)`, `test.if(gate)(…)`, and chains of them
+const testModifiers = new Set(['each', 'skipIf', 'if']);
+
+const setupTestOnly = {
+  meta: {
+    type: 'problem',
+    messages: {
+      declaration:
+        'Remove the module-level `{{name}}`: a test file declares one function, `setupTest()`, and nothing else. Inline it where it is used, swap it for a registered matcher, or move it to the shared test utils with tests of its own. A module-level `const` stays only as a skip gate that `skipIf(...)` arguments alone read.',
+      statement:
+        'Move this statement into a test or `setupTest()`: at module level a test file holds only imports, types, `setupTest()` and `test` calls.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      Program(program) {
+        if (!testFilePattern.test(basename(context.physicalFilename))) {
+          return;
+        }
+
+        const testNames = collectTestNames(context, program);
+        const constants = [];
+        let hasSetupTest = false;
+
+        for (const statement of program.body) {
+          if (allowedStatementTypes.has(statement.type) || isTestCall(statement, testNames)) {
+            continue;
+          }
+
+          if (
+            statement.type === 'FunctionDeclaration' &&
+            statement.id?.name === 'setupTest' &&
+            !hasSetupTest
+          ) {
+            hasSetupTest = true;
+
+            continue;
+          }
+
+          if (statement.type === 'VariableDeclaration' && statement.kind === 'const') {
+            constants.push(...statement.declarations);
+
+            continue;
+          }
+
+          emitReport(context, statement);
+        }
+
+        const gates = collectSkipGates(context, constants, testNames);
+        const declarations = new Set(constants.map((declarator) => declarator.parent));
+
+        for (const declaration of declarations) {
+          const leaks = declaration.declarations.filter((declarator) => !gates.has(declarator));
+
+          if (leaks.length > 0) {
+            emitReport(context, declaration, leaks);
+          }
+        }
+      },
+    };
+  },
+};
+
+// the local names that `test` from `bun:test` goes by, so an aliased import
+// such as `import { test as check }` counts; a file that imports no `test`
+// reads the global one, unless a module binding of its own takes the name
+function collectTestNames(context, program) {
+  const names = program.body
+    .filter(
+      (statement) =>
+        statement.type === 'ImportDeclaration' &&
+        statement.source.value === 'bun:test' &&
+        statement.importKind !== 'type',
+    )
+    .flatMap((statement) => statement.specifiers)
+    .filter(
+      (specifier) =>
+        specifier.type === 'ImportSpecifier' &&
+        specifier.importKind !== 'type' &&
+        getImportedName(specifier) === 'test',
+    )
+    .map((specifier) => specifier.local.name);
+
+  if (names.length === 0 && !hasModuleBinding(context, program, 'test')) {
+    return new Set(['test']);
+  }
+
+  return new Set(names);
+}
+
+// every import form and every module-level declaration defines a binding in
+// the module scope, which ESM nests under the global one
+function hasModuleBinding(context, program, name) {
+  const scope = context.sourceCode.getScope(program);
+  const scopes = [scope, ...scope.childScopes.filter((child) => child.type === 'module')];
+
+  return scopes.some((candidate) => (candidate.set.get(name)?.defs.length ?? 0) > 0);
+}
+
+function getImportedName(specifier) {
+  return specifier.imported.type === 'Identifier'
+    ? specifier.imported.name
+    : specifier.imported.value;
+}
+
+function isTestCall(statement, testNames) {
+  return (
+    statement.type === 'ExpressionStatement' &&
+    statement.expression.type === 'CallExpression' &&
+    isTestRunner(statement.expression.callee, testNames)
+  );
+}
+
+// `test` itself or a chain of its modifiers, such as `test.skipIf(gate).each(rows)`
+function isTestRunner(node, testNames) {
+  let current = node;
+
+  while (current.type !== 'Identifier') {
+    if (current.type === 'CallExpression') {
+      current = current.callee;
+    } else if (
+      current.type === 'MemberExpression' &&
+      !current.computed &&
+      testModifiers.has(current.property.name)
+    ) {
+      current = current.object;
+    } else {
+      return false;
+    }
+  }
+
+  return testNames.has(current.name);
+}
+
+function emitReport(context, statement, declarators) {
+  const name = findDeclaredName(context, statement, declarators);
+
+  if (name === undefined) {
+    context.report({ node: statement, messageId: 'statement' });
+
+    return;
+  }
+
+  context.report({ node: statement, messageId: 'declaration', data: { name } });
+}
+
+function findDeclaredName(context, statement, declarators) {
+  if (statement.type === 'VariableDeclaration') {
+    return (declarators ?? statement.declarations)
+      .flatMap((declarator) => context.sourceCode.getDeclaredVariables(declarator))
+      .map((variable) => variable.name)
+      .join('`, `');
+  }
+
+  return statement.id?.name;
+}
+
+// a gate is a declarator whose every binding is read, only in a `skipIf(...)`
+// argument or another gate's initializer; the set grows out from the `skipIf`
+// reads, so consts that only read each other never join it
+function collectSkipGates(context, constants, testNames) {
+  const gates = new Set();
+  let changed = true;
+
+  while (changed) {
+    changed = false;
+
+    for (const declarator of constants) {
+      if (!gates.has(declarator) && isSkipGate(context, declarator, gates, testNames)) {
+        gates.add(declarator);
+        changed = true;
+      }
+    }
+  }
+
+  return gates;
+}
+
+function isSkipGate(context, declarator, gates, testNames) {
+  const variables = context.sourceCode.getDeclaredVariables(declarator);
+
+  // a declarator that binds nothing, such as `const {} = registerHooks()`, is
+  // a module-level call, not a gate
+  return (
+    variables.length > 0 &&
+    variables.every((variable) => {
+      const reads = variable.references.filter(
+        (reference) => !reference.init && reference.isRead(),
+      );
+
+      return (
+        reads.length > 0 &&
+        reads.every(
+          (reference) =>
+            isInSkipIfArgument(reference.identifier, testNames) ||
+            isInGateInit(reference.identifier, gates),
+        )
+      );
+    })
+  );
+}
+
+const functionTypes = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+]);
+
+// a read counts only at collection time, so no function may enclose it: a
+// `skipIf` inside `setupTest()` or a test runs later
+function isInSkipIfArgument(identifier, testNames) {
+  let child = identifier;
+  let isSkipIfArgument = false;
+
+  for (let node = identifier.parent; node !== null && node !== undefined; node = node.parent) {
+    if (functionTypes.has(node.type)) {
+      return false;
+    }
+
+    if (
+      node.type === 'CallExpression' &&
+      node.arguments.includes(child) &&
+      node.callee.type === 'MemberExpression' &&
+      !node.callee.computed &&
+      node.callee.property.name === 'skipIf' &&
+      isTestRunner(node.callee.object, testNames)
+    ) {
+      isSkipIfArgument = true;
+    }
+
+    child = node;
+  }
+
+  return isSkipIfArgument;
+}
+
+function isInGateInit(identifier, gates) {
+  let child = identifier;
+
+  for (let node = identifier.parent; isOutsideFunction(node); node = node.parent) {
+    if (node.type === 'VariableDeclarator') {
+      return node.init === child && gates.has(node);
+    }
+
+    child = node;
+  }
+
+  return false;
+}
+
+function isOutsideFunction(node) {
+  return node !== null && node !== undefined && !functionTypes.has(node.type);
+}
+
+export default setupTestOnly;