kensington-eslint-plugin 0.5.1 → 0.6.0

package/README.md

@@ -42,7 +42,7 @@ 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:
+The `strict` config opts in to maximum-safety reactive correctness. It extends `recommended`, promotes every reactive-correctness `warn` rule to `error`, and adds `no-helper-function-trap` at `error` (single-file call-graph analysis that catches unkeyed `signal()` / `computed()` / `.transform()` inside helpers reachable from a reactive callback — the trap most lexical rules miss).
 
 ```js
 import kensington from 'kensington-eslint-plugin';
@@ -55,11 +55,22 @@ export default [
 
 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.
+- **Adds `no-helper-function-trap`** (error). The most valuable single rule the plugin ships.
+- **Promotes from `warn` to `error`**: `no-signal-async-write`, `no-ignored-effect-return`, `prefer-value-in-async`, `no-out-of-scope-reactive-reference`. 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.
 
+### Optional: `require-reactive-key`
+
+A separate rule, not enabled by either config. Flags every unkeyed `signal()` / `computed()` / `.transform()` call site, period — including at module scope. Keys are no-ops at module scope and required inside reactive scopes, so passing one always is safer than auditing call-site reachability. But in practice the rule generates mechanical retrofits that don't catch real bugs (the keys it forces at module scope have no runtime effect). Opt in explicitly when you want refactor-safety enforcement so that a later lift into a reactive scope finds the key already in place:
+
+```js
+export default [
+  kensington.configs.strict,
+  { rules: { 'kensington/require-reactive-key': 'error' } },
+];
+```
+
 The `style` config is opt-in and bundles the formatting rules at `warn` level:
 
 ```js
@@ -116,11 +127,12 @@ Because this is a standard ESLint plugin, it works anywhere ESLint runs with no
 | [`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-new-computed-in-computed`](#no-new-computed-in-computed) | Require a stable key for `computed()` and `.transform()` calls inside a `computed()` body (**deprecated**. use `no-out-of-scope-reactive-reference`) | off | off |
 | [`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-async-set`](#no-async-set) | Disallow passing an async function to `.set()` on a signal | 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 |
@@ -212,6 +224,21 @@ effect(() => {
 });
 ```
 
+Also fires for `liveSignal()` imports from `kensington/live`, `kensington/live/client`, or `kensington/live/server`. The lazy-registry creation on first sight happens inside the effect's reactive scope and trips the runtime warning.
+
+```js
+// Bad
+import { effect } from 'kensington';
+import { liveSignal } from 'kensington/live';
+effect(() => {
+  const c = liveSignal(0, 'counter'); // error. Registry lookup inside reactive scope.
+});
+
+// Good. Declare at module scope, or eager-seed via queueMicrotask outside.
+const c = liveSignal(0, 'counter');
+effect(() => { c.set(c.get() + 1); });
+```
+
 ---
 
 ### `no-effect-in-computed`
@@ -328,6 +355,21 @@ const temp = signal(0);
 const c = computed(() => temp.get() + base.get());
 ```
 
+Also fires for `liveSignal()` calls inside a `computed()` body, from any of `kensington/live`, `kensington/live/client`, or `kensington/live/server`. liveSignal's second argument is always a name (not optional), so the rule fires regardless of args length. The trap is the first-call lazy creation inside the reactive scope.
+
+```js
+// Bad
+import { computed } from 'kensington';
+import { liveSignal } from 'kensington/live';
+const c = computed(() => {
+  return liveSignal(0, 'foo').get(); // error. Lazy-registry creation inside reactive scope.
+});
+
+// Good. Declare at module scope, or eager-seed via queueMicrotask outside.
+const foo = liveSignal(0, 'foo');
+const c = computed(() => foo.get());
+```
+
 ---
 
 ### `no-unsafe-literal`
@@ -346,6 +388,10 @@ t.literal(userContent);
 
 ### `no-new-computed-in-computed`
 
+**Deprecated.** Removed from the `recommended` and `strict` configs. The kensington runtime now defers the `computed-in-computed` and `transform-in-computed` warnings to subscription time and only fires when a user `effect` or user `computed` subscribes to the inner. Inline consumption as an attribute, class, text, or prop slot is silent by design, so the purely-lexical flag this rule emitted became mostly false positives. The remaining real concern — a nested inner that escapes the surrounding computed's scope — is covered by [`no-out-of-scope-reactive-reference`](#no-out-of-scope-reactive-reference), which uses a full escape classifier. Teams that want every unkeyed call site flagged can opt into [`require-reactive-key`](#require-reactive-key).
+
+The rule stays registered so existing configs that reference it don't error, but enabling it is no longer recommended.
+
 Creating `computed()` or `.transform()` inside a `computed()` body without a key creates a new orphaned derived signal on every recompute. Pass a stable key as the second argument to reuse the same instance across outer re-runs.
 
 ```js
@@ -488,6 +534,25 @@ effect(() => {
 
 ---
 
+### `no-async-set`
+
+`.set()` stores whatever value the updater returns. An async function returns a `Promise` immediately, so the Promise object itself becomes the signal's value. Reads then see a `Thenable` where consumers expect `T`. For a `liveSignal`, the Promise serializes to `"{}"` on the wire, corrupting every subscriber's view.
+
+The pattern almost always means "do async work then update the signal". Await the async work first and then call `.set(resolvedValue)`, or schedule the write from an `effect()`.
+
+```js
+// Bad. Signal value becomes a Promise, not the resolved user.
+user.set(async (prev) => { // error
+  return await fetchUser(prev.id);
+});
+
+// Good. Resolve first, then set the final value.
+const next = await fetchUser(user.value.id);
+user.set(next);
+```
+
+---
+
 ### `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.
@@ -515,6 +580,30 @@ Single-file analysis only. A helper defined in `cell.ts` and called from a react
 
 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.
 
+Also fires for `liveSignal()` calls inside such helpers, from any of `kensington/live`, `kensington/live/client`, or `kensington/live/server`. The trap is the same shape (first-call lazy creation inside the surrounding reactive scope), and liveSignal's second argument is always a name (not optional), so the rule fires regardless of args length. The fix is to declare the liveSignal at module scope, or eager-seed it via `queueMicrotask` outside the reactive scope.
+
+```js
+// Bad. getRow is a lazy registry; the first call for a given id creates the
+// transport entry inside the per-key computed run by mapWithKey.
+import { liveSignal } from 'kensington/live';
+function getRow(id) { return liveSignal(0, 'row:' + id); }
+const list = items.mapWithKey('id', item => getRow(item.id));
+
+// Good. Eager-seed once outside the reactive scope.
+const rows = new Map();
+function getRow(id) {
+  let s = rows.get(id);
+  if (s === undefined) { s = liveSignal(0, 'row:' + id); rows.set(id, s); }
+  return s;
+}
+// In an addConnectedCallback or top-of-component effect:
+effect(() => {
+  const ids = items.get().map(i => i.id);
+  queueMicrotask(() => { for (const id of ids) { getRow(id); } });
+});
+const list = items.mapWithKey('id', item => getRow(item.id));
+```
+
 ---
 
 ### `require-reactive-key`

package/bin/check-reactive.js

@@ -1,32 +1,114 @@
 #!/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.
+// detection rules, 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. Until then THIS COMMENT BLOCK is the canonical description of
+// what the command does.
 //
-// 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.
+// ---------------------------------------------------------------------------
+// What it does
+// ---------------------------------------------------------------------------
 //
-// 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.
+// Cross-file static analyzer for two classes of kensington reactive bugs that
+// in-file ESLint rules cannot catch on their own. Parses every .ts/.tsx/.js/
+// .jsx/.mjs/.cjs file under the given roots, builds a project-wide call
+// graph across imports (named imports, default imports, re-exports, and
+// re-export-all), and reports two kinds of findings:
+//
+//   1. Unkeyed reactive primitive inside a reachable helper.
+//      Any signal(), computed(), or .transform() call site (no key argument)
+//      inside a NAMED function that is reachable from a reactive callback
+//      (computed(fn), effect(fn), signal.transform(fn), signal.mapWithKey(key,
+//      mapFn)) anywhere in the project. The kensington-eslint-plugin rule
+//      `no-helper-function-trap` catches this for helpers defined in the same
+//      file as the reactive callback. This script catches the cross-file case
+//      where the helper is imported.
+//
+//      Reported with kind: 'unkeyed-in-reactive-callback'.
+//
+//   2. Duplicate keyed-primitive call with mismatched primitive initial.
+//      Two or more call sites that pass the same literal string key to
+//      signal(initial, 'key') (or the same literal string name to
+//      liveSignal(initial, 'name') from kensington/live) but with different
+//      primitive literal initial values. The second caller's initial is
+//      silently ignored at runtime — the registry returns the existing
+//      signal with its current value — so without this static check the bug
+//      surfaces later as a wrong-value UI surprise. Object and array
+//      initials are skipped (false-positive risk on
+//      structurally-equal-but-reference-different cases). signal and
+//      liveSignal are grouped separately because their collision namespaces
+//      differ.
+//
+//      Reported with kind: 'duplicate-key-initial-mismatch'.
+//
+// Static analysis only. Both detectors require literal-string keys and
+// (for #2) primitive literal initials to fire. Dynamic keys built at runtime
+// (`cell:${addr}`) and dynamic initials (getCurrentUser()) are uncatchable
+// statically; the kensington runtime emits paired throttled warnings for
+// those cases at call time.
+//
+// ---------------------------------------------------------------------------
+// Suppression
+// ---------------------------------------------------------------------------
+//
+// Per-call-site escape hatch. Add either form on the offending line or on
+// the line above it:
+//
+//   // kensington-check-reactive-ignore
+//   // check-reactive-ignore
+//
+// The line-above form also suppresses the next code line, which covers tight
+// declaration groups. Intended for the lazy-registry pattern (the script
+// can't tell whether the lazy creation has been pre-seeded by the consumer)
+// and the rare legitimate cross-file initial mismatch.
+//
+// ---------------------------------------------------------------------------
+// Usage (subject to change)
+// ---------------------------------------------------------------------------
 //
-// Usage (subject to change):
 //   kensington-check-reactive [paths...]
+//       Scan and print human-readable findings to stdout.
+//
 //   kensington-check-reactive [paths...] --json
-//   kensington-check-reactive [paths...] --quiet     # exit-code only, no output
+//       Print findings as { findings: [...] } JSON. Each finding has a
+//       `kind` field distinguishing the two detection types.
+//
+//   kensington-check-reactive [paths...] --quiet
+//       Exit-code only. No stdout.
+//
 //   kensington-check-reactive --help
+//       Brief help.
+//
+// Paths default to `.` (the current working directory). Skipped directory
+// names: node_modules, .git, dist, build, cjs, .next, .wrangler, public,
+// coverage.
+//
+// Exit codes: 0 on no findings, 1 on findings, 2 on script error
+// (e.g. no source files found, fatal parse error in the analyzer).
 //
-// Exits 0 on no findings, 1 on findings, 2 on script error.
+// ---------------------------------------------------------------------------
+// Recommended invocation
+// ---------------------------------------------------------------------------
+//
+// Chain into the project's lint script so every `npm run lint` runs the
+// check alongside ESLint:
+//
+//   "lint": "eslint . && kensington-check-reactive src --quiet"
+//
+// --quiet keeps the script exit-code-only; ESLint's own output stays
+// visible, and a non-zero exit fails the script. Drop --quiet to print
+// findings inline above the lint output.
+//
+// Programmatic entry point: `analyzeProject(roots, opts)` is exported at the
+// bottom of this file. Returns `{ findings, fileCount }` without writing to
+// stdout or calling process.exit. Suitable for editor integrations and tests.
 
 /* global process */
 import { readFileSync, statSync, readdirSync } from 'node:fs';
@@ -178,6 +260,15 @@ function analyzeFile(file) {
   const signalNames = new Set();
   const computedNames = new Set();
   const effectNames = new Set();
+  // Live-signal names from `kensington/live`. Tracked separately because the
+  // collision namespace differs from regular keyed signals: liveSignal names
+  // are global across the app, regular keyed signal keys are per-computed.
+  const liveSignalNames = new Set();
+  // Per-file literal-key + literal-initial calls. Aggregated cross-file in
+  // `findDuplicateKeyInitialMismatches` to surface collisions where two
+  // unrelated call sites share a literal key/name but pass different
+  // primitive initials.
+  const keyedLiteralInits = [];
 
   // Track which function we are currently inside (named/binding) and how
   // deeply nested in a reactive callback we are.
@@ -271,6 +362,8 @@ function analyzeFile(file) {
             if (imported === 'signal') { signalNames.add(local); }
             else if (imported === 'computed') { computedNames.add(local); }
             else if (imported === 'effect') { effectNames.add(local); }
+          } else if (node.source.value === 'kensington/live') {
+            if (imported === 'liveSignal') { liveSignalNames.add(local); }
           }
         } else if (spec.type === 'ImportDefaultSpecifier') {
           imports.set(spec.local.name, { sourceFile, exportedName: 'default' });
@@ -354,6 +447,29 @@ function analyzeFile(file) {
     const callee = node.callee;
     const hasKey = node.arguments.length >= 2;
 
+    // Capture (literal-key, literal-initial) pairs for cross-file collision detection.
+    // signal(initial, 'literal-key') and liveSignal(initial, 'literal-name') only.
+    // Computed and .transform don't have an "initial" so collisions there
+    // can't be mismatched in the same way.
+    if (node.arguments.length === 2) {
+      const arg0 = node.arguments[0];
+      const arg1 = node.arguments[1];
+      const isStringLiteralKey = arg1 && arg1.type === 'Literal' && typeof arg1.value === 'string';
+      const isPrimitiveLiteralInitial = arg0 && arg0.type === 'Literal'
+        && (arg0.value === null || ['string', 'number', 'boolean'].includes(typeof arg0.value));
+      if (isStringLiteralKey && isPrimitiveLiteralInitial) {
+        let primitive = null;
+        if (callee.type === 'Identifier' && signalNames.has(callee.name)) { primitive = 'signal'; }
+        else if (callee.type === 'Identifier' && liveSignalNames.has(callee.name)) { primitive = 'liveSignal'; }
+        if (primitive !== null) {
+          const loc = node.loc ? { line: node.loc.start.line, column: node.loc.start.column + 1 } : { line: 0, column: 0 };
+          if (!suppressedLines.has(loc.line)) {
+            keyedLiteralInits.push({ primitive, key: arg1.value, initial: arg0.value, loc });
+          }
+        }
+      }
+    }
+
     // Reactive-callback bare-identifier detection (callback IS an identifier,
     // not a function expression).
     function detectBareIdent(arg, _reason) {
@@ -403,7 +519,7 @@ function analyzeFile(file) {
 
   walk(ast, null);
 
-  return { file, imports, exports, funcs, reactiveLocalEntries };
+  return { file, imports, exports, funcs, reactiveLocalEntries, keyedLiteralInits };
 }
 
 // === Cross-file resolution + propagation ===================================
@@ -511,6 +627,7 @@ function report(index, reachable) {
       const reason = reachable.get(key);
       for (const hit of fn.unkeyedCalls) {
         findings.push({
+          kind: 'unkeyed-in-reactive-callback',
           file: relPath(file),
           line: hit.loc.line,
           column: hit.loc.column,
@@ -521,10 +638,63 @@ function report(index, reachable) {
       }
     }
   }
+  for (const f of findDuplicateKeyInitialMismatches(index)) {
+    findings.push(f);
+  }
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
   return findings;
 }
 
+// Cross-file aggregation. Groups every `signal(literal, 'literal-key')` and
+// `liveSignal(literal, 'literal-name')` call by (primitive, key) and emits one
+// finding per call site when the group has disagreeing initial values. The
+// two primitives are grouped separately because their collision namespaces
+// differ: liveSignal names are global; regular signal keys are per-computed
+// (but two calls with the same literal key landing in the same outer computed
+// from different files is the bug shape we want to surface).
+function findDuplicateKeyInitialMismatches(index) {
+  const groups = new Map(); // `${primitive}::${key}` -> Array<{ file, loc, initial, primitive, key }>
+  for (const [file, rec] of index) {
+    if (!rec.keyedLiteralInits) { continue; }
+    for (const entry of rec.keyedLiteralInits) {
+      const groupKey = `${entry.primitive}::${entry.key}`;
+      let group = groups.get(groupKey);
+      if (group === undefined) { group = []; groups.set(groupKey, group); }
+      group.push({ ...entry, file });
+    }
+  }
+  const out = [];
+  for (const [, group] of groups) {
+    if (group.length < 2) { continue; }
+    // Find any disagreement among initials. Object.is for primitive comparison.
+    const first = group[0].initial;
+    const allMatch = group.every(e => Object.is(e.initial, first));
+    if (allMatch) { continue; }
+    // Disagreement: emit one finding per call site, cross-referencing the group.
+    const others = group.map(e => `${relPath(e.file)}:${e.loc.line}:${e.loc.column} (initial=${formatInitial(e.initial)})`);
+    for (const entry of group) {
+      out.push({
+        kind: 'duplicate-key-initial-mismatch',
+        file: relPath(entry.file),
+        line: entry.loc.line,
+        column: entry.loc.column,
+        primitive: entry.primitive,
+        key: entry.key,
+        initial: entry.initial,
+        groupSize: group.length,
+        otherSites: others.filter(s => !s.startsWith(`${relPath(entry.file)}:${entry.loc.line}:${entry.loc.column}`)),
+      });
+    }
+  }
+  return out;
+}
+
+function formatInitial(v) {
+  if (v === null) { return 'null'; }
+  if (typeof v === 'string') { return JSON.stringify(v); }
+  return String(v);
+}
+
 // === Public API ============================================================
 
 // Programmatic entry. Returns { findings, fileCount }. Pure (no process exit,
@@ -548,11 +718,17 @@ 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'
+    + 'Cross-file static analyzer for two classes of kensington reactive bugs:\n'
+    + '  1. Unkeyed signal()/computed()/.transform() inside helpers reachable\n'
+    + '     from a reactive callback anywhere in the project.\n'
+    + '  2. Duplicate signal(initial, KEY) or liveSignal(initial, NAME) calls\n'
+    + '     with the same literal key/name but different primitive initials.\n'
+    + '\n'
+    + 'This binary is shipped for early testing only. The CLI surface, output\n'
+    + 'format, detection rules, and even its presence in the package may change\n'
+    + 'without notice. Do not build tooling on top of it until it appears in\n'
+    + 'README.md. See the comment header in bin/check-reactive.js for the\n'
+    + 'canonical description until then.\n'
     + '\n'
     + 'Usage:\n'
     + '  kensington-check-reactive [paths...]            scan and print findings\n'
@@ -560,6 +736,9 @@ function printHelp() {
     + '  kensington-check-reactive [paths...] --quiet    exit code only, no output\n'
     + '  kensington-check-reactive --help                this message\n'
     + '\n'
+    + 'Paths default to the current working directory. Suppress per call site\n'
+    + 'with `// kensington-check-reactive-ignore` on or above the line.\n'
+    + '\n'
     + 'Exits 0 on no findings, 1 on findings, 2 on script error.\n',
   );
 }
@@ -594,9 +773,17 @@ function main() {
       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`,
-        );
+        if (f.kind === 'duplicate-key-initial-mismatch') {
+          const others = f.otherSites.length ? ` (other sites: ${f.otherSites.join('; ')})` : '';
+          process.stdout.write(
+            `${f.file}:${f.line}:${f.column}: warning: ${f.primitive}(initial=${formatInitial(f.initial)}, '${f.key}') `
+            + `disagrees with other call sites' initial for the same key${others}\n`,
+          );
+        } else {
+          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`);
     }

package/index.js

@@ -24,6 +24,7 @@ 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';
+import noAsyncSet from './rules/no-async-set.js';
 
 const plugin = {
   meta: { name: 'eslint-plugin-kensington' },
@@ -54,6 +55,7 @@ const plugin = {
     'consistent-content-layout': consistentContentLayout,
     'no-helper-function-trap': noHelperFunctionTrap,
     'require-reactive-key': requireReactiveKey,
+    'no-async-set': noAsyncSet,
   },
   configs: {},
 };
@@ -72,12 +74,12 @@ plugin.configs.recommended = {
     'kensington/no-new-computed-in-effect': 'error',
     'kensington/no-new-signal-in-computed': 'error',
     'kensington/no-unsafe-literal': 'error',
-    'kensington/no-new-computed-in-computed': 'warn',
     'kensington/no-effect-in-effect': 'error',
     'kensington/no-async-effect': 'error',
     'kensington/no-async-computed': 'error',
     'kensington/no-out-of-scope-reactive-reference': 'warn',
     'kensington/no-helper-function-trap': 'warn',
+    'kensington/no-async-set': 'error',
   },
 };
 
@@ -87,13 +89,19 @@ plugin.configs.strict = {
     ...plugin.configs.recommended.rules,
     // Promote every reactive-correctness warning to error. Strict mode trades
     // tolerance of false positives for zero silent misses.
+    //
+    // Note: require-reactive-key is NOT included. The rule flags every unkeyed
+    // signal()/computed()/.transform() call site including at module scope,
+    // which generates mechanical retrofits that don't catch real bugs (keys are
+    // no-ops at module scope). Opt in explicitly with
+    //   'kensington/require-reactive-key': 'error'
+    // if you want refactor-safety enforcement (a later lift into a reactive
+    // scope finds the key already in place).
     '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,6 +1,6 @@
 {
   "name": "kensington-eslint-plugin",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "ESLint rules for kensington signal correctness",
   "type": "module",
   "main": "index.js",
@@ -8,7 +8,7 @@
     "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 tests/no-helper-function-trap.test.js tests/require-reactive-key.test.js tests/check-reactive.test.js"
+    "test": "node --test tests/*.test.js"
   },
   "peerDependencies": {
     "eslint": ">=9"

package/rules/_utils.js

@@ -1,5 +1,19 @@
 // Shared helpers used by the formatting rules.
 
+// Module specifier paths that export `liveSignal`. Imports from any of these
+// resolve to the same function. Rules that look for reactive-primitive creation
+// inside reactive scopes must recognize all three so liveSignal lazy-registry
+// traps surface the same way plain signal traps do.
+export const KENSINGTON_LIVE_SOURCES = new Set([
+  'kensington/live',
+  'kensington/live/client',
+  'kensington/live/server',
+]);
+
+export function isKensingtonLiveSource(value) {
+  return KENSINGTON_LIVE_SOURCES.has(value);
+}
+
 // HTML boolean attributes per the WHATWG HTML spec. Kebab-case form is the
 // attribute name; camelCase keys (e.g. `formNoValidate`) also match because the
 // tag-call check looks at the key text after camel-to-kebab conversion.

package/rules/no-async-set.js

@@ -0,0 +1,50 @@
+// Reports `.set(async fn)` on any signal. An async updater returns a Promise
+// instead of the next value, which:
+//   - For a regular signal, stores the Promise object as the value. Reads
+//     return the Promise; downstream code that expects T sees a Thenable.
+//   - For a liveSignal, serializes the Promise to "{}" on the wire,
+//     corrupting every subscriber's view of the value.
+//
+// The async-fn pattern is almost always a sign of "I want to do async work
+// then update the signal." The right shape is to await the async work
+// first, THEN call `.set(value)` with the resolved value. Or use
+// effect()/setTimeout to schedule the write.
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'disallow passing an async function to .set() on a signal. The Promise return corrupts the stored value (especially across the wire for liveSignals).',
+    },
+    messages: {
+      noAsyncSet:
+        '.set(async fn) is almost always a bug. The function returns a Promise instead of the next value, '
+        + 'which gets stored as-is (and serializes to "{}" on the wire for liveSignals). '
+        + 'Await the async work first, then call `.set(resolvedValue)`. Or use effect() to schedule the write.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+        if (
+          callee.type !== 'MemberExpression'
+          || callee.computed
+          || callee.property.type !== 'Identifier'
+          || callee.property.name !== 'set'
+        ) { return; }
+        const arg = node.arguments[0];
+        if (arg === undefined) { return; }
+        if (
+          (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression')
+          && arg.async === true
+        ) {
+          context.report({ node: arg, messageId: 'noAsyncSet' });
+        }
+      },
+    };
+  },
+};

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

@@ -8,6 +8,13 @@
 // from inside a computed/transform/mapFn callback, so at runtime the call runs
 // in a reactive scope).
 //
+// Also reports `liveSignal()` calls inside helpers reachable from a reactive
+// callback. liveSignal's second argument is always a name (not optional), so
+// the rule fires regardless of args length. The trap is the same shape as the
+// plain signal case but in the liveSignal namespace: the first call for a given
+// name creates the transport entry inside the reactive scope.
+import { isKensingtonLiveSource } from './_utils.js';
+//
 // Single-file analysis only. We track only named top-level functions; nested
 // anonymous helpers are out of scope (the lexical rule already covers them).
 //
@@ -42,12 +49,20 @@ export default {
         + '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.',
+      helperFunctionTrapLive:
+        'liveSignal() call inside `{{fnName}}`, which is called from a reactive '
+        + 'callback in this file ({{reason}}). The first call for this name creates '
+        + 'the transport entry inside the surrounding reactive scope at runtime. '
+        + 'Eager-seed the liveSignal outside the reactive scope (queueMicrotask is '
+        + 'the canonical pattern). See agent-docs/live-signals.md → "liveSignal '
+        + 'inside a reactive callback".',
     },
     schema: [],
   },
 
   create(context) {
     const signalNames = new Set();
+    const liveSignalNames = new Set();
     const computedNames = new Set();
     const effectNames = new Set();
 
@@ -135,16 +150,24 @@ export default {
 
     return {
       ImportDeclaration(node) {
-        if (node.source.value !== 'kensington') {
+        if (node.source.value === 'kensington') {
+          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); }
+          }
           return;
         }
-        for (const spec of node.specifiers) {
-          if (spec.type !== 'ImportSpecifier') {
-            continue;
+        if (isKensingtonLiveSource(node.source.value)) {
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ImportSpecifier') {
+              continue;
+            }
+            if (spec.imported.name === 'liveSignal') { liveSignalNames.add(spec.local.name); }
           }
-          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); }
         }
       },
 
@@ -213,9 +236,13 @@ export default {
         const fn = currentFn();
         if (fn && !fn.anonymous) {
           if (callee.type === 'Identifier' && signalNames.has(callee.name) && !hasKey) {
-            fn.unkeyedCalls.push({ node, primitive: 'signal' });
+            fn.unkeyedCalls.push({ node, primitive: 'signal', isLive: false });
+          } else if (callee.type === 'Identifier' && liveSignalNames.has(callee.name)) {
+            // liveSignal's second arg is a name (always present); flag it
+            // regardless of args length. The trap is structural, not key-presence.
+            fn.unkeyedCalls.push({ node, primitive: 'liveSignal', isLive: true });
           } else if (callee.type === 'Identifier' && computedNames.has(callee.name) && !hasKey) {
-            fn.unkeyedCalls.push({ node, primitive: 'computed' });
+            fn.unkeyedCalls.push({ node, primitive: 'computed', isLive: false });
           } else if (
             callee.type === 'MemberExpression'
             && !callee.computed
@@ -223,7 +250,7 @@ export default {
             && callee.property.name === 'transform'
             && !hasKey
           ) {
-            fn.unkeyedCalls.push({ node, primitive: '.transform' });
+            fn.unkeyedCalls.push({ node, primitive: '.transform', isLive: false });
           } else if (callee.type === 'Identifier') {
             fn.callees.add(callee.name);
           }
@@ -262,7 +289,7 @@ export default {
           for (const hit of rec.unkeyedCalls) {
             context.report({
               node: hit.node,
-              messageId: 'helperFunctionTrap',
+              messageId: hit.isLive ? 'helperFunctionTrapLive' : 'helperFunctionTrap',
               data: { primitive: hit.primitive, fnName: name, reason },
             });
           }

package/rules/no-new-computed-in-computed.js

@@ -1,23 +1,33 @@
-// Reports unkeyed computed() or .transform() calls inside a computed() callback. Each
-// recompute creates a new orphaned derived signal with no cleanup path. Pass a stable key
-// as the second argument (e.g. computed(fn, item.id) or sig.transform(fn, item.id)) to
-// scope the derived signal to the surrounding computed so the same instance is reused
-// across re-runs.
+// Deprecated. The kensington runtime now defers the computed-in-computed and
+// transform-in-computed warnings to subscription time and only fires when a user
+// effect or user computed subscribes to the inner. Inline consumption as an attribute,
+// class, text, or prop slot is silent by design. That change makes this rule's
+// purely-lexical flag redundant. Escape cases are already covered by
+// `no-out-of-scope-reactive-reference` (which uses a full escape classifier).
+// The `strict` config's `require-reactive-key` still catches every unkeyed call site
+// for teams that want refactor-safety enforcement.
+//
+// The rule remains registered so existing configs that reference it don't error.
+// Removed from the `recommended` and `strict` configs.
 export default {
   meta: {
     type: 'suggestion',
+    deprecated: true,
+    replacedBy: ['no-out-of-scope-reactive-reference'],
     docs: {
-      description: 'require a stable key for computed() and .transform() calls inside a computed() body',
+      description: 'require a stable key for computed() and .transform() calls inside a computed() body (deprecated. see no-out-of-scope-reactive-reference)',
     },
     messages: {
       noNewComputedInComputed:
-        'computed() called inside a computed() body without a key. The DOM node will be replaced ' +
-        'on every outer re-render. Pass a stable key as the second argument ' +
-        '(e.g. computed(fn, item.id)) so the same instance is reused across computed re-runs.',
+        'computed() called inside a computed() body without a key. The runtime warns only when ' +
+        'a user effect or user computed subscribes to the inner. Inline consumption as an ' +
+        'attribute, class, or text slot is silent. Pass a stable key when the inner is held by ' +
+        'user subscribers (e.g. computed(fn, item.id)).',
       noNewTransformInComputed:
-        '.transform() called inside a computed() body without a key. The DOM node will be replaced ' +
-        'on every outer re-render. Pass a stable key as the second argument ' +
-        '(e.g. sig.transform(fn, item.id)) so the same instance is reused across computed re-runs.',
+        '.transform() called inside a computed() body without a key. The runtime warns only when ' +
+        'a user effect or user computed subscribes to the inner. Inline consumption as an ' +
+        'attribute, class, or text slot is silent. Pass a stable key when the inner is held by ' +
+        'user subscribers (e.g. sig.transform(fn, item.id)).',
     },
   },
 

package/rules/no-new-signal-in-computed.js

@@ -3,11 +3,18 @@
 // resets to the initial value on every outer re-render and DOM identity is not preserved.
 // Pass a stable key as the second argument (e.g. signal(false, item.id)) to scope the
 // signal to the surrounding computed so the same instance is reused across re-runs.
+//
+// Also reports liveSignal() calls inside a computed() body. liveSignal always has a name
+// as its second argument so the key-presence check doesn't apply, but the lazy-registry
+// creation on first sight still happens inside the reactive scope and trips the runtime
+// warning. The fix is to eager-seed via queueMicrotask outside the reactive scope.
+import { isKensingtonLiveSource } from './_utils.js';
+
 export default {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'require a stable key for signal() calls inside a computed() body',
+      description: 'require a stable key for signal() and flag liveSignal() inside a computed() body',
     },
     messages: {
       noNewSignalInComputed:
@@ -15,11 +22,17 @@ export default {
         'every outer re-render. Pass a stable key as the second argument ' +
         '(e.g. signal(initial, item.id)) so the same signal instance is reused across ' +
         'computed re-runs.',
+      noLiveSignalInComputed:
+        'liveSignal() called inside a computed() body. The first call for this name creates '
+        + 'the transport entry inside the reactive scope, tripping the runtime warning. '
+        + 'Eager-seed the liveSignal outside the reactive scope (queueMicrotask is the canonical '
+        + 'pattern). See agent-docs/live-signals.md → "liveSignal inside a reactive callback".',
     },
   },
 
   create(context) {
     const signalNames = new Set();
+    const liveSignalNames = new Set();
     const computedNames = new Set();
     const effectNames = new Set();
     // Each entry is 'computed', 'effect', or 'other' — innermost frame is last.
@@ -27,12 +40,20 @@ export default {
 
     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); }
+        if (node.source.value === 'kensington') {
+          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); }
+          }
+          return;
+        }
+        if (isKensingtonLiveSource(node.source.value)) {
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ImportSpecifier') { continue; }
+            if (spec.imported.name === 'liveSignal') { liveSignalNames.add(spec.local.name); }
+          }
         }
       },
 
@@ -60,16 +81,22 @@ export default {
       },
 
       CallExpression(node) {
-        if (
-          node.callee.type !== 'Identifier' ||
-          !signalNames.has(node.callee.name)
-        ) { return; }
-        // A key was supplied — this is the intended pattern, not a problem.
-        if (node.arguments.length >= 2) { return; }
+        if (node.callee.type !== 'Identifier') { return; }
+        const isPlainSignal = signalNames.has(node.callee.name);
+        const isLiveSignal = liveSignalNames.has(node.callee.name);
+        if (!isPlainSignal && !isLiveSignal) { return; }
+        // Plain signal: a second-arg key means the call is keyed correctly.
+        // liveSignal: the second arg is always a name, but the lazy-registry
+        // creation still happens inside the reactive scope on first sight,
+        // so the trap applies regardless of args length.
+        if (isPlainSignal && node.arguments.length >= 2) { return; }
 
         for (let i = fnStack.length - 1; i >= 0; i--) {
           if (fnStack[i] === 'computed') {
-            context.report({ node, messageId: 'noNewSignalInComputed' });
+            context.report({
+              node,
+              messageId: isLiveSignal ? 'noLiveSignalInComputed' : 'noNewSignalInComputed',
+            });
             return;
           }
           if (fnStack[i] === 'effect') { return; }

package/rules/no-new-signal-in-effect.js

@@ -1,34 +1,51 @@
-// Reports signal() called inside an effect() callback. Each effect run creates a new
-// orphaned signal with no cleanup path, which is almost always a bug — the signal
-// should be declared outside the effect.
+// Reports signal() or liveSignal() called inside an effect() callback. Each
+// effect run creates a new orphaned signal (or a new transport entry, for
+// liveSignal) with no cleanup path, which is almost always a bug. The
+// primitive should be declared outside the effect.
+import { isKensingtonLiveSource } from './_utils.js';
+
 export default {
   meta: {
     type: 'problem',
     docs: {
-      description: 'disallow creating a new signal() inside an effect() body',
+      description: 'disallow creating a new signal() or liveSignal() inside an effect() body',
     },
     messages: {
       noNewSignalInEffect:
         'signal() called inside an effect() body. Each effect run creates a new orphaned signal. ' +
         'Declare the signal outside the effect instead.',
+      noNewLiveSignalInEffect:
+        'liveSignal() called inside an effect() body. Each effect run looks up (and on first '
+        + 'sight, creates) the transport entry inside the effect\'s reactive scope. Declare the '
+        + 'liveSignal outside the effect, or eager-seed it via queueMicrotask outside the '
+        + 'reactive scope. See agent-docs/live-signals.md → "liveSignal inside a reactive callback".',
     },
   },
 
   create(context) {
     const effectNames = new Set();
     const signalNames = new Set();
+    const liveSignalNames = new Set();
     const computedNames = new Set();
     // Each entry is 'effect', 'computed', or 'other'.
     const fnStack = [];
 
     return {
       ImportDeclaration(node) {
-        if (node.source.value !== 'kensington') { return; }
-        for (const spec of node.specifiers) {
-          if (spec.type !== 'ImportSpecifier') { continue; }
-          if (spec.imported.name === 'effect') { effectNames.add(spec.local.name); }
-          if (spec.imported.name === 'signal') { signalNames.add(spec.local.name); }
-          if (spec.imported.name === 'computed') { computedNames.add(spec.local.name); }
+        if (node.source.value === 'kensington') {
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ImportSpecifier') { continue; }
+            if (spec.imported.name === 'effect') { effectNames.add(spec.local.name); }
+            if (spec.imported.name === 'signal') { signalNames.add(spec.local.name); }
+            if (spec.imported.name === 'computed') { computedNames.add(spec.local.name); }
+          }
+          return;
+        }
+        if (isKensingtonLiveSource(node.source.value)) {
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ImportSpecifier') { continue; }
+            if (spec.imported.name === 'liveSignal') { liveSignalNames.add(spec.local.name); }
+          }
         }
       },
 
@@ -56,14 +73,17 @@ export default {
       },
 
       CallExpression(node) {
-        if (
-          node.callee.type !== 'Identifier' ||
-          !signalNames.has(node.callee.name)
-        ) { return; }
+        if (node.callee.type !== 'Identifier') { return; }
+        const isPlainSignal = signalNames.has(node.callee.name);
+        const isLiveSignal = liveSignalNames.has(node.callee.name);
+        if (!isPlainSignal && !isLiveSignal) { return; }
 
         for (let i = fnStack.length - 1; i >= 0; i--) {
           if (fnStack[i] === 'effect') {
-            context.report({ node, messageId: 'noNewSignalInEffect' });
+            context.report({
+              node,
+              messageId: isLiveSignal ? 'noNewLiveSignalInEffect' : 'noNewSignalInEffect',
+            });
             return;
           }
           if (fnStack[i] === 'computed') { return; }