eslint-plugin-kerfjs 0.10.0 → 0.11.1

package/README.md

@@ -58,11 +58,13 @@ 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` |
 
-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. `ai-assistant-configs` doesn't map to a Hard Rule — it checks that the bundled kerf-app Claude Code skill / Cursor rules drop-ins are installed and current in projects that use those tools. See [`docs/12-ai-assistant-configs.md`](../docs/12-ai-assistant-configs.md) on the main kerf repo for the design.
+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 (and not more)?
+## Why these four 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.
 

package/docs/rules/no-inline-jsx-event-handlers.md

@@ -14,16 +14,34 @@ Maps to **kerf Hard Rule 9** — kerf's JSX runtime renders to HTML strings, so
 
 ## ✅ Correct
 
+Preferred — use `attr()` so the attribute name lives in one typed constant and
+renames propagate to both JSX and `delegate()` automatically:
+
 ```tsx
-// In the template:
-<button data-action="save">Save</button>
-<input data-action="update" />
-<form data-action="submit">…</form>
+import { attr, delegate, type AttrSpec } from 'kerfjs';
+
+const ACTIONS = {
+  save:   attr('data-action', 'save'),
+  update: attr('data-action', 'update'),
+  submit: attr('data-action', 'submit'),
+} as const satisfies Record<string, AttrSpec<'data-action'>>;
+
+// In the template — spread .attrs (no hardcoded 'data-action' at each call site):
+<button {...ACTIONS.save.attrs}>Save</button>
+<input {...ACTIONS.update.attrs} />
+<form {...ACTIONS.submit.attrs}>…</form>
+
+// Once, at module init — use .selector:
+delegate(rootEl, 'click',  ACTIONS.save.selector,   save);
+delegate(rootEl, 'input',  ACTIONS.update.selector,  update);
+delegate(rootEl, 'submit', ACTIONS.submit.selector,  submit);
+```
 
-// Once, at module init:
+String literals still work for ad-hoc fixed selectors:
+
+```tsx
+<button data-action="save">Save</button>
 delegate(rootEl, 'click', '[data-action="save"]', save);
-delegate(rootEl, 'input', '[data-action="update"]', update);
-delegate(rootEl, 'submit', '[data-action="submit"]', submit);
 ```
 
 ## Why this rule is AST-only

package/docs/rules/no-raw-with-dynamic-arg.md

@@ -0,0 +1,41 @@
+# `kerfjs/no-raw-with-dynamic-arg`
+
+Warn when `raw()` is called with a dynamic argument (any expression that is not a static string literal or an expression-free template literal).
+
+`raw(html)` bypasses kerf's HTML escaping and marks a string as trusted for direct DOM injection. Passing dynamic or user-controlled content is an XSS vulnerability. This rule forces an explicit `// eslint-disable-next-line` acknowledgment at every dynamic injection point, creating a searchable audit trail.
+
+**Severity in `kerfjs.configs.recommended`: `warn`** (not `error`) because sanitized pipelines like `raw(DOMPurify.sanitize(marked(input)))` look dynamic to an AST rule but are legitimate. The warn prompts review; `eslint-disable` makes the intent explicit.
+
+## ❌ Incorrect
+
+```ts
+raw(userInput)                     // variable reference
+raw(fetchedHtml())                 // function call
+raw(`<b>${title}</b>`)             // template literal with expressions
+raw(isAdmin ? adminHtml : guestHtml)  // conditional expression
+```
+
+## ✅ Correct
+
+```ts
+raw('<p>Static markup</p>')        // string literal — no warning
+raw(`<p>Static template</p>`)      // expression-free template literal — no warning
+
+// Dynamic but audited — suppress with eslint-disable
+// eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg
+raw(DOMPurify.sanitize(marked(userMarkdown)))
+```
+
+## Why `warn` and not `error`
+
+Sanitization pipelines (`DOMPurify`, `sanitize-html`, server-rendered trusted content) are legitimate uses of `raw()` with a dynamic argument. An `error` severity would block every such callsite. `warn` surfaces the pattern for review; the `eslint-disable` suppression becomes the permanent audit marker.
+
+## What this rule catches
+
+- Bare `raw(expr)` calls
+- Member-expression calls `kerf.raw(expr)` and `kerfjs.raw(expr)`
+
+## What this rule does NOT catch
+
+- `raw()` calls where the binding was renamed via a local alias (`const inject = raw; inject(expr)`)
+- The correctness of any sanitizer passed to `raw()` — that remains the caller's responsibility

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

@@ -1,16 +1,20 @@
 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: {},
@@ -19,11 +23,18 @@ const plugin = {
 // Most rules ship as `error` in recommended (AST-shaped antipatterns are
 // bugs). `ai-assistant-configs` is `warn` — it's a project-hygiene nudge,
 // not a code defect, and a missing skill file shouldn't fail CI.
+// `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/no-raw-with-dynamic-arg.js

@@ -0,0 +1,64 @@
+/**
+ * Flags calls to `raw(expr)` where `expr` is not a static string literal or a
+ * template literal with no dynamic expressions. `raw()` bypasses kerf's
+ * HTML auto-escaping — passing a dynamic value (user input, API response, any
+ * expression the user can influence) is the canonical XSS vector.
+ *
+ * Safe:  raw("<strong>static</strong>")
+ * Safe:  raw(`<em>static template</em>`)          (no ${} expressions)
+ * Error: raw(someVariable)
+ * Error: raw(fetchedHtml)
+ * Error: raw(`<b>${userContent}</b>`)              (template has expressions)
+ * Error: raw(marked(markdown))                     (unsanitized pipeline)
+ *
+ * When the input IS user-controlled, the canonical fix is to sanitize first:
+ *   raw(DOMPurify.sanitize(marked(userMarkdown)))
+ *
+ * To let the linter know the call is intentionally safe (e.g., a
+ * fully-sanitized pipeline), add an eslint-disable-next-line comment.
+ */
+
+const meta = {
+  type: 'problem',
+  docs: {
+    description:
+      "Disallow `raw()` with dynamic arguments; `raw()` bypasses HTML escaping and passing dynamic values is an XSS vector.",
+    url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/no-raw-with-dynamic-arg.md',
+  },
+  schema: [],
+  messages: {
+    dynamic:
+      "`raw()` bypasses HTML auto-escaping. Passing a dynamic value is an XSS risk unless the input has been sanitized. Sanitize first (`DOMPurify.sanitize(...)`) then pass to `raw()`, or add `// eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg` to mark a call as intentionally safe.",
+  },
+};
+
+function isStaticArg(node) {
+  if (!node) return false;
+  // String or numeric literal: raw("html")
+  if (node.type === 'Literal') return typeof node.value === 'string';
+  // Template literal with no expressions: raw(`static`)
+  if (node.type === 'TemplateLiteral') return node.expressions.length === 0;
+  return false;
+}
+
+function create(context) {
+  return {
+    CallExpression(node) {
+      const callee = node.callee;
+      if (!callee) return;
+      // Match bare `raw(...)` and `kerfjs.raw(...)` / `kerf.raw(...)` shapes.
+      const isRaw = (callee.type === 'Identifier' && callee.name === 'raw')
+        || (callee.type === 'MemberExpression'
+            && callee.property.type === 'Identifier'
+            && callee.property.name === 'raw');
+      if (!isRaw) return;
+      if (node.arguments.length === 0) return;
+      const arg = node.arguments[0];
+      if (!isStaticArg(arg)) {
+        context.report({ node, messageId: 'dynamic' });
+      }
+    },
+  };
+}
+
+export default { meta, create };

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.10.0",
+  "version": "0.11.1",
   "description": "ESLint rules that enforce kerf's hard rules — catches AI-shaped bugs at edit time.",
   "type": "module",
   "license": "MIT",