eslint-plugin-runtime-cleanup 1.2.8

package/docs/rules/no-floating-file-watchers.md

@@ -0,0 +1,111 @@
+# no-floating-file-watchers
+
+Require Node.js file watcher handles to be retained so they can be closed.
+
+> **Rule catalog ID:** R010
+
+## Targeted pattern scope
+
+This rule targets Node.js `fs.watch()` calls from `fs` and `node:fs`:
+
+- `watch`
+- `fs.watch`
+- `require("fs").watch`
+- `require("node:fs").watch`
+
+The rule reports watcher handles that are immediately discarded or chained
+directly into a method call other than `.close()`. It does not target
+`node:fs/promises` async iterator watchers because those use different
+ownership and cancellation patterns.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone watcher creation such as `watch("src", onChange);`
+- voided watcher creation such as `void fs.watch("src", onChange);`
+- discarded CommonJS namespace or destructured `watch` calls
+- immediate event registration on an unowned watcher such as
+  `fs.watch("src").on("error", onError);`
+
+It intentionally does not require same-function `close()` calls. Watcher
+ownership can be transferred by returning the watcher or passing it to a
+dedicated lifecycle manager.
+
+## Why this rule exists
+
+`fs.watch()` returns an `FSWatcher`. Active watchers can keep the Node.js event
+loop alive and continue receiving file-system events until they are closed. If
+the watcher handle is discarded, later cleanup cannot reliably call `.close()`
+or coordinate shutdown behavior.
+
+## Incorrect
+
+```ts
+import { watch } from "node:fs";
+
+watch("src", onChange);
+```
+
+```ts
+import * as fs from "node:fs";
+
+void fs.watch("src", onChange);
+```
+
+```ts
+import * as fs from "node:fs";
+
+fs.watch("src", onChange).on("error", onError);
+```
+
+## Correct
+
+```ts
+import { watch } from "node:fs";
+
+const watcher = watch("src", onChange);
+
+watcher.close();
+```
+
+```ts
+import * as fs from "node:fs";
+
+return fs.watch("src", onChange);
+```
+
+```ts
+registerWatcher(fs.watch("src", onChange));
+```
+
+## Behavior and migration notes
+
+Keep the watcher handle in the owner that will close it during teardown. For
+development tools, that is usually the process-level watcher manager. For
+library code, returning the watcher or passing it to a lifecycle manager makes
+the ownership contract explicit.
+
+This rule does not autofix. Introducing a variable without a matching close
+path would hide the lifecycle problem instead of fixing it.
+
+## 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 where a watcher intentionally lives until
+process exit and no explicit shutdown path is needed. Prefer a narrow disable
+comment with a reason for those cases.
+
+## Further reading
+
+- [Node.js: `fs.watch()`](https://nodejs.org/api/fs.html#fswatchfilename-options-listener)
+- [Node.js: `FSWatcher.close()`](https://nodejs.org/api/fs.html#watcherclose)

package/docs/rules/no-floating-geolocation-watches.md

@@ -0,0 +1,95 @@
+# no-floating-geolocation-watches
+
+Require geolocation watch IDs to be retained so they can be cleared.
+
+> **Rule catalog ID:** R014
+
+## Targeted pattern scope
+
+This rule targets browser geolocation watcher registration:
+
+- `navigator.geolocation.watchPosition(...)`
+- `window.navigator.geolocation.watchPosition(...)`
+- `globalThis.navigator.geolocation.watchPosition(...)`
+
+The rule reports calls whose returned watch ID is immediately discarded. The
+watch ID is the handle needed to unregister the watcher with
+`navigator.geolocation.clearWatch(...)`.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone watcher registration such as
+  `navigator.geolocation.watchPosition(onPosition);`
+- voided watcher registration such as
+  `void navigator.geolocation.watchPosition(onPosition);`
+- TypeScript-wrapped expressions that still discard the returned watch ID
+
+It intentionally does not require same-function `clearWatch()` calls. Ownership
+can be transferred to a component instance, route lifecycle, returned value, or
+watch manager.
+
+## Why this rule exists
+
+`watchPosition()` installs repeated location monitoring callbacks. The browser
+returns a numeric ID for that watch, and `clearWatch(id)` uses that ID to remove
+the registered monitoring handlers. If the ID is discarded, the code that owns
+the lifecycle cannot reliably unregister the watcher.
+
+## Incorrect
+
+```ts
+navigator.geolocation.watchPosition(onPosition);
+```
+
+```ts
+void navigator.geolocation.watchPosition(onPosition, onError);
+```
+
+## Correct
+
+```ts
+const watchId = navigator.geolocation.watchPosition(onPosition);
+
+navigator.geolocation.clearWatch(watchId);
+```
+
+```ts
+return navigator.geolocation.watchPosition(onPosition);
+```
+
+```ts
+registerWatch(navigator.geolocation.watchPosition(onPosition));
+```
+
+## Behavior and migration notes
+
+Store the returned watch ID in the owner that will call `clearWatch()`. In UI
+code, that is usually the component, route, or view lifecycle. In shared
+libraries, returning the ID or passing it to a watcher manager keeps ownership
+explicit.
+
+This rule does not autofix. Choosing the owner and cleanup 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 page-lifetime
+geolocation watches and does not need explicit teardown. Prefer a narrow disable
+comment with a reason in those files.
+
+## Further reading
+
+- [MDN: `Geolocation.watchPosition()`](https://developer.mozilla.org/docs/Web/API/Geolocation/watchPosition)
+- [MDN: `Geolocation.clearWatch()`](https://developer.mozilla.org/docs/Web/API/Geolocation/clearWatch)

package/docs/rules/no-floating-infinite-animations.md

@@ -0,0 +1,110 @@
+# no-floating-infinite-animations
+
+Require infinite Web Animations to be retained so they can be canceled.
+
+> **Rule catalog ID:** R020
+
+## Targeted pattern scope
+
+This type-aware rule targets `Element#animate(...)` calls whose timing options
+explicitly use infinite iterations:
+
+- `{ iterations: Infinity }`
+- `{ iterations: +Infinity }`
+- `{ iterations: Number.POSITIVE_INFINITY }`
+- `{ iterations: globalThis.Number.POSITIVE_INFINITY }`
+
+The rule uses TypeScript parser services to confirm that the receiver is a DOM
+`Element`. That keeps project-local `animate(...)` methods out of scope.
+
+## What this rule reports
+
+The rule reports infinite animations when the returned `Animation` is discarded
+or immediately used through a non-cleanup member:
+
+- standalone infinite `element.animate(...)` calls
+- immediate chains such as `element.animate(...).play()`
+
+Finite one-shot animations are intentionally allowed. Fire-and-forget finite
+animations are common and do not have the same long-running cleanup risk.
+Immediate `cancel()` and `finish()` calls are allowed.
+
+## Why this rule exists
+
+`Element#animate()` returns an `Animation` object. Infinite animations continue
+until canceled, finished, the effect is removed, or the document lifecycle ends.
+If the returned `Animation` is discarded, component or route cleanup code cannot
+reliably stop it.
+
+## Incorrect
+
+```ts
+element.animate(keyframes, {
+    duration: 1000,
+    iterations: Infinity,
+});
+```
+
+```ts
+element.animate(keyframes, {
+    iterations: Number.POSITIVE_INFINITY,
+}).play();
+```
+
+## Correct
+
+```ts
+const animation = element.animate(keyframes, {
+    duration: 1000,
+    iterations: Infinity,
+});
+
+cleanupCallbacks.add(() => animation.cancel());
+```
+
+```ts
+function startPulse(element: Element) {
+    return element.animate(keyframes, {
+        duration: 1000,
+        iterations: Infinity,
+    });
+}
+```
+
+```ts
+element.animate(keyframes, {
+    iterations: 1,
+});
+```
+
+## Behavior and migration notes
+
+This rule is deliberately narrower than a general `Element#animate()` rule. It
+only targets explicitly infinite animations because one-shot animations are often
+safe to let complete naturally.
+
+This rule does not autofix. A safe fix needs to choose the correct lifecycle
+owner and cancellation point.
+
+## ESLint flat config example
+
+```js
+import runtimeCleanup from "eslint-plugin-runtime-cleanup";
+
+export default [
+    runtimeCleanup.configs["recommended-type-checked"],
+];
+```
+
+## When not to use it
+
+Do not enable this rule without TypeScript parser services. For intentionally
+page-lifetime infinite decorative animations, use a narrow disable comment near
+the animation start.
+
+## Further reading
+
+- [MDN: `Element.animate()`](https://developer.mozilla.org/docs/Web/API/Element/animate)
+- [MDN: `Animation.cancel()`](https://developer.mozilla.org/docs/Web/API/Animation/cancel)
+- [MDN: `Animation.finish()`](https://developer.mozilla.org/docs/Web/API/Animation/finish)
+

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

@@ -0,0 +1,113 @@
+# no-floating-media-streams
+
+Require captured `MediaStream` handles to be retained so their tracks can be
+stopped.
+
+> **Rule catalog ID:** R015
+
+## Targeted pattern scope
+
+This rule targets browser media capture APIs:
+
+- `navigator.mediaDevices.getUserMedia(...)`
+- `navigator.mediaDevices.getDisplayMedia(...)`
+- `window.navigator.mediaDevices.getUserMedia(...)`
+- `globalThis.navigator.mediaDevices.getDisplayMedia(...)`
+
+The rule reports capture requests whose resulting `MediaStream` is immediately
+discarded, including `await` expressions that do not store, return, or pass the
+stream to another owner.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone media capture requests
+- voided media capture requests
+- `await navigator.mediaDevices.getUserMedia(...)` used as a standalone
+  expression
+- `await navigator.mediaDevices.getDisplayMedia(...)` used as a standalone
+  expression
+
+It intentionally allows promise chains and lifecycle-manager calls that receive
+the stream. The rule focuses on obviously unowned stream handles, not on proving
+that every possible owner eventually stops every track.
+
+## Why this rule exists
+
+`getUserMedia()` and `getDisplayMedia()` return `MediaStream` objects backed by
+media tracks. Tracks can keep cameras, microphones, screen capture, indicators,
+or permission-sensitive resources active. `MediaStreamTrack.stop()` tells the
+browser that a track's source is no longer needed. If the stream handle is
+discarded, cleanup code cannot reliably stop its tracks.
+
+## Incorrect
+
+```ts
+navigator.mediaDevices.getUserMedia({ video: true });
+```
+
+```ts
+void navigator.mediaDevices.getDisplayMedia({ video: true });
+```
+
+```ts
+async function openCamera() {
+    await navigator.mediaDevices.getUserMedia({ video: true });
+}
+```
+
+## Correct
+
+```ts
+async function openCamera() {
+    const stream = await navigator.mediaDevices.getUserMedia({ video: true });
+
+    stream.getTracks().forEach((track) => track.stop());
+}
+```
+
+```ts
+async function openScreen() {
+    return navigator.mediaDevices.getDisplayMedia({ video: true });
+}
+```
+
+```ts
+async function openCamera() {
+    registerStream(
+        await navigator.mediaDevices.getUserMedia({ audio: true }),
+    );
+}
+```
+
+## Behavior and migration notes
+
+Store the stream in the lifecycle owner that will stop its tracks. For UI code,
+that is usually a component cleanup hook, route cleanup hook, recording
+controller, or media session manager.
+
+This rule does not autofix. Introducing a local variable without a matching
+track-stop lifecycle would hide the cleanup bug instead of solving it.
+
+## 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 short demo snippets where the browser page lifetime
+is the intended cleanup boundary. Prefer narrow disable comments for those
+snippets rather than weakening the rule globally.
+
+## Further reading
+
+- [MDN: `MediaDevices.getUserMedia()`](https://developer.mozilla.org/docs/Web/API/MediaDevices/getUserMedia)
+- [MDN: `MediaDevices.getDisplayMedia()`](https://developer.mozilla.org/docs/Web/API/MediaDevices/getDisplayMedia)
+- [MDN: `MediaStreamTrack.stop()`](https://developer.mozilla.org/docs/Web/API/MediaStreamTrack/stop)

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

@@ -0,0 +1,114 @@
+# no-floating-message-channels
+
+Require `MessageChannel` ports to be retained so they can be closed.
+
+> **Rule catalog ID:** R012
+
+## Targeted pattern scope
+
+This rule targets browser `MessageChannel` constructors:
+
+- `MessageChannel`
+- `window.MessageChannel`
+- `self.MessageChannel`
+- `globalThis.MessageChannel`
+
+The rule reports channel instances that are immediately discarded or whose
+`port1`/`port2` properties are accessed directly from the temporary channel
+object. Keeping only one inline port loses the peer port and makes full
+teardown ambiguous.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone channel construction such as `new MessageChannel();`
+- voided channel construction such as `void new MessageChannel();`
+- immediate port sends such as `new MessageChannel().port1.postMessage(message);`
+- retaining a single inline port such as `const port = new MessageChannel().port1;`
+
+It intentionally does not require same-function `close()` calls. Ownership can
+be transferred to a component instance, channel manager, returned value, or both
+destructured `MessagePort` handles.
+
+## Why this rule exists
+
+`MessageChannel` creates two linked `MessagePort` handles. `MessagePort.close()`
+disconnects a port so it is no longer active. If the channel object is discarded
+or only one port is retained from an inline expression, code cannot reliably
+close both sides of the channel during cleanup.
+
+## Incorrect
+
+```ts
+new MessageChannel();
+```
+
+```ts
+void new MessageChannel();
+```
+
+```ts
+new MessageChannel().port1.postMessage(message);
+```
+
+```ts
+const port = new MessageChannel().port2;
+```
+
+## Correct
+
+```ts
+const channel = new MessageChannel();
+
+channel.port1.addEventListener("message", onMessage);
+channel.port1.close();
+channel.port2.close();
+```
+
+```ts
+const { port1, port2 } = new MessageChannel();
+
+port1.postMessage(message);
+port1.close();
+port2.close();
+```
+
+```ts
+return new MessageChannel();
+```
+
+```ts
+registerChannel(new MessageChannel());
+```
+
+## Behavior and migration notes
+
+Store either the `MessageChannel` object or both `MessagePort` handles in the
+owner that will close them. For UI code, that owner is usually a component,
+worker bridge, route lifecycle, or application-level channel manager.
+
+This rule does not autofix. Introducing a variable without selecting the owner
+and teardown point would hide the lifecycle problem instead of solving it.
+
+## 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 runtime-lifetime
+message ports 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: `MessageChannel`](https://developer.mozilla.org/docs/Web/API/MessageChannel)
+- [MDN: `MessagePort`](https://developer.mozilla.org/docs/Web/API/MessagePort)
+- [MDN: `MessagePort.close()`](https://developer.mozilla.org/docs/Web/API/MessagePort/close)

package/docs/rules/no-floating-network-connections.md

@@ -0,0 +1,116 @@
+# no-floating-network-connections
+
+Require browser network connection handles to be retained so they can be
+closed.
+
+> **Rule catalog ID:** R009
+
+## Targeted pattern scope
+
+This rule targets browser connection constructors with explicit `.close()`
+lifecycle APIs:
+
+- `WebSocket`
+- `EventSource`
+- `window.WebSocket`, `self.WebSocket`, and `globalThis.WebSocket`
+- `window.EventSource`, `self.EventSource`, and `globalThis.EventSource`
+
+The rule reports connection instances that are immediately discarded or chained
+directly into a method call other than `.close()`. In both cases there is no
+remaining connection handle available for teardown.
+
+## What this rule reports
+
+The rule reports:
+
+- standalone connection construction such as `new WebSocket(url);`
+- voided connection construction such as `void new EventSource(url);`
+- immediate send or listener chains such as `new WebSocket(url).send(message);`
+- immediate `EventSource` listener registration on a discarded instance
+
+It intentionally does not require same-function `close()` calls. Ownership can
+be transferred to a component instance, connection manager, returned value, or
+longer-lived runtime owner.
+
+## Why this rule exists
+
+`WebSocket` and `EventSource` create long-lived network connections. If the
+handle is not retained, code cannot reliably call `.close()`, remove listeners,
+or coordinate reconnect and shutdown behavior. Discarding the handle makes the
+connection lifecycle implicit and usually leaks work until the page or runtime
+exits.
+
+## Incorrect
+
+```ts
+new WebSocket("wss://example.com/socket");
+```
+
+```ts
+void new EventSource("/events");
+```
+
+```ts
+new WebSocket(url).send("hello");
+```
+
+```ts
+new EventSource("/events").addEventListener("message", onMessage);
+```
+
+## Correct
+
+```ts
+const socket = new WebSocket("wss://example.com/socket");
+
+socket.addEventListener("message", onMessage);
+socket.close();
+```
+
+```ts
+const source = new EventSource("/events");
+
+source.addEventListener("message", onMessage);
+source.close();
+```
+
+```ts
+return new WebSocket(url);
+```
+
+```ts
+registerConnection(new EventSource(url));
+```
+
+## Behavior and migration notes
+
+Store the connection handle in the owner that will close it. For UI code, that
+is usually the component or route lifecycle. For shared libraries, returning
+the connection or passing it to a connection manager makes the ownership
+contract explicit.
+
+This rule does not autofix. Introducing a variable without a matching close
+path would hide the lifecycle problem instead of solving it.
+
+## 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
+connections and does not need explicit teardown. Prefer a narrow disable
+comment with a reason when a connection is meant to live for the whole runtime.
+
+## Further reading
+
+- [MDN: `WebSocket`](https://developer.mozilla.org/docs/Web/API/WebSocket)
+- [MDN: `WebSocket.close()`](https://developer.mozilla.org/docs/Web/API/WebSocket/close)
+- [MDN: `EventSource`](https://developer.mozilla.org/docs/Web/API/EventSource)
+- [MDN: `EventSource.close()`](https://developer.mozilla.org/docs/Web/API/EventSource/close)