eslint-plugin-kerfjs 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# eslint-plugin-kerfjs
+
+ESLint rules that enforce kerf's hard rules. Catches AI-shaped bugs at edit time, before they reach `tsc` or the runtime dev-warns.
+
+This plugin sits alongside two other defense layers shipped by [`kerfjs`](https://github.com/brianwestphal/kerf):
+
+| Layer | Catches | When |
+|---|---|---|
+| `tsc --noEmit` with strict typings | Hard Rules 8 (partial-set), most type errors | Build time |
+| Opt-in dev-warns (`KERF_DEV_WARN_*`) | Hard Rules 4 (rebuilt listeners), 7 (untracked signals), 8 (narrow set) | Runtime |
+| **This plugin** | Hard Rules 2, 5, 9, 11 — AST-shaped antipatterns | **Edit time** |
+
+The rules are AST-only — no `@typescript-eslint/parser` *service* dependency is required by the plugin (consumers configure their own parser).
+
+## Install
+
+```bash
+npm install --save-dev eslint-plugin-kerfjs
+```
+
+## Configure (flat config, ESLint v9+)
+
+```js
+// eslint.config.js
+import kerfjs from 'eslint-plugin-kerfjs';
+import tsParser from '@typescript-eslint/parser';
+
+export default [
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+  },
+  kerfjs.configs.recommended,
+];
+```
+
+## Configure (legacy `.eslintrc`)
+
+```json
+{
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": { "ecmaFeatures": { "jsx": true } },
+  "extends": ["plugin:kerfjs/legacy-recommended"]
+}
+```
+
+## Rules
+
+| Rule | Hard Rule | Severity (recommended) |
+|---|---|---|
+| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md) | 9 — 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` |
+
+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.
+
+## Why these four (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.
+
+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.
+
+## Develop / test
+
+```bash
+npm install
+npm test
+```
+
+The test suite uses ESLint's `RuleTester` with `@typescript-eslint/parser`.
+
+## License
+
+MIT

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

@@ -0,0 +1,36 @@
+# `kerfjs/no-inline-jsx-event-handlers`
+
+Disallow inline `onClick`-style JSX event handler attributes on intrinsic (lowercase-tag) elements.
+
+Maps to **kerf Hard Rule 9** — kerf's JSX runtime renders to HTML strings, so an inline `onClick={fn}` has no way to attach the handler to the resulting node. Use a `data-action` attribute and `delegate()` from the mount root instead.
+
+## ❌ Incorrect
+
+```tsx
+<button onClick={save}>Save</button>
+<input onChange={update} />
+<form onSubmit={submit}>…</form>
+```
+
+## ✅ Correct
+
+```tsx
+// In the template:
+<button data-action="save">Save</button>
+<input data-action="update" />
+<form data-action="submit">…</form>
+
+// Once, at module init:
+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
+
+The check is a pure syntactic scan: attribute name starts with `on` followed by an uppercase letter, on a JSX element whose tag begins with a lowercase letter. No type information needed.
+
+## What this rule does NOT catch
+
+- Handler-shaped props on custom components (`<MyButton onClick={fn} />`) — these are valid JSX prop names; kerf's runtime calls `MyButton({ onClick })`. Whether the component does the right thing with it is its own responsibility.
+- Lowercase HTML attributes that begin with `on` (e.g. `onload` as a literal string attribute on `<body onload="…">`) — these are HTML-string attributes, not handlers, and kerf passes them through verbatim.

package/docs/rules/no-nested-mount.md

@@ -0,0 +1,34 @@
+# `kerfjs/no-nested-mount`
+
+Disallow `mount()` calls nested inside another `mount()`'s render callback.
+
+Maps to **kerf Hard Rule 5** — there is one `mount()` per render root. Composition is via plain functions that return JSX, not via nesting another mount tree inside an outer one.
+
+## ❌ Incorrect
+
+```tsx
+mount(root, () => {
+  mount(otherRoot, () => <div>nested</div>); // ← reported
+  return <div>outer</div>;
+});
+
+mount(root, () => mount(otherRoot, () => <div />)); // ← reported
+```
+
+## ✅ Correct
+
+```tsx
+// Two sibling roots, mounted at module init:
+mount(headerRoot, () => <Header />);
+mount(bodyRoot, () => <Body />);
+
+// Composition via plain functions:
+const Header = () => <h1>{title.value}</h1>;
+const Body = () => <main><Header /><div>{count.value}</div></main>;
+mount(root, () => <Body />);
+```
+
+## What this rule does NOT catch
+
+- `mount()` called from a helper invoked from within a render: the rule only walks lexical ancestors, so `mount(root, () => { helperThatCallsMount(); })` is not flagged.
+- `mount()` qualified by a namespace (`MyLib.mount(…)`) — only the bare `mount` identifier is checked.

package/docs/rules/prefer-module-jsx-augmentation.md

@@ -0,0 +1,40 @@
+# `kerfjs/prefer-module-jsx-augmentation`
+
+Disallow declaration-merging `JSX.IntrinsicElements` into the global namespace; use the `kerfjs/jsx-runtime` module instead.
+
+Maps to **kerf Hard Rule 11** — kerf's JSX runtime looks up custom-element typings on its own module's `JSX` namespace. A global augmentation does not flow through to kerf's intrinsic-element table.
+
+## ❌ Incorrect
+
+```ts
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'my-tag': { foo?: string };
+    }
+  }
+}
+```
+
+## ✅ Correct
+
+```ts
+declare module 'kerfjs/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'my-tag': KerfCustomElement & { foo?: string };
+    }
+  }
+}
+```
+
+Import the building-block types from `kerfjs/jsx-runtime`:
+
+```ts
+import type { KerfCustomElement, KerfBaseAttrs, AttrLike } from 'kerfjs/jsx-runtime';
+```
+
+## What this rule does NOT catch
+
+- Other `declare global { … }` blocks that augment things outside `JSX.IntrinsicElements` (e.g. `interface Window { … }`).
+- Augmentations of `JSX.Element` or `JSX.ElementClass` inside `declare global` — only `IntrinsicElements` is reported, since that is what kerf's typed-tag-table consumes.

package/docs/rules/require-data-key-in-each.md

@@ -0,0 +1,34 @@
+# `kerfjs/require-data-key-in-each`
+
+Require `data-key` (or `id`) on the root element returned by an `each()` row render.
+
+Maps to **kerf Hard Rule 2** — the keyed reconciler matches items by `id` first, then `data-key`. Without a key, the diff matches by position, which loses identity, focus, and cursor position on insert/delete/move.
+
+## ❌ Incorrect
+
+```tsx
+each(items, (item) => <li>{item.name}</li>)
+
+each(items, (item) => {
+  return <li class="row">{item.name}</li>;
+})
+
+each(items, (item) => <>{item.name}</>)
+```
+
+## ✅ Correct
+
+```tsx
+each(items, (item) => <li data-key={item.id}>{item.name}</li>)
+
+each(items, (item) => <li id={item.id}>{item.name}</li>)
+
+// Spread attributes are conservatively allowed — they may include the key.
+each(items, (item) => <li {...item.attrs}>{item.name}</li>)
+```
+
+## What this rule does NOT catch
+
+- Non-inline callbacks: `each(items, renderRow)` — the rule only inspects arrow / function-expression callbacks passed directly to `each()`.
+- `each` calls qualified by a namespace: `MyLib.each(items, …)` — the rule only fires on a bare `each` identifier.
+- Computed key keys behind a runtime branch: if the JSX root only sometimes carries a `data-key`, the rule reports the missing static attribute. Fix by always setting it.

package/index.js

@@ -0,0 +1,37 @@
+import noInlineJsxEventHandlers from './lib/rules/no-inline-jsx-event-handlers.js';
+import noNestedMount from './lib/rules/no-nested-mount.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.1.0' },
+  rules: {
+    'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
+    'require-data-key-in-each': requireDataKeyInEach,
+    'no-nested-mount': noNestedMount,
+    'prefer-module-jsx-augmentation': preferModuleJsxAugmentation,
+  },
+  configs: {},
+};
+
+const errorRules = {
+  'kerfjs/no-inline-jsx-event-handlers': 'error',
+  'kerfjs/require-data-key-in-each': 'error',
+  'kerfjs/no-nested-mount': 'error',
+  'kerfjs/prefer-module-jsx-augmentation': 'error',
+};
+
+// Flat config (ESLint v9+) — consumers add this object to their config array.
+plugin.configs.recommended = {
+  plugins: { kerfjs: plugin },
+  rules: errorRules,
+};
+plugin.configs.all = plugin.configs.recommended;
+
+// Legacy `.eslintrc` config — consumers extend `'plugin:kerfjs/legacy-recommended'`.
+plugin.configs['legacy-recommended'] = {
+  plugins: ['kerfjs'],
+  rules: errorRules,
+};
+
+export default plugin;

package/lib/rules/no-inline-jsx-event-handlers.js

@@ -0,0 +1,38 @@
+/**
+ * Hard Rule 9 — kerf's JSX-to-string runtime does not support inline `onClick`-style
+ * event handlers. Use a `data-action` attribute and `delegate()` from the mount root.
+ */
+
+const meta = {
+  type: 'problem',
+  docs: {
+    description:
+      "Disallow inline `onClick`-style JSX event handler attributes; use `data-action` + `delegate()` instead.",
+    url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/no-inline-jsx-event-handlers.md',
+  },
+  schema: [],
+  messages: {
+    inline:
+      "Inline JSX event handler `{{name}}` is not supported by kerf's JSX-to-string runtime. Use a `data-action` attribute + `delegate()` from the mount root instead. See Hard Rule 9.",
+  },
+};
+
+function create(context) {
+  return {
+    JSXAttribute(node) {
+      const attr = node.name;
+      if (!attr || attr.type !== 'JSXIdentifier') return;
+      const name = attr.name;
+      if (!/^on[A-Z]/.test(name)) return;
+      const opening = node.parent;
+      if (!opening || opening.type !== 'JSXOpeningElement') return;
+      const elName = opening.name;
+      if (!elName || elName.type !== 'JSXIdentifier') return;
+      const first = elName.name[0];
+      if (first !== first.toLowerCase()) return;
+      context.report({ node, messageId: 'inline', data: { name } });
+    },
+  };
+}
+
+export default { meta, create };

package/lib/rules/no-nested-mount.js

@@ -0,0 +1,50 @@
+/**
+ * Hard Rule 5 — one `mount()` per root. Composition is via plain functions that
+ * return JSX, not nested `mount()` calls.
+ */
+
+function isMountCall(node) {
+  return (
+    node &&
+    node.type === 'CallExpression' &&
+    node.callee &&
+    node.callee.type === 'Identifier' &&
+    node.callee.name === 'mount'
+  );
+}
+
+const meta = {
+  type: 'problem',
+  docs: {
+    description:
+      "Disallow `mount()` calls nested inside another `mount()`'s render callback.",
+    url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/no-nested-mount.md',
+  },
+  schema: [],
+  messages: {
+    nested:
+      'Nested `mount()` is not supported — one `mount()` per root. Compose with plain functions that return JSX. See Hard Rule 5.',
+  },
+};
+
+function create(context) {
+  return {
+    CallExpression(node) {
+      if (!isMountCall(node)) return;
+      let p = node.parent;
+      while (p) {
+        if (
+          (p.type === 'ArrowFunctionExpression' || p.type === 'FunctionExpression') &&
+          isMountCall(p.parent) &&
+          p.parent.arguments.includes(p)
+        ) {
+          context.report({ node, messageId: 'nested' });
+          return;
+        }
+        p = p.parent;
+      }
+    },
+  };
+}
+
+export default { meta, create };

package/lib/rules/prefer-module-jsx-augmentation.js

@@ -0,0 +1,56 @@
+/**
+ * Hard Rule 11 — declaration-merge `JSX.IntrinsicElements` into the
+ * `kerfjs/jsx-runtime` module, not the global namespace. Kerf's JSX runtime
+ * looks up custom-element typings on its own module's JSX namespace; a global
+ * augmentation does not flow through.
+ */
+
+function findGlobalJSXIntrinsics(moduleBlock) {
+  if (!moduleBlock || moduleBlock.type !== 'TSModuleBlock') return null;
+  for (const m of moduleBlock.body) {
+    if (m.type !== 'TSModuleDeclaration') continue;
+    const idNode = m.id;
+    if (!idNode || idNode.type !== 'Identifier' || idNode.name !== 'JSX') continue;
+    const inner = m.body;
+    if (!inner || inner.type !== 'TSModuleBlock') continue;
+    for (const member of inner.body) {
+      if (
+        member.type === 'TSInterfaceDeclaration' &&
+        member.id &&
+        member.id.type === 'Identifier' &&
+        member.id.name === 'IntrinsicElements'
+      ) {
+        return member;
+      }
+    }
+  }
+  return null;
+}
+
+const meta = {
+  type: 'problem',
+  docs: {
+    description:
+      "Declaration-merge `JSX.IntrinsicElements` into `kerfjs/jsx-runtime`, not the global namespace.",
+    url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/prefer-module-jsx-augmentation.md',
+  },
+  schema: [],
+  messages: {
+    preferModule:
+      "Declaration-merge `JSX.IntrinsicElements` into the `kerfjs/jsx-runtime` module, not `declare global`. Use `declare module 'kerfjs/jsx-runtime' { namespace JSX { interface IntrinsicElements { ... } } }`. See Hard Rule 11.",
+  },
+};
+
+function create(context) {
+  return {
+    TSModuleDeclaration(node) {
+      if (!node.global) return;
+      const target = findGlobalJSXIntrinsics(node.body);
+      if (target) {
+        context.report({ node: target, messageId: 'preferModule' });
+      }
+    },
+  };
+}
+
+export default { meta, create };

package/lib/rules/require-data-key-in-each.js

@@ -0,0 +1,65 @@
+/**
+ * Hard Rule 2 — `each()` rows must carry a per-item key (`data-key` or `id`).
+ * Without a key, the keyed reconciler matches by position and loses identity,
+ * focus, and cursor position on insert/delete.
+ */
+
+function findRootJSXFromBody(body) {
+  if (!body) return null;
+  if (body.type === 'JSXElement' || body.type === 'JSXFragment') return body;
+  if (body.type === 'BlockStatement') {
+    for (const stmt of body.body) {
+      if (stmt.type === 'ReturnStatement' && stmt.argument) {
+        const a = stmt.argument;
+        if (a.type === 'JSXElement' || a.type === 'JSXFragment') return a;
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+const meta = {
+  type: 'problem',
+  docs: {
+    description:
+      'Require `data-key` (or `id`) on the root element returned from `each()` row renders.',
+    url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/require-data-key-in-each.md',
+  },
+  schema: [],
+  messages: {
+    missingKey:
+      '`each()` row root must set `data-key={...}` (or `id={...}`) per item. Without a key, the diff matches by position and loses identity, focus, and cursor position on insert/delete. See Hard Rule 2.',
+    fragmentRoot:
+      '`each()` row must produce exactly one top-level element with a `data-key`. Fragment root is not allowed (see Hard Rule 12).',
+  },
+};
+
+function create(context) {
+  return {
+    CallExpression(node) {
+      if (node.callee.type !== 'Identifier' || node.callee.name !== 'each') return;
+      const cb = node.arguments[1];
+      if (!cb) return;
+      if (cb.type !== 'ArrowFunctionExpression' && cb.type !== 'FunctionExpression') return;
+      const root = findRootJSXFromBody(cb.body);
+      if (!root) return;
+      if (root.type === 'JSXFragment') {
+        context.report({ node: root, messageId: 'fragmentRoot' });
+        return;
+      }
+      const attrs = root.openingElement.attributes;
+      const hasKey = attrs.some((a) => {
+        if (a.type === 'JSXSpreadAttribute') return true;
+        if (a.type !== 'JSXAttribute') return false;
+        const n = a.name && a.name.name;
+        return n === 'data-key' || n === 'id';
+      });
+      if (!hasKey) {
+        context.report({ node: root.openingElement, messageId: 'missingKey' });
+      }
+    },
+  };
+}
+
+export default { meta, create };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "eslint-plugin-kerfjs",
+  "version": "0.1.0",
+  "description": "ESLint rules that enforce kerf's hard rules — catches AI-shaped bugs at edit time.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Brian Westphal <brian.westphal@bleugris.com>",
+  "homepage": "https://github.com/brianwestphal/kerf/tree/main/eslint-plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brianwestphal/kerf",
+    "directory": "eslint-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/brianwestphal/kerf/issues"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "kerf",
+    "kerfjs"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/rules/*.test.js"
+  },
+  "peerDependencies": {
+    "eslint": ">=8"
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0"
+  }
+}