kensington-eslint-plugin 0.1.2

package/rules/no-ignored-effect-return.js

@@ -0,0 +1,60 @@
+// Reports effect() calls whose return value is discarded inside a function body.
+// The return value is { pause, resume, stop } — dropping it makes cleanup impossible,
+// causing subscription leaks when the surrounding function runs more than once.
+// Module-level effects are intentionally long-lived and are not flagged.
+
+function isInsideFunction(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === 'FunctionDeclaration' ||
+      current.type === 'FunctionExpression' ||
+      current.type === 'ArrowFunctionExpression'
+    ) { return true; }
+    current = current.parent;
+  }
+  return false;
+}
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'require capturing the return value of effect() when called inside a function',
+    },
+    messages: {
+      noIgnoredEffectReturn:
+        'The return value of effect() is discarded. Inside a function, capture it so you can call ' +
+        '.stop() for cleanup — otherwise each call creates a new subscription that can never be removed.',
+    },
+  },
+
+  create(context) {
+    const effectNames = 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 === 'effect') { effectNames.add(spec.local.name); }
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'Identifier' ||
+          !effectNames.has(node.callee.name)
+        ) { return; }
+
+        // Return value is used unless the call is a bare ExpressionStatement.
+        if (node.parent.type !== 'ExpressionStatement') { return; }
+
+        // Only flag inside a function body — module-level effects are intentional.
+        if (!isInsideFunction(node)) { return; }
+
+        context.report({ node, messageId: 'noIgnoredEffectReturn' });
+      },
+    };
+  },
+};

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

@@ -0,0 +1,71 @@
+// Reports computed() called inside a computed() callback. Each recompute creates a new
+// orphaned derived signal with no cleanup path — declare the computed outside.
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow creating a new computed() 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.',
+    },
+  },
+
+  create(context) {
+    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 === '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) {
+        if (
+          node.callee.type !== 'Identifier' ||
+          !computedNames.has(node.callee.name)
+        ) { return; }
+
+        for (let i = fnStack.length - 1; i >= 0; i--) {
+          if (fnStack[i] === 'computed') {
+            context.report({ node, messageId: 'noNewComputedInComputed' });
+            return;
+          }
+          if (fnStack[i] === 'effect') { return; }
+        }
+      },
+    };
+  },
+};

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

@@ -0,0 +1,71 @@
+// Reports computed() called inside an effect() callback. Each effect run creates a new
+// orphaned derived signal with no cleanup path — declare the computed outside the effect.
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow creating a new computed() inside an effect() body',
+    },
+    messages: {
+      noNewComputedInEffect:
+        'computed() called inside an effect() body. Each effect run creates a new orphaned derived signal. ' +
+        'Declare the computed outside the effect instead.',
+    },
+  },
+
+  create(context) {
+    const effectNames = new Set();
+    const computedNames = new Set();
+    // Each entry is 'effect', 'computed', 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 === 'effect') { effectNames.add(spec.local.name); }
+          if (spec.imported.name === 'computed') { computedNames.add(spec.local.name); }
+        }
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression)'(node) {
+        const { parent } = node;
+        if (
+          parent.type === 'CallExpression' &&
+          parent.arguments[0] === node &&
+          parent.callee.type === 'Identifier'
+        ) {
+          if (effectNames.has(parent.callee.name)) {
+            fnStack.push('effect');
+            return;
+          }
+          if (computedNames.has(parent.callee.name)) {
+            fnStack.push('computed');
+            return;
+          }
+        }
+        fnStack.push('other');
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression):exit'() {
+        fnStack.pop();
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'Identifier' ||
+          !computedNames.has(node.callee.name)
+        ) { return; }
+
+        for (let i = fnStack.length - 1; i >= 0; i--) {
+          if (fnStack[i] === 'effect') {
+            context.report({ node, messageId: 'noNewComputedInEffect' });
+            return;
+          }
+          if (fnStack[i] === 'computed') { return; }
+        }
+      },
+    };
+  },
+};

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

@@ -0,0 +1,73 @@
+// Reports signal() called inside a computed() callback. Each recompute creates a new
+// orphaned signal with no cleanup path — declare the signal outside the computed.
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow creating a new signal() inside a computed() body',
+    },
+    messages: {
+      noNewSignalInComputed:
+        'signal() called inside a computed() body. Each recompute creates a new orphaned signal. ' +
+        'Declare the signal outside the computed instead.',
+    },
+  },
+
+  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) {
+        if (
+          node.callee.type !== 'Identifier' ||
+          !signalNames.has(node.callee.name)
+        ) { return; }
+
+        for (let i = fnStack.length - 1; i >= 0; i--) {
+          if (fnStack[i] === 'computed') {
+            context.report({ node, messageId: 'noNewSignalInComputed' });
+            return;
+          }
+          if (fnStack[i] === 'effect') { return; }
+        }
+      },
+    };
+  },
+};

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

@@ -0,0 +1,74 @@
+// 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.
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow creating a new signal() 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.',
+    },
+  },
+
+  create(context) {
+    const effectNames = new Set();
+    const signalNames = 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); }
+        }
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression)'(node) {
+        const { parent } = node;
+        if (
+          parent.type === 'CallExpression' &&
+          parent.arguments[0] === node &&
+          parent.callee.type === 'Identifier'
+        ) {
+          if (effectNames.has(parent.callee.name)) {
+            fnStack.push('effect');
+            return;
+          }
+          if (computedNames.has(parent.callee.name)) {
+            fnStack.push('computed');
+            return;
+          }
+        }
+        fnStack.push('other');
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression):exit'() {
+        fnStack.pop();
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'Identifier' ||
+          !signalNames.has(node.callee.name)
+        ) { return; }
+
+        for (let i = fnStack.length - 1; i >= 0; i--) {
+          if (fnStack[i] === 'effect') {
+            context.report({ node, messageId: 'noNewSignalInEffect' });
+            return;
+          }
+          if (fnStack[i] === 'computed') { return; }
+        }
+      },
+    };
+  },
+};

package/rules/no-self-read-write.js

@@ -0,0 +1,81 @@
+// Reports .get() and .set() on the same binding within the top-level body of
+// an effect() or computed() callback. Nested functions are excluded — the async
+// case is covered by the no-signal-async-write rule.
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow reading and writing the same signal in the same effect or computed run',
+    },
+    messages: {
+      noSelfReadWrite:
+        "'{{name}}' is read via .get() and written via .set() in the same {{contextType}} run. " +
+        'This creates a reactive loop — the write re-triggers the run. ' +
+        'Use .value instead of .get() to read the current value without subscribing.',
+    },
+  },
+
+  create(context) {
+    const effectNames = new Set();
+    const computedNames = new Set();
+    // Each frame: { type: 'effect'|'computed'|'other', reads: Set<string> }
+    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 === 'computed') { computedNames.add(spec.local.name); }
+        }
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression)'(node) {
+        const { parent } = node;
+        if (
+          parent.type === 'CallExpression' &&
+          parent.arguments[0] === node &&
+          parent.callee.type === 'Identifier'
+        ) {
+          if (effectNames.has(parent.callee.name)) {
+            fnStack.push({ type: 'effect', reads: new Set() });
+            return;
+          }
+          if (computedNames.has(parent.callee.name)) {
+            fnStack.push({ type: 'computed', reads: new Set() });
+            return;
+          }
+        }
+        fnStack.push({ type: 'other', reads: new Set() });
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression):exit'() {
+        fnStack.pop();
+      },
+
+      CallExpression(node) {
+        const top = fnStack[fnStack.length - 1];
+        if (!top || top.type === 'other') { return; }
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.object.type !== 'Identifier' ||
+          node.callee.property.type !== 'Identifier'
+        ) { return; }
+
+        const name = node.callee.object.name;
+        const method = node.callee.property.name;
+
+        if (method === 'get' && node.arguments.length === 0) {
+          top.reads.add(name);
+        } else if (method === 'set' && node.arguments.length === 1 && top.reads.has(name)) {
+          context.report({
+            node,
+            messageId: 'noSelfReadWrite',
+            data: { name, contextType: top.type },
+          });
+        }
+      },
+    };
+  },
+};

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

@@ -0,0 +1,74 @@
+// Reports .set() calls inside a computed() callback imported from kensington.
+// Stops searching when a nested effect() or computed() is reached (separate reactive context).
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow .set() inside a computed() body',
+    },
+    messages: {
+      noSetInComputed:
+        '.set() called inside a computed() body. Computed functions must be pure derivations. ' +
+        'Move the write into a separate effect() instead.',
+    },
+  },
+
+  create(context) {
+    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 === '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) {
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.object.type !== 'Identifier' ||
+          node.callee.property.type !== 'Identifier' ||
+          node.callee.property.name !== 'set' ||
+          node.arguments.length !== 1
+        ) { return; }
+
+        for (let i = fnStack.length - 1; i >= 0; i--) {
+          if (fnStack[i] === 'computed') {
+            context.report({ node, messageId: 'noSetInComputed' });
+            return;
+          }
+          if (fnStack[i] === 'effect') { return; }
+        }
+      },
+    };
+  },
+};

package/rules/no-set-on-computed.js

@@ -0,0 +1,56 @@
+// Reports .set() on a variable that was directly assigned from computed() imported from kensington.
+// Computed signals are read-only — kensington throws at runtime, but this catches it statically.
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow .set() on a computed signal',
+    },
+    messages: {
+      noSetOnComputed:
+        "'{{name}}' is a computed signal and cannot be written with .set(). " +
+        'Use signal() for writable state.',
+    },
+  },
+
+  create(context) {
+    const computedNames = new Set();
+    const computedBindings = 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 === 'computed') { computedNames.add(spec.local.name); }
+        }
+      },
+
+      VariableDeclarator(node) {
+        if (
+          node.id.type !== 'Identifier' ||
+          !node.init ||
+          node.init.type !== 'CallExpression' ||
+          node.init.callee.type !== 'Identifier' ||
+          !computedNames.has(node.init.callee.name)
+        ) { return; }
+        computedBindings.add(node.id.name);
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.object.type !== 'Identifier' ||
+          node.callee.property.type !== 'Identifier' ||
+          node.callee.property.name !== 'set' ||
+          node.arguments.length !== 1
+        ) { return; }
+
+        const name = node.callee.object.name;
+        if (computedBindings.has(name)) {
+          context.report({ node, messageId: 'noSetOnComputed', data: { name } });
+        }
+      },
+    };
+  },
+};

package/rules/no-signal-async-write.js

@@ -0,0 +1,105 @@
+// Reports .set() on a binding that was read via .get() in the enclosing effect() body,
+// when the .set() is inside an async callback (setTimeout, rAF, .then, etc.).
+// The async boundary means the write happens after the effect completes — re-triggering
+// it on every async resolution and creating an invisible reactive loop.
+
+const ASYNC_GLOBAL_FNS = new Set([
+  'setTimeout', 'setInterval', 'setImmediate',
+  'queueMicrotask', 'requestAnimationFrame', 'requestIdleCallback',
+]);
+
+const ASYNC_METHODS = new Set(['then', 'catch', 'finally']);
+
+function isAsyncParent(fnNode) {
+  const { parent } = fnNode;
+  if (parent.type !== 'CallExpression' || !parent.arguments.includes(fnNode)) { return false; }
+  const { callee } = parent;
+  if (callee.type === 'Identifier' && ASYNC_GLOBAL_FNS.has(callee.name)) { return true; }
+  if (
+    callee.type === 'MemberExpression' &&
+    callee.property.type === 'Identifier' &&
+    ASYNC_METHODS.has(callee.property.name)
+  ) { return true; }
+  return false;
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow writing a signal in an async callback when it was read in the enclosing effect()',
+    },
+    messages: {
+      noSignalAsyncWrite:
+        "'{{name}}' is read via .get() in the effect body and written via .set() in an async callback. " +
+        'This re-triggers the effect after each async operation, creating a potential reactive loop. ' +
+        'Use .value instead of .get() to read without subscribing, or guard the write with a condition check.',
+    },
+  },
+
+  create(context) {
+    const effectNames = new Set();
+    // Each frame: { type: 'effectTop'|'asyncCb'|'other', reads: Set<string>|null }
+    // asyncCb shares the reads reference from its parent effectTop so .get() calls
+    // registered before the async boundary are visible when checking .set() inside it.
+    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); }
+        }
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression)'(node) {
+        const { parent } = node;
+        if (
+          parent.type === 'CallExpression' &&
+          parent.arguments[0] === node &&
+          parent.callee.type === 'Identifier' &&
+          effectNames.has(parent.callee.name)
+        ) {
+          fnStack.push({ type: 'effectTop', reads: new Set() });
+          return;
+        }
+
+        const top = fnStack[fnStack.length - 1];
+        if (top && (top.type === 'effectTop' || top.type === 'asyncCb') && isAsyncParent(node)) {
+          fnStack.push({ type: 'asyncCb', reads: top.reads });
+          return;
+        }
+
+        fnStack.push({ type: 'other', reads: null });
+      },
+
+      ':matches(ArrowFunctionExpression, FunctionExpression):exit'() {
+        fnStack.pop();
+      },
+
+      CallExpression(node) {
+        const top = fnStack[fnStack.length - 1];
+        if (!top || top.type === 'other') { return; }
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.object.type !== 'Identifier' ||
+          node.callee.property.type !== 'Identifier'
+        ) { return; }
+
+        const name = node.callee.object.name;
+        const method = node.callee.property.name;
+
+        if (method === 'get' && node.arguments.length === 0 && top.type === 'effectTop') {
+          top.reads.add(name);
+        } else if (method === 'set' && node.arguments.length === 1 && top.type === 'asyncCb' && top.reads.has(name)) {
+          context.report({
+            node,
+            messageId: 'noSignalAsyncWrite',
+            data: { name },
+          });
+        }
+      },
+    };
+  },
+};