kensington-eslint-plugin 0.4.0 → 0.5.0

package/README.md

@@ -42,6 +42,24 @@ export default [
 ];
 ```
 
+The `strict` config opts in to maximum-safety reactive correctness. It extends `recommended`, promotes every reactive-correctness `warn` rule to `error`, and adds two extra rules:
+
+```js
+import kensington from 'kensington-eslint-plugin';
+
+export default [
+  kensington.configs.strict,
+  // ...your other configs
+];
+```
+
+What `strict` changes on top of `recommended`:
+
+- **Adds `require-reactive-key`** (error). Paranoid mode. Flags every unkeyed `signal()`/`computed()`/`.transform()` call site, period. Not in `recommended` at any level. Keys are no-ops at module scope and required inside reactive scopes, so passing one always is safer than auditing call-site reachability. Suppress per call site with `eslint-disable-next-line kensington/require-reactive-key` when a top-level signal is known never to move into a reactive scope.
+- **Promotes from `warn` to `error`**. `no-signal-async-write`, `no-ignored-effect-return`, `prefer-value-in-async`, `no-new-computed-in-computed`, `no-out-of-scope-reactive-reference`, `no-helper-function-trap`. All real reactive-correctness issues; strict mode chooses zero silent misses over tolerance of false positives.
+
+Use `strict` if you want CI to fail on any reactive-correctness issue, or if you're using an agent-driven workflow that benefits from harder enforcement. Use `recommended` for production codebases that prefer the warnings as guidance.
+
 The `style` config is opt-in and bundles the formatting rules at `warn` level:
 
 ```js
@@ -85,32 +103,34 @@ Because this is a standard ESLint plugin, it works anywhere ESLint runs with no
 
 ## Rules
 
-| Rule | Description | Recommended |
-|------|-------------|-------------|
-| [`no-set-in-derivation`](#no-set-in-derivation) | Disallow `.set()` inside a `computed()` body or `.transform()` callback | error |
-| [`no-self-read-write`](#no-self-read-write) | Disallow reading and writing the same signal in the same reactive run | error |
-| [`no-set-on-derived-signal`](#no-set-on-derived-signal) | Disallow `.set()` on a derived (computed or transform) signal | error |
-| [`no-new-signal-in-effect`](#no-new-signal-in-effect) | Disallow creating a new `signal()` inside an `effect()` body | error |
-| [`no-effect-in-computed`](#no-effect-in-computed) | Disallow calling `effect()` inside a `computed()` body | error |
-| [`no-signal-async-write`](#no-signal-async-write) | Disallow writing a signal in an async callback when it was read in the enclosing `effect()` | warn |
-| [`no-ignored-effect-return`](#no-ignored-effect-return) | Require capturing the return value of `effect()` inside a function | warn |
-| [`prefer-value-in-async`](#prefer-value-in-async) | Prefer `.value` over `.get()` inside async callbacks within an `effect()` | warn |
-| [`no-new-computed-in-effect`](#no-new-computed-in-effect) | Disallow creating a new `computed()` inside an `effect()` body | error |
-| [`no-new-signal-in-computed`](#no-new-signal-in-computed) | Require a stable key for `signal()` calls inside a `computed()` body | error |
-| [`no-unsafe-literal`](#no-unsafe-literal) | Disallow `.unsafeLiteral()` calls that bypass XSS protection | error |
-| [`no-new-computed-in-computed`](#no-new-computed-in-computed) | Require a stable key for `computed()` and `.transform()` calls inside a `computed()` body | warn |
-| [`no-out-of-scope-reactive-reference`](#no-out-of-scope-reactive-reference) | Disallow referencing a `signal()`, `computed()`, or `.transform()` from outside the computed scope where it was created | warn |
-| [`no-effect-in-effect`](#no-effect-in-effect) | Disallow creating a new `effect()` inside an `effect()` body | error |
-| [`no-async-effect`](#no-async-effect) | Disallow async callbacks passed to `effect()` | error |
-| [`no-async-computed`](#no-async-computed) | Disallow async callbacks passed to `computed()` | error |
-| [`prefer-boolean-attribute-true`](#prefer-boolean-attribute-true) | Prefer `true` over `''` for boolean HTML attributes | style |
-| [`prefer-camelcase-attrs`](#prefer-camelcase-attrs) | Prefer camelCase identifier keys over quoted kebab-case | style |
-| [`prefer-style-object`](#prefer-style-object) | Prefer a `style` object over a CSS string | style |
-| [`prefer-nested-attr-groups`](#prefer-nested-attr-groups) | Prefer nested form when attrs share a kebab prefix | style |
-| [`prefer-array-for-multiline-content`](#prefer-array-for-multiline-content) | Require array brackets around multi-line tag content | style |
-| [`attrs-on-call-line`](#attrs-on-call-line) | Attributes object must hug the tag call on both ends | style |
-| [`attrs-canonical-shape`](#attrs-canonical-shape) | Attributes object must be inline or canonically stacked | style |
-| [`consistent-content-layout`](#consistent-content-layout) | Tag content must hug the attrs `}` and the call's `)` | style |
+| Rule | Description | Recommended | Strict |
+|------|-------------|-------------|--------|
+| [`no-set-in-derivation`](#no-set-in-derivation) | Disallow `.set()` inside a `computed()` body or `.transform()` callback | error | error |
+| [`no-self-read-write`](#no-self-read-write) | Disallow reading and writing the same signal in the same reactive run | error | error |
+| [`no-set-on-derived-signal`](#no-set-on-derived-signal) | Disallow `.set()` on a derived (computed or transform) signal | error | error |
+| [`no-new-signal-in-effect`](#no-new-signal-in-effect) | Disallow creating a new `signal()` inside an `effect()` body | error | error |
+| [`no-effect-in-computed`](#no-effect-in-computed) | Disallow calling `effect()` inside a `computed()` body | error | error |
+| [`no-signal-async-write`](#no-signal-async-write) | Disallow writing a signal in an async callback when it was read in the enclosing `effect()` | warn | error |
+| [`no-ignored-effect-return`](#no-ignored-effect-return) | Require capturing the return value of `effect()` inside a function | warn | error |
+| [`prefer-value-in-async`](#prefer-value-in-async) | Prefer `.value` over `.get()` inside async callbacks within an `effect()` | warn | error |
+| [`no-new-computed-in-effect`](#no-new-computed-in-effect) | Disallow creating a new `computed()` inside an `effect()` body | error | error |
+| [`no-new-signal-in-computed`](#no-new-signal-in-computed) | Require a stable key for `signal()` calls inside a `computed()` body | error | error |
+| [`no-unsafe-literal`](#no-unsafe-literal) | Disallow `.unsafeLiteral()` calls that bypass XSS protection | error | error |
+| [`no-new-computed-in-computed`](#no-new-computed-in-computed) | Require a stable key for `computed()` and `.transform()` calls inside a `computed()` body | warn | error |
+| [`no-out-of-scope-reactive-reference`](#no-out-of-scope-reactive-reference) | Disallow referencing a `signal()`, `computed()`, or `.transform()` from outside the computed scope where it was created | warn | error |
+| [`no-effect-in-effect`](#no-effect-in-effect) | Disallow creating a new `effect()` inside an `effect()` body | error | error |
+| [`no-async-effect`](#no-async-effect) | Disallow async callbacks passed to `effect()` | error | error |
+| [`no-async-computed`](#no-async-computed) | Disallow async callbacks passed to `computed()` | error | error |
+| [`no-helper-function-trap`](#no-helper-function-trap) | Require a stable key for `signal()`/`computed()`/`.transform()` inside helpers reachable from a reactive callback in the same file | warn | error |
+| [`require-reactive-key`](#require-reactive-key) | Require a stable key on every `signal()`/`computed()`/`.transform()` call site, regardless of context | off | error |
+| [`prefer-boolean-attribute-true`](#prefer-boolean-attribute-true) | Prefer `true` over `''` for boolean HTML attributes | style | style |
+| [`prefer-camelcase-attrs`](#prefer-camelcase-attrs) | Prefer camelCase identifier keys over quoted kebab-case | style | style |
+| [`prefer-style-object`](#prefer-style-object) | Prefer a `style` object over a CSS string | style | style |
+| [`prefer-nested-attr-groups`](#prefer-nested-attr-groups) | Prefer nested form when attrs share a kebab prefix | style | style |
+| [`prefer-array-for-multiline-content`](#prefer-array-for-multiline-content) | Require array brackets around multi-line tag content | style | style |
+| [`attrs-on-call-line`](#attrs-on-call-line) | Attributes object must hug the tag call on both ends | style | style |
+| [`attrs-canonical-shape`](#attrs-canonical-shape) | Attributes object must be inline or canonically stacked | style | style |
+| [`consistent-content-layout`](#consistent-content-layout) | Tag content must hug the attrs `}` and the call's `)` | style | style |
 
 ---
 
@@ -468,6 +488,55 @@ effect(() => {
 
 ---
 
+### `no-helper-function-trap`
+
+Catches the call-stack version of the helper-function trap that the existing `no-new-signal-in-computed` and `no-new-computed-in-computed` rules miss. Those rules only flag lexical positions (the call is written directly inside a `computed(() => ...)` body in the source). This rule does single-file call-graph analysis. For every `signal()`/`computed()`/`.transform()` call without a key inside a named function, the rule checks whether that function is reachable (directly or transitively) from a reactive callback in the same file. Reactive callbacks recognized. function args to `computed(fn)`, `effect(fn)`, `signal.transform(fn)`, and `signal.mapWithKey(key, fn)`. Both inline arrow callbacks (`mapWithKey('id', x => row(x))`) and bare-identifier callbacks (`mapWithKey('id', row)`) are recognized.
+
+```js
+// Bad. row() is a plain helper, so signal() looks top-level in the source,
+// but row() is called from inside mapWithKey's mapFn. The signal runs in the
+// per-key computed at runtime.
+function row(item) {
+  const highlight = signal(false);
+  return t.li({ class: highlight }, item.name);
+}
+const list = items.mapWithKey('id', item => row(item));
+
+// Good. Key scopes the signal to the surrounding computed so the same
+// instance is reused across re-runs.
+function row(item) {
+  const highlight = signal(false, item.id);
+  return t.li({ class: highlight }, item.name);
+}
+const list = items.mapWithKey('id', item => row(item));
+```
+
+Single-file analysis only. A helper defined in `cell.ts` and called from a reactive callback in `grid.ts` is NOT flagged by this rule on `cell.ts` (the call site is invisible). For cross-file coverage use `require-reactive-key`, which flags every unkeyed call site regardless of context.
+
+False-positive surface. Helpers reachable from a reactive callback are flagged, even if they are ALSO called from non-reactive sites. The conservative choice is correct: if any call path enters a reactive scope, the key is needed.
+
+---
+
+### `require-reactive-key`
+
+Paranoid mode. Flags every unkeyed `signal()`/`computed()`/`.transform()` call site, full stop. Keys are no-ops at module scope (the key argument is ignored when not inside a reactive scope) and required inside reactive scopes, so passing one always is safer than auditing call-site reachability.
+
+```js
+// Flagged. Pass a key.
+const count = signal(0);
+const doubled = computed(() => count.get() * 2);
+const half = count.transform(v => v / 2);
+
+// Suppress per call site if the call is genuinely top-level and you do not
+// want the noise.
+// eslint-disable-next-line kensington/require-reactive-key
+const theme = signal('light');
+```
+
+Off in the recommended config (too noisy for production codebases that legitimately scatter top-level signals). On in the `strict` config. Intended for agent-driven workflows, refactor-prone codebases, and projects that want maximum safety against later lifting code into a reactive callback.
+
+---
+
 ### `prefer-boolean-attribute-true`
 
 The HTML spec lists ~30 boolean attributes (`disabled`, `checked`, `hidden`, `selected`, etc.). Kensington treats `true` as "present" and `false`/`null`/`undefined` as "absent". An empty string is a confusing way to spell the same thing.

package/bin/check-reactive.js

@@ -0,0 +1,611 @@
+#!/usr/bin/env node
+// kensington-check-reactive
+//
+// EXPERIMENTAL. NOT YET RELEASED.
+// This binary ships in the published package but is intentionally not
+// documented in README.md or CHANGELOG.md. The CLI flags, output format,
+// suppression-comment syntax, presence in the package, and even its name
+// may change or be removed in any future release without notice. Do not
+// build tooling on top of it yet. The first release that documents this
+// tool in README.md is the release that commits to its contract.
+//
+// Cross-file static analyzer for the kensington helper-function trap. Parses
+// every .ts/.tsx/.js/.jsx file under the given roots, builds a project-wide
+// call graph (across imports), and reports every unkeyed signal()/computed()/
+// .transform() call site inside a function reachable from a reactive callback
+// anywhere in the project.
+//
+// Complements the single-file ESLint rule (`no-helper-function-trap`). The
+// ESLint rule catches the case where the helper and the reactive callback live
+// in the same file. This script catches the case where they live in different
+// files connected by imports.
+//
+// Usage (subject to change):
+//   kensington-check-reactive [paths...]
+//   kensington-check-reactive [paths...] --json
+//   kensington-check-reactive [paths...] --quiet     # exit-code only, no output
+//   kensington-check-reactive --help
+//
+// Exits 0 on no findings, 1 on findings, 2 on script error.
+
+/* global process */
+import { readFileSync, statSync, readdirSync } from 'node:fs';
+import { resolve, dirname, join, extname, isAbsolute, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse } from '@typescript-eslint/typescript-estree';
+
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'cjs', '.next', '.wrangler', 'public', 'coverage']);
+
+// Module-level config flags. Set by main() before analysis runs.
+let flagJson = false;
+let flagQuiet = false;
+
+// === File discovery ========================================================
+
+function listSourceFiles(root) {
+  const out = [];
+  function walk(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (SKIP_DIRS.has(e.name)) {
+        continue;
+      }
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        walk(full);
+      } else if (e.isFile() && SOURCE_EXTS.has(extname(e.name))) {
+        out.push(full);
+      }
+    }
+  }
+  try {
+    const st = statSync(root);
+    if (st.isFile()) {
+      if (SOURCE_EXTS.has(extname(root))) {
+        out.push(resolve(root));
+      }
+    } else {
+      walk(resolve(root));
+    }
+  } catch {
+    // ignore missing roots
+  }
+  return out;
+}
+
+// === Import resolution =====================================================
+
+function resolveImportPath(fromFile, spec) {
+  // Only resolve relative imports. Bare specifiers (`kensington`, `react`) are
+  // out of scope.
+  if (!spec.startsWith('.') && !isAbsolute(spec)) {
+    return null;
+  }
+  const baseDir = isAbsolute(spec) ? '/' : dirname(fromFile);
+  const baseGuess = isAbsolute(spec) ? spec : join(baseDir, spec);
+  // Try exact match, then extensions, then /index.{ext}.
+  const candidates = [
+    baseGuess,
+    ...['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].map(ext => baseGuess + ext),
+    ...['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].map(ext => join(baseGuess, 'index' + ext)),
+  ];
+  // Spec may include .js extension for a .ts file (common with moduleResolution: node16).
+  for (const cand of candidates) {
+    try {
+      const st = statSync(cand);
+      if (st.isFile()) {
+        return resolve(cand);
+      }
+    } catch {
+      // continue
+    }
+  }
+  // Try swapping .js -> .ts.
+  if (spec.endsWith('.js')) {
+    const swap = baseGuess.replace(/\.js$/, '.ts');
+    try {
+      if (statSync(swap).isFile()) {
+        return resolve(swap);
+      }
+    } catch {
+      // continue
+    }
+    const swapTsx = baseGuess.replace(/\.js$/, '.tsx');
+    try {
+      if (statSync(swapTsx).isFile()) {
+        return resolve(swapTsx);
+      }
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}
+
+// === Per-file analysis =====================================================
+
+// Per-file record:
+//   imports: Map<localName, { sourceFile: string|null, exportedName: string }>
+//   exports: Map<exportedName, localName>   (exportedName 'default' for default exports)
+//   funcs:   Map<localName, { unkeyedCalls: [{loc, primitive}], callees: Set<localName> }>
+//   reactiveLocalEntries: Set<localName>    (function names passed as reactive callbacks within this file)
+
+function analyzeFile(file) {
+  let src;
+  try {
+    src = readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  let ast;
+  try {
+    ast = parse(src, { loc: true, range: false, jsx: file.endsWith('.tsx') || file.endsWith('.jsx'), comment: true });
+  } catch (err) {
+    if (!flagQuiet) {
+      process.stderr.write(`parse error: ${file}: ${err.message}\n`);
+    }
+    return null;
+  }
+
+  // Lines tagged with `// kensington-check-reactive-ignore` (or the
+  // shorter `// check-reactive-ignore`) at the end of the line or the line
+  // above are suppressed. Used for legitimate lazy-registry patterns and
+  // similar cases where the rule's static analysis can't tell the call site
+  // is safe in practice (e.g. registry pre-seeded at mount).
+  const suppressedLines = new Set();
+  const srcLines = src.split('\n');
+  for (let i = 0; i < srcLines.length; i++) {
+    const line = srcLines[i];
+    if (/\/\/\s*(kensington-)?check-reactive-ignore\b/.test(line)) {
+      // 1-based; suppress the line the comment is on AND the next code line.
+      suppressedLines.add(i + 1);
+      suppressedLines.add(i + 2);
+    }
+  }
+
+  const imports = new Map();
+  const exports = new Map();
+  const funcs = new Map();
+  const reactiveLocalEntries = new Set();
+
+  // Kensington-imported reactive primitive names (local-alias resolution).
+  const signalNames = new Set();
+  const computedNames = new Set();
+  const effectNames = new Set();
+
+  // Track which function we are currently inside (named/binding) and how
+  // deeply nested in a reactive callback we are.
+  const fnStack = []; // entries: { name | null, rec }
+  let reactiveDepth = 0;
+
+  function currentFn() {
+    return fnStack.length ? fnStack[fnStack.length - 1] : null;
+  }
+
+  function ensureFunc(name) {
+    if (!funcs.has(name)) {
+      funcs.set(name, { unkeyedCalls: [], callees: new Set() });
+    }
+    return funcs.get(name);
+  }
+
+  function fnBindingName(node, parent) {
+    if (node.type === 'FunctionDeclaration' && node.id) {
+      return node.id.name;
+    }
+    if (parent && parent.type === 'VariableDeclarator' && parent.id.type === 'Identifier' && parent.init === node) {
+      return parent.id.name;
+    }
+    if (parent && parent.type === 'AssignmentExpression' && parent.left.type === 'Identifier' && parent.right === node) {
+      return parent.left.name;
+    }
+    if (parent && parent.type === 'Property' && !parent.computed && parent.key.type === 'Identifier' && parent.value === node) {
+      // Object property method form. Less useful for graph but we record.
+      return parent.key.name;
+    }
+    if (parent && parent.type === 'ExportDefaultDeclaration') {
+      // Default export of an anonymous function. Use a synthetic name.
+      return '__default__';
+    }
+    return null;
+  }
+
+  function isReactiveCallback(node, parent) {
+    if (!parent || parent.type !== 'CallExpression') {
+      return false;
+    }
+    const callee = parent.callee;
+    if (callee.type === 'Identifier') {
+      if ((computedNames.has(callee.name) || effectNames.has(callee.name)) && parent.arguments[0] === node) {
+        return true;
+      }
+    }
+    if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier') {
+      if (callee.property.name === 'transform' && parent.arguments[0] === node) {
+        return true;
+      }
+      if (callee.property.name === 'mapWithKey' && parent.arguments[1] === node) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Generic AST walker.
+  function walk(node, parent) {
+    if (!node || typeof node !== 'object') {
+      return;
+    }
+    if (Array.isArray(node)) {
+      for (const child of node) { walk(child, parent); }
+      return;
+    }
+    if (typeof node.type !== 'string') {
+      return;
+    }
+
+    let pushedFrame = false;
+    let pushedDepth = false;
+
+    // Enter
+    if (node.type === 'ImportDeclaration') {
+      const sourceFile = resolveImportPath(file, node.source.value);
+      for (const spec of node.specifiers) {
+        if (spec.type === 'ImportSpecifier') {
+          const imported = spec.imported.name;
+          const local = spec.local.name;
+          if (node.importKind === 'type') {
+            continue;
+          }
+          if (spec.importKind === 'type') {
+            continue;
+          }
+          imports.set(local, { sourceFile, exportedName: imported });
+          if (node.source.value === 'kensington') {
+            if (imported === 'signal') { signalNames.add(local); }
+            else if (imported === 'computed') { computedNames.add(local); }
+            else if (imported === 'effect') { effectNames.add(local); }
+          }
+        } else if (spec.type === 'ImportDefaultSpecifier') {
+          imports.set(spec.local.name, { sourceFile, exportedName: 'default' });
+        } else if (spec.type === 'ImportNamespaceSpecifier') {
+          imports.set(spec.local.name, { sourceFile, exportedName: '*' });
+        }
+      }
+    } else if (node.type === 'ExportNamedDeclaration') {
+      if (node.declaration) {
+        if (node.declaration.type === 'FunctionDeclaration' && node.declaration.id) {
+          exports.set(node.declaration.id.name, node.declaration.id.name);
+        } else if (node.declaration.type === 'VariableDeclaration') {
+          for (const d of node.declaration.declarations) {
+            if (d.id.type === 'Identifier') {
+              exports.set(d.id.name, d.id.name);
+            }
+          }
+        }
+      }
+      if (node.specifiers) {
+        for (const spec of node.specifiers) {
+          if (spec.type !== 'ExportSpecifier') { continue; }
+          const exported = spec.exported.name;
+          const local = spec.local.name;
+          if (node.source) {
+            // Re-export from another file. exported -> { sourceFile, exportedName }
+            const sourceFile = resolveImportPath(file, node.source.value);
+            // Treat as both import (so resolution can chain) and export.
+            imports.set(local, { sourceFile, exportedName: local });
+          }
+          exports.set(exported, local);
+        }
+      }
+    } else if (node.type === 'ExportDefaultDeclaration') {
+      const inner = node.declaration;
+      if (inner.type === 'Identifier') {
+        exports.set('default', inner.name);
+      } else if (inner.type === 'FunctionDeclaration' && inner.id) {
+        exports.set('default', inner.id.name);
+      } else if (inner.type === 'FunctionDeclaration' || inner.type === 'ArrowFunctionExpression' || inner.type === 'FunctionExpression') {
+        exports.set('default', '__default__');
+      }
+    } else if (node.type === 'ExportAllDeclaration') {
+      if (node.source) {
+        const sourceFile = resolveImportPath(file, node.source.value);
+        if (sourceFile) {
+          exports.set('*', { reExportAll: sourceFile });
+        }
+      }
+    }
+
+    if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {
+      const name = fnBindingName(node, parent);
+      const rec = name ? ensureFunc(name) : { unkeyedCalls: [], callees: new Set(), anonymous: true };
+      fnStack.push({ name, rec });
+      pushedFrame = true;
+      if (isReactiveCallback(node, parent)) {
+        reactiveDepth++;
+        pushedDepth = true;
+      }
+    }
+
+    if (node.type === 'CallExpression') {
+      handleCall(node);
+    }
+
+    // Recurse into children.
+    for (const key of Object.keys(node)) {
+      if (key === 'parent' || key === 'loc' || key === 'range' || key === 'type') {
+        continue;
+      }
+      walk(node[key], node);
+    }
+
+    // Exit
+    if (pushedDepth) { reactiveDepth--; }
+    if (pushedFrame) { fnStack.pop(); }
+  }
+
+  function handleCall(node) {
+    const callee = node.callee;
+    const hasKey = node.arguments.length >= 2;
+
+    // Reactive-callback bare-identifier detection (callback IS an identifier,
+    // not a function expression).
+    function detectBareIdent(arg, _reason) {
+      if (arg && arg.type === 'Identifier') {
+        reactiveLocalEntries.add(arg.name);
+      }
+    }
+    if (callee.type === 'Identifier') {
+      if (computedNames.has(callee.name)) { detectBareIdent(node.arguments[0]); }
+      else if (effectNames.has(callee.name)) { detectBareIdent(node.arguments[0]); }
+    } else if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier') {
+      if (callee.property.name === 'transform') { detectBareIdent(node.arguments[0]); }
+      else if (callee.property.name === 'mapWithKey') { detectBareIdent(node.arguments[1]); }
+    }
+
+    // While we're lexically inside any reactive callback, every named-identifier
+    // call also makes that function a reactive entry point.
+    if (reactiveDepth > 0 && callee.type === 'Identifier') {
+      reactiveLocalEntries.add(callee.name);
+    }
+
+    // Record unkeyed reactive-primitive calls in the current named function.
+    const fn = currentFn();
+    if (!fn || !fn.name || fn.rec.anonymous) {
+      return;
+    }
+    const loc = node.loc ? { line: node.loc.start.line, column: node.loc.start.column + 1 } : { line: 0, column: 0 };
+    if (suppressedLines.has(loc.line)) {
+      return;
+    }
+    if (callee.type === 'Identifier' && signalNames.has(callee.name) && !hasKey) {
+      fn.rec.unkeyedCalls.push({ loc, primitive: 'signal' });
+    } else if (callee.type === 'Identifier' && computedNames.has(callee.name) && !hasKey) {
+      fn.rec.unkeyedCalls.push({ loc, primitive: 'computed' });
+    } else if (
+      callee.type === 'MemberExpression'
+      && !callee.computed
+      && callee.property.type === 'Identifier'
+      && callee.property.name === 'transform'
+      && !hasKey
+    ) {
+      fn.rec.unkeyedCalls.push({ loc, primitive: '.transform' });
+    } else if (callee.type === 'Identifier') {
+      fn.rec.callees.add(callee.name);
+    }
+  }
+
+  walk(ast, null);
+
+  return { file, imports, exports, funcs, reactiveLocalEntries };
+}
+
+// === Cross-file resolution + propagation ===================================
+
+function buildProjectIndex(roots) {
+  const files = new Set();
+  for (const r of roots) {
+    for (const f of listSourceFiles(r)) { files.add(f); }
+  }
+  const index = new Map(); // file -> per-file record
+  for (const f of files) {
+    const rec = analyzeFile(f);
+    if (rec) {
+      index.set(f, rec);
+    }
+  }
+  return index;
+}
+
+// Resolve a local name in a file to a (file, fnName) pair where fnName is
+// defined. Follows re-exports. Returns null if it doesn't resolve to a local
+// function in any scanned file. The exportedName='*' (namespace import) case
+// is not followed.
+function resolveLocal(index, file, localName, visited = new Set()) {
+  const visitKey = `${file}::${localName}`;
+  if (visited.has(visitKey)) { return null; }
+  visited.add(visitKey);
+
+  const rec = index.get(file);
+  if (!rec) { return null; }
+  // Local function defined here?
+  if (rec.funcs.has(localName)) {
+    return { file, fnName: localName };
+  }
+  // Imported?
+  const imp = rec.imports.get(localName);
+  if (imp && imp.sourceFile && index.has(imp.sourceFile) && imp.exportedName !== '*') {
+    const targetRec = index.get(imp.sourceFile);
+    const exportedLocal = targetRec.exports.get(imp.exportedName);
+    if (typeof exportedLocal === 'string') {
+      return resolveLocal(index, imp.sourceFile, exportedLocal, visited);
+    }
+    // Re-export-all: search every file in the * chain.
+    if (exportedLocal && typeof exportedLocal === 'object' && exportedLocal.reExportAll) {
+      const r = resolveLocal(index, exportedLocal.reExportAll, imp.exportedName, visited);
+      if (r) { return r; }
+    }
+    // Last-resort. Maybe the target file has the function by the imported name
+    // (common pattern: re-export named directly).
+    if (targetRec.funcs.has(imp.exportedName)) {
+      return { file: imp.sourceFile, fnName: imp.exportedName };
+    }
+  }
+  return null;
+}
+
+function propagate(index) {
+  // Seed reactive-reachable set.
+  const reachable = new Map(); // key 'file::fnName' -> reason string
+  const queue = [];
+  for (const [file, rec] of index) {
+    for (const local of rec.reactiveLocalEntries) {
+      const r = resolveLocal(index, file, local);
+      if (r) {
+        const key = `${r.file}::${r.fnName}`;
+        if (!reachable.has(key)) {
+          reachable.set(key, `entered via ${relPath(file)} reactive callback`);
+          queue.push(r);
+        }
+      }
+    }
+  }
+  // BFS through callees.
+  while (queue.length) {
+    const { file, fnName } = queue.shift();
+    const rec = index.get(file);
+    if (!rec) { continue; }
+    const fn = rec.funcs.get(fnName);
+    if (!fn) { continue; }
+    for (const callee of fn.callees) {
+      const r = resolveLocal(index, file, callee);
+      if (!r) { continue; }
+      const key = `${r.file}::${r.fnName}`;
+      if (!reachable.has(key)) {
+        reachable.set(key, `called from ${fnName} in ${relPath(file)}`);
+        queue.push(r);
+      }
+    }
+  }
+  return reachable;
+}
+
+function relPath(p) {
+  const cwd = process.cwd() + sep;
+  if (p.startsWith(cwd)) { return p.slice(cwd.length); }
+  return p;
+}
+
+function report(index, reachable) {
+  const findings = [];
+  for (const [file, rec] of index) {
+    for (const [fnName, fn] of rec.funcs) {
+      const key = `${file}::${fnName}`;
+      if (!reachable.has(key)) { continue; }
+      const reason = reachable.get(key);
+      for (const hit of fn.unkeyedCalls) {
+        findings.push({
+          file: relPath(file),
+          line: hit.loc.line,
+          column: hit.loc.column,
+          primitive: hit.primitive,
+          fnName,
+          reason,
+        });
+      }
+    }
+  }
+  findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+  return findings;
+}
+
+// === Public API ============================================================
+
+// Programmatic entry. Returns { findings, fileCount }. Pure (no process exit,
+// no stdout). Suitable for tests and tooling integration.
+export function analyzeProject(roots, opts = {}) {
+  const prevQuiet = flagQuiet;
+  flagQuiet = opts.quiet ?? true;
+  try {
+    const index = buildProjectIndex(roots);
+    const reachable = propagate(index);
+    const findings = report(index, reachable);
+    return { findings, fileCount: index.size };
+  } finally {
+    flagQuiet = prevQuiet;
+  }
+}
+
+// === Main ==================================================================
+
+function printHelp() {
+  process.stdout.write(
+    'kensington-check-reactive (EXPERIMENTAL, NOT YET RELEASED)\n'
+    + '\n'
+    + 'Cross-file static analyzer for unkeyed signal()/computed()/.transform()\n'
+    + 'calls inside helper functions reachable from a reactive callback. This\n'
+    + 'binary is shipped for early testing only. The CLI surface, output format,\n'
+    + 'and even its presence in the package may change without notice. Do not\n'
+    + 'build tooling on top of it until it appears in README.md.\n'
+    + '\n'
+    + 'Usage:\n'
+    + '  kensington-check-reactive [paths...]            scan and print findings\n'
+    + '  kensington-check-reactive [paths...] --json     structured JSON output\n'
+    + '  kensington-check-reactive [paths...] --quiet    exit code only, no output\n'
+    + '  kensington-check-reactive --help                this message\n'
+    + '\n'
+    + 'Exits 0 on no findings, 1 on findings, 2 on script error.\n',
+  );
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+  flagJson = args.includes('--json');
+  flagQuiet = args.includes('--quiet');
+  const roots = args.filter(a => !a.startsWith('--'));
+  if (roots.length === 0) {
+    roots.push('.');
+  }
+
+  const index = buildProjectIndex(roots);
+  if (index.size === 0) {
+    if (!flagQuiet) {
+      process.stderr.write(`no source files found under: ${roots.join(', ')}\n`);
+    }
+    process.exit(2);
+  }
+  const reachable = propagate(index);
+  const findings = report(index, reachable);
+
+  if (flagJson) {
+    process.stdout.write(JSON.stringify({ findings }, null, 2) + '\n');
+  } else if (!flagQuiet) {
+    if (findings.length === 0) {
+      process.stdout.write(`kensington-check-reactive: 0 findings across ${index.size} files\n`);
+    } else {
+      for (const f of findings) {
+        process.stdout.write(
+          `${f.file}:${f.line}:${f.column}: warning: ${f.primitive}() unkeyed in \`${f.fnName}\` (${f.reason})\n`,
+        );
+      }
+      process.stdout.write(`\n${findings.length} finding${findings.length === 1 ? '' : 's'} across ${index.size} files\n`);
+    }
+  }
+
+  process.exit(findings.length > 0 ? 1 : 0);
+}
+
+// Run main() only when invoked as a CLI, not when imported.
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main();
+}

package/index.js

@@ -22,6 +22,8 @@ import preferArrayForMultilineContent from './rules/prefer-array-for-multiline-c
 import attrsOnCallLine from './rules/attrs-on-call-line.js';
 import attrsCanonicalShape from './rules/attrs-canonical-shape.js';
 import consistentContentLayout from './rules/consistent-content-layout.js';
+import noHelperFunctionTrap from './rules/no-helper-function-trap.js';
+import requireReactiveKey from './rules/require-reactive-key.js';
 
 const plugin = {
   meta: { name: 'eslint-plugin-kensington' },
@@ -50,6 +52,8 @@ const plugin = {
     'attrs-on-call-line': attrsOnCallLine,
     'attrs-canonical-shape': attrsCanonicalShape,
     'consistent-content-layout': consistentContentLayout,
+    'no-helper-function-trap': noHelperFunctionTrap,
+    'require-reactive-key': requireReactiveKey,
   },
   configs: {},
 };
@@ -73,6 +77,23 @@ plugin.configs.recommended = {
     'kensington/no-async-effect': 'error',
     'kensington/no-async-computed': 'error',
     'kensington/no-out-of-scope-reactive-reference': 'warn',
+    'kensington/no-helper-function-trap': 'warn',
+  },
+};
+
+plugin.configs.strict = {
+  plugins: { kensington: plugin },
+  rules: {
+    ...plugin.configs.recommended.rules,
+    // Promote every reactive-correctness warning to error. Strict mode trades
+    // tolerance of false positives for zero silent misses.
+    'kensington/no-signal-async-write': 'error',
+    'kensington/no-ignored-effect-return': 'error',
+    'kensington/prefer-value-in-async': 'error',
+    'kensington/no-new-computed-in-computed': 'error',
+    'kensington/no-out-of-scope-reactive-reference': 'error',
+    'kensington/no-helper-function-trap': 'error',
+    'kensington/require-reactive-key': 'error',
   },
 };
 

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "kensington-eslint-plugin",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "ESLint rules for kensington signal correctness",
   "type": "module",
   "main": "index.js",
+  "bin": {
+    "kensington-check-reactive": "./bin/check-reactive.js"
+  },
   "scripts": {
-    "test": "node --test tests/no-set-in-derivation.test.js tests/no-self-read-write.test.js tests/no-signal-async-write.test.js tests/no-set-on-derived-signal.test.js tests/no-new-signal-in-effect.test.js tests/no-effect-in-computed.test.js tests/no-ignored-effect-return.test.js tests/prefer-value-in-async.test.js tests/no-new-computed-in-effect.test.js tests/no-new-signal-in-computed.test.js tests/no-unsafe-literal.test.js tests/no-new-computed-in-computed.test.js tests/no-effect-in-effect.test.js tests/no-async-effect.test.js tests/no-async-computed.test.js tests/prefer-boolean-attribute-true.test.js tests/prefer-camelcase-attrs.test.js tests/prefer-style-object.test.js tests/prefer-nested-attr-groups.test.js tests/prefer-array-for-multiline-content.test.js tests/attrs-on-call-line.test.js tests/attrs-canonical-shape.test.js tests/consistent-content-layout.test.js tests/no-out-of-scope-reactive-reference.test.js"
+    "test": "node --test tests/no-set-in-derivation.test.js tests/no-self-read-write.test.js tests/no-signal-async-write.test.js tests/no-set-on-derived-signal.test.js tests/no-new-signal-in-effect.test.js tests/no-effect-in-computed.test.js tests/no-ignored-effect-return.test.js tests/prefer-value-in-async.test.js tests/no-new-computed-in-effect.test.js tests/no-new-signal-in-computed.test.js tests/no-unsafe-literal.test.js tests/no-new-computed-in-computed.test.js tests/no-effect-in-effect.test.js tests/no-async-effect.test.js tests/no-async-computed.test.js tests/prefer-boolean-attribute-true.test.js tests/prefer-camelcase-attrs.test.js tests/prefer-style-object.test.js tests/prefer-nested-attr-groups.test.js tests/prefer-array-for-multiline-content.test.js tests/attrs-on-call-line.test.js tests/attrs-canonical-shape.test.js tests/consistent-content-layout.test.js tests/no-out-of-scope-reactive-reference.test.js tests/no-helper-function-trap.test.js tests/require-reactive-key.test.js tests/check-reactive.test.js"
   },
   "peerDependencies": {
     "eslint": ">=9"
@@ -30,6 +33,10 @@
   "license": "ISC",
   "files": [
     "index.js",
-    "rules"
-  ]
+    "rules",
+    "bin"
+  ],
+  "dependencies": {
+    "@typescript-eslint/typescript-estree": "^8.62.0"
+  }
 }

package/rules/no-helper-function-trap.js

@@ -0,0 +1,278 @@
+// Reports unkeyed `signal()`, `computed()`, or `.transform()` calls inside named
+// functions that are transitively reachable from a reactive callback in the
+// same file (a mapWithKey mapFn, a `computed(fn)`, `transform(fn)`, or
+// `effect(fn)`). The existing `no-new-signal-in-computed` and
+// `no-new-computed-in-computed` rules catch the LEXICAL case (the call is
+// directly inside a `computed(() => ...)` body in the source). This rule
+// catches the CALL-STACK case (the call is in a helper, the helper is called
+// from inside a computed/transform/mapFn callback, so at runtime the call runs
+// in a reactive scope).
+//
+// Single-file analysis only. We track only named top-level functions; nested
+// anonymous helpers are out of scope (the lexical rule already covers them).
+//
+// Algorithm:
+//   Single AST walk that maintains TWO stacks:
+//     - fnStack: named-function frames (innermost last). Used to attribute
+//       unkeyed reactive primitives to their containing function and to record
+//       which other named functions each function calls.
+//     - reactiveDepth: an integer counter incremented when entering a reactive
+//       callback (the function argument to `computed(fn)`, `effect(fn)`,
+//       `signal.transform(fn)`, or `signal.mapWithKey(key, fn)`). When > 0,
+//       every named CallExpression encountered marks its callee as a reactive
+//       entry point. This captures helpers reached via arbitrary intermediate
+//       wrappers (`.map(a => cell(a))`, nested arrows, loops, etc.).
+//   Then on Program:exit, BFS from reactive entry points through the call
+//   graph; every reached function is in a reactive scope. Report every unkeyed
+//   reactive-primitive call site inside any reached function.
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'require a stable key for signal/computed/.transform calls inside helper '
+        + 'functions called from a reactive callback (mapWithKey mapFn, '
+        + 'computed/transform/effect body) in the same file',
+    },
+    messages: {
+      helperFunctionTrap:
+        '{{primitive}}() call without a key inside `{{fnName}}`, which is called from '
+        + 'a reactive callback in this file ({{reason}}). The call runs inside the '
+        + 'surrounding reactive scope at runtime even though the call site looks '
+        + 'top-level here. Pass a stable key as the second argument to scope the '
+        + 'instance to the surrounding reactive scope.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const signalNames = new Set();
+    const computedNames = new Set();
+    const effectNames = new Set();
+
+    // funcName -> { unkeyedCalls: [{node, primitive}], callees: Set<funcName> }
+    const funcs = new Map();
+    // funcName -> reason it's a reactive entry point.
+    const reactiveEntryPoints = new Map();
+    // Stack of named-function frames; innermost last.
+    const fnStack = [];
+    // How many reactive callbacks deep we are at the lexical level.
+    let reactiveDepth = 0;
+
+    function currentFn() {
+      return fnStack.length ? fnStack[fnStack.length - 1] : null;
+    }
+
+    function ensureFunc(name) {
+      if (!funcs.has(name)) {
+        funcs.set(name, { unkeyedCalls: [], callees: new Set() });
+      }
+      return funcs.get(name);
+    }
+
+    function fnBindingName(node) {
+      if (node.type === 'FunctionDeclaration' && node.id) {
+        return node.id.name;
+      }
+      if (
+        node.parent
+        && node.parent.type === 'VariableDeclarator'
+        && node.parent.id.type === 'Identifier'
+        && node.parent.init === node
+      ) {
+        return node.parent.id.name;
+      }
+      return null;
+    }
+
+    // True when the given (Function|Arrow)Expression is being passed as a
+    // reactive callback argument to a kensington reactive wrapper or method.
+    function isReactiveCallback(node) {
+      const { parent } = node;
+      if (!parent || parent.type !== 'CallExpression') {
+        return false;
+      }
+      const callee = parent.callee;
+      if (callee.type === 'Identifier') {
+        if (
+          (computedNames.has(callee.name) || effectNames.has(callee.name))
+          && parent.arguments[0] === node
+        ) {
+          return true;
+        }
+      }
+      if (
+        callee.type === 'MemberExpression'
+        && !callee.computed
+        && callee.property.type === 'Identifier'
+      ) {
+        // signal.transform(fn) — first arg is the callback.
+        if (callee.property.name === 'transform' && parent.arguments[0] === node) {
+          return true;
+        }
+        // signal.mapWithKey(key, fn) — second arg is the callback.
+        if (callee.property.name === 'mapWithKey' && parent.arguments[1] === node) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    function reasonFor(node) {
+      const { parent } = node;
+      const callee = parent.callee;
+      if (callee.type === 'Identifier') {
+        if (computedNames.has(callee.name)) { return 'passed to computed()'; }
+        if (effectNames.has(callee.name)) { return 'passed to effect()'; }
+      }
+      if (callee.type === 'MemberExpression' && callee.property.type === 'Identifier') {
+        if (callee.property.name === 'transform') { return 'passed to .transform()'; }
+        if (callee.property.name === 'mapWithKey') { return 'passed to mapWithKey() as mapFn'; }
+      }
+      return 'inside a reactive callback';
+    }
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== 'kensington') {
+          return;
+        }
+        for (const spec of node.specifiers) {
+          if (spec.type !== 'ImportSpecifier') {
+            continue;
+          }
+          if (spec.imported.name === 'signal') { signalNames.add(spec.local.name); }
+          if (spec.imported.name === 'computed') { computedNames.add(spec.local.name); }
+          if (spec.imported.name === 'effect') { effectNames.add(spec.local.name); }
+        }
+      },
+
+      ':matches(FunctionDeclaration, FunctionExpression, ArrowFunctionExpression)'(node) {
+        const name = fnBindingName(node);
+        if (name) {
+          fnStack.push(ensureFunc(name));
+        } else {
+          fnStack.push({ unkeyedCalls: [], callees: new Set(), anonymous: true });
+        }
+        if (isReactiveCallback(node)) {
+          reactiveDepth++;
+        }
+      },
+
+      ':matches(FunctionDeclaration, FunctionExpression, ArrowFunctionExpression):exit'(node) {
+        if (isReactiveCallback(node)) {
+          reactiveDepth--;
+        }
+        fnStack.pop();
+      },
+
+      CallExpression(node) {
+        const callee = node.callee;
+        const hasKey = node.arguments.length >= 2;
+
+        // 1. If we are lexically inside ANY reactive callback and the callee is a
+        //    named identifier, mark that function as a reactive entry point.
+        if (reactiveDepth > 0 && callee.type === 'Identifier') {
+          if (!reactiveEntryPoints.has(callee.name)) {
+            reactiveEntryPoints.set(
+              callee.name,
+              `transitively reached from a reactive callback in this file`,
+            );
+          }
+        }
+
+        // 1b. Detect bare-identifier callbacks passed to reactive wrappers:
+        //     computed(fn), effect(fn), signal.transform(fn), signal.mapWithKey(key, fn).
+        //     The callback isn't lexically a Function/Arrow, so it never enters our
+        //     reactiveDepth tracking. Mark the identifier as an entry point directly.
+        function checkBareIdent(arg, reason) {
+          if (arg && arg.type === 'Identifier' && !reactiveEntryPoints.has(arg.name)) {
+            reactiveEntryPoints.set(arg.name, reason);
+          }
+        }
+        if (callee.type === 'Identifier') {
+          if (computedNames.has(callee.name)) {
+            checkBareIdent(node.arguments[0], 'passed to computed()');
+          } else if (effectNames.has(callee.name)) {
+            checkBareIdent(node.arguments[0], 'passed to effect()');
+          }
+        } else if (
+          callee.type === 'MemberExpression'
+          && !callee.computed
+          && callee.property.type === 'Identifier'
+        ) {
+          if (callee.property.name === 'transform') {
+            checkBareIdent(node.arguments[0], 'passed to .transform()');
+          } else if (callee.property.name === 'mapWithKey') {
+            checkBareIdent(node.arguments[1], 'passed to mapWithKey() as mapFn');
+          }
+        }
+
+        // 2. Record unkeyed reactive-primitive calls inside the current named function.
+        const fn = currentFn();
+        if (fn && !fn.anonymous) {
+          if (callee.type === 'Identifier' && signalNames.has(callee.name) && !hasKey) {
+            fn.unkeyedCalls.push({ node, primitive: 'signal' });
+          } else if (callee.type === 'Identifier' && computedNames.has(callee.name) && !hasKey) {
+            fn.unkeyedCalls.push({ node, primitive: 'computed' });
+          } else if (
+            callee.type === 'MemberExpression'
+            && !callee.computed
+            && callee.property.type === 'Identifier'
+            && callee.property.name === 'transform'
+            && !hasKey
+          ) {
+            fn.unkeyedCalls.push({ node, primitive: '.transform' });
+          } else if (callee.type === 'Identifier') {
+            fn.callees.add(callee.name);
+          }
+        }
+      },
+
+      'Program:exit'() {
+        // BFS over the call graph starting from reactive entry points.
+        const reachable = new Map();
+        const queue = [];
+        for (const [name, reason] of reactiveEntryPoints) {
+          if (funcs.has(name)) {
+            reachable.set(name, reason);
+            queue.push(name);
+          }
+        }
+        while (queue.length) {
+          const name = queue.shift();
+          const rec = funcs.get(name);
+          if (!rec) {
+            continue;
+          }
+          for (const callee of rec.callees) {
+            if (!reachable.has(callee) && funcs.has(callee)) {
+              reachable.set(callee, `called transitively from ${name}`);
+              queue.push(callee);
+            }
+          }
+        }
+
+        for (const [name, rec] of funcs) {
+          if (!reachable.has(name)) {
+            continue;
+          }
+          const reason = reachable.get(name);
+          for (const hit of rec.unkeyedCalls) {
+            context.report({
+              node: hit.node,
+              messageId: 'helperFunctionTrap',
+              data: { primitive: hit.primitive, fnName: name, reason },
+            });
+          }
+        }
+
+        // The reasonFor helper isn't used by the simplified entry-point recording
+        // (reason text is generic now). Keeping the function for future detail
+        // upgrades without changing the public message shape.
+        void reasonFor;
+      },
+    };
+  },
+};

package/rules/require-reactive-key.js

@@ -0,0 +1,96 @@
+// Paranoid mode. Flags EVERY `signal()`, `computed()`, or `.transform()` call
+// site that does not pass a key. Keys are cheap and harmless: at runtime the
+// key is IGNORED when the call is not inside a reactive scope. The only cost is
+// a few extra characters per call. The benefit is that the code is robust to
+// future refactors that lift a top-level helper inside a `computed()` callback
+// or a `mapWithKey()` mapFn. Without the key, that refactor silently introduces
+// the helper-function trap; per-row local state then resets on every outer
+// re-run and the operator only discovers it during manual testing.
+//
+// Suppress per call site with `// eslint-disable-next-line kensington/require-reactive-key`
+// when you're certain the call site will never be moved into a reactive scope.
+//
+// Off in the `recommended` config. On in `strict` and intended for use by
+// agents and projects that want maximum safety.
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'require a stable key on every signal/computed/.transform call. Keys are no-ops '
+        + 'at the module scope and required inside reactive callbacks; passing one always '
+        + 'is safer than auditing call-site reachability.',
+    },
+    messages: {
+      missingKey:
+        '{{primitive}}() called without a key. Pass a stable key as the second argument '
+        + '(e.g. {{primitive}}({{exampleFirstArg}}, \'{{exampleKey}}\')). Keys are ignored '
+        + 'outside a reactive scope so this is safe everywhere; required inside one. '
+        + 'Suppress per call site with `eslint-disable-next-line kensington/require-reactive-key` '
+        + 'when the call site is known never to move into a reactive scope.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const signalNames = new Set();
+    const computedNames = new Set();
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== 'kensington') {
+          return;
+        }
+        for (const spec of node.specifiers) {
+          if (spec.type !== 'ImportSpecifier') {
+            continue;
+          }
+          if (spec.imported.name === 'signal') { signalNames.add(spec.local.name); }
+          if (spec.imported.name === 'computed') { computedNames.add(spec.local.name); }
+        }
+      },
+
+      CallExpression(node) {
+        const callee = node.callee;
+        const hasKey = node.arguments.length >= 2;
+        if (hasKey) {
+          return;
+        }
+
+        if (callee.type === 'Identifier' && signalNames.has(callee.name)) {
+          // signal(initial) — second arg should be the key.
+          context.report({
+            node,
+            messageId: 'missingKey',
+            data: { primitive: callee.name, exampleFirstArg: 'initial', exampleKey: 'unique-id' },
+          });
+          return;
+        }
+
+        if (callee.type === 'Identifier' && computedNames.has(callee.name)) {
+          context.report({
+            node,
+            messageId: 'missingKey',
+            data: { primitive: callee.name, exampleFirstArg: 'fn', exampleKey: 'unique-id' },
+          });
+          return;
+        }
+
+        if (
+          callee.type === 'MemberExpression'
+          && !callee.computed
+          && callee.property.type === 'Identifier'
+          && callee.property.name === 'transform'
+        ) {
+          // .transform(fn) — second arg should be the key.
+          context.report({
+            node,
+            messageId: 'missingKey',
+            data: { primitive: '.transform', exampleFirstArg: 'fn', exampleKey: 'unique-id' },
+          });
+        }
+      },
+    };
+  },
+};