@sarj/eslint-plugin 4.0.0 → 4.1.0

package/dist/index.d.cts

@@ -303,6 +303,12 @@ declare const rules: {
     "no-sleep-in-test-body": _typescript_eslint_utils_ts_eslint.RuleModule<"noSleepInTestBody", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "no-hand-rolled-sleep": _typescript_eslint_utils_ts_eslint.RuleModule<"handRolledSleep" | "handRolledTimeoutRace", readonly [{
+        allowIn?: readonly string[];
+        checkClientModules?: boolean;
+    }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
     "no-conditional-in-test": _typescript_eslint_utils_ts_eslint.RuleModule<"noConditionalInTest", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
@@ -472,6 +478,12 @@ declare const plugin: {
         "no-sleep-in-test-body": _typescript_eslint_utils_ts_eslint.RuleModule<"noSleepInTestBody", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "no-hand-rolled-sleep": _typescript_eslint_utils_ts_eslint.RuleModule<"handRolledSleep" | "handRolledTimeoutRace", readonly [{
+            allowIn?: readonly string[];
+            checkClientModules?: boolean;
+        }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
         "no-conditional-in-test": _typescript_eslint_utils_ts_eslint.RuleModule<"noConditionalInTest", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
@@ -564,6 +576,7 @@ declare const plugin: {
                 "@sarj/store-insert-requires-on-conflict": string;
                 "@sarj/no-offset-pagination": string;
                 "@sarj/no-select-star": string;
+                "@sarj/no-hand-rolled-sleep": string;
                 "@sarj/no-sleep-in-test-body": string;
                 "@sarj/no-conditional-in-test": string;
                 "@sarj/no-repeated-string-literal": string;
@@ -618,6 +631,7 @@ declare const plugin: {
                 "@sarj/store-insert-requires-on-conflict": string;
                 "@sarj/no-offset-pagination": string;
                 "@sarj/no-select-star": string;
+                "@sarj/no-hand-rolled-sleep": string;
                 "@sarj/no-sleep-in-test-body": string;
                 "@sarj/no-conditional-in-test": string;
                 "@sarj/no-repeated-string-literal": string;

package/dist/index.d.ts

@@ -303,6 +303,12 @@ declare const rules: {
     "no-sleep-in-test-body": _typescript_eslint_utils_ts_eslint.RuleModule<"noSleepInTestBody", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    "no-hand-rolled-sleep": _typescript_eslint_utils_ts_eslint.RuleModule<"handRolledSleep" | "handRolledTimeoutRace", readonly [{
+        allowIn?: readonly string[];
+        checkClientModules?: boolean;
+    }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
     "no-conditional-in-test": _typescript_eslint_utils_ts_eslint.RuleModule<"noConditionalInTest", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
@@ -472,6 +478,12 @@ declare const plugin: {
         "no-sleep-in-test-body": _typescript_eslint_utils_ts_eslint.RuleModule<"noSleepInTestBody", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        "no-hand-rolled-sleep": _typescript_eslint_utils_ts_eslint.RuleModule<"handRolledSleep" | "handRolledTimeoutRace", readonly [{
+            allowIn?: readonly string[];
+            checkClientModules?: boolean;
+        }?], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
         "no-conditional-in-test": _typescript_eslint_utils_ts_eslint.RuleModule<"noConditionalInTest", readonly [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
@@ -564,6 +576,7 @@ declare const plugin: {
                 "@sarj/store-insert-requires-on-conflict": string;
                 "@sarj/no-offset-pagination": string;
                 "@sarj/no-select-star": string;
+                "@sarj/no-hand-rolled-sleep": string;
                 "@sarj/no-sleep-in-test-body": string;
                 "@sarj/no-conditional-in-test": string;
                 "@sarj/no-repeated-string-literal": string;
@@ -618,6 +631,7 @@ declare const plugin: {
                 "@sarj/store-insert-requires-on-conflict": string;
                 "@sarj/no-offset-pagination": string;
                 "@sarj/no-select-star": string;
+                "@sarj/no-hand-rolled-sleep": string;
                 "@sarj/no-sleep-in-test-body": string;
                 "@sarj/no-conditional-in-test": string;
                 "@sarj/no-repeated-string-literal": string;

package/dist/index.js

@@ -7385,9 +7385,186 @@ var no_async_callback_in_waitfor_default = ESLintUtils49.RuleCreator(
   }
 });
 
-// src/rules/prefer-setup-file-mocks.ts
+// src/rules/no-hand-rolled-sleep.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES37, ESLintUtils as ESLintUtils50 } from "@typescript-eslint/utils";
-var prefer_setup_file_mocks_default = ESLintUtils50.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 === AST_NODE_TYPES37.Identifier) {
+    return callee.name === "setTimeout";
+  }
+  return callee.type === AST_NODE_TYPES37.MemberExpression && !callee.computed && callee.property.type === AST_NODE_TYPES37.Identifier && callee.property.name === "setTimeout" && callee.object.type === AST_NODE_TYPES37.Identifier && GLOBAL_OBJECTS2.has(callee.object.name);
+}
+function soleCall(fn) {
+  if (fn.body.type !== AST_NODE_TYPES37.BlockStatement) {
+    return fn.body.type === AST_NODE_TYPES37.CallExpression ? fn.body : null;
+  }
+  if (fn.body.body.length !== 1) {
+    return null;
+  }
+  const [only] = fn.body.body;
+  if (only?.type !== AST_NODE_TYPES37.ExpressionStatement) {
+    return null;
+  }
+  return only.expression.type === AST_NODE_TYPES37.CallExpression ? only.expression : null;
+}
+function isTimedDelay(delay) {
+  if (delay === void 0) {
+    return false;
+  }
+  if (delay.type === AST_NODE_TYPES37.Literal && typeof delay.value === "number") {
+    return delay.value !== 0;
+  }
+  return true;
+}
+function settlesWithoutValue(callback, name) {
+  if (callback.type === AST_NODE_TYPES37.Identifier) {
+    return callback.name === name;
+  }
+  if (callback.type !== AST_NODE_TYPES37.ArrowFunctionExpression && callback.type !== AST_NODE_TYPES37.FunctionExpression) {
+    return false;
+  }
+  const call = soleCall(callback);
+  return call !== null && call.arguments.length === 0 && call.callee.type === AST_NODE_TYPES37.Identifier && call.callee.name === name;
+}
+function rejectsInCallback(callback, name) {
+  if (callback.type === AST_NODE_TYPES37.Identifier) {
+    return callback.name === name;
+  }
+  if (callback.type !== AST_NODE_TYPES37.ArrowFunctionExpression && callback.type !== AST_NODE_TYPES37.FunctionExpression) {
+    return false;
+  }
+  const call = soleCall(callback);
+  return call !== null && call.callee.type === AST_NODE_TYPES37.Identifier && call.callee.name === name;
+}
+function parameterName(fn, index) {
+  const parameter = fn.params[index];
+  return parameter?.type === AST_NODE_TYPES37.Identifier ? parameter.name : null;
+}
+function isRaceArm(node) {
+  const array = node.parent;
+  if (array?.type !== AST_NODE_TYPES37.ArrayExpression) {
+    return false;
+  }
+  const call = array.parent;
+  return call?.type === AST_NODE_TYPES37.CallExpression && call.arguments[0] === array && call.callee.type === AST_NODE_TYPES37.MemberExpression && !call.callee.computed && call.callee.object.type === AST_NODE_TYPES37.Identifier && call.callee.object.name === "Promise" && call.callee.property.type === AST_NODE_TYPES37.Identifier && RACE_METHODS.has(call.callee.property.name);
+}
+var no_hand_rolled_sleep_default = ESLintUtils50.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 === AST_NODE_TYPES37.ExpressionStatement && statement.expression.type === AST_NODE_TYPES37.Literal && statement.expression.value === "use client") {
+          return true;
+        }
+        if (statement.type === AST_NODE_TYPES37.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 !== AST_NODE_TYPES37.Identifier || node.callee.name !== "Promise") {
+          return;
+        }
+        const executor = node.arguments[0];
+        if (executor?.type !== AST_NODE_TYPES37.ArrowFunctionExpression && executor?.type !== AST_NODE_TYPES37.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
+import { AST_NODE_TYPES as AST_NODE_TYPES38, ESLintUtils as ESLintUtils51 } from "@typescript-eslint/utils";
+var prefer_setup_file_mocks_default = ESLintUtils51.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
   name: "prefer-setup-file-mocks",
@@ -7408,7 +7585,7 @@ var prefer_setup_file_mocks_default = ESLintUtils50.RuleCreator(
     }
     return {
       CallExpression(node) {
-        if (node.callee.type === AST_NODE_TYPES37.MemberExpression && node.callee.object.type === AST_NODE_TYPES37.Identifier && (node.callee.object.name === "vi" || node.callee.object.name === "jest") && node.callee.property.type === AST_NODE_TYPES37.Identifier && node.callee.property.name === "mock") {
+        if (node.callee.type === AST_NODE_TYPES38.MemberExpression && node.callee.object.type === AST_NODE_TYPES38.Identifier && (node.callee.object.name === "vi" || node.callee.object.name === "jest") && node.callee.property.type === AST_NODE_TYPES38.Identifier && node.callee.property.name === "mock") {
           context.report({
             node,
             messageId: "preferSetupFileMocks"
@@ -7453,6 +7630,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,
@@ -7475,7 +7653,7 @@ var rules = {
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "4.0.0"
+    version: "4.1.0"
   },
   rules,
   configs: {
@@ -7522,6 +7700,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",
@@ -7538,7 +7720,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
@@ -7549,7 +7732,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.
@@ -7609,6 +7792,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",