eslint-plugin-kerfjs 0.9.1 → 0.11.0

package/README.md

@@ -58,11 +58,12 @@ 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` |
+| [`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/index.js

@@ -1,6 +1,7 @@
 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 preferModuleJsxAugmentation from './lib/rules/prefer-module-jsx-augmentation.js';
 import requireDataKeyInEach from './lib/rules/require-data-key-in-each.js';
 
@@ -8,6 +9,7 @@ const plugin = {
   meta: { name: 'eslint-plugin-kerfjs', version: '0.9.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,
@@ -19,8 +21,12 @@ 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.
 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',

package/lib/rules/ai-assistant-configs.js

@@ -39,6 +39,13 @@ function resolveManifestPath(cwd) {
     const req = createRequire(join(cwd, 'noop.js'));
     return req.resolve('kerfjs/ai/manifest.json');
   } catch {
+    // Fallback: kerfjs versions before the `./ai/*` exports entry landed
+    // block subpath resolution under Node's strict `exports` rules
+    // (ERR_PACKAGE_PATH_NOT_EXPORTED). Look directly at the package on disk —
+    // good enough for the plain-npm layout, and the rule should fire for
+    // those installs too rather than silently no-op.
+    const direct = join(cwd, 'node_modules', 'kerfjs', 'ai', 'manifest.json');
+    if (existsSync(direct)) return direct;
     return null;
   }
 }

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/package.json

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