@noctcore/eslint-plugin-async-safety 0.1.0

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

@@ -0,0 +1,46 @@
+# `noctcore-async-safety/forward-abort-signal`
+
+> A function that accepts an `AbortSignal` but never forwards it to the work it awaits leaves that work uncancellable.
+
+## Why
+
+Threading an `AbortSignal` through a call graph is only useful if every layer passes it down. A function that
+takes a `signal`, maybe checks `signal.aborted`, but then `await`s a `fetch`/call without passing the signal
+along has a dead parameter: callers think they can cancel, but the actual I/O ignores them. The cancel never
+reaches the socket.
+
+## What it flags
+
+A function (declaration, expression, or arrow) that:
+
+- accepts an AbortSignal-shaped parameter — named `signal`, typed `AbortSignal`, or the destructured `{ signal }` form; **and**
+- contains an awaited call or a `fetch(...)` (something that could have received the signal); **and**
+- never forwards the signal — every use is a member-access check (`signal.aborted`, `signal.throwIfAborted()`), or it is unused.
+
+"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
+async function load(url: string, signal: AbortSignal) {
+  return await fetch(url);
+}
+
+// ✓ signal forwarded
+async function load(url: string, signal: AbortSignal) {
+  return await fetch(url, { signal });
+}
+```
+
+A function with no awaited call or `fetch` (e.g. a pure `while (!signal.aborted)` polling loop) is never flagged
+— there is nothing to forward to.
+
+## Options
+
+None.
+
+## When not to use it
+
+If you deliberately accept a signal only to poll `.aborted` in a compute loop with no downstream call, this rule
+will still fire when that loop `await`s something (a `sleep`, say) that cannot accept a signal. Disable it inline
+for those functions.

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

@@ -0,0 +1,48 @@
+# `noctcore-async-safety/no-concurrent-shared-mutation`
+
+> A read-modify-write of an outer-scope binding inside a concurrent `Promise.all(arr.map(async …))` callback can lose updates.
+
+## Why
+
+`Promise.all(arr.map(async …))` starts every callback before any of them resolve, so their `await` points
+interleave. A read-modify-write of a shared outer binding — `total = total + await amount()`, `total += …`,
+`count++` after an await — can have two iterations read the same value and one clobber the other. The classic
+lost update: the final total is wrong, non-deterministically.
+
+## What it flags
+
+Inside an `async` callback passed to `.map`/`.flatMap`/`.forEach` whose result is wrapped in `Promise.all` /
+`Promise.allSettled`, and which contains at least one `await`:
+
+- a compound assignment to an outer binding (`x += …`, `x *= …`, …);
+- a self-referential assignment (`x = x + …`);
+- an update expression on an outer binding (`x++`, `--x`).
+
+```ts
+// ✗ lost updates
+let total = 0;
+await Promise.all(items.map(async (item) => {
+  total += await priceOf(item);
+}));
+
+// ✓ collect, then reduce
+const prices = await Promise.all(items.map((item) => priceOf(item)));
+const total = prices.reduce((a, b) => a + b, 0);
+```
+
+Deliberately conservative to distinguish real races from safe patterns:
+
+- `arr.push(…)`, `map.set(…)`, and distinct-index writes (`results[i] = …`) are **not** flagged — they are
+  order-tolerant, not lost updates;
+- a plain overwrite (`x = await f()`, no self-reference) is **not** flagged — that is last-write-wins, not a read-modify-write;
+- a binding declared inside the callback is local per iteration, so it is never flagged;
+- the callback must be `async` and contain an `await` — a synchronous callback has no interleaving point.
+
+## Options
+
+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.

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

@@ -0,0 +1,62 @@
+# `noctcore-async-safety/no-shared-mutable-module-state`
+
+> A module-scoped mutable binding written from an exported async/handler function is shared across concurrent requests.
+
+## Why
+
+On a server, module scope is process-wide: every concurrent request runs against the same module-level
+variables. A `let` counter or a `const cache = new Map()` written inside a request handler is not per-request
+state — request B observes and overwrites what request A left behind. This leaks data across users and produces
+races that never appear in single-request local testing.
+
+## What it flags
+
+Only when the file matches an `include` glob (see Options — the rule is **off by default**), a write to a
+module-scoped mutable binding performed inside an **exported async function** or a **handler-named export**:
+
+- a module-level `let`/`var` reassigned (`x = …`, `x += …`, `x++`); or
+- a module-level mutable container `const` (`[]`, `{}`, `new Map()`/`Set()`/`WeakMap()`/`WeakSet()`) mutated
+  (`c.push(…)`, `c.set(…)`, `c[i] = …`, `c.prop = …`).
+
+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
+let requestCount = 0;
+export async function GET() {
+  requestCount += 1;
+}
+
+// ✓ per-request
+export async function GET() {
+  const requestCount = 1;
+}
+```
+
+The lazy-initialization idioms `x ??= …` and `x ||= …` are always skipped (the common singleton/memoization
+pattern), and names in `allow` are exempt.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `include` | `string[]` (globs) | `[]` | Glob patterns for server files to arm the rule on. Empty = the rule does nothing. |
+| `allow` | `string[]` | `[]` | Binding names to exempt (intentional singletons / process-wide caches). |
+
+Globs support `**` (any run including `/`), `*` (any run except `/`), `?`, and a leading `**/` that also matches
+zero leading segments.
+
+```js
+'noctcore-async-safety/no-shared-mutable-module-state': [
+  'error',
+  { include: ['**/server/**', '**/*.server.ts'], allow: ['metricsRegistry'] },
+]
+```
+
+## When not to use it
+
+Client-side modules legitimately hold shared mutable state (caches, stores, singletons). Keep `include` scoped
+to server code so those are never touched.

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

@@ -0,0 +1,45 @@
+# `noctcore-async-safety/prefer-parallel-awaits`
+
+> Consecutive independent awaits run sequentially — they could run concurrently with `Promise.all`. 💡
+
+## Why
+
+`const a = await getUser(); const b = await getFeed();` waits for `getUser` to finish before `getFeed` even
+starts. When the two have no data dependency, that is latency added for nothing: `await Promise.all([...])`
+runs them concurrently and finishes in the time of the slower one.
+
+## What it flags
+
+A run of two or more **consecutive** statements of the exact shape `const <id> = await <call>()`, where:
+
+- every awaited expression is a single flat call whose arguments hide no nested call, `await`, or assignment
+  (so side-effect ordering stays out of scope);
+- the callee does not look like a mutation (`save*`, `create*`, `send*`, `commit*`, `push*`, …) — sequencing
+  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();
+
+// ✓ concurrent
+const [user, feed] = await Promise.all([getUser(), getFeed()]);
+```
+
+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.
+
+## Suggestion
+
+Reports offer an editor suggestion (never an autofix, since parallelizing also changes rejection timing) that
+rewrites the run into a single `const [a, b] = await Promise.all([...])`.
+
+## Options
+
+None.
+
+## When not to use it
+
+If your consecutive awaits carry side effects whose ordering matters but that this rule cannot see (e.g. reads
+that mutate a stream), disable it — the suggestion assumes the awaited reads are independent.

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

@@ -0,0 +1,55 @@
+# `noctcore-async-safety/require-fetch-timeout`
+
+> A `fetch` (or configured wrapper) call must carry a cancellation signal or timeout — an unbounded request can hang forever. 💡
+
+## Why
+
+`fetch` has no default timeout. A hung TCP connection or a server that accepts but never responds leaves the
+promise pending indefinitely, tying up a request slot, a connection, and any resources awaiting it. Passing
+`signal: AbortSignal.timeout(ms)` (or an equivalent `timeout` option on a wrapper) bounds the wait and makes
+the failure observable.
+
+## What it flags
+
+A call to global `fetch` — or any wrapper named in the `callees` option (e.g. `undici.request`, `axios`) —
+whose options carry neither a `signal` nor a `timeout`.
+
+The rule is purely syntactic and stays silent whenever it cannot see the arguments:
+
+- a spread argument (`fetch(url, ...opts)`) or a `...spread` inside the options object — opaque, skipped;
+- an options slot that is an identifier/call/member (`fetch(url, opts)`) — that bag may already set a signal, skipped;
+- a single non-string argument (`fetch(request)`) — could be a `Request` carrying its own signal, skipped.
+
+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
+await fetch('https://api.example.com/data');
+await fetch(url, { method: 'POST' });
+
+// ✓ bounded
+await fetch('https://api.example.com/data', { signal: AbortSignal.timeout(10000) });
+await fetch(url, { method: 'POST', signal: controller.signal });
+```
+
+## Suggestion
+
+Reports offer an editor suggestion (not an autofix) that inserts `signal: AbortSignal.timeout(<defaultTimeoutMs>)`
+into the options object, creating one if needed.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `callees` | `string[]` | `[]` | Additional callee texts to check, matched literally (`'axios'`, `'undici.request'`). `fetch` is always checked. |
+| `defaultTimeoutMs` | `integer` (≥1) | `10000` | The timeout value used in the suggestion. |
+
+```js
+'noctcore-async-safety/require-fetch-timeout': ['error', { callees: ['undici.request'], defaultTimeoutMs: 5000 }]
+```
+
+## When not to use it
+
+If your `fetch` wrapper enforces a timeout centrally (an interceptor, a default `AbortSignal`), the per-call
+signal is redundant — leave `callees` at its default so only bare `fetch` is checked, or disable the rule.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@noctcore/eslint-plugin-async-safety",
+  "version": "0.1.0",
+  "description": "ESLint rules for async correctness: fetch timeouts, AbortSignal forwarding, and shared-state / concurrency races.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "async",
+    "abortsignal",
+    "fetch",
+    "concurrency",
+    "noctcore"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noctcore/eslint-plugins.git",
+    "directory": "packages/eslint-plugin-async-safety"
+  },
+  "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/eslint-plugin-async-safety",
+  "bugs": "https://github.com/noctcore/eslint-plugins/issues",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@noctcore/eslint-utils": "^0.1.0",
+    "@typescript-eslint/utils": "^8.61.1"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@noctcore/eslint-test-utils": "workspace:*",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/parser": "^8.61.1",
+    "@typescript-eslint/rule-tester": "^8.61.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0",
+    "vitest": "^3"
+  }
+}