@sarj/eslint-plugin 4.0.0 → 4.1.0

package/README.md

@@ -12,10 +12,47 @@ import sarj from "@sarj/eslint-plugin";
 export default [...sarj.configs.recommended];
 ```
 
-46 rules. Each rule's source under `src/rules/` carries its own `@fileoverview` rationale plus `meta.docs.description` + `meta.messages` — read the file for the full reasoning, including the false positives it deliberately does not fire on.
+51 rules. Each rule's source under `src/rules/` carries its own `@fileoverview` rationale plus `meta.docs.description` + `meta.messages` — read the file for the full reasoning, including the false positives it deliberately does not fire on.
 
 Presets: `recommended` (warn-first), `strict` (every rule at error), `style-guide` (formatting/naming subset).
 
+## New in 4.1.0 — `no-hand-rolled-sleep`
+
+`new Promise((resolve) => setTimeout(resolve, ms))` is `node:timers/promises`'s
+`setTimeout` rewritten by hand, minus the `AbortSignal` — so it is a capability
+loss, not verbosity. The hand-rolled sleep holds a live timer that nothing can
+clear, and its mirror image, the `Promise.race([work, rejectAfter(ms)])` timeout
+arm, leaks the timer the other way: when `work` wins, nothing clears it and it
+keeps the event loop alive until it fires.
+
+Shipped only after confirming nothing already enabled reports this position. The
+enabled set was resolved with `ESLint#calculateConfigForFile` against the shipped
+`eslint.strict.mjs` (204 rules before this one) and a file containing every
+shape was linted through it: no report. `eslint-plugin-unicorn` 72 has no
+promisified-timer rule among its 341; `unicorn/prefer-abort-signal-timeout` covers the
+`AbortController` + `setTimeout` idiom and not the race arm; core
+`no-promise-executor-return` fires on the concise-arrow spelling only and its
+remedy ("add braces") entrenches the hand-rolled sleep. The polling-loop variant
+(`while (!done) await sleep(ms)`) is deliberately absent — core `no-await-in-loop`
+is already enabled and reports that exact position.
+
+Measured over 1,471 files containing `setTimeout` across 15 OSS repos (hono,
+tRPC, drizzle-orm, undici, vitest, got, cal.com, documenso, dub, formbricks,
+midday, openstatus, papermark, unkey, zod) and seven internal ones: 85 + 11
+sleeps and 2 + 1 leaky race arms at the default settings, **0 false positives**.
+
+`checkClientModules` is the option that matters. A browser or React Native
+bundle cannot import `node:timers/promises` and the web platform ships no
+equivalent, so client modules are skipped by default — 79% of the internal
+corpus's occurrences live in `.tsx` components where the fix cannot be applied.
+Turn it on only in a tree where every file resolves `node:` builtins. The race
+message is reported everywhere regardless: `AbortSignal.timeout` is on the web
+platform too.
+
+| Rule | What it catches | Preset |
+|---|---|---|
+| `no-hand-rolled-sleep` | `new Promise((r) => setTimeout(r, ms))` in any spelling, and an uncleared `Promise.race`/`Promise.any` timeout arm. Options: `checkClientModules` (default `false`), `allowIn`. | warn / error |
+
 ## New in 2.14.0 — `no-tautological-expect`
 
 The TS half of SARJ057. An `expect(...)` whose operands are all literals has
@@ -125,7 +162,7 @@ Glob patterns whose files opt out (generated code already opts out by default).
 
 ## Configurable rules
 
-Most rules take no options. These three do, because they encode a codebase's
+Most rules take no options. These do, because they encode a codebase's
 architecture rather than a language fact — the defaults describe one convention
 and every repo gets to name its own.
 
@@ -135,10 +172,15 @@ and every repo gets to name its own.
 | `no-dynamic-sql` | `methods` | `["prepare", "exec", "query"]` | Statement-taking methods to inspect |
 | `no-storage-in-stateless-modules` | `modules` | `[]` (rule off) | Directories declared stateless |
 | `no-storage-in-stateless-modules` | `methods` | `["prepare", "put", "getWithMetadata"]` | Storage methods to flag |
-
-Every option value is a **regular-expression source matched against the absolute
-filename**, not a glob — so it can express both path separators. Supplying an
-option **replaces** the default rather than extending it.
+| `no-hand-rolled-sleep` | `checkClientModules` | `false` | Also report the sleep form in browser/React Native modules |
+| `no-hand-rolled-sleep` | `allowIn` | `[]` | Glob patterns for a sanctioned sleep wrapper module |
+
+The path options on the first three rules are **regular-expression sources
+matched against the absolute filename**, not globs — so they can express both
+path separators. `allowIn` is the exception, on `no-hand-rolled-sleep` as on
+`require-fetch-timeout`: it takes minimatch-ish **globs**, also matched against
+the absolute path, so anchor them with a `**/` prefix. Supplying an option
+**replaces** the default rather than extending it.
 
 `no-storage-in-stateless-modules` is a **no-op until `modules` is set**. The
 method names alone (`put`, `prepare`) carry no type information, so the rule is

package/dist/index.cjs

@@ -7388,9 +7388,186 @@ var no_async_callback_in_waitfor_default = import_utils54.ESLintUtils.RuleCreato
   }
 });
 
-// src/rules/prefer-setup-file-mocks.ts
+// src/rules/no-hand-rolled-sleep.ts
 var import_utils55 = require("@typescript-eslint/utils");
-var prefer_setup_file_mocks_default = import_utils55.ESLintUtils.RuleCreator(
+var GLOBAL_OBJECTS2 = /* @__PURE__ */ new Set([
+  "globalThis",
+  "window",
+  "self",
+  "global"
+]);
+var CLIENT_ONLY_MODULES = /^(react|react-dom|react-native|svelte|vue|preact|solid-js)(\/|$)|^next\/(navigation|router|link|image)$/;
+var RACE_METHODS = /* @__PURE__ */ new Set(["race", "any"]);
+function matchesAnyPattern3(filename, patterns) {
+  for (const pattern of patterns) {
+    const regexSource = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "::DOUBLESTAR::").replace(/\*/g, "[^/\\\\]*").replace(/::DOUBLESTAR::/g, ".*");
+    if (new RegExp(`^${regexSource}$`).test(filename)) {
+      return true;
+    }
+  }
+  return false;
+}
+function isSetTimeoutCallee(callee) {
+  if (callee.type === import_utils55.AST_NODE_TYPES.Identifier) {
+    return callee.name === "setTimeout";
+  }
+  return callee.type === import_utils55.AST_NODE_TYPES.MemberExpression && !callee.computed && callee.property.type === import_utils55.AST_NODE_TYPES.Identifier && callee.property.name === "setTimeout" && callee.object.type === import_utils55.AST_NODE_TYPES.Identifier && GLOBAL_OBJECTS2.has(callee.object.name);
+}
+function soleCall(fn) {
+  if (fn.body.type !== import_utils55.AST_NODE_TYPES.BlockStatement) {
+    return fn.body.type === import_utils55.AST_NODE_TYPES.CallExpression ? fn.body : null;
+  }
+  if (fn.body.body.length !== 1) {
+    return null;
+  }
+  const [only] = fn.body.body;
+  if (only?.type !== import_utils55.AST_NODE_TYPES.ExpressionStatement) {
+    return null;
+  }
+  return only.expression.type === import_utils55.AST_NODE_TYPES.CallExpression ? only.expression : null;
+}
+function isTimedDelay(delay) {
+  if (delay === void 0) {
+    return false;
+  }
+  if (delay.type === import_utils55.AST_NODE_TYPES.Literal && typeof delay.value === "number") {
+    return delay.value !== 0;
+  }
+  return true;
+}
+function settlesWithoutValue(callback, name) {
+  if (callback.type === import_utils55.AST_NODE_TYPES.Identifier) {
+    return callback.name === name;
+  }
+  if (callback.type !== import_utils55.AST_NODE_TYPES.ArrowFunctionExpression && callback.type !== import_utils55.AST_NODE_TYPES.FunctionExpression) {
+    return false;
+  }
+  const call = soleCall(callback);
+  return call !== null && call.arguments.length === 0 && call.callee.type === import_utils55.AST_NODE_TYPES.Identifier && call.callee.name === name;
+}
+function rejectsInCallback(callback, name) {
+  if (callback.type === import_utils55.AST_NODE_TYPES.Identifier) {
+    return callback.name === name;
+  }
+  if (callback.type !== import_utils55.AST_NODE_TYPES.ArrowFunctionExpression && callback.type !== import_utils55.AST_NODE_TYPES.FunctionExpression) {
+    return false;
+  }
+  const call = soleCall(callback);
+  return call !== null && call.callee.type === import_utils55.AST_NODE_TYPES.Identifier && call.callee.name === name;
+}
+function parameterName(fn, index) {
+  const parameter = fn.params[index];
+  return parameter?.type === import_utils55.AST_NODE_TYPES.Identifier ? parameter.name : null;
+}
+function isRaceArm(node) {
+  const array = node.parent;
+  if (array?.type !== import_utils55.AST_NODE_TYPES.ArrayExpression) {
+    return false;
+  }
+  const call = array.parent;
+  return call?.type === import_utils55.AST_NODE_TYPES.CallExpression && call.arguments[0] === array && call.callee.type === import_utils55.AST_NODE_TYPES.MemberExpression && !call.callee.computed && call.callee.object.type === import_utils55.AST_NODE_TYPES.Identifier && call.callee.object.name === "Promise" && call.callee.property.type === import_utils55.AST_NODE_TYPES.Identifier && RACE_METHODS.has(call.callee.property.name);
+}
+var no_hand_rolled_sleep_default = import_utils55.ESLintUtils.RuleCreator(
+  (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
+)({
+  name: "no-hand-rolled-sleep",
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow hand-rolled promisified timers (`new Promise((r) => setTimeout(r, ms))`) and hand-rolled `Promise.race` timeout arms; the stdlib forms are cancellable, these are not."
+    },
+    schema: [
+      {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          allowIn: {
+            description: "Glob patterns for modules exempt from the rule (e.g. a single sanctioned `sleep` utility). Matched against the ABSOLUTE file path, so anchor with a `**/` prefix (e.g. `**/lib/sleep.ts`).",
+            type: "array",
+            items: { type: "string" }
+          },
+          checkClientModules: {
+            description: "Also report the sleep form in browser/React Native modules. Off by default: those bundles cannot import `node:timers/promises` and the web platform has no equivalent, so the fix is impossible to follow. Turn on only where every file can resolve `node:` builtins.",
+            type: "boolean"
+          }
+        }
+      }
+    ],
+    messages: {
+      handRolledSleep: 'Hand-rolled sleep: `new Promise((resolve) => setTimeout(resolve, ms))` cannot be cancelled, so an aborted request or a lost race still waits out the full delay. Use `import { setTimeout as sleep } from "node:timers/promises"` and pass `{ signal }`.',
+      handRolledTimeoutRace: "Hand-rolled timeout arm: when the other promise wins, this timer is never cleared and keeps the event loop alive until it fires. Use `AbortSignal.timeout(ms)` and pass the signal to the operation."
+    }
+  },
+  defaultOptions: [{}],
+  create(context, [optionsArg]) {
+    const { filename, sourceCode } = context;
+    if (isTestFile(filename) || isScriptFile(filename) || isGeneratedFile(filename, sourceCode.getText())) {
+      return {};
+    }
+    const allowIn = optionsArg?.allowIn ?? [];
+    if (allowIn.length > 0 && matchesAnyPattern3(filename, allowIn)) {
+      return {};
+    }
+    const checkClientModules = optionsArg?.checkClientModules ?? false;
+    function isClientModule() {
+      if (/\.[cm]?[jt]sx$/.test(filename)) {
+        return true;
+      }
+      const program = sourceCode.ast;
+      for (const statement of program.body) {
+        if (statement.type === import_utils55.AST_NODE_TYPES.ExpressionStatement && statement.expression.type === import_utils55.AST_NODE_TYPES.Literal && statement.expression.value === "use client") {
+          return true;
+        }
+        if (statement.type === import_utils55.AST_NODE_TYPES.ImportDeclaration && typeof statement.source.value === "string" && CLIENT_ONLY_MODULES.test(statement.source.value)) {
+          return true;
+        }
+      }
+      return false;
+    }
+    let clientModule = null;
+    const reportsSleepHere = () => {
+      if (checkClientModules) {
+        return true;
+      }
+      clientModule ??= isClientModule();
+      return !clientModule;
+    };
+    return {
+      NewExpression(node) {
+        if (node.callee.type !== import_utils55.AST_NODE_TYPES.Identifier || node.callee.name !== "Promise") {
+          return;
+        }
+        const executor = node.arguments[0];
+        if (executor?.type !== import_utils55.AST_NODE_TYPES.ArrowFunctionExpression && executor?.type !== import_utils55.AST_NODE_TYPES.FunctionExpression) {
+          return;
+        }
+        const call = soleCall(executor);
+        if (call === null || !isSetTimeoutCallee(call.callee)) {
+          return;
+        }
+        const [callback, delay] = call.arguments;
+        if (callback === void 0 || !isTimedDelay(delay)) {
+          return;
+        }
+        const resolveName = parameterName(executor, 0);
+        if (resolveName !== null && settlesWithoutValue(callback, resolveName)) {
+          if (reportsSleepHere()) {
+            context.report({ node, messageId: "handRolledSleep" });
+          }
+          return;
+        }
+        const rejectName = parameterName(executor, 1);
+        if (rejectName !== null && isRaceArm(node) && rejectsInCallback(callback, rejectName)) {
+          context.report({ node, messageId: "handRolledTimeoutRace" });
+        }
+      }
+    };
+  }
+});
+
+// src/rules/prefer-setup-file-mocks.ts
+var import_utils56 = require("@typescript-eslint/utils");
+var prefer_setup_file_mocks_default = import_utils56.ESLintUtils.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
   name: "prefer-setup-file-mocks",
@@ -7411,7 +7588,7 @@ var prefer_setup_file_mocks_default = import_utils55.ESLintUtils.RuleCreator(
     }
     return {
       CallExpression(node) {
-        if (node.callee.type === import_utils55.AST_NODE_TYPES.MemberExpression && node.callee.object.type === import_utils55.AST_NODE_TYPES.Identifier && (node.callee.object.name === "vi" || node.callee.object.name === "jest") && node.callee.property.type === import_utils55.AST_NODE_TYPES.Identifier && node.callee.property.name === "mock") {
+        if (node.callee.type === import_utils56.AST_NODE_TYPES.MemberExpression && node.callee.object.type === import_utils56.AST_NODE_TYPES.Identifier && (node.callee.object.name === "vi" || node.callee.object.name === "jest") && node.callee.property.type === import_utils56.AST_NODE_TYPES.Identifier && node.callee.property.name === "mock") {
           context.report({
             node,
             messageId: "preferSetupFileMocks"
@@ -7456,6 +7633,7 @@ var rules = {
   "no-repeated-string-literal": no_repeated_string_literal_default,
   "no-select-star": no_select_star_default,
   "no-sleep-in-test-body": no_sleep_in_test_body_default,
+  "no-hand-rolled-sleep": no_hand_rolled_sleep_default,
   "no-conditional-in-test": no_conditional_in_test_default,
   "prefer-constant-time-secret-compare": prefer_constant_time_secret_compare_default,
   "store-insert-requires-on-conflict": store_insert_requires_on_conflict_default,
@@ -7478,7 +7656,7 @@ var rules = {
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "4.0.0"
+    version: "4.1.0"
   },
   rules,
   configs: {
@@ -7525,6 +7703,10 @@ var plugin = {
         "@sarj/store-insert-requires-on-conflict": "warn",
         "@sarj/no-offset-pagination": "warn",
         "@sarj/no-select-star": "warn",
+        // Uncancellable hand-rolled timers. Verified against the shipped
+        // strict config (205 enabled rules) that nothing already reports this
+        // position; `unicorn` 72 has no promisified-timer rule at all.
+        "@sarj/no-hand-rolled-sleep": "warn",
         "@sarj/no-sleep-in-test-body": "warn",
         "@sarj/no-conditional-in-test": "warn",
         "@sarj/no-repeated-string-literal": "warn",
@@ -7541,7 +7723,8 @@ var plugin = {
         // Anti-comment-verbosity family (2026-07), from a 37,918-comment,
         // nine-repo measurement study. Each is a deletion-class finding, so each
         // was validated against pydantic / trio / attrs as well as the maintained
-        // repos: `no-restated-comment` 0 hits in bulbul and 4 in the three famous
+        // repos: `no-restated-comment` 0 hits in the flagship first-party
+        // repo and 4 in the three famous
         // corpora combined; `trailing-value-narration` 18 hits, 18 true
         // positives; `jsdoc-restates-signature` 36 hits, 0 measured false
         // positives, and it offers a suggestion rather than a `--fix` because a
@@ -7552,7 +7735,7 @@ var plugin = {
         // The TS half of SARJ057 (2026-07). Python has caught the
         // assertion-FREE test since 0.15.0 (SARJ043) and had no TS
         // counterpart, which is how `expect(true).toBe(true); // placeholder`
-        // survived in internal-automations: the file HAS an assertion.
+        // survived in a first-party repo: the file HAS an assertion.
         // Measured across 5,819 .ts/.tsx files (1,003 of them test files) in
         // six internal repos plus got / hono / swr / trpc: 3 hits, 3 true
         // positives, 0 false positives.
@@ -7612,6 +7795,10 @@ var plugin = {
         "@sarj/store-insert-requires-on-conflict": "error",
         "@sarj/no-offset-pagination": "error",
         "@sarj/no-select-star": "error",
+        // Uncancellable hand-rolled timers. Verified against the shipped
+        // strict config (205 enabled rules) that nothing already reports this
+        // position; `unicorn` 72 has no promisified-timer rule at all.
+        "@sarj/no-hand-rolled-sleep": "error",
         "@sarj/no-sleep-in-test-body": "error",
         "@sarj/no-conditional-in-test": "error",
         "@sarj/no-repeated-string-literal": "error",