@noctcore/eslint-plugin-async-safety 0.1.0 → 0.2.0

package/README.md

@@ -42,6 +42,7 @@ export default [
 | Rule | Description | 💡 |
 | --- | --- | --- |
 | [`require-fetch-timeout`](./docs/rules/require-fetch-timeout.md) | A `fetch` (or configured wrapper) call must carry a `signal`/`timeout` — an unbounded request can hang forever. | 💡 |
+| [`require-client-timeout`](./docs/rules/require-client-timeout.md) | A configured network client (`new S3Client(...)`, `nodemailer.createTransport(...)`) must be built with one of its timeout options. Ships with no client list. | |
 | [`forward-abort-signal`](./docs/rules/forward-abort-signal.md) | A function that accepts an `AbortSignal` but awaits a call without forwarding it leaves that work uncancellable. | |
 | [`no-shared-mutable-module-state`](./docs/rules/no-shared-mutable-module-state.md) | A module-scoped mutable binding written from an exported async/handler function is shared across concurrent requests (opt in via `include`). | |
 | [`prefer-parallel-awaits`](./docs/rules/prefer-parallel-awaits.md) | Consecutive independent awaits can run concurrently with `Promise.all`. | 💡 |
@@ -52,6 +53,7 @@ export default [
 | Rule | Severity | Notes |
 | --- | --- | --- |
 | `require-fetch-timeout` | `error` | Precise and syntactic. |
+| `require-client-timeout` | `error` | Inert until you list `clients`, so it ships enabled but checks nothing by default. |
 | `no-shared-mutable-module-state` | `error` | Inert until you set `include` globs, so it ships enabled but off by default. |
 | `forward-abort-signal` | `warn` | Heuristic — advisory. |
 | `prefer-parallel-awaits` | `warn` | Heuristic — advisory suggestion. |

package/dist/index.cjs

@@ -30,6 +30,8 @@ module.exports = __toCommonJS(index_exports);
 var recommended = {
   // Precise, syntactic — safe as errors.
   "noctcore-async-safety/require-fetch-timeout": "error",
+  // Inert until you list `clients`, so it ships enabled but checks nothing by default.
+  "noctcore-async-safety/require-client-timeout": "error",
   // Inert until you set `include` globs, so it ships enabled but off by default.
   "noctcore-async-safety/no-shared-mutable-module-state": "error",
   // Heuristic — advisory. Warns rather than blocking.
@@ -703,29 +705,129 @@ var preferParallelAwaitsRule = createRule({
   }
 });
 
-// src/rules/require-fetch-timeout.ts
+// src/rules/require-client-timeout.ts
 var import_utils10 = require("@typescript-eslint/utils");
-var RULE_NAME5 = "require-fetch-timeout";
-var DEFAULT_TIMEOUT_MS = 1e4;
-var SIGNAL_KEYS = /* @__PURE__ */ new Set(["signal", "timeout"]);
+var RULE_NAME5 = "require-client-timeout";
+var clientSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["callee", "requireAnyOf"],
+  properties: {
+    callee: { type: "string", minLength: 1 },
+    construct: { type: "boolean", default: false },
+    requireAnyOf: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      minItems: 1,
+      uniqueItems: true
+    }
+  }
+};
 var optionSchema2 = {
   type: "object",
   additionalProperties: false,
   properties: {
-    callees: { type: "array", items: { type: "string" }, uniqueItems: true },
-    defaultTimeoutMs: { type: "integer", minimum: 1 }
+    clients: { type: "array", items: clientSchema, default: [] }
   }
 };
 function isUrlLike(node) {
   return node.type === import_utils10.AST_NODE_TYPES.TemplateLiteral || node.type === import_utils10.AST_NODE_TYPES.Literal && typeof node.value === "string";
 }
-function probeOptionsObject(object) {
+function probeOptionsObject(object, keys) {
   for (const property of object.properties) {
     if (property.type === import_utils10.AST_NODE_TYPES.SpreadElement) {
       return { satisfied: false, opaque: true };
     }
     const key = property.key;
     const name = key.type === import_utils10.AST_NODE_TYPES.Identifier ? key.name : key.type === import_utils10.AST_NODE_TYPES.Literal && typeof key.value === "string" ? key.value : null;
+    if (name !== null && keys.has(name)) {
+      return { satisfied: true, opaque: false };
+    }
+  }
+  return { satisfied: false, opaque: false };
+}
+function lacksTimeout(args, keys) {
+  if (args.some((arg) => arg.type === import_utils10.AST_NODE_TYPES.SpreadElement)) {
+    return false;
+  }
+  const objectArgs = args.filter(
+    (arg) => arg.type === import_utils10.AST_NODE_TYPES.ObjectExpression
+  );
+  if (objectArgs.length > 0) {
+    const probes = objectArgs.map((object) => probeOptionsObject(object, keys));
+    return !probes.some((probe) => probe.satisfied || probe.opaque);
+  }
+  return args.every(isUrlLike);
+}
+var requireClientTimeoutRule = createRule({
+  name: RULE_NAME5,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "A configured network client must be constructed with a timeout option; an unbounded client can hang forever."
+    },
+    schema: [optionSchema2],
+    messages: {
+      missingTimeout: "`{{callee}}` is created without a timeout. Set one of {{keys}} in its options so a stalled peer cannot hang the caller indefinitely."
+    }
+  },
+  defaultOptions: [{ clients: [] }],
+  create(context, [options]) {
+    const clients = (options.clients ?? []).map((client) => ({
+      callee: client.callee,
+      construct: client.construct ?? false,
+      keys: new Set(client.requireAnyOf),
+      label: client.requireAnyOf.map((key) => `\`${key}\``).join(", ")
+    }));
+    if (clients.length === 0) {
+      return {};
+    }
+    const check = (node) => {
+      const name = calleeText(node.callee);
+      if (name === null) {
+        return;
+      }
+      const construct = node.type === import_utils10.AST_NODE_TYPES.NewExpression;
+      for (const client of clients) {
+        if (client.callee !== name || client.construct !== construct) {
+          continue;
+        }
+        if (lacksTimeout(node.arguments, client.keys)) {
+          context.report({
+            node: node.callee,
+            messageId: "missingTimeout",
+            data: { callee: name, keys: client.label }
+          });
+        }
+      }
+    };
+    return { CallExpression: check, NewExpression: check };
+  }
+});
+
+// src/rules/require-fetch-timeout.ts
+var import_utils12 = require("@typescript-eslint/utils");
+var RULE_NAME6 = "require-fetch-timeout";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var SIGNAL_KEYS = /* @__PURE__ */ new Set(["signal", "timeout"]);
+var optionSchema3 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    callees: { type: "array", items: { type: "string" }, uniqueItems: true },
+    defaultTimeoutMs: { type: "integer", minimum: 1 }
+  }
+};
+function isUrlLike2(node) {
+  return node.type === import_utils12.AST_NODE_TYPES.TemplateLiteral || node.type === import_utils12.AST_NODE_TYPES.Literal && typeof node.value === "string";
+}
+function probeOptionsObject2(object) {
+  for (const property of object.properties) {
+    if (property.type === import_utils12.AST_NODE_TYPES.SpreadElement) {
+      return { satisfied: false, opaque: true };
+    }
+    const key = property.key;
+    const name = key.type === import_utils12.AST_NODE_TYPES.Identifier ? key.name : key.type === import_utils12.AST_NODE_TYPES.Literal && typeof key.value === "string" ? key.value : null;
     if (name !== null && SIGNAL_KEYS.has(name)) {
       return { satisfied: true, opaque: false };
     }
@@ -733,14 +835,14 @@ function probeOptionsObject(object) {
   return { satisfied: false, opaque: false };
 }
 var requireFetchTimeoutRule = createRule({
-  name: RULE_NAME5,
+  name: RULE_NAME6,
   meta: {
     type: "problem",
     docs: {
       description: "A `fetch` (or configured wrapper) call must carry a `signal`/`timeout` in its options \u2014 an unbounded request can hang forever."
     },
     hasSuggestions: true,
-    schema: [optionSchema2],
+    schema: [optionSchema3],
     messages: {
       missingTimeout: "`{{callee}}` has no timeout \u2014 pass a `signal` (e.g. `AbortSignal.timeout({{ms}})`) or a `timeout` option so the request cannot hang indefinitely.",
       addTimeout: "Add `signal: AbortSignal.timeout({{ms}})`."
@@ -757,14 +859,14 @@ var requireFetchTimeoutRule = createRule({
           return;
         }
         const args = node.arguments;
-        if (args.some((arg) => arg.type === import_utils10.AST_NODE_TYPES.SpreadElement)) {
+        if (args.some((arg) => arg.type === import_utils12.AST_NODE_TYPES.SpreadElement)) {
           return;
         }
         const objectArgs = args.filter(
-          (arg) => arg.type === import_utils10.AST_NODE_TYPES.ObjectExpression
+          (arg) => arg.type === import_utils12.AST_NODE_TYPES.ObjectExpression
         );
         if (objectArgs.length > 0) {
-          const probes = objectArgs.map(probeOptionsObject);
+          const probes = objectArgs.map(probeOptionsObject2);
           if (probes.some((probe) => probe.satisfied || probe.opaque)) {
             return;
           }
@@ -793,7 +895,7 @@ var requireFetchTimeoutRule = createRule({
           });
           return;
         }
-        if (args.length === 0 || !args.every(isUrlLike)) {
+        if (args.length === 0 || !args.every(isUrlLike2)) {
           return;
         }
         const lastArg = args[args.length - 1];
@@ -820,6 +922,7 @@ var requireFetchTimeoutRule = createRule({
 // src/rules/index.ts
 var rules = {
   "require-fetch-timeout": requireFetchTimeoutRule,
+  "require-client-timeout": requireClientTimeoutRule,
   "forward-abort-signal": forwardAbortSignalRule,
   "no-shared-mutable-module-state": noSharedMutableModuleStateRule,
   "prefer-parallel-awaits": preferParallelAwaitsRule,
@@ -828,7 +931,7 @@ var rules = {
 
 // src/index.ts
 var NAMESPACE = "noctcore-async-safety";
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-async-safety", version: VERSION },
   rules,

package/dist/index.d.cts

@@ -5,6 +5,19 @@ interface NoSharedMutableModuleStateOptions {
     readonly allow?: readonly string[];
 }
 
+/** One client constructor or factory whose options must bound its waits. */
+interface ClientTimeoutSpec {
+    /** Dotted callee text, matched literally (`S3Client`, `nodemailer.createTransport`). */
+    readonly callee: string;
+    /** Match `new <callee>(...)` instead of `<callee>(...)`. Default `false`. */
+    readonly construct?: boolean;
+    /** The options object must carry at least one of these top-level keys. */
+    readonly requireAnyOf: readonly string[];
+}
+interface RequireClientTimeoutOptions {
+    readonly clients?: readonly ClientTimeoutSpec[];
+}
+
 interface RequireFetchTimeoutOptions {
     readonly callees?: readonly string[];
     readonly defaultTimeoutMs?: number;
@@ -15,6 +28,9 @@ declare const rules: {
     'require-fetch-timeout': _typescript_eslint_utils_ts_eslint.RuleModule<"missingTimeout" | "addTimeout", [RequireFetchTimeoutOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    'require-client-timeout': _typescript_eslint_utils_ts_eslint.RuleModule<"missingTimeout", [RequireClientTimeoutOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
     'forward-abort-signal': _typescript_eslint_utils_ts_eslint.RuleModule<"unforwardedSignal", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
@@ -38,6 +54,9 @@ declare const plugin: {
         'require-fetch-timeout': _typescript_eslint_utils_ts_eslint.RuleModule<"missingTimeout" | "addTimeout", [RequireFetchTimeoutOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        'require-client-timeout': _typescript_eslint_utils_ts_eslint.RuleModule<"missingTimeout", [RequireClientTimeoutOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
         'forward-abort-signal': _typescript_eslint_utils_ts_eslint.RuleModule<"unforwardedSignal", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };

package/dist/index.d.ts

@@ -5,6 +5,19 @@ interface NoSharedMutableModuleStateOptions {
     readonly allow?: readonly string[];
 }
 
+/** One client constructor or factory whose options must bound its waits. */
+interface ClientTimeoutSpec {
+    /** Dotted callee text, matched literally (`S3Client`, `nodemailer.createTransport`). */
+    readonly callee: string;
+    /** Match `new <callee>(...)` instead of `<callee>(...)`. Default `false`. */
+    readonly construct?: boolean;
+    /** The options object must carry at least one of these top-level keys. */
+    readonly requireAnyOf: readonly string[];
+}
+interface RequireClientTimeoutOptions {
+    readonly clients?: readonly ClientTimeoutSpec[];
+}
+
 interface RequireFetchTimeoutOptions {
     readonly callees?: readonly string[];
     readonly defaultTimeoutMs?: number;
@@ -15,6 +28,9 @@ declare const rules: {
     'require-fetch-timeout': _typescript_eslint_utils_ts_eslint.RuleModule<"missingTimeout" | "addTimeout", [RequireFetchTimeoutOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
+    'require-client-timeout': _typescript_eslint_utils_ts_eslint.RuleModule<"missingTimeout", [RequireClientTimeoutOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+        name: string;
+    };
     'forward-abort-signal': _typescript_eslint_utils_ts_eslint.RuleModule<"unforwardedSignal", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
         name: string;
     };
@@ -38,6 +54,9 @@ declare const plugin: {
         'require-fetch-timeout': _typescript_eslint_utils_ts_eslint.RuleModule<"missingTimeout" | "addTimeout", [RequireFetchTimeoutOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };
+        'require-client-timeout': _typescript_eslint_utils_ts_eslint.RuleModule<"missingTimeout", [RequireClientTimeoutOptions], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
+            name: string;
+        };
         'forward-abort-signal': _typescript_eslint_utils_ts_eslint.RuleModule<"unforwardedSignal", [], unknown, _typescript_eslint_utils_ts_eslint.RuleListener> & {
             name: string;
         };

package/dist/index.js

@@ -2,6 +2,8 @@
 var recommended = {
   // Precise, syntactic — safe as errors.
   "noctcore-async-safety/require-fetch-timeout": "error",
+  // Inert until you list `clients`, so it ships enabled but checks nothing by default.
+  "noctcore-async-safety/require-client-timeout": "error",
   // Inert until you set `include` globs, so it ships enabled but off by default.
   "noctcore-async-safety/no-shared-mutable-module-state": "error",
   // Heuristic — advisory. Warns rather than blocking.
@@ -675,29 +677,129 @@ var preferParallelAwaitsRule = createRule({
   }
 });
 
-// src/rules/require-fetch-timeout.ts
+// src/rules/require-client-timeout.ts
 import { AST_NODE_TYPES as AST_NODE_TYPES6 } from "@typescript-eslint/utils";
-var RULE_NAME5 = "require-fetch-timeout";
-var DEFAULT_TIMEOUT_MS = 1e4;
-var SIGNAL_KEYS = /* @__PURE__ */ new Set(["signal", "timeout"]);
+var RULE_NAME5 = "require-client-timeout";
+var clientSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["callee", "requireAnyOf"],
+  properties: {
+    callee: { type: "string", minLength: 1 },
+    construct: { type: "boolean", default: false },
+    requireAnyOf: {
+      type: "array",
+      items: { type: "string", minLength: 1 },
+      minItems: 1,
+      uniqueItems: true
+    }
+  }
+};
 var optionSchema2 = {
   type: "object",
   additionalProperties: false,
   properties: {
-    callees: { type: "array", items: { type: "string" }, uniqueItems: true },
-    defaultTimeoutMs: { type: "integer", minimum: 1 }
+    clients: { type: "array", items: clientSchema, default: [] }
   }
 };
 function isUrlLike(node) {
   return node.type === AST_NODE_TYPES6.TemplateLiteral || node.type === AST_NODE_TYPES6.Literal && typeof node.value === "string";
 }
-function probeOptionsObject(object) {
+function probeOptionsObject(object, keys) {
   for (const property of object.properties) {
     if (property.type === AST_NODE_TYPES6.SpreadElement) {
       return { satisfied: false, opaque: true };
     }
     const key = property.key;
     const name = key.type === AST_NODE_TYPES6.Identifier ? key.name : key.type === AST_NODE_TYPES6.Literal && typeof key.value === "string" ? key.value : null;
+    if (name !== null && keys.has(name)) {
+      return { satisfied: true, opaque: false };
+    }
+  }
+  return { satisfied: false, opaque: false };
+}
+function lacksTimeout(args, keys) {
+  if (args.some((arg) => arg.type === AST_NODE_TYPES6.SpreadElement)) {
+    return false;
+  }
+  const objectArgs = args.filter(
+    (arg) => arg.type === AST_NODE_TYPES6.ObjectExpression
+  );
+  if (objectArgs.length > 0) {
+    const probes = objectArgs.map((object) => probeOptionsObject(object, keys));
+    return !probes.some((probe) => probe.satisfied || probe.opaque);
+  }
+  return args.every(isUrlLike);
+}
+var requireClientTimeoutRule = createRule({
+  name: RULE_NAME5,
+  meta: {
+    type: "problem",
+    docs: {
+      description: "A configured network client must be constructed with a timeout option; an unbounded client can hang forever."
+    },
+    schema: [optionSchema2],
+    messages: {
+      missingTimeout: "`{{callee}}` is created without a timeout. Set one of {{keys}} in its options so a stalled peer cannot hang the caller indefinitely."
+    }
+  },
+  defaultOptions: [{ clients: [] }],
+  create(context, [options]) {
+    const clients = (options.clients ?? []).map((client) => ({
+      callee: client.callee,
+      construct: client.construct ?? false,
+      keys: new Set(client.requireAnyOf),
+      label: client.requireAnyOf.map((key) => `\`${key}\``).join(", ")
+    }));
+    if (clients.length === 0) {
+      return {};
+    }
+    const check = (node) => {
+      const name = calleeText(node.callee);
+      if (name === null) {
+        return;
+      }
+      const construct = node.type === AST_NODE_TYPES6.NewExpression;
+      for (const client of clients) {
+        if (client.callee !== name || client.construct !== construct) {
+          continue;
+        }
+        if (lacksTimeout(node.arguments, client.keys)) {
+          context.report({
+            node: node.callee,
+            messageId: "missingTimeout",
+            data: { callee: name, keys: client.label }
+          });
+        }
+      }
+    };
+    return { CallExpression: check, NewExpression: check };
+  }
+});
+
+// src/rules/require-fetch-timeout.ts
+import { AST_NODE_TYPES as AST_NODE_TYPES7 } from "@typescript-eslint/utils";
+var RULE_NAME6 = "require-fetch-timeout";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var SIGNAL_KEYS = /* @__PURE__ */ new Set(["signal", "timeout"]);
+var optionSchema3 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    callees: { type: "array", items: { type: "string" }, uniqueItems: true },
+    defaultTimeoutMs: { type: "integer", minimum: 1 }
+  }
+};
+function isUrlLike2(node) {
+  return node.type === AST_NODE_TYPES7.TemplateLiteral || node.type === AST_NODE_TYPES7.Literal && typeof node.value === "string";
+}
+function probeOptionsObject2(object) {
+  for (const property of object.properties) {
+    if (property.type === AST_NODE_TYPES7.SpreadElement) {
+      return { satisfied: false, opaque: true };
+    }
+    const key = property.key;
+    const name = key.type === AST_NODE_TYPES7.Identifier ? key.name : key.type === AST_NODE_TYPES7.Literal && typeof key.value === "string" ? key.value : null;
     if (name !== null && SIGNAL_KEYS.has(name)) {
       return { satisfied: true, opaque: false };
     }
@@ -705,14 +807,14 @@ function probeOptionsObject(object) {
   return { satisfied: false, opaque: false };
 }
 var requireFetchTimeoutRule = createRule({
-  name: RULE_NAME5,
+  name: RULE_NAME6,
   meta: {
     type: "problem",
     docs: {
       description: "A `fetch` (or configured wrapper) call must carry a `signal`/`timeout` in its options \u2014 an unbounded request can hang forever."
     },
     hasSuggestions: true,
-    schema: [optionSchema2],
+    schema: [optionSchema3],
     messages: {
       missingTimeout: "`{{callee}}` has no timeout \u2014 pass a `signal` (e.g. `AbortSignal.timeout({{ms}})`) or a `timeout` option so the request cannot hang indefinitely.",
       addTimeout: "Add `signal: AbortSignal.timeout({{ms}})`."
@@ -729,14 +831,14 @@ var requireFetchTimeoutRule = createRule({
           return;
         }
         const args = node.arguments;
-        if (args.some((arg) => arg.type === AST_NODE_TYPES6.SpreadElement)) {
+        if (args.some((arg) => arg.type === AST_NODE_TYPES7.SpreadElement)) {
           return;
         }
         const objectArgs = args.filter(
-          (arg) => arg.type === AST_NODE_TYPES6.ObjectExpression
+          (arg) => arg.type === AST_NODE_TYPES7.ObjectExpression
         );
         if (objectArgs.length > 0) {
-          const probes = objectArgs.map(probeOptionsObject);
+          const probes = objectArgs.map(probeOptionsObject2);
           if (probes.some((probe) => probe.satisfied || probe.opaque)) {
             return;
           }
@@ -765,7 +867,7 @@ var requireFetchTimeoutRule = createRule({
           });
           return;
         }
-        if (args.length === 0 || !args.every(isUrlLike)) {
+        if (args.length === 0 || !args.every(isUrlLike2)) {
           return;
         }
         const lastArg = args[args.length - 1];
@@ -792,6 +894,7 @@ var requireFetchTimeoutRule = createRule({
 // src/rules/index.ts
 var rules = {
   "require-fetch-timeout": requireFetchTimeoutRule,
+  "require-client-timeout": requireClientTimeoutRule,
   "forward-abort-signal": forwardAbortSignalRule,
   "no-shared-mutable-module-state": noSharedMutableModuleStateRule,
   "prefer-parallel-awaits": preferParallelAwaitsRule,
@@ -800,7 +903,7 @@ var rules = {
 
 // src/index.ts
 var NAMESPACE = "noctcore-async-safety";
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-async-safety", version: VERSION },
   rules,

package/docs/rules/require-client-timeout.md

@@ -0,0 +1,90 @@
+# `noctcore-async-safety/require-client-timeout`
+
+> A configured network client must be constructed with a timeout option. An unbounded client can hang
+> forever.
+
+## Why
+
+Many clients are configured once, at construction, and never see a per-request `signal`: an S3 client
+whose request handler has no connection timeout, an SMTP transport with no connection or socket
+timeout, a database pool with no connect timeout. A peer that accepts the connection and never answers
+leaves every caller waiting indefinitely. [`require-fetch-timeout`](./require-fetch-timeout.md)
+covers `fetch`; this rule covers the clients you name.
+
+## What it flags
+
+The rule ships knowing **no** client. For each entry in `clients`, it reports a matching call (or
+`new`, with `construct: true`) whose options visibly carry none of the `requireAnyOf` keys.
+
+It follows the same precision contract as `require-fetch-timeout`: no type information, and silent
+whenever it cannot see the options.
+
+- A spread argument (`new Client(...args)`) or a `...spread` inside the options literal is opaque:
+  skipped.
+- An options slot that is an identifier, call or member (`new Client(config)`) may already set a
+  timeout: skipped.
+- It reports a visible options object literal with none of the keys, or an argument list with nothing
+  but string/template literals (a connection URL), including no arguments at all.
+
+Keys are matched at the top level of the options object only.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `clients` | `{ callee, construct?, requireAnyOf }[]` | `[]` | The clients to check. |
+| `clients[].callee` | `string` | (required) | Dotted callee text, matched literally: `'S3Client'`, `'nodemailer.createTransport'`. |
+| `clients[].construct` | `boolean` | `false` | Match `new <callee>(...)` instead of `<callee>(...)`. |
+| `clients[].requireAnyOf` | `string[]` (at least one) | (required) | The options object must carry at least one of these top-level keys. |
+
+With the default `clients: []` the rule is inert, which is why `recommended` can ship it at `error`.
+
+## Worked example
+
+A NestJS API that talks to S3 and sends mail over SMTP:
+
+```js
+'noctcore-async-safety/require-client-timeout': [
+  'error',
+  {
+    clients: [
+      // AWS SDK v3: timeouts live on the request handler.
+      { callee: 'S3Client', construct: true, requireAnyOf: ['requestHandler'] },
+      // Nodemailer SMTP transport.
+      {
+        callee: 'nodemailer.createTransport',
+        requireAnyOf: ['connectionTimeout', 'socketTimeout'],
+      },
+    ],
+  },
+],
+```
+
+```ts
+// Bad: no request handler, so no connection or request timeout
+this.s3 = new S3Client({ region, credentials });
+
+// Bad: SMTP transport with default (unbounded in practice) timeouts
+this.transporter = nodemailer.createTransport({ host, port, secure: true });
+
+// Good
+this.s3 = new S3Client({
+  region,
+  credentials,
+  requestHandler: { connectionTimeout: 5_000, requestTimeout: 30_000 },
+});
+this.transporter = nodemailer.createTransport({
+  host,
+  port,
+  secure: true,
+  connectionTimeout: 10_000,
+});
+```
+
+## Limits
+
+- It enforces that a listed key is **present**, not that its value is a sane timeout.
+  `requestHandler: new NodeHttpHandler({})` passes.
+- Matching is by callee text. An aliased import (`import { S3Client as S3 }`) or a destructured factory
+  (`const { createTransport } = nodemailer`) is not matched unless you list that name too.
+- A client built from an opaque config object (`new S3Client(config)`) is never reported.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-async-safety",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "ESLint rules for async correctness: fetch timeouts, AbortSignal forwarding, and shared-state / concurrency races.",
   "license": "MIT",
   "type": "module",
@@ -62,6 +62,6 @@
     "@typescript-eslint/rule-tester": "^8.61.1",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0",
-    "vitest": "^3"
+    "vitest": "^4"
   }
 }