@sarj/eslint-plugin 3.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

@@ -7177,126 +7177,8 @@ var prefer_non_nullable_collection_default = import_utils51.ESLintUtils.RuleCrea
   }
 });
 
-// src/rules/primary-export-file-name.ts
-var import_utils52 = require("@typescript-eslint/utils");
-var CONVENTIONAL_BUCKET_EXPORTS = /* @__PURE__ */ new Set(["cn"]);
-var GENERIC_ENTRYPOINTS = /* @__PURE__ */ new Set(["main", "run", "cli", "setup", "teardown", "execute"]);
-var ACRONYM_OVERRIDES = [
-  [/OAuth/g, "Oauth"],
-  [/GraphQL/g, "Graphql"],
-  [/gRPC/g, "Grpc"]
-];
-var CAMEL_BOUNDARY_RE = /(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g;
-var basename = (filename) => filename.split(/[/\\]/).pop() ?? filename;
-var stemOf = (base) => base.replace(/\.(test|spec|config|d|stories)\.[cm]?[jt]sx?$/i, "").replace(/\.[cm]?[jt]sx?$/i, "");
-var kebabCase = (name) => {
-  let normalized = name;
-  for (const [pattern, replacement] of ACRONYM_OVERRIDES) {
-    normalized = normalized.replace(pattern, replacement);
-  }
-  return normalized.replace(CAMEL_BOUNDARY_RE, "-").toLowerCase();
-};
-var isFunctionOrClass = (node) => node.type === import_utils52.AST_NODE_TYPES.ArrowFunctionExpression || node.type === import_utils52.AST_NODE_TYPES.FunctionExpression;
-var findPrimaryExport = (body) => {
-  let exportCount = 0;
-  let primaryCandidate = null;
-  for (const statement of body) {
-    if (statement.type === import_utils52.AST_NODE_TYPES.ExportAllDeclaration) {
-      return null;
-    }
-    if (statement.type === import_utils52.AST_NODE_TYPES.ExportDefaultDeclaration) {
-      exportCount += 1;
-      const decl = statement.declaration;
-      if ((decl.type === import_utils52.AST_NODE_TYPES.FunctionDeclaration || decl.type === import_utils52.AST_NODE_TYPES.ClassDeclaration) && decl.id !== null) {
-        primaryCandidate = { name: decl.id.name, node: statement, isDefault: true };
-      } else if (decl.type === import_utils52.AST_NODE_TYPES.Identifier) {
-        primaryCandidate = { name: decl.name, node: statement, isDefault: true };
-      }
-    } else if (statement.type === import_utils52.AST_NODE_TYPES.ExportNamedDeclaration) {
-      if (statement.source !== null) {
-        return null;
-      }
-      const decl = statement.declaration;
-      if (decl === null) {
-        exportCount += statement.specifiers.length;
-        if (statement.specifiers.length === 1 && primaryCandidate === null) {
-          const spec = statement.specifiers[0];
-          if (spec && spec.exported.type === import_utils52.AST_NODE_TYPES.Identifier) {
-            primaryCandidate = { name: spec.exported.name, node: statement, isDefault: false };
-          }
-        }
-      } else if (decl.type === import_utils52.AST_NODE_TYPES.FunctionDeclaration || decl.type === import_utils52.AST_NODE_TYPES.ClassDeclaration) {
-        if (decl.id !== null) {
-          exportCount += 1;
-          if (primaryCandidate === null) {
-            primaryCandidate = { name: decl.id.name, node: statement, isDefault: false };
-          }
-        }
-      } else if (decl.type === import_utils52.AST_NODE_TYPES.VariableDeclaration) {
-        for (const declarator of decl.declarations) {
-          if (declarator.id.type === import_utils52.AST_NODE_TYPES.Identifier) {
-            exportCount += 1;
-            if (primaryCandidate === null && declarator.init && isFunctionOrClass(declarator.init)) {
-              primaryCandidate = { name: declarator.id.name, node: statement, isDefault: false };
-            }
-          }
-        }
-      } else if (decl.type === import_utils52.AST_NODE_TYPES.TSTypeAliasDeclaration || decl.type === import_utils52.AST_NODE_TYPES.TSInterfaceDeclaration) {
-        exportCount += 1;
-        if (primaryCandidate === null) {
-          primaryCandidate = { name: decl.id.name, node: statement, isDefault: false };
-        }
-      }
-    }
-  }
-  if (primaryCandidate === null || exportCount > 2) {
-    return null;
-  }
-  return { ...primaryCandidate, count: exportCount };
-};
-var primary_export_file_name_default = import_utils52.ESLintUtils.RuleCreator(
-  (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
-)({
-  name: "primary-export-file-name",
-  meta: {
-    type: "suggestion",
-    docs: {
-      description: "Enforce semantic naming alignment: a file with a single primary export must be named after that export."
-    },
-    schema: [],
-    messages: {
-      primaryExportMismatch: "Module stem '{{stem}}' does not match its primary export '{{name}}' \u2014 rename the file to '{{expected}}{{ext}}' to describe its responsibility."
-    }
-  },
-  defaultOptions: [],
-  create(context) {
-    const base = basename(context.filename);
-    if (base.endsWith(".d.ts") || base.startsWith("index.") || base.startsWith("_")) return {};
-    if (isTestFile(context.filename) || isGeneratedFile(context.filename, context.sourceCode.text)) return {};
-    const stem3 = stemOf(base);
-    if (stem3 === "page" || stem3 === "layout" || stem3 === "loading" || stem3 === "error" || stem3 === "not-found" || stem3 === "route" || stem3 === "__root" || stem3 === "config" || stem3 === "constants" || stem3 === "types" || stem3.startsWith("$") || stem3.startsWith("[")) {
-      return {};
-    }
-    return {
-      Program(node) {
-        const primary = findPrimaryExport(node.body);
-        if (primary === null) return;
-        if (CONVENTIONAL_BUCKET_EXPORTS.has(primary.name) || GENERIC_ENTRYPOINTS.has(primary.name)) return;
-        const expectedStem = kebabCase(primary.name);
-        if (stem3 === expectedStem) return;
-        const ext = base.endsWith(".tsx") ? ".tsx" : ".ts";
-        context.report({
-          node: primary.node,
-          messageId: "primaryExportMismatch",
-          data: { stem: stem3, name: primary.name, expected: expectedStem, ext }
-        });
-      }
-    };
-  }
-});
-
 // src/rules/no-implicit-attribute-access.ts
-var import_utils53 = require("@typescript-eslint/utils");
+var import_utils52 = require("@typescript-eslint/utils");
 var EXCLUDED_BASES = /* @__PURE__ */ new Set([
   "environ",
   "headers",
@@ -7312,15 +7194,15 @@ var EXCLUDED_BASES = /* @__PURE__ */ new Set([
   "sessionStorage"
 ]);
 function getBaseName(node) {
-  if (node.type === import_utils53.AST_NODE_TYPES.Identifier) {
+  if (node.type === import_utils52.AST_NODE_TYPES.Identifier) {
     return node.name;
   }
-  if (node.type === import_utils53.AST_NODE_TYPES.MemberExpression && node.property.type === import_utils53.AST_NODE_TYPES.Identifier) {
+  if (node.type === import_utils52.AST_NODE_TYPES.MemberExpression && node.property.type === import_utils52.AST_NODE_TYPES.Identifier) {
     return node.property.name;
   }
   return null;
 }
-var no_implicit_attribute_access_default = import_utils53.ESLintUtils.RuleCreator(
+var no_implicit_attribute_access_default = import_utils52.ESLintUtils.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
   name: "no-implicit-attribute-access",
@@ -7341,7 +7223,7 @@ var no_implicit_attribute_access_default = import_utils53.ESLintUtils.RuleCreato
         if (!node.computed) {
           return;
         }
-        if (node.property.type === import_utils53.AST_NODE_TYPES.Literal && typeof node.property.value === "string") {
+        if (node.property.type === import_utils52.AST_NODE_TYPES.Literal && typeof node.property.value === "string") {
           const baseName = getBaseName(node.object);
           if (!baseName || !EXCLUDED_BASES.has(baseName)) {
             context.report({
@@ -7354,11 +7236,11 @@ var no_implicit_attribute_access_default = import_utils53.ESLintUtils.RuleCreato
       },
       CallExpression(node) {
         const callee = node.callee;
-        if (callee.type === import_utils53.AST_NODE_TYPES.MemberExpression) {
-          const method = callee.property.type === import_utils53.AST_NODE_TYPES.Identifier ? callee.property.name : null;
+        if (callee.type === import_utils52.AST_NODE_TYPES.MemberExpression) {
+          const method = callee.property.type === import_utils52.AST_NODE_TYPES.Identifier ? callee.property.name : null;
           if (method === "get") {
             const arg = node.arguments[0];
-            if (arg && arg.type === import_utils53.AST_NODE_TYPES.Literal && typeof arg.value === "string") {
+            if (arg && arg.type === import_utils52.AST_NODE_TYPES.Literal && typeof arg.value === "string") {
               const baseName = getBaseName(callee.object);
               if (!baseName || !EXCLUDED_BASES.has(baseName)) {
                 context.report({
@@ -7376,8 +7258,8 @@ var no_implicit_attribute_access_default = import_utils53.ESLintUtils.RuleCreato
 });
 
 // src/rules/strict-test-assertions.ts
-var import_utils54 = require("@typescript-eslint/utils");
-var strict_test_assertions_default = import_utils54.ESLintUtils.RuleCreator.withoutDocs({
+var import_utils53 = require("@typescript-eslint/utils");
+var strict_test_assertions_default = import_utils53.ESLintUtils.RuleCreator.withoutDocs({
   meta: {
     type: "suggestion",
     docs: {
@@ -7395,9 +7277,9 @@ var strict_test_assertions_default = import_utils54.ESLintUtils.RuleCreator.with
       let currentObject = null;
       let sequence = [];
       function getExpectObject(expr) {
-        if (expr.type === import_utils54.AST_NODE_TYPES.CallExpression && expr.callee.type === import_utils54.AST_NODE_TYPES.MemberExpression && expr.callee.object.type === import_utils54.AST_NODE_TYPES.CallExpression && expr.callee.object.callee.type === import_utils54.AST_NODE_TYPES.Identifier && expr.callee.object.callee.name === "expect" && expr.callee.object.arguments.length === 1) {
+        if (expr.type === import_utils53.AST_NODE_TYPES.CallExpression && expr.callee.type === import_utils53.AST_NODE_TYPES.MemberExpression && expr.callee.object.type === import_utils53.AST_NODE_TYPES.CallExpression && expr.callee.object.callee.type === import_utils53.AST_NODE_TYPES.Identifier && expr.callee.object.callee.name === "expect" && expr.callee.object.arguments.length === 1) {
           const arg = expr.callee.object.arguments.at(0);
-          if (arg?.type === import_utils54.AST_NODE_TYPES.MemberExpression) {
+          if (arg?.type === import_utils53.AST_NODE_TYPES.MemberExpression) {
             return arg.object;
           }
         }
@@ -7413,12 +7295,12 @@ var strict_test_assertions_default = import_utils54.ESLintUtils.RuleCreator.with
               if (!currentObject) return null;
               const objectText = context.sourceCode.getText(currentObject);
               const props = sequence.map((stmt) => {
-                if (stmt.expression.type !== import_utils54.AST_NODE_TYPES.CallExpression || stmt.expression.callee.type !== import_utils54.AST_NODE_TYPES.MemberExpression || stmt.expression.callee.object.type !== import_utils54.AST_NODE_TYPES.CallExpression) {
+                if (stmt.expression.type !== import_utils53.AST_NODE_TYPES.CallExpression || stmt.expression.callee.type !== import_utils53.AST_NODE_TYPES.MemberExpression || stmt.expression.callee.object.type !== import_utils53.AST_NODE_TYPES.CallExpression) {
                   return null;
                 }
                 const actual = stmt.expression.callee.object.arguments.at(0);
                 const expected = stmt.expression.arguments.at(0);
-                if (actual?.type === import_utils54.AST_NODE_TYPES.MemberExpression && actual.property.type === import_utils54.AST_NODE_TYPES.Identifier && expected) {
+                if (actual?.type === import_utils53.AST_NODE_TYPES.MemberExpression && actual.property.type === import_utils53.AST_NODE_TYPES.Identifier && expected) {
                   const propName2 = actual.property.name;
                   const valText = context.sourceCode.getText(expected);
                   return `${propName2}: ${valText}`;
@@ -7436,7 +7318,7 @@ var strict_test_assertions_default = import_utils54.ESLintUtils.RuleCreator.with
         }
       }
       for (const statement of body) {
-        if (statement.type === import_utils54.AST_NODE_TYPES.ExpressionStatement) {
+        if (statement.type === import_utils53.AST_NODE_TYPES.ExpressionStatement) {
           const obj = getExpectObject(statement.expression);
           if (obj && currentObject && context.sourceCode.getText(obj) === context.sourceCode.getText(currentObject)) {
             sequence.push(statement);
@@ -7470,8 +7352,8 @@ var strict_test_assertions_default = import_utils54.ESLintUtils.RuleCreator.with
 });
 
 // src/rules/no-async-callback-in-waitfor.ts
-var import_utils55 = require("@typescript-eslint/utils");
-var no_async_callback_in_waitfor_default = import_utils55.ESLintUtils.RuleCreator(
+var import_utils54 = require("@typescript-eslint/utils");
+var no_async_callback_in_waitfor_default = import_utils54.ESLintUtils.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
   name: "no-async-callback-in-waitfor",
@@ -7492,9 +7374,9 @@ var no_async_callback_in_waitfor_default = import_utils55.ESLintUtils.RuleCreato
     }
     return {
       CallExpression(node) {
-        if (node.callee.type === import_utils55.AST_NODE_TYPES.Identifier && node.callee.name === "waitFor") {
+        if (node.callee.type === import_utils54.AST_NODE_TYPES.Identifier && node.callee.name === "waitFor") {
           const callback = node.arguments[0];
-          if (callback && (callback.type === import_utils55.AST_NODE_TYPES.ArrowFunctionExpression || callback.type === import_utils55.AST_NODE_TYPES.FunctionExpression) && callback.async) {
+          if (callback && (callback.type === import_utils54.AST_NODE_TYPES.ArrowFunctionExpression || callback.type === import_utils54.AST_NODE_TYPES.FunctionExpression) && callback.async) {
             context.report({
               node: callback,
               messageId: "noAsyncCallbackInWaitFor"
@@ -7506,6 +7388,183 @@ var no_async_callback_in_waitfor_default = import_utils55.ESLintUtils.RuleCreato
   }
 });
 
+// src/rules/no-hand-rolled-sleep.ts
+var import_utils55 = require("@typescript-eslint/utils");
+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(
@@ -7567,7 +7626,6 @@ var rules = {
   "no-unsafe-mock-casting": no_unsafe_mock_casting_default,
   "prefer-string-literal-union": prefer_string_literal_union_default,
   "prefer-zod-enum": prefer_zod_enum_default,
-  "primary-export-file-name": primary_export_file_name_default,
   "no-silent-promise-catch": no_silent_promise_catch_default,
   "require-fetch-timeout": require_fetch_timeout_default,
   "no-offset-pagination": no_offset_pagination_default,
@@ -7575,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,
@@ -7597,7 +7656,7 @@ var rules = {
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "3.0.0"
+    version: "4.1.0"
   },
   rules,
   configs: {
@@ -7631,7 +7690,6 @@ var plugin = {
         "@sarj/no-cors-wildcard-with-credentials": "warn",
         "@sarj/no-secret-in-log": "warn",
         "@sarj/no-unsafe-mock-casting": "warn",
-        "@sarj/primary-export-file-name": "warn",
         "@sarj/prefer-string-literal-union": "warn",
         "@sarj/prefer-zod-enum": "warn",
         // Mined from 2y of PR review feedback + 5-repo code-smell audit (2026-07).
@@ -7645,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",
@@ -7661,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
@@ -7672,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.
@@ -7721,7 +7784,6 @@ var plugin = {
         "@sarj/no-cors-wildcard-with-credentials": "error",
         "@sarj/no-secret-in-log": "error",
         "@sarj/no-unsafe-mock-casting": "error",
-        "@sarj/primary-export-file-name": "error",
         // Promoted to error 2026-07-25 — strict means strict (user directive).
         "@sarj/prefer-string-literal-union": "error",
         "@sarj/prefer-zod-enum": "error",
@@ -7733,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",