eslint-plugin-kerfjs 0.11.0 → 0.12.0

package/README.md

@@ -58,6 +58,7 @@ export default [
 | [`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` |
+| [`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` |
 

package/docs/rules/prefer-attr-selector.md

@@ -0,0 +1,47 @@
+# `kerfjs/prefer-attr-selector`
+
+Prefer `attr('name', 'value').selector` over a literal `[name="value"]` selector when calling `delegate()` or `delegateCapture()`.
+
+`attr()` (added in kerf 0.11) defines an action key once and exposes both `.attrs` (spread into JSX) and `.selector` (passed to `delegate()`). Routing JSX and the delegate target through one typed constant means renames stay in sync — change the value in one place and both the JSX attribute and the selector update together.
+
+## ❌ Discouraged
+
+```tsx
+<button data-action="toggle">Toggle</button>
+delegate(root, 'click', '[data-action="toggle"]', handler);
+```
+
+The JSX attribute and the selector string are two independent literals; renaming the action key in JSX leaves the delegate selector unchanged, and the handler silently stops firing.
+
+## ✅ Recommended
+
+```tsx
+import { attr, delegate, type AttrSpec } from 'kerfjs';
+
+const ACTIONS = {
+  toggle: attr('data-action', 'toggle'),
+} as const satisfies Record<string, AttrSpec<'data-action'>>;
+
+<button {...ACTIONS.toggle.attrs}>Toggle</button>
+delegate(root, 'click', ACTIONS.toggle.selector, handler);
+```
+
+Rename `'toggle'` to `'on'` in the `ACTIONS` map and both the rendered attribute and the delegate selector update — no string-grep migration required.
+
+## What this rule flags
+
+A `CallExpression` whose callee is `delegate` or `delegateCapture` (by name) and whose 3rd argument is a **simple** attribute-equals string literal: `[name="value"]` or `[name='value']`, with no compound selectors, tag prefixes, or pseudo-classes.
+
+## What this rule does NOT flag
+
+These are intentionally left alone because `attr()` isn't a 1:1 swap for them:
+
+- Class / id selectors: `'.toggle'`, `'#submit'`.
+- Bare presence selectors: `'[data-new]'`, `'[data-edit]'` (no value to bind).
+- Tag-qualified attribute selectors: `'button[data-action="x"]'`.
+- Compound attribute selectors: `'[data-action="x"][data-id="y"]'` — for these, concatenate two `.selector` strings (`A.selector + B.selector`) or use `attr()` only for one of the legs.
+- Selectors held in variables (not string literals) — already abstracted.
+
+## Severity
+
+Reported as `warn` in the recommended config. The literal-selector form still works at runtime, and a one-off selector that's never shared with JSX is a legitimate use case — this rule is a nudge toward the rename-safe pattern, not a correctness bug.

package/index.js

@@ -2,17 +2,19 @@ import aiAssistantConfigs from './lib/rules/ai-assistant-configs.js';
 import noInlineJsxEventHandlers from './lib/rules/no-inline-jsx-event-handlers.js';
 import noNestedMount from './lib/rules/no-nested-mount.js';
 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';
 
 const plugin = {
-  meta: { name: 'eslint-plugin-kerfjs', version: '0.9.0' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '0.11.0' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,
     'require-data-key-in-each': requireDataKeyInEach,
     'no-nested-mount': noNestedMount,
     'prefer-module-jsx-augmentation': preferModuleJsxAugmentation,
+    'prefer-attr-selector': preferAttrSelector,
     'ai-assistant-configs': aiAssistantConfigs,
   },
   configs: {},
@@ -24,12 +26,15 @@ const plugin = {
 // `no-raw-with-dynamic-arg` is `warn` in recommended — false-positive rate is
 // non-trivial (sanitized pipelines look dynamic to an AST rule), so `error`
 // 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.
 const recommendedRules = {
   'kerfjs/no-inline-jsx-event-handlers': 'error',
   'kerfjs/no-raw-with-dynamic-arg': 'warn',
   'kerfjs/require-data-key-in-each': 'error',
   'kerfjs/no-nested-mount': 'error',
   'kerfjs/prefer-module-jsx-augmentation': 'error',
+  'kerfjs/prefer-attr-selector': 'warn',
   'kerfjs/ai-assistant-configs': 'warn',
 };
 

package/lib/rules/prefer-attr-selector.js

@@ -0,0 +1,60 @@
+/**
+ * When you call `delegate()` or `delegateCapture()` with a string-literal
+ * selector that matches an `[name="value"]` shape, recommend `attr()`'s
+ * `.selector`. Pairs JSX (`{...ACTIONS.x.attrs}`) and the delegate target
+ * (`ACTIONS.x.selector`) under one typed source of truth so a rename of the
+ * action key can't desync the two.
+ *
+ * Conservative on purpose: only flags the *exact* attribute-equals shape
+ * (`[data-action="save"]`, `[role="dialog"]`). Compound selectors,
+ * tag-qualified selectors, and class/id selectors are left alone — those
+ * are the cases `attr()` doesn't directly replace.
+ */
+
+const meta = {
+  type: 'suggestion',
+  docs: {
+    description:
+      "Prefer `attr('name', 'value').selector` over a literal `[name=\"value\"]` selector when calling `delegate()` / `delegateCapture()`.",
+    url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/prefer-attr-selector.md',
+  },
+  schema: [],
+  messages: {
+    preferAttr:
+      "Selector `[{{name}}=\"{{value}}\"]` is a literal string. Define `attr('{{name}}', '{{value}}')` once and pass its `.selector` here — JSX can then spread `.attrs` to stay in sync on rename. See kerf docs §5.4 (attr() helper).",
+  },
+};
+
+const DELEGATE_FNS = new Set(['delegate', 'delegateCapture']);
+
+// Matches a simple attribute-equals selector: leading `[`, name, `=`, quoted
+// value, trailing `]`. Anchored to the full string so compound selectors
+// (`[data-action="x"][data-id="y"]`) and qualified selectors
+// (`button[data-action="x"]`) do NOT match — those aren't a 1:1 attr() swap.
+const ATTR_EQUALS_RE = /^\[([a-zA-Z][\w-]*)=(['"])([^'"]*)\2\]$/;
+
+function create(context) {
+  return {
+    CallExpression(node) {
+      const callee = node.callee;
+      if (!callee || callee.type !== 'Identifier') return;
+      if (!DELEGATE_FNS.has(callee.name)) return;
+
+      // `delegate(root, type, selector, fn)` — selector is the 3rd arg.
+      const selectorArg = node.arguments[2];
+      if (!selectorArg || selectorArg.type !== 'Literal') return;
+      if (typeof selectorArg.value !== 'string') return;
+
+      const m = ATTR_EQUALS_RE.exec(selectorArg.value);
+      if (!m) return;
+
+      context.report({
+        node: selectorArg,
+        messageId: 'preferAttr',
+        data: { name: m[1], value: m[3] },
+      });
+    },
+  };
+}
+
+export default { meta, create };

package/package.json

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