kensington-eslint-plugin 0.3.2 → 0.4.0

package/README.md

@@ -96,9 +96,10 @@ Because this is a standard ESLint plugin, it works anywhere ESLint runs with no
 | [`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) | Disallow creating a new `signal()` inside a `computed()` 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) | Disallow creating a new `computed()` inside a `computed()` body | 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 |
@@ -325,18 +326,86 @@ t.literal(userContent);
 
 ### `no-new-computed-in-computed`
 
-Creating `computed()` inside a `computed()` body creates a new orphaned derived signal on every recompute.
+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
-// Bad
-const outer = computed(() => {
-  const inner = computed(() => count.get() * 2); // error. Orphaned every recompute.
-  return inner.get() + 1;
-});
+// Bad. New instance on every outer re-run, inner state lost
+const list = computed(() =>
+  items.get().map(item => {
+    const cls = computed(() => filter.get() === item.cat ? 'on' : ''); // warn
+    return t.li({ dataKey: item.id, class: cls }, item.name);
+  })
+);
 
-// Good
-const inner = computed(() => count.get() * 2);
-const outer = computed(() => inner.get() + 1);
+// Bad. Same problem with .transform()
+const list = computed(() =>
+  items.get().map(item =>
+    t.li({ dataKey: item.id, class: filter.transform(f => f === item.cat ? 'on' : '') }, item.name) // warn
+  )
+);
+
+// Good. Keyed computed
+const list = computed(() =>
+  items.get().map(item =>
+    t.li({ dataKey: item.id, class: computed(() => filter.get() === item.cat ? 'on' : '', item.id) }, item.name)
+  )
+);
+
+// Good. Keyed transform
+const list = computed(() =>
+  items.get().map(item =>
+    t.li({ dataKey: item.id, class: filter.transform(f => f === item.cat ? 'on' : '', item.id) }, item.name)
+  )
+);
+
+// Also good. Declare outside when fn has no per-item closure
+const upper = computed(() => name.get().toUpperCase());
+const outer = computed(() => upper.get() + '!');
+```
+
+---
+
+### `no-out-of-scope-reactive-reference`
+
+A reactive primitive (`signal()`, `computed()`, or `.transform()`) created inside a `computed()` body is owned by the surrounding computed. The owner can stop it at any time. When a re-run doesn't access the key, the instance is swept from the registry and stopped. Any reference held outside the owner's scope silently drops subscribers and produces out-of-sync state.
+
+Two inline-consumption patterns are safe and allowed:
+
+1. The result is consumed by an immediate method chain (`.get()`, `.transform()`, `.toString()`, etc.). The chain consumes the instance; the instance itself never escapes.
+2. The result is passed directly to a tag call as content or an attribute value. The DOM binding effect created by `toElement()` is part of the owner's own render cycle, so its lifetime is tied to the DOM.
+
+```js
+// Bad. Instance escapes via module-level cache; external code can hold a dead signal
+const editingSignals = new Map();
+const list = computed(() =>
+  items.get().map(item => {
+    const editing = signal(false, item.id);
+    editingSignals.set(item.id, editing); // warn
+    return t.li({ dataKey: item.id, class: editing.transform(v => v ? 'on' : '') }, item.name);
+  })
+);
+
+// Bad. Instance returned from map; consumers see a stale signal after a sweep
+const list = computed(() =>
+  items.get().map(item => computed(() => item.v * 2, item.id)) // warn
+);
+
+// Good. Consumed via method chain
+const list = computed(() =>
+  items.get().map(item =>
+    computed(() => filter.get() === item.cat ? 'on' : '', item.id).get()
+  )
+);
+
+// Good. Passed directly to a tag; DOM binding owns lifetime
+const list = computed(() =>
+  items.get().map(item =>
+    t.li({
+      dataKey: item.id,
+      class: computed(() => filter.get() === item.cat ? 'on' : '', item.id),
+    }, item.name)
+  )
+);
 ```
 
 ---
@@ -470,7 +539,7 @@ Auto-fixable when the group's members are contiguous in the source. Non-contiguo
 
 ### `prefer-array-for-multiline-content`
 
-Mirrors what `html-to-kensington` emits: when a tag's content occupies its own line(s) — separated from both the opening and closing paren — it goes in an array, even when it's the only item. The array form makes line-by-line edits easier (no need to add `[ ]` when adding a sibling).
+Mirrors what `html-to-kensington` emits: when a tag's content occupies its own line(s). Separated from both the opening and closing paren. It goes in an array, even when it's the only item. The array form makes line-by-line edits easier (no need to add `[ ]` when adding a sibling).
 
 ```js
 // Bad
@@ -483,7 +552,7 @@ t.div({ class: 'x' }, [
   t.p('only'),
 ]);
 
-// Also good — content trails on the closing-paren line, no array needed
+// Also good. Content trails on the closing-paren line, no array needed
 t.a({
   href: 'https://example.com',
   target: '_blank',

package/index.js

@@ -11,6 +11,7 @@ import noNewSignalInComputed from './rules/no-new-signal-in-computed.js';
 import noUnsafeLiteral from './rules/no-unsafe-literal.js';
 import noNewComputedInComputed from './rules/no-new-computed-in-computed.js';
 import noEffectInEffect from './rules/no-effect-in-effect.js';
+import noOutOfScopeReactiveReference from './rules/no-out-of-scope-reactive-reference.js';
 import noAsyncEffect from './rules/no-async-effect.js';
 import noAsyncComputed from './rules/no-async-computed.js';
 import preferBooleanAttributeTrue from './rules/prefer-boolean-attribute-true.js';
@@ -38,6 +39,7 @@ const plugin = {
     'no-unsafe-literal': noUnsafeLiteral,
     'no-new-computed-in-computed': noNewComputedInComputed,
     'no-effect-in-effect': noEffectInEffect,
+    'no-out-of-scope-reactive-reference': noOutOfScopeReactiveReference,
     'no-async-effect': noAsyncEffect,
     'no-async-computed': noAsyncComputed,
     'prefer-boolean-attribute-true': preferBooleanAttributeTrue,
@@ -66,10 +68,11 @@ 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': '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',
   },
 };
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "kensington-eslint-plugin",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "ESLint rules for kensington signal correctness",
   "type": "module",
   "main": "index.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"
+    "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"
   },
   "peerDependencies": {
     "eslint": ">=9"

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

@@ -1,22 +1,30 @@
-// Reports computed() called inside a computed() callback. Each recompute creates a new
-// orphaned derived signal with no cleanup path — declare the computed outside.
+// 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.
 export default {
   meta: {
-    type: 'problem',
+    type: 'suggestion',
     docs: {
-      description: 'disallow creating a new computed() inside a computed() body',
+      description: 'require a stable key for computed() and .transform() calls inside a computed() body',
     },
     messages: {
       noNewComputedInComputed:
-        'computed() called inside a computed() body. Each recompute creates a new orphaned derived signal. ' +
-        'Declare the computed outside instead.',
+        '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.',
+      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.',
     },
   },
 
   create(context) {
     const computedNames = new Set();
     const effectNames = new Set();
-    // Each entry is 'computed', 'effect', or 'other' — innermost frame is last.
+    // Each entry is 'computed', 'effect', or 'other'. Innermost frame is last.
     const fnStack = [];
 
     return {
@@ -53,14 +61,28 @@ export default {
       },
 
       CallExpression(node) {
+        let messageId;
         if (
-          node.callee.type !== 'Identifier' ||
-          !computedNames.has(node.callee.name)
-        ) { return; }
+          node.callee.type === 'Identifier'
+          && computedNames.has(node.callee.name)
+        ) {
+          messageId = 'noNewComputedInComputed';
+        } else if (
+          node.callee.type === 'MemberExpression'
+          && !node.callee.computed
+          && node.callee.property.type === 'Identifier'
+          && node.callee.property.name === 'transform'
+        ) {
+          messageId = 'noNewTransformInComputed';
+        } else {
+          return;
+        }
+        // A key was supplied. This is the intended keyed pattern, not a problem.
+        if (node.arguments.length >= 2) { return; }
 
         for (let i = fnStack.length - 1; i >= 0; i--) {
           if (fnStack[i] === 'computed') {
-            context.report({ node, messageId: 'noNewComputedInComputed' });
+            context.report({ node, messageId });
             return;
           }
           if (fnStack[i] === 'effect') { return; }

package/rules/no-out-of-scope-reactive-reference.js

@@ -0,0 +1,160 @@
+// Reports reactive primitives (signal, computed, .transform) that are created inside a
+// `computed()` callback but escape its scope. Assigned to a variable that survives the
+// callback, returned for external use, captured by module-level state, etc. Even with a
+// stable key, the owning computed can stop the inner instance at any time (when its key
+// isn't accessed during a re-run), so external references silently drop subscribers and
+// produce out-of-sync state.
+//
+// Two consumption patterns are safe and allowed:
+//   1. Calling .get() immediately. Extracts the value as a plain JS value
+//   2. Passing the result directly to a tag call as content or an attribute value. 
+//      the DOM-binding effect created by toElement() is flagged as internal at runtime
+//      and is part of the owner's own render cycle, so its lifetime is tied to the DOM.
+
+// Returns true when `node` is being used as an argument to a tag-builder method call
+// (t.li(node), t.div({ class: node }), t.span([..., node, ...])). Recurses through
+// containing object/array literals to handle attribute objects and content arrays.
+function isTagArgument(node) {
+  let current = node.parent;
+  let inner = node;
+  while (current) {
+    if (current.type === 'CallExpression') {
+      const c = current.callee;
+      if (
+        c.type === 'MemberExpression'
+        && !c.computed
+        && c.object.type === 'Identifier'
+        && c.property.type === 'Identifier'
+        && /^[a-z]/.test(c.property.name)
+      ) {
+        if (current.arguments.includes(inner)) { return true; }
+      }
+      return false;
+    }
+    if (
+      current.type === 'ArrayExpression'
+      || current.type === 'ObjectExpression'
+      || current.type === 'Property'
+      || current.type === 'SpreadElement'
+    ) {
+      inner = current;
+      current = current.parent;
+      continue;
+    }
+    return false;
+  }
+  return false;
+}
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'disallow referencing a signal/computed/transform from outside the computed scope where it was created',
+    },
+    messages: {
+      noOutOfScopeSignal:
+        'signal() created inside a computed() body is referenced out of scope. ' +
+        'The instance is owned by the surrounding computed and may be stopped at any time. ' +
+        'Consume inline: call .get() on it, or pass it directly to a tag.',
+      noOutOfScopeComputed:
+        'computed() created inside a computed() body is referenced out of scope. ' +
+        'The instance is owned by the surrounding computed and may be stopped at any time. ' +
+        'Consume inline: call .get() on it, or pass it directly to a tag.',
+      noOutOfScopeTransform:
+        '.transform() called inside a computed() body is referenced out of scope. ' +
+        'The instance is owned by the surrounding computed and may be stopped at any time. ' +
+        'Consume inline: call .get() on it, or pass it directly to a tag.',
+    },
+  },
+
+  create(context) {
+    const signalNames = new Set();
+    const computedNames = new Set();
+    const effectNames = new Set();
+    // Each entry is 'computed', 'effect', or 'other'. Innermost frame is last.
+    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 === '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(ArrowFunctionExpression, FunctionExpression)'(node) {
+        const { parent } = node;
+        if (
+          parent.type === 'CallExpression' &&
+          parent.arguments[0] === node &&
+          parent.callee.type === 'Identifier'
+        ) {
+          if (computedNames.has(parent.callee.name)) {
+            fnStack.push('computed');
+            return;
+          }
+          if (effectNames.has(parent.callee.name)) {
+            fnStack.push('effect');
+            return;
+          }
+        }
+        fnStack.push('other');
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression):exit'() {
+        fnStack.pop();
+      },
+
+      CallExpression(node) {
+        let messageId;
+        if (
+          node.callee.type === 'Identifier'
+          && signalNames.has(node.callee.name)
+        ) {
+          messageId = 'noOutOfScopeSignal';
+        } else if (
+          node.callee.type === 'Identifier'
+          && computedNames.has(node.callee.name)
+        ) {
+          messageId = 'noOutOfScopeComputed';
+        } else if (
+          node.callee.type === 'MemberExpression'
+          && !node.callee.computed
+          && node.callee.property.type === 'Identifier'
+          && node.callee.property.name === 'transform'
+        ) {
+          messageId = 'noOutOfScopeTransform';
+        } else {
+          return;
+        }
+
+        // Must be inside a computed callback. Inside an effect is a different concern.
+        let insideComputed = false;
+        for (let i = fnStack.length - 1; i >= 0; i--) {
+          if (fnStack[i] === 'computed') { insideComputed = true; break; }
+          if (fnStack[i] === 'effect') { return; }
+        }
+        if (!insideComputed) { return; }
+
+        // Safe: result is consumed immediately by a method chain. Call.get(),
+        // call.transform(...), call.toString(), etc. The chain consumes the instance;
+        // the instance itself never escapes the scope.
+        const { parent } = node;
+        if (
+          parent.type === 'MemberExpression'
+          && !parent.computed
+          && parent.object === node
+        ) { return; }
+
+        // Safe: passed directly to a tag call as content or an attribute value.
+        if (isTagArgument(node)) { return; }
+
+        context.report({ node, messageId });
+      },
+    };
+  },
+};