eslint-plugin-runtime-cleanup 1.2.8

package/docs/rules/guides/rollout-and-fix-safety.md

@@ -0,0 +1,42 @@
+---
+title: Rollout and fix safety
+description: Guidance for phased rollout, fix safety, and manual verification.
+---
+
+# Rollout and fix safety
+
+This page centralizes rollout guidance used across rule migrations.
+
+## Phased rollout model
+
+1. Start with `warn` severity to measure blast radius.
+2. Run `--fix` only on a scoped folder first.
+3. Review runtime-sensitive call sites manually.
+4. Promote to `error` after baseline cleanup.
+
+## Fix safety expectations
+
+- **Autofix-safe patterns:** simple API shape substitutions where runtime behavior is equivalent.
+- **Suggestion-only patterns:** potentially behavior-sensitive changes requiring explicit reviewer choice.
+- **Manual migrations:** replacements that depend on local typing, nullability, or control flow assumptions.
+
+## Manual verification checklist
+
+1. Verify import changes are deduplicated and stable.
+2. Confirm narrowed types still match downstream usage.
+3. Validate guard/predicate behavior with tests.
+4. Confirm no accidental semantic changes in edge cases.
+
+## FAQ
+
+### Why not migrate everything in one pass?
+
+Large one-shot migrations make regressions harder to detect and review. Smaller batches isolate risk.
+
+### Should we always use `--fix` in CI?
+
+No. Prefer running `--fix` locally and committing explicit changes. CI should validate, not rewrite, code.
+
+### How do we handle wrapper utilities?
+
+Either align wrappers to canonical helpers/types used by this plugin or deprecate wrappers that duplicate behavior.

package/docs/rules/guides/snapshot-testing.md

@@ -0,0 +1,20 @@
+---
+description: How to use Vitest snapshots safely and effectively in eslint-plugin-runtime-cleanup.
+---
+
+# Snapshot testing
+
+Prefer explicit assertions for rule behavior. Snapshots are useful only for
+stable generated surfaces such as preset matrices or public contract summaries.
+
+## Good snapshot targets
+
+- plugin preset contract summaries
+- generated README rule tables
+- generated docs navigation fragments
+
+## Avoid snapshots for rule fixes
+
+Autofix output should be written as explicit strings in RuleTester cases. That
+keeps cleanup transformations reviewable and prevents accidental acceptance of
+unsafe fixer behavior.

package/docs/rules/guides/type-aware-linting-readiness.md

@@ -0,0 +1,20 @@
+---
+description: Checklist and rollout playbook for enabling type-aware eslint-plugin-runtime-cleanup rules safely.
+---
+
+# Type-aware linting readiness
+
+Some future cleanup rules may need TypeScript parser services to distinguish
+resource-like values from unrelated identifiers. Use type-aware rules only when
+the project can provide reliable type information.
+
+## Requirements
+
+- `@typescript-eslint/parser` configured for the files being linted.
+- `parserOptions.projectService` or an equivalent typed parser setup.
+- CI memory and runtime budgets sized for type-aware linting.
+
+## Rollout
+
+Start with a small package or workspace. Compare runtime and findings against
+the non-type-aware preset before enabling typed rules broadly.

package/docs/rules/no-floating-abort-controllers.md

@@ -0,0 +1,126 @@
+# no-floating-abort-controllers
+
+Require `AbortController` handles to be retained so work can be aborted during
+cleanup.
+
+> **Rule catalog ID:** R006
+
+## Targeted pattern scope
+
+This rule targets `AbortController` construction where the controller handle is
+lost before the owning lifecycle can call `abort()`:
+
+- `new AbortController()`
+- `new window.AbortController()`
+- `new self.AbortController()`
+- `new globalThis.AbortController()`
+- `new AbortController().signal`
+
+The rule reports controllers that are immediately discarded and inline
+`.signal` handoffs that keep only the signal. A signal can observe cancellation,
+but it cannot initiate cancellation; the controller is the cleanup handle.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone controller construction such as `new AbortController();`
+- voided controller construction such as `void new AbortController();`
+- inline signal-only ownership such as
+  `fetch(url, { signal: new AbortController().signal })`
+- assignments that keep only `new AbortController().signal`
+
+It intentionally does not require a same-function `abort()` call. Ownership can
+be transferred to a component instance, request manager, disposable collection,
+returned object, or another lifecycle owner.
+
+## Why this rule exists
+
+`AbortController` is the cancellation handle for an `AbortSignal`. APIs such as
+`fetch()` and `addEventListener()` accept a signal, and calling
+`AbortController.abort()` later cancels or removes the associated work. If code
+passes only `new AbortController().signal`, no reachable owner remains that can
+abort the work during cleanup.
+
+## Incorrect
+
+```ts
+new AbortController();
+```
+
+```ts
+void new AbortController();
+```
+
+```ts
+fetch("/api", {
+    signal: new AbortController().signal,
+});
+```
+
+```ts
+const signal = new AbortController().signal;
+```
+
+## Correct
+
+```ts
+const controller = new AbortController();
+
+fetch("/api", {
+    signal: controller.signal,
+});
+
+controller.abort();
+```
+
+```ts
+return new AbortController();
+```
+
+```ts
+registerAbortController(new AbortController());
+```
+
+```ts
+using controller = createAbortControllerDisposable();
+```
+
+## Behavior and migration notes
+
+Store the controller in the same owner that is responsible for cancelling the
+work. In UI code, that is usually the component setup scope or a cleanup
+callback. In service code, it may be a request context, operation manager, or
+explicit disposable.
+
+When a controller is intentionally owned elsewhere, pass the controller itself
+to that owner instead of passing only the signal. A signal-only API boundary is
+appropriate for consumers that should observe cancellation but should not be
+able to cancel the operation.
+
+This rule does not autofix. Introducing a new controller variable without
+placing the matching `abort()` call in the correct lifecycle path would make the
+code look managed without actually solving cleanup.
+
+## ESLint flat config example
+
+```js
+import runtimeCleanup from "eslint-plugin-runtime-cleanup";
+
+export default [
+    runtimeCleanup.configs.recommended,
+];
+```
+
+## When not to use it
+
+Do not enable this rule for code that intentionally creates page-lifetime or
+process-lifetime cancellation signals and never expects to abort them. Prefer a
+narrow disable comment with a reason when the lifecycle is intentionally owned
+by the whole runtime.
+
+## Further reading
+
+- [MDN: `AbortController`](https://developer.mozilla.org/docs/Web/API/AbortController)
+- [MDN: `AbortSignal`](https://developer.mozilla.org/docs/Web/API/AbortSignal)
+- [MDN: `addEventListener()` signal option](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener)

package/docs/rules/no-floating-audio-contexts.md

@@ -0,0 +1,104 @@
+# no-floating-audio-contexts
+
+Require `AudioContext` instances to be retained so they can be closed.
+
+> **Rule catalog ID:** R018
+
+## Targeted pattern scope
+
+This rule targets browser audio context construction:
+
+- `new AudioContext(...)`
+- `new webkitAudioContext(...)`
+- `new window.AudioContext(...)`
+- `new globalThis.AudioContext(...)`
+
+The rule reports contexts that are immediately discarded, explicitly voided, or
+used through an immediate non-cleanup method call such as
+`new AudioContext().resume()`. It ignores locally shadowed direct constructor
+bindings so project-local classes with the same name are not treated as browser
+audio contexts.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone `new AudioContext()` expressions
+- `void new AudioContext()`
+- immediate non-cleanup use of an unowned context
+
+Immediate `close()` calls are allowed because they do not leave an owned context
+behind.
+
+## Why this rule exists
+
+`AudioContext` can hold audio hardware, decoding, graph, and scheduling
+resources. `AudioContext.close()` releases system audio resources used by the
+context. If the context is discarded, cleanup code cannot close it.
+
+## Incorrect
+
+```ts
+new AudioContext();
+```
+
+```ts
+void new window.AudioContext();
+```
+
+```ts
+new AudioContext().resume();
+```
+
+## Correct
+
+```ts
+const context = new AudioContext();
+
+try {
+    await context.resume();
+} finally {
+    await context.close();
+}
+```
+
+```ts
+function createAudioContext() {
+    return new AudioContext();
+}
+```
+
+```ts
+audioContextRegistry.add(new AudioContext());
+```
+
+## Behavior and migration notes
+
+Store the context in the audio session, component, game engine, visualizer, or
+test fixture that owns the audio graph. That owner should call `close()` during
+cleanup.
+
+This rule does not autofix because adding a variable without a matching
+`close()` path would not fix the resource lifecycle.
+
+## ESLint flat config example
+
+```js
+import runtimeCleanup from "eslint-plugin-runtime-cleanup";
+
+export default [
+    runtimeCleanup.configs.recommended,
+];
+```
+
+## When not to use it
+
+Do not enable this rule for tiny one-page demos where the browser page lifetime
+is intentionally the cleanup boundary. Use narrow inline disables for those
+examples.
+
+## Further reading
+
+- [MDN: `AudioContext`](https://developer.mozilla.org/docs/Web/API/AudioContext)
+- [MDN: `AudioContext.close()`](https://developer.mozilla.org/docs/Web/API/AudioContext/close)
+

package/docs/rules/no-floating-broadcast-channels.md

@@ -0,0 +1,105 @@
+# no-floating-broadcast-channels
+
+Require `BroadcastChannel` handles to be retained so they can be closed.
+
+> **Rule catalog ID:** R011
+
+## Targeted pattern scope
+
+This rule targets browser `BroadcastChannel` constructors:
+
+- `BroadcastChannel`
+- `window.BroadcastChannel`
+- `self.BroadcastChannel`
+- `globalThis.BroadcastChannel`
+
+The rule reports channel instances that are immediately discarded or chained
+directly into a method call other than `.close()`. In both cases there is no
+remaining channel handle available for teardown.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone channel construction such as `new BroadcastChannel("updates");`
+- voided channel construction such as `void new BroadcastChannel("updates");`
+- immediate message sends such as
+  `new BroadcastChannel("updates").postMessage(message);`
+- immediate listener registration on a discarded channel
+
+It intentionally does not require same-function `close()` calls. Ownership can
+be transferred to a component instance, channel manager, returned value, or
+longer-lived runtime owner.
+
+## Why this rule exists
+
+`BroadcastChannel.close()` terminates the connection to the underlying channel
+and lets the browser know the channel is no longer needed. If the channel handle
+is discarded, code cannot reliably call `.close()` or remove listeners during
+cleanup.
+
+## Incorrect
+
+```ts
+new BroadcastChannel("updates");
+```
+
+```ts
+void new BroadcastChannel("updates");
+```
+
+```ts
+new BroadcastChannel("updates").postMessage(message);
+```
+
+```ts
+new BroadcastChannel("updates").addEventListener("message", onMessage);
+```
+
+## Correct
+
+```ts
+const channel = new BroadcastChannel("updates");
+
+channel.addEventListener("message", onMessage);
+channel.close();
+```
+
+```ts
+return new BroadcastChannel(name);
+```
+
+```ts
+registerChannel(new BroadcastChannel(name));
+```
+
+## Behavior and migration notes
+
+Store the channel in the owner that will close it. For UI code, that is
+usually the component, route, or application shell lifecycle. For shared
+libraries, returning the channel or passing it to a channel manager keeps
+ownership explicit.
+
+This rule does not autofix. Choosing the owner and close point is a semantic
+decision.
+
+## ESLint flat config example
+
+```js
+import runtimeCleanup from "eslint-plugin-runtime-cleanup";
+
+export default [
+    runtimeCleanup.configs.recommended,
+];
+```
+
+## When not to use it
+
+Do not enable this rule for code that intentionally creates application-lifetime
+channels and does not need explicit teardown. Prefer a narrow disable comment
+with a reason when a channel is meant to live for the whole runtime.
+
+## Further reading
+
+- [MDN: `BroadcastChannel`](https://developer.mozilla.org/docs/Web/API/BroadcastChannel)
+- [MDN: `BroadcastChannel.close()`](https://developer.mozilla.org/docs/Web/API/BroadcastChannel/close)

package/docs/rules/no-floating-child-processes.md

@@ -0,0 +1,123 @@
+# no-floating-child-processes
+
+Require child process handles to be retained so they can be killed during
+cleanup.
+
+> **Rule catalog ID:** R005
+
+## Targeted pattern scope
+
+This rule targets asynchronous Node.js child process factories whose returned
+handle is needed for cleanup:
+
+- `spawn`
+- `exec`
+- `execFile`
+- `fork`
+
+The rule recognizes those factories when they come from `node:child_process` or
+`child_process` through named imports, default or namespace imports, CommonJS
+`require(...)` module bindings, destructured `require(...)`, or direct
+`require("node:child_process").spawn(...)` calls.
+
+The rule reports child process handles that are immediately discarded or chained
+directly into a method call other than `.kill()` or `.disconnect()`.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone child process calls such as `spawn("node", ["worker.js"]);`
+- voided child process calls such as `void childProcess.exec("node worker.js");`
+- immediate method chains such as
+  `childProcess.fork("./worker.js").on("exit", handleExit);`
+- inline require calls such as
+  `require("node:child_process").spawn("node", ["worker.js"]);`
+
+It intentionally does not require same-function `kill()` calls. Ownership can be
+transferred to a supervisor, returned handle, disposable collection, or
+process-lifetime owner.
+
+## Why this rule exists
+
+Asynchronous child process factories return a `ChildProcess` handle. That handle
+is the API surface for terminating the process, disconnecting IPC, inspecting
+exit state, and wiring teardown. Discarding it leaves no explicit owner that can
+clean up the subprocess when the surrounding runtime scope ends.
+
+## Incorrect
+
+```ts
+import { spawn } from "node:child_process";
+
+spawn("node", ["worker.js"]);
+```
+
+```ts
+import childProcess from "node:child_process";
+
+void childProcess.exec("node worker.js");
+```
+
+```ts
+import * as childProcess from "child_process";
+
+childProcess.fork("./worker.js").on("exit", handleExit);
+```
+
+```ts
+require("node:child_process").spawn("node", ["worker.js"]);
+```
+
+## Correct
+
+```ts
+import { spawn } from "node:child_process";
+
+const child = spawn("node", ["worker.js"]);
+
+child.kill();
+```
+
+```ts
+import { fork } from "node:child_process";
+
+return fork("./worker.js");
+```
+
+```ts
+import childProcess from "node:child_process";
+
+registerChildProcess(childProcess.spawn("node", ["worker.js"]));
+```
+
+## Behavior and migration notes
+
+Store the `ChildProcess` handle in the owner that will terminate or supervise
+the subprocess. For test helpers and task runners, that is usually a local
+cleanup scope. For long-running services, it can be a process supervisor or
+resource registry.
+
+This rule does not autofix. Inserting a variable without a real shutdown path
+would only make ownership look explicit while preserving the leak.
+
+## ESLint flat config example
+
+```js
+import runtimeCleanup from "eslint-plugin-runtime-cleanup";
+
+export default [
+    runtimeCleanup.configs.recommended,
+];
+```
+
+## When not to use it
+
+Do not enable this rule for scripts that intentionally start detached,
+process-lifetime children and do not own their cleanup. Prefer a narrow disable
+comment with a reason for those launch points.
+
+## Further reading
+
+- [Node.js: asynchronous process creation](https://nodejs.org/api/child_process.html#asynchronous-process-creation)
+- [Node.js: `subprocess.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal)

package/docs/rules/no-floating-disposable-stacks.md

@@ -0,0 +1,118 @@
+# no-floating-disposable-stacks
+
+Require `DisposableStack` handles to be retained so registered disposers run.
+
+> **Rule catalog ID:** R008
+
+## Targeted pattern scope
+
+This rule targets the standard explicit resource-management stack
+constructors:
+
+- `DisposableStack`
+- `AsyncDisposableStack`
+- `globalThis.DisposableStack`, `window.DisposableStack`, and
+  `self.DisposableStack`
+- `globalThis.AsyncDisposableStack`, `window.AsyncDisposableStack`, and
+  `self.AsyncDisposableStack`
+
+The rule reports disposable stack instances that are immediately discarded or
+chained directly into a method call other than `.dispose()` or
+`.disposeAsync()`. In both cases there is no remaining stack handle available to
+dispose registered resources.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone stack construction such as `new DisposableStack();`
+- voided stack construction such as `void new AsyncDisposableStack();`
+- immediate registration calls such as `new DisposableStack().defer(cleanup);`
+- immediate async registration calls such as
+  `new AsyncDisposableStack().use(resource);`
+
+It intentionally does not require same-function disposal for retained stacks.
+Ownership can be handled by a `using` or `await using` declaration, a returned
+stack, or a dedicated lifecycle manager.
+
+## Why this rule exists
+
+`DisposableStack` and `AsyncDisposableStack` are ownership containers. They only
+provide cleanup if the stack itself is retained and later disposed. Discarding
+the stack after registering work silently drops the only object that can run the
+registered disposers.
+
+## Incorrect
+
+```ts
+new DisposableStack();
+```
+
+```ts
+void new AsyncDisposableStack();
+```
+
+```ts
+new DisposableStack().defer(cleanup);
+```
+
+```ts
+new AsyncDisposableStack().use(resource);
+```
+
+## Correct
+
+```ts
+using stack = new DisposableStack();
+
+stack.defer(cleanup);
+```
+
+```ts
+await using stack = new AsyncDisposableStack();
+
+stack.use(resource);
+```
+
+```ts
+return new DisposableStack();
+```
+
+```ts
+registerDisposableStack(new AsyncDisposableStack());
+```
+
+## Behavior and migration notes
+
+Keep the stack in the same lifecycle owner that will dispose it. Prefer
+`using` for synchronous stacks and `await using` for asynchronous stacks when
+the current runtime and compiler settings support explicit resource
+management. If a framework or library owns disposal, pass the stack directly to
+that owner.
+
+This rule does not autofix. Choosing between `using`, `await using`, returning
+the stack, or wiring a lifecycle manager changes ownership semantics and must
+be decided by the developer.
+
+## ESLint flat config example
+
+```js
+import runtimeCleanup from "eslint-plugin-runtime-cleanup";
+
+export default [
+    runtimeCleanup.configs.recommended,
+];
+```
+
+## When not to use it
+
+Do not enable this rule for generated code or compatibility layers that
+intentionally construct disposable stack shims for feature detection. Prefer a
+narrow disable comment with a reason for those cases.
+
+## Further reading
+
+- [MDN: JavaScript resource management](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Resource_management)
+- [MDN: `DisposableStack`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DisposableStack)
+- [MDN: `AsyncDisposableStack`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/AsyncDisposableStack)
+- [TypeScript 5.2: Explicit Resource Management](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html)