eslint-plugin-runtime-cleanup 1.2.8

package/docs/rules/no-floating-object-urls.md

@@ -0,0 +1,102 @@
+# no-floating-object-urls
+
+Require object URLs to be retained so they can be revoked.
+
+> **Rule catalog ID:** R017
+
+## Targeted pattern scope
+
+This rule targets browser object URL creation APIs:
+
+- `URL.createObjectURL(...)`
+- `globalThis.URL.createObjectURL(...)`
+- `window.URL.createObjectURL(...)`
+- `self.URL.createObjectURL(...)`
+
+The rule reports object URLs that are immediately discarded or explicitly
+voided. It ignores locally shadowed `URL` bindings so project-local helpers with
+the same name are not treated as the platform API.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone `URL.createObjectURL(...)` calls
+- `void URL.createObjectURL(...)`
+- static computed global forms such as:
+
+```ts
+window["URL"]["createObjectURL"](blob);
+```
+
+The rule intentionally allows object URLs that are stored, returned, or passed to
+a lifecycle manager. It does not try to prove that every retained URL is later
+revoked.
+
+## Why this rule exists
+
+`URL.createObjectURL()` creates a URL that keeps the backing `Blob`, `File`, or
+media source reachable until the URL is revoked. Discarding the returned string
+means cleanup code cannot call `URL.revokeObjectURL()` for that object URL.
+
+## Incorrect
+
+```ts
+URL.createObjectURL(blob);
+```
+
+```ts
+void window.URL.createObjectURL(file);
+```
+
+## Correct
+
+```ts
+const objectUrl = URL.createObjectURL(blob);
+
+try {
+    image.src = objectUrl;
+} finally {
+    URL.revokeObjectURL(objectUrl);
+}
+```
+
+```ts
+function createDownloadUrl(file: File) {
+    return URL.createObjectURL(file);
+}
+```
+
+```ts
+objectUrlRegistry.add(URL.createObjectURL(blob));
+```
+
+## Behavior and migration notes
+
+Store the object URL in the owner that will revoke it. For UI code, that is
+usually a component cleanup hook, image preview controller, download manager, or
+temporary asset registry.
+
+This rule does not autofix. Adding a generated variable without adding
+`URL.revokeObjectURL()` would make the lint error disappear while preserving the
+resource 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 throwaway snippets where the document lifetime is
+the intended cleanup boundary. Prefer a narrow disable comment for those cases.
+
+## Further reading
+
+- [MDN: `URL.createObjectURL()`](https://developer.mozilla.org/docs/Web/API/URL/createObjectURL_static)
+- [MDN: `URL.revokeObjectURL()`](https://developer.mozilla.org/docs/Web/API/URL/revokeObjectURL_static)

package/docs/rules/no-floating-observers.md

@@ -0,0 +1,108 @@
+# no-floating-observers
+
+Require observer instances to be retained so they can be disconnected during
+cleanup.
+
+> **Rule catalog ID:** R003
+
+## Targeted pattern scope
+
+This rule targets native observer constructors whose active observation must be
+stopped with `disconnect()`:
+
+- `IntersectionObserver`
+- `MutationObserver`
+- `PerformanceObserver`
+- `ReportingObserver`
+- `ResizeObserver`
+
+The rule reports observer instances that are immediately discarded or chained
+directly into `.observe(...)`. In both cases there is no remaining observer
+handle available for teardown.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone observer construction expressions such as
+  `new ResizeObserver(callback);`
+- voided observer construction such as
+  `void new MutationObserver(callback);`
+- immediate observation chains such as
+  `new IntersectionObserver(callback).observe(element);`
+
+It intentionally does not require same-function `disconnect()` calls. That is a
+separate ownership question, and many valid designs transfer observer ownership
+to a manager, component instance, returned disposable, or framework lifecycle.
+
+## Why this rule exists
+
+Observer APIs hold callbacks and continue delivering records until disconnected.
+If the observer instance is not retained, later cleanup cannot call
+`disconnect()`, and the code has no explicit ownership point for the active
+runtime resource.
+
+## Incorrect
+
+```ts
+new ResizeObserver(handleResize);
+```
+
+```ts
+void new MutationObserver(handleMutations);
+```
+
+```ts
+new IntersectionObserver(handleIntersections).observe(element);
+```
+
+## Correct
+
+```ts
+const observer = new ResizeObserver(handleResize);
+
+observer.observe(element);
+observer.disconnect();
+```
+
+```ts
+return new MutationObserver(handleMutations);
+```
+
+```ts
+registerObserver(new IntersectionObserver(handleIntersections));
+```
+
+## Behavior and migration notes
+
+Store observer instances in the same lifecycle owner that will disconnect them.
+For components, that is usually the component setup scope or an owned disposable
+collection. For shared utilities, returning the observer or passing it to a
+dedicated resource manager is acceptable because ownership is explicit.
+
+This rule does not autofix. Choosing the right owner and cleanup point is a
+semantic decision, and inserting a variable without a matching `disconnect()`
+would only make the leak less obvious.
+
+## 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 observers without later cleanup. Prefer a narrow disable
+comment with a reason when an observer is meant to live for the whole runtime.
+
+## Further reading
+
+- [MDN: `IntersectionObserver`](https://developer.mozilla.org/docs/Web/API/IntersectionObserver)
+- [MDN: `MutationObserver`](https://developer.mozilla.org/docs/Web/API/MutationObserver)
+- [MDN: `PerformanceObserver`](https://developer.mozilla.org/docs/Web/API/PerformanceObserver)
+- [MDN: `ResizeObserver`](https://developer.mozilla.org/docs/Web/API/ResizeObserver)

package/docs/rules/no-floating-servers.md

@@ -0,0 +1,127 @@
+# no-floating-servers
+
+Require Node.js server handles to be retained so they can be closed.
+
+> **Rule catalog ID:** R013
+
+## Targeted pattern scope
+
+This rule targets server factory calls from Node.js core networking modules:
+
+- `http.createServer`
+- `https.createServer`
+- `http2.createServer`
+- `http2.createSecureServer`
+- `net.createServer`
+- equivalent named imports, namespace imports, default imports, destructured
+  `require(...)` calls, and inline `require(...).createServer(...)` calls
+
+The rule reports server handles that are immediately discarded, including
+discarded `.listen(...)` chains. It does not require type information because
+the recognized factories are tied to import and `require` sources.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone server creation such as `createServer(handler);`
+- voided server creation such as `void http.createServer(handler);`
+- discarded listen chains such as `http.createServer(handler).listen(3000);`
+- discarded method chains that start from an unretained server handle
+
+It intentionally does not require same-function `close()` calls. Ownership can
+be transferred to a framework adapter, test harness, returned value, or shutdown
+manager.
+
+## Why this rule exists
+
+Node.js server factories create long-lived handles that can keep the process
+alive and hold open ports. Once a server is listening, retaining the `Server`
+object is the normal way to call `.close()`, coordinate graceful shutdown, and
+stop accepting new work.
+
+## Incorrect
+
+```ts
+import { createServer } from "node:http";
+
+createServer(handler);
+```
+
+```ts
+import http from "node:http";
+
+http.createServer(handler).listen(3000);
+```
+
+```ts
+const http2 = require("http2");
+
+http2.createSecureServer(options, handler).listen(8443);
+```
+
+## Correct
+
+```ts
+import { createServer } from "node:http";
+
+const server = createServer(handler);
+
+server.listen(3000);
+server.close();
+```
+
+```ts
+import * as http from "node:http";
+
+const server = http.createServer(handler).listen(3000);
+
+server.close();
+```
+
+```ts
+return createServer(handler).listen(3000);
+```
+
+```ts
+registerServer(createServer(handler).listen(3000));
+```
+
+## Behavior and migration notes
+
+Store the returned server handle in the owner that will shut it down. In
+applications, that is usually the process lifecycle or graceful-shutdown
+coordinator. In tests, it is usually the test fixture cleanup hook.
+
+This rule allows immediate `.close()` calls and returned or passed server
+handles. It reports discarded `.listen(...)` chains because `listen()` returns
+the server object; discarding that returned handle makes later shutdown
+coordination difficult.
+
+This rule does not autofix. Choosing whether the owner is a module variable,
+dependency-injected lifecycle manager, framework adapter, or test fixture 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 tiny one-off scripts where the server is
+intentionally process-lifetime and never needs graceful shutdown. Prefer a
+narrow disable comment with a reason in those files rather than weakening the
+rule globally.
+
+## Further reading
+
+- [Node.js: `http.createServer()`](https://nodejs.org/api/http.html#httpcreateserveroptions-requestlistener)
+- [Node.js: `server.close()`](https://nodejs.org/api/http.html#serverclosecallback)
+- [Node.js: `net.createServer()`](https://nodejs.org/api/net.html#netcreateserveroptions-connectionlistener)
+- [Node.js: `net.Server.close()`](https://nodejs.org/api/net.html#serverclosecallback)

package/docs/rules/no-floating-streams.md

@@ -0,0 +1,120 @@
+# no-floating-streams
+
+Require Node.js file stream handles to be retained so they can be closed during
+cleanup.
+
+> **Rule catalog ID:** R007
+
+## Targeted pattern scope
+
+This rule targets Node.js file stream factories from `fs` and `node:fs`:
+
+- `createReadStream`
+- `createWriteStream`
+- `fs.createReadStream`
+- `fs.createWriteStream`
+- `require("fs").createReadStream`
+- `require("node:fs").createWriteStream`
+
+The rule reports only immediately discarded stream factory calls. It does not
+report assigned, returned, manager-owned, or immediately piped streams.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone file stream creation such as `createReadStream(path);`
+- voided file stream creation such as `void fs.createWriteStream(path);`
+- discarded CommonJS namespace or destructured factory calls
+
+It intentionally does not require same-function `destroy()` or `end()` calls.
+Streams are often owned by a pipeline, HTTP response, higher-level resource
+manager, or returned API contract.
+
+## Why this rule exists
+
+Node.js streams can hold file descriptors and other underlying resources until
+they close or are destroyed. A discarded file stream has no reachable handle for
+`destroy()`, `end()`, error handling, or ownership transfer. Unlike an
+immediately piped stream, a bare discarded stream is almost always accidental.
+
+## Incorrect
+
+```ts
+import { createReadStream } from "node:fs";
+
+createReadStream("input.txt");
+```
+
+```ts
+import * as fs from "node:fs";
+
+void fs.createWriteStream("output.txt");
+```
+
+```ts
+const fs = require("fs");
+
+fs.createReadStream("input.txt");
+```
+
+## Correct
+
+```ts
+import { createReadStream } from "node:fs";
+
+const stream = createReadStream("input.txt");
+
+stream.destroy();
+```
+
+```ts
+import * as fs from "node:fs";
+
+return fs.createWriteStream("output.txt");
+```
+
+```ts
+import * as fs from "node:fs";
+
+fs.createReadStream("input.txt").pipe(response);
+```
+
+```ts
+registerStream(fs.createReadStream("input.txt"));
+```
+
+## Behavior and migration notes
+
+Keep the stream handle in the same lifecycle owner that will observe errors and
+close or destroy the stream. If another API owns the stream, make that
+ownership explicit by returning it, passing it to a resource manager, or piping
+it into the destination that owns the pipeline.
+
+This rule is intentionally narrow. It focuses on `fs` file stream factories
+because they are common, have concrete resource ownership implications, and can
+be detected reliably without type information.
+
+This rule does not autofix. Choosing whether to store, return, pipe, or destroy
+the stream 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 one-off scripts where discarded
+file stream construction is intentional and process lifetime owns the cleanup.
+Prefer a narrow disable comment with a reason for those cases.
+
+## Further reading
+
+- [Node.js: Stream](https://nodejs.org/api/stream.html)
+- [Node.js: File system streams](https://nodejs.org/api/fs.html#filehandlecreatereadstreamoptions)

package/docs/rules/no-floating-timers.md

@@ -0,0 +1,120 @@
+# no-floating-timers
+
+Require timer handles to be retained so they can be cleared during cleanup.
+
+> **Rule catalog ID:** R001
+
+## Targeted pattern scope
+
+This rule targets timer APIs that return handles with an explicit cleanup
+counterpart. It is intentionally conservative: the rule reports only calls where
+the returned handle is immediately discarded.
+
+### Matched patterns
+
+The rule checks direct global calls to:
+
+- `setTimeout`
+- `setInterval`
+- `setImmediate`
+- `requestAnimationFrame`
+- `requestIdleCallback`
+
+It also checks the same methods when called through these global receivers:
+
+- `globalThis`
+- `window`
+- `self`
+- `global`
+
+### Detection boundaries
+
+The rule does not prove that every retained handle is cleared. That broader
+lifetime analysis needs separate rules that understand cleanup blocks, effect
+callbacks, disposal protocols, and framework lifecycle APIs.
+
+The rule also skips locally declared or imported direct timer identifiers, so a
+project-local helper named `setTimeout` is not treated as the platform timer API.
+
+## What this rule reports
+
+The rule reports timer calls when the returned handle is used only as a bare
+expression or deliberately discarded with `void`.
+
+## Why this rule exists
+
+Floating timer handles make cleanup impossible. Intervals keep running, timeouts
+can fire after teardown, animation callbacks can touch detached state, and idle
+callbacks can outlive the component or request that scheduled them. Retaining
+the handle is the first enforceable step toward calling the matching cleanup API
+from the correct lifecycle boundary.
+
+## ❌ Incorrect
+
+```ts
+setInterval(poll, 1000);
+```
+
+```ts
+globalThis.setTimeout(flush, 250);
+```
+
+```ts
+void window.requestAnimationFrame(render);
+```
+
+## ✅ Correct
+
+```ts
+const intervalId = setInterval(poll, 1000);
+
+clearInterval(intervalId);
+```
+
+```ts
+const timeoutId = globalThis.setTimeout(flush, 250);
+
+clearTimeout(timeoutId);
+```
+
+```ts
+return window.requestAnimationFrame(render);
+```
+
+```ts
+timerRegistry.add(setTimeout(flush, 250));
+```
+
+## Behavior and migration notes
+
+Start by storing each reported handle in a variable, returning it to the caller,
+or passing it to an existing timer registry. Then clear the handle from the
+nearest lifecycle cleanup path, such as a `finally` block, component cleanup
+callback, request teardown hook, or disposable object.
+
+This rule does not autofix because choosing the correct cleanup location is a
+semantic decision. A mechanical fix that only introduces a variable would still
+leave the resource alive.
+
+## 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 files that intentionally schedule process-lifetime
+timers and have no teardown path. Prefer a narrow ESLint disable comment at the
+call site with a reason when that pattern is deliberate.
+
+## Further reading
+
+- [MDN: `setTimeout`](https://developer.mozilla.org/docs/Web/API/Window/setTimeout)
+- [MDN: `clearTimeout`](https://developer.mozilla.org/docs/Web/API/Window/clearTimeout)
+- [MDN: `requestAnimationFrame`](https://developer.mozilla.org/docs/Web/API/Window/requestAnimationFrame)
+- [Node.js timers](https://nodejs.org/api/timers.html)

package/docs/rules/no-floating-wake-locks.md

@@ -0,0 +1,109 @@
+# no-floating-wake-locks
+
+Require `WakeLockSentinel` handles to be retained so they can be released.
+
+> **Rule catalog ID:** R016
+
+## Targeted pattern scope
+
+This rule targets screen wake lock requests:
+
+- `navigator.wakeLock.request(...)`
+- `window.navigator.wakeLock.request(...)`
+- `globalThis.navigator.wakeLock.request(...)`
+
+The rule reports wake lock requests whose resulting `WakeLockSentinel` is
+immediately discarded, including `await` expressions that do not store, return,
+or pass the sentinel to another owner.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone wake lock requests such as
+  `navigator.wakeLock.request("screen");`
+- voided wake lock requests such as
+  `void navigator.wakeLock.request("screen");`
+- awaited standalone requests such as
+  `await navigator.wakeLock.request("screen");`
+
+It intentionally allows promise chains and lifecycle-manager calls that receive
+the sentinel. The rule focuses on obviously unowned wake lock handles.
+
+## Why this rule exists
+
+`navigator.wakeLock.request()` resolves to a `WakeLockSentinel`. The sentinel is
+the handle that can be released manually with `release()`, and applications
+usually need to retain it to update UI, react to release events, or release the
+wake lock during cleanup.
+
+## Incorrect
+
+```ts
+navigator.wakeLock.request("screen");
+```
+
+```ts
+void navigator.wakeLock.request("screen");
+```
+
+```ts
+async function keepAwake() {
+    await navigator.wakeLock.request("screen");
+}
+```
+
+## Correct
+
+```ts
+async function keepAwake() {
+    const sentinel = await navigator.wakeLock.request("screen");
+
+    await sentinel.release();
+}
+```
+
+```ts
+async function keepAwake() {
+    return navigator.wakeLock.request("screen");
+}
+```
+
+```ts
+async function keepAwake() {
+    registerWakeLock(await navigator.wakeLock.request("screen"));
+}
+```
+
+## Behavior and migration notes
+
+Store the sentinel in the owner that will call `release()`. For UI code, that is
+usually a component, route, or media/session controller. Applications should
+also consider listening for the sentinel's `release` event because user agents
+can release wake locks automatically.
+
+This rule does not autofix. Choosing the owning lifecycle and release behavior
+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 where wake lock ownership is intentionally
+hidden inside an abstraction that the rule cannot see. Prefer wrapping
+`navigator.wakeLock.request()` in that abstraction and disabling the rule only
+inside the wrapper if needed.
+
+## Further reading
+
+- [MDN: Screen Wake Lock API](https://developer.mozilla.org/docs/Web/API/Screen_Wake_Lock_API)
+- [MDN: `WakeLockSentinel`](https://developer.mozilla.org/docs/Web/API/WakeLockSentinel)
+- [MDN: `WakeLockSentinel.release()`](https://developer.mozilla.org/docs/Web/API/WakeLockSentinel/release)