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

package/README.md

@@ -55,9 +55,11 @@ export default [
 | `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. |
-| `no-concurrent-shared-mutation` | `warn` | Heuristic — advisory. |
+| `forward-abort-signal` | `error` | A dead `signal` is a real bug; any forwarding shape counts as a pass. |
+| `no-concurrent-shared-mutation` | `error` | A lost update is a real bug; order-tolerant writes are skipped. |
+| `prefer-parallel-awaits` | `off` | A latency hint, not a bug. Sequential awaits are often deliberate. Opt in where you want it. |
+
+Every rule is `error` or `off`, never `warn`: a warning is a rule nobody obeys.
 
 The 💡 rules provide editor suggestions (not autofixes) — parallelizing awaits and adding a timeout both change
 runtime behavior, so they are never applied automatically.

package/dist/index.cjs

@@ -34,10 +34,16 @@ var recommended = {
   "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.
-  "noctcore-async-safety/forward-abort-signal": "warn",
-  "noctcore-async-safety/prefer-parallel-awaits": "warn",
-  "noctcore-async-safety/no-concurrent-shared-mutation": "warn"
+  // A dead `signal` parameter is a real bug (the cancel never reaches the I/O), and
+  // the rule counts any forwarding shape as a pass, so it errs toward silence.
+  "noctcore-async-safety/forward-abort-signal": "error",
+  // A lost update is a real bug, and the rule skips order-tolerant writes
+  // (`push`, `set`, distinct-index) and plain overwrites.
+  "noctcore-async-safety/no-concurrent-shared-mutation": "error",
+  // Ships OFF: a latency hint, not a correctness bug. Sequential awaits are often
+  // deliberate (one transaction client, rate limits, deterministic test setup), and
+  // the rule cannot see that. Enable it where you want the nudge.
+  "noctcore-async-safety/prefer-parallel-awaits": "off"
 };
 
 // src/rules/forward-abort-signal.ts

package/dist/index.js

@@ -6,10 +6,16 @@ var recommended = {
   "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.
-  "noctcore-async-safety/forward-abort-signal": "warn",
-  "noctcore-async-safety/prefer-parallel-awaits": "warn",
-  "noctcore-async-safety/no-concurrent-shared-mutation": "warn"
+  // A dead `signal` parameter is a real bug (the cancel never reaches the I/O), and
+  // the rule counts any forwarding shape as a pass, so it errs toward silence.
+  "noctcore-async-safety/forward-abort-signal": "error",
+  // A lost update is a real bug, and the rule skips order-tolerant writes
+  // (`push`, `set`, distinct-index) and plain overwrites.
+  "noctcore-async-safety/no-concurrent-shared-mutation": "error",
+  // Ships OFF: a latency hint, not a correctness bug. Sequential awaits are often
+  // deliberate (one transaction client, rate limits, deterministic test setup), and
+  // the rule cannot see that. Enable it where you want the nudge.
+  "noctcore-async-safety/prefer-parallel-awaits": "off"
 };
 
 // src/rules/forward-abort-signal.ts

package/docs/rules/forward-abort-signal.md

@@ -20,13 +20,15 @@ A function (declaration, expression, or arrow) that:
 "Forwarding" is deliberately generous: passing the signal as an argument, into an options object, assigning it,
 or returning it all count — so the rule errs toward silence rather than false positives.
 
-```ts
-// ✗ signal accepted, fetch left uncancellable
+```ts bad
+// signal accepted, fetch left uncancellable
 async function load(url: string, signal: AbortSignal) {
   return await fetch(url);
 }
+```
 
-// ✓ signal forwarded
+```ts good
+// signal forwarded
 async function load(url: string, signal: AbortSignal) {
   return await fetch(url, { signal });
 }

package/docs/rules/no-concurrent-shared-mutation.md

@@ -18,14 +18,16 @@ Inside an `async` callback passed to `.map`/`.flatMap`/`.forEach` whose result i
 - a self-referential assignment (`x = x + …`);
 - an update expression on an outer binding (`x++`, `--x`).
 
-```ts
-// ✗ lost updates
+```ts bad
+// lost updates
 let total = 0;
 await Promise.all(items.map(async (item) => {
   total += await priceOf(item);
 }));
+```
 
-// ✓ collect, then reduce
+```ts good
+// collect, then reduce
 const prices = await Promise.all(items.map((item) => priceOf(item)));
 const total = prices.reduce((a, b) => a + b, 0);
 ```
@@ -45,4 +47,4 @@ None.
 ## When not to use it
 
 If you intentionally accumulate into shared state and have externally serialized the callbacks (e.g. a mutex, or
-a concurrency limit of 1), this rule's warning is a false positive — disable it inline for that block.
+a concurrency limit of 1), this rule's report is a false positive: disable it inline for that block.

package/docs/rules/no-shared-mutable-module-state.md

@@ -21,16 +21,16 @@ module-scoped mutable binding performed inside an **exported async function** or
 Exported functions qualify when they are `async` or named like a handler (`GET`/`POST`/…, `loader`, `action`,
 `handler`, `*Handler`, `middleware`).
 
-```ts
-// server.ts  (include: ['**/server/**'])
-
-// ✗ shared across requests
+```ts bad filename=src/server/metrics.ts options={"include":["**/server/**"]}
+// shared across requests
 let requestCount = 0;
 export async function GET() {
   requestCount += 1;
 }
+```
 
-// ✓ per-request
+```ts good filename=src/server/metrics.ts options={"include":["**/server/**"]}
+// per-request
 export async function GET() {
   const requestCount = 1;
 }

package/docs/rules/prefer-parallel-awaits.md

@@ -18,15 +18,26 @@ A run of two or more **consecutive** statements of the exact shape `const <id> =
   writes is usually intentional;
 - no later statement references an earlier statement's binding (no data dependency).
 
-```ts
-// ✗ sequential, but independent
-const user = await getUser();
-const feed = await getFeed();
+```ts bad
+// sequential, but independent
+async function loadHome() {
+  const user = await getUser();
+  const feed = await getFeed();
+  return { user, feed };
+}
+```
 
-// ✓ concurrent
-const [user, feed] = await Promise.all([getUser(), getFeed()]);
+```ts good
+// concurrent
+async function loadHome() {
+  const [user, feed] = await Promise.all([getUser(), getFeed()]);
+  return { user, feed };
+}
 ```
 
+Only runs inside a block (a function body, or any `{ ... }`) are checked. Top-level `await`s at
+module scope are not.
+
 The rule is intentionally conservative — a data dependency, a mutation-looking callee, a `let`, a nested call
 argument, or any non-await statement between them all suppress it.
 

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

@@ -60,14 +60,15 @@ A NestJS API that talks to S3 and sends mail over SMTP:
 ],
 ```
 
-```ts
-// Bad: no request handler, so no connection or request timeout
+```ts bad reports=2 options={"clients":[{"callee":"S3Client","construct":true,"requireAnyOf":["requestHandler"]},{"callee":"nodemailer.createTransport","requireAnyOf":["connectionTimeout","socketTimeout"]}]}
+// no request handler, so no connection or request timeout
 this.s3 = new S3Client({ region, credentials });
 
-// Bad: SMTP transport with default (unbounded in practice) timeouts
+// SMTP transport with default (unbounded in practice) timeouts
 this.transporter = nodemailer.createTransport({ host, port, secure: true });
+```
 
-// Good
+```ts good options={"clients":[{"callee":"S3Client","construct":true,"requireAnyOf":["requestHandler"]},{"callee":"nodemailer.createTransport","requireAnyOf":["connectionTimeout","socketTimeout"]}]}
 this.s3 = new S3Client({
   region,
   credentials,

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

@@ -23,12 +23,14 @@ The rule is purely syntactic and stays silent whenever it cannot see the argumen
 It reports only when the arguments are plainly signal-free: a bare string/template URL, or a visible options
 object literal with neither key.
 
-```ts
-// ✗ no timeout — can hang forever
+```ts bad reports=2
+// no timeout: can hang forever
 await fetch('https://api.example.com/data');
 await fetch(url, { method: 'POST' });
+```
 
-// ✓ bounded
+```ts good
+// bounded
 await fetch('https://api.example.com/data', { signal: AbortSignal.timeout(10000) });
 await fetch(url, { method: 'POST', signal: controller.signal });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-async-safety",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "ESLint rules for async correctness: fetch timeouts, AbortSignal forwarding, and shared-state / concurrency races.",
   "license": "MIT",
   "type": "module",