eslint-plugin-kerfjs 0.12.0 → 0.13.0

package/README.md

@@ -54,19 +54,20 @@ export default [
 
 | Rule | Hard Rule | Severity (recommended) |
 |---|---|---|
-| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md) | 9 — use `data-action` + `delegate()` | `error` |
+| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md) | 10 — use `data-action` + `delegate()` | `error` |
 | [`require-data-key-in-each`](docs/rules/require-data-key-in-each.md) | 2 — `data-key` per item | `error` |
-| [`no-nested-mount`](docs/rules/no-nested-mount.md) | 5 — one `mount()` per root | `error` |
-| [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 11 — augment `kerfjs/jsx-runtime`, not global | `error` |
+| [`require-delegate-disposer`](docs/rules/require-delegate-disposer.md) | 5 — capture `delegate()` disposers when scope < page | `warn` |
+| [`no-nested-mount`](docs/rules/no-nested-mount.md) | 6 — one `mount()` per root | `error` |
+| [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 12 — augment `kerfjs/jsx-runtime`, not global | `error` |
 | [`prefer-attr-selector`](docs/rules/prefer-attr-selector.md) | — (rename-safety nudge for `delegate()` selectors) | `warn` |
 | [`no-raw-with-dynamic-arg`](docs/rules/no-raw-with-dynamic-arg.md) | — (XSS audit trail) | `warn` |
 | [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md) | — (project hygiene) | `warn` |
 
 The "Hard Rule" column refers to the numbered rules in [`docs/ai/usage-guide.md`](../docs/ai/usage-guide.md) on the main kerf repo. `no-raw-with-dynamic-arg` and `ai-assistant-configs` don't map to numbered Hard Rules — the former creates an audit trail for every dynamic `raw()` call site (potential XSS); the latter checks that the bundled AI-assistant configs are installed and current. See [`docs/12-ai-assistant-configs.md`](../docs/12-ai-assistant-configs.md) on the main kerf repo for the AI-configs design.
 
-## Why these four Hard-Rule rules (and not more)?
+## Why these five Hard-Rule rules (and not more)?
 
-Rules that need flow analysis (signal reads outside render — Rule 7), call-graph analysis (`addEventListener` inside the mount tree — Rule 4), or type information (partial-set against multi-key state — Rule 8) are already covered by the opt-in dev-warns and strict TS. Duplicating them here would mean either high false-positive rates without type info, or a `parserServices` dependency that complicates consumer setup.
+Rules that need flow analysis (signal reads outside render — Rule 8), call-graph analysis (`addEventListener` inside the mount tree — Rule 4), or type information (partial-set against multi-key state — Rule 9) are already covered by the opt-in dev-warns and strict TS. Duplicating them here would mean either high false-positive rates without type info, or a `parserServices` dependency that complicates consumer setup.
 
 When a real bug ships that the existing defense stack misses AND a new lint rule would not false-positive on legitimate code, file an issue on the main kerf repo.
 

package/docs/rules/require-delegate-disposer.md

@@ -0,0 +1,93 @@
+# `kerfjs/require-delegate-disposer`
+
+Require capturing the disposer returned by `delegate()` and `delegateCapture()`.
+
+Both helpers install a single listener on the root element and return a `() => void` disposer — the *only* way to remove the listener once it's attached. Discarding the return value is safe in exactly one case: the registration is genuinely page-lifetime (root is `document.body` or another never-torn-down element, attached once at startup, never re-registered). In every other case the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state) — so an undisposed delegate on a transient root leaks both the listener and the app graph it references, and re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you.
+
+See [kerf docs §5.3 — Disposers](https://brianwestphal.github.io/kerf/docs/5-event-delegation/#53-disposers) for the full rationale.
+
+## ❌ Discouraged
+
+```ts
+// Transient root: the modal is mounted on open and torn down on close, but
+// the delegate listener (and its closure over stores) stays attached forever.
+function openModal(host: HTMLElement) {
+  mount(host, () => <ModalView />);
+  delegate(host, 'click', '[data-action]', handleAction);  // disposer discarded
+}
+```
+
+```ts
+// Re-mount cycle: every htmx swap re-attaches mount + delegate, but the
+// previous delegate's listener never gets removed. Listener count grows
+// linearly with swap count.
+function onSwap(initial: CartItem[]) {
+  mount(root, () => <Cart items={items} />);
+  delegate(root, 'click', '.remove', handleRemove);  // disposer discarded
+}
+```
+
+## ✅ Recommended
+
+Capture and call the disposer alongside the mount teardown:
+
+```ts
+function openModal(host: HTMLElement) {
+  const stopMount    = mount(host, () => <ModalView />);
+  const stopDelegate = delegate(host, 'click', '[data-action]', handleAction);
+
+  return function closeModal() {
+    stopMount();
+    stopDelegate();
+    host.remove();
+  };
+}
+```
+
+Or collect into a disposer array:
+
+```ts
+const disposers: Array<() => void> = [];
+disposers.push(mount(host, render));
+disposers.push(delegate(host, 'click', '[data-action]', onAction));
+disposers.push(delegate(host, 'keydown', '[data-edit]', onEdit));
+
+function teardown() {
+  for (const off of disposers) off();
+  disposers.length = 0;
+}
+```
+
+## When the registration really is page-lifetime
+
+If the registration is attached once at module load and the root never tears down (`document.body`, a never-removed app shell), discarding the disposer matches the intent. Two opt-outs:
+
+```ts
+// 1. The `void` operator as an explicit-discard sigil.
+void delegate(document.body, 'click', ACTIONS.inc.selector, () => count.value++);
+```
+
+```ts
+// 2. Standard eslint-disable for one-off cases.
+// eslint-disable-next-line kerfjs/require-delegate-disposer
+delegate(document.body, 'click', ACTIONS.inc.selector, () => count.value++);
+```
+
+`void` is the lower-friction option when the file has many page-lifetime registrations clustered together; eslint-disable carries the rule name with it, which makes it easier to grep for.
+
+## What the rule does and doesn't see
+
+The rule flags `delegate(...)` or `delegateCapture(...)` whose immediate parent is an `ExpressionStatement` — i.e. the call is the entire statement and nothing consumes its return value. Any non-statement parent is accepted: assignments (`const off = …`), returns (`return …`), array elements (`[…, delegate(…), …]`), object properties (`{ off: delegate(…) }`), call arguments (`onCleanup(delegate(…))`), the `void` operator, etc.
+
+What the rule does NOT do:
+
+- It does not verify that the captured disposer is actually called somewhere. `const off = delegate(...)` followed by never calling `off()` still passes the rule — that's cross-function flow analysis and out of scope.
+- It does not track imports. The rule matches by callee name (`delegate` / `delegateCapture`). A local function with the same name will trigger the rule; suppress with `eslint-disable` or rename the local.
+- It does not look at `mount()` disposers. `mount()` has the same lifecycle property but is out of scope for this rule.
+
+## When to suppress
+
+- **Genuinely page-lifetime registration** — use `void delegate(...)` or `// eslint-disable-next-line kerfjs/require-delegate-disposer`.
+- **A local `delegate()` function unrelated to kerf** — rename it or suppress per-file with a directive.
+
+Don't suppress because "it's only a small leak" or "we'll add disposal later." The cost of capturing the disposer is one variable assignment; the cost of a slow leak that compounds across user actions is much higher.

package/index.js

@@ -5,13 +5,15 @@ import noRawWithDynamicArg from './lib/rules/no-raw-with-dynamic-arg.js';
 import preferAttrSelector from './lib/rules/prefer-attr-selector.js';
 import preferModuleJsxAugmentation from './lib/rules/prefer-module-jsx-augmentation.js';
 import requireDataKeyInEach from './lib/rules/require-data-key-in-each.js';
+import requireDelegateDisposer from './lib/rules/require-delegate-disposer.js';
 
 const plugin = {
-  meta: { name: 'eslint-plugin-kerfjs', version: '0.11.0' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '0.13.0' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,
     'require-data-key-in-each': requireDataKeyInEach,
+    'require-delegate-disposer': requireDelegateDisposer,
     'no-nested-mount': noNestedMount,
     'prefer-module-jsx-augmentation': preferModuleJsxAugmentation,
     'prefer-attr-selector': preferAttrSelector,
@@ -28,10 +30,15 @@ const plugin = {
 // would block too many legitimate uses without eslint-disable comments.
 // `prefer-attr-selector` is `warn` — the literal-selector form is still
 // correct at runtime; this rule nudges toward the rename-safe pattern.
+// `require-delegate-disposer` is `warn` — the discarded-disposer form is
+// still correct at runtime for page-lifetime roots, and downstream code
+// that's been around since before the rule shipped needs a deprecation
+// window to audit. Promote to `error` after one or two releases.
 const recommendedRules = {
   'kerfjs/no-inline-jsx-event-handlers': 'error',
   'kerfjs/no-raw-with-dynamic-arg': 'warn',
   'kerfjs/require-data-key-in-each': 'error',
+  'kerfjs/require-delegate-disposer': 'warn',
   'kerfjs/no-nested-mount': 'error',
   'kerfjs/prefer-module-jsx-augmentation': 'error',
   'kerfjs/prefer-attr-selector': 'warn',

package/lib/rules/require-delegate-disposer.js

@@ -0,0 +1,67 @@
+/**
+ * `delegate()` and `delegateCapture()` return a `() => void` disposer that
+ * removes the underlying root listener. Discarding the return value is only
+ * safe when the registration is genuinely page-lifetime (root never torn down,
+ * handler closure references no reclaimable state). In every other case —
+ * modal mounts, route views, mount swaps, dynamic widgets — discarding the
+ * disposer leaks the listener AND every store / signal / app object the
+ * handler closes over, and re-mount cycles stack listeners linearly.
+ *
+ * This rule flags the bare-statement form (`delegate(...);`) where the
+ * disposer is silently discarded. Accept any non-statement parent: assignment,
+ * return, array push, argument to another call, member expression, etc. — all
+ * of those carry the disposer somewhere a future scope can call it.
+ *
+ * Explicit-discard escape hatch: `void delegate(...)`. That signals "I know
+ * this is page-lifetime and I'm intentionally not capturing." Standard
+ * `eslint-disable-next-line` works too.
+ *
+ * Matched by callee name (`delegate` / `delegateCapture`) — consistent with
+ * the other kerfjs rules. False positives on an unrelated local `delegate()`
+ * function exist in principle; suppress with the standard mechanism.
+ */
+
+const meta = {
+  type: 'problem',
+  docs: {
+    description:
+      'Require capturing the disposer returned by `delegate()` / `delegateCapture()`. Discarding the return value leaks the listener and everything the handler closes over.',
+    url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/require-delegate-disposer.md',
+  },
+  schema: [],
+  messages: {
+    requireDisposer:
+      "`{{fn}}()` returns a `() => void` disposer that must be captured and called when the delegate's scope ends. Discarding it leaks the listener (and every store/signal the handler closes over) and stacks listeners on re-mount. Assign it (`const off = {{fn}}(...)`), return it, or push it into a disposer array. If the registration is genuinely page-lifetime (root is `document.body` or equivalent, never torn down), opt out with `void {{fn}}(...)` or `eslint-disable-next-line kerfjs/require-delegate-disposer`. See kerf docs §5.3.",
+  },
+};
+
+const DELEGATE_FNS = new Set(['delegate', 'delegateCapture']);
+
+function create(context) {
+  return {
+    CallExpression(node) {
+      const callee = node.callee;
+      if (!callee || callee.type !== 'Identifier') return;
+      if (!DELEGATE_FNS.has(callee.name)) return;
+
+      // Walk up through any wrappers that don't actually consume the value.
+      // The only case we need to handle specially is `void delegate(...)` —
+      // an explicit discard sigil that opts out of the rule. Every other
+      // parent shape (VariableDeclarator, ReturnStatement, ArrayExpression,
+      // Property, CallExpression argument, MemberExpression, etc.) means
+      // the disposer is being routed somewhere reachable — accept.
+      const parent = node.parent;
+      if (!parent) return;
+      if (parent.type === 'UnaryExpression' && parent.operator === 'void') return;
+      if (parent.type !== 'ExpressionStatement') return;
+
+      context.report({
+        node,
+        messageId: 'requireDisposer',
+        data: { fn: callee.name },
+      });
+    },
+  };
+}
+
+export default { meta, create };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-kerfjs",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "ESLint rules that enforce kerf's hard rules — catches AI-shaped bugs at edit time.",
   "type": "module",
   "license": "MIT",