@ethlete/eslint-plugin 0.1.0-next.0 → 0.1.0-next.10

package/src/rules/prefer-linked-signal.js

@@ -0,0 +1,124 @@
+// @ts-check
+'use strict';
+
+/**
+ * Prefer linkedSignal over setting a signal inside an effect().
+ *
+ * When a signal is set inside an effect(), it usually means the new value is
+ * derived from other reactive state. That pattern is better expressed with
+ * linkedSignal(), which is declarative, avoids the scheduling overhead of
+ * effect(), and makes the dependency chain explicit.
+ *
+ * BAD:
+ *   selectedItem = signal<Item | null>(null);
+ *
+ *   constructor() {
+ *     effect(() => {
+ *       // Reset selection whenever the list changes
+ *       this.selectedItem.set(this.items()[0] ?? null);  // ❌
+ *     });
+ *   }
+ *
+ * GOOD:
+ *   selectedItem = linkedSignal(() => this.items()[0] ?? null);
+ *
+ * NOTE: Only flag when .set() is called directly inside an effect() callback.
+ * Setting signals outside effects (in methods, event handlers, etc.) is fine.
+ */
+
+/**
+ * Returns true only when the `.set()` call node is a *pure derivation* inside
+ * an effect() callback — meaning:
+ *
+ * 1. The IMMEDIATE enclosing function (the first function boundary walking up
+ *    from the node) IS the first argument passed to `effect()`. This ensures
+ *    that `.set()` calls nested inside `untracked(() => ...)` or other inner
+ *    functions within the effect are NOT flagged — those are intentional
+ *    write-back patterns, not derivations.
+ *
+ * 2. The `.set()` call is the SOLE expression in that callback:
+ *    - Arrow with expression body: `effect(() => sig.set(x))`
+ *    - Block body with a single ExpressionStatement: `effect(() => { sig.set(x); })`
+ *
+ *    Multi-statement blocks (even if they end with a `.set()`) indicate that the
+ *    effect is performing side effects alongside the signal write, so they are
+ *    not flagged either.
+ *
+ * @param {import('eslint').Rule.Node} node The `.set()` CallExpression node
+ */
+const isPureSetInDirectEffectCallback = (node) => {
+  // Find the immediate enclosing function (cross exactly one boundary).
+  let current = node.parent;
+  let immediateFunction = null;
+
+  while (current) {
+    if (current.type === 'ArrowFunctionExpression' || current.type === 'FunctionExpression') {
+      immediateFunction = current;
+      break;
+    }
+    current = current.parent;
+  }
+
+  if (!immediateFunction) return false;
+
+  // The immediate function must be the first argument to an effect() call.
+  const funcParent = immediateFunction.parent;
+  if (
+    !funcParent ||
+    funcParent.type !== 'CallExpression' ||
+    funcParent.callee.type !== 'Identifier' ||
+    funcParent.callee.name !== 'effect' ||
+    funcParent.arguments[0] !== immediateFunction
+  ) {
+    return false;
+  }
+
+  // The .set() must be the sole expression — no surrounding statements.
+  // Case A: arrow with expression body — the body IS the .set() call.
+  if (immediateFunction.type === 'ArrowFunctionExpression' && immediateFunction.body === node) {
+    return true;
+  }
+
+  // Case B: block body with exactly one ExpressionStatement wrapping the .set() call.
+  const body = immediateFunction.body;
+  return (
+    body.type === 'BlockStatement' &&
+    body.body.length === 1 &&
+    body.body[0].type === 'ExpressionStatement' &&
+    body.body[0].expression === node
+  );
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const preferLinkedSignal = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: "Prefer 'linkedSignal' over setting a signal inside effect().",
+      recommended: true,
+    },
+    messages: {
+      preferLinkedSignal:
+        "Setting a signal inside 'effect()' usually means the value is derived from reactive state. Use 'linkedSignal(() => ...)' instead — it is declarative and avoids effect scheduling overhead.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+
+        if (
+          callee.type === 'MemberExpression' &&
+          callee.property.type === 'Identifier' &&
+          callee.property.name === 'set' &&
+          isPureSetInDirectEffectCallback(node)
+        ) {
+          context.report({ node, messageId: 'preferLinkedSignal' });
+        }
+      },
+    };
+  },
+};
+
+module.exports = preferLinkedSignal;

package/src/rules/prefer-match-media.js

@@ -0,0 +1,101 @@
+// @ts-check
+'use strict';
+
+/**
+ * Prefers the typed media-query signal utilities from @ethlete/core over
+ * calling window.matchMedia() directly or using Angular CDK's BreakpointObserver.
+ *
+ * The utilities:
+ * - Return reactive signals that update when the media query result changes
+ * - Are SSR-safe (no window access during server rendering)
+ * - Are automatically cleaned up when the component is destroyed
+ *
+ * BAD:
+ *   window.matchMedia('(prefers-color-scheme: dark)').matches
+ *   const mq = window.matchMedia('(max-width: 768px)');
+ *   mq.addEventListener('change', handler);
+ *   inject(BreakpointObserver);
+ *   import { BreakpointObserver } from '@angular/cdk/layout';
+ *
+ * GOOD:
+ *   // For arbitrary media queries:
+ *   const isDark = injectMediaQueryIsMatched('(prefers-color-scheme: dark)');
+ *
+ *   // For standard breakpoints:
+ *   const isMobile = injectBreakpointIsMatched({ max: 'sm' });
+ *
+ *   // For reactive BreakpointObserver access:
+ *   const bo = injectBreakpointObserver();  // from @ethlete/core
+ *
+ *   // For common checks that are pre-built:
+ *   const canHover       = injectCanHover();
+ *   const hasTouchInput  = injectHasTouchInput();
+ *   const isPortrait     = injectIsPortrait();
+ *   const isLandscape    = injectIsLandscape();
+ *   const isXs           = injectIsXs();
+ *   const isSm           = injectIsSm();
+ *   // … etc. All from @ethlete/core.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const preferMatchMedia = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: "Prefer reactive media-query signal utilities from '@ethlete/core' over 'window.matchMedia()'.",
+      recommended: true,
+    },
+    messages: {
+      preferMatchMedia:
+        "Avoid 'window.matchMedia()' directly. Use 'injectMediaQueryIsMatched(query)' or a pre-built helper (injectCanHover, injectHasTouchInput, injectIsPortrait, injectBreakpointIsMatched, …) from '@ethlete/core' — they return reactive signals and are SSR-safe.",
+      noBreakpointObserver:
+        "Do not use Angular CDK's 'BreakpointObserver' directly. Use 'injectBreakpointObserver()' from '@ethlete/core' instead, which wraps it with a reactive signal API and proper DI scoping.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+
+        // ── window.matchMedia() ───────────────────────────────────────────────
+        if (
+          callee.type === 'MemberExpression' &&
+          callee.property.type === 'Identifier' &&
+          callee.property.name === 'matchMedia'
+        ) {
+          // Flag any .matchMedia() call — the object is almost certainly window or
+          // document.defaultView, but even a forwarded reference should be replaced.
+          context.report({ node, messageId: 'preferMatchMedia' });
+          return;
+        }
+
+        // ── inject(BreakpointObserver) ────────────────────────────────────────
+        if (
+          callee.type === 'Identifier' &&
+          callee.name === 'inject' &&
+          node.arguments[0]?.type === 'Identifier' &&
+          node.arguments[0].name === 'BreakpointObserver'
+        ) {
+          context.report({ node, messageId: 'noBreakpointObserver' });
+        }
+      },
+
+      ImportDeclaration(node) {
+        // ── import { BreakpointObserver } from '@angular/cdk/layout' ─────────
+        if (node.source.value !== '@angular/cdk/layout') return;
+        const hasBreakpointObserver = node.specifiers.some(
+          (s) =>
+            s.type === 'ImportSpecifier' &&
+            s.imported.type === 'Identifier' &&
+            s.imported.name === 'BreakpointObserver',
+        );
+        if (hasBreakpointObserver) {
+          context.report({ node, messageId: 'noBreakpointObserver' });
+        }
+      },
+    };
+  },
+};
+
+module.exports = preferMatchMedia;

package/src/rules/prefer-rxjs-timer.js

@@ -0,0 +1,82 @@
+// @ts-check
+'use strict';
+
+/**
+ * Prefer RxJS timer/interval/fromEvent operators over native browser APIs.
+ *
+ * RxJS operators integrate with takeUntilDestroyed() for automatic cleanup,
+ * whereas native APIs require manual cleanup and are easy to leak.
+ *
+ * BAD:
+ *   setTimeout(() => this.refresh(), 500);     // leaks if component destroyed first
+ *   setInterval(() => this.poll(), 2000);      // leaks
+ *   element.addEventListener('click', handler); // must be removed manually
+ *   element.removeEventListener('click', handler);
+ *
+ * GOOD:
+ *   timer(500).pipe(takeUntilDestroyed()).subscribe(() => this.refresh());
+ *   interval(2000).pipe(takeUntilDestroyed()).subscribe(() => this.poll());
+ *   fromEvent(element, 'click').pipe(takeUntilDestroyed()).subscribe(handler);
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const preferRxjsTimer = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Prefer RxJS timer / interval / fromEvent over native browser timer and event APIs.',
+      recommended: true,
+    },
+    messages: {
+      preferTimer:
+        "Use RxJS 'timer(delay)' from 'rxjs' instead of 'setTimeout()'. Combine with 'takeUntilDestroyed()' for automatic cleanup.",
+      preferInterval:
+        "Use RxJS 'interval(period)' from 'rxjs' instead of 'setInterval()'. Combine with 'takeUntilDestroyed()' for automatic cleanup.",
+      preferUnsubscribe:
+        "Remove '{{name}}()' — cancel the timer / interval by calling 'subscription.unsubscribe()' or use 'takeUntilDestroyed()' / 'take(1)'.",
+      preferFromEvent:
+        "Use RxJS 'fromEvent(target, event)' from 'rxjs' instead of '.addEventListener()'. Combine with 'takeUntilDestroyed()' for automatic cleanup.",
+      preferFromEventRemove:
+        "Remove '.removeEventListener()' — use 'fromEvent()' with 'takeUntilDestroyed()' to avoid ever needing to remove listeners manually.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+
+        // ── Global timer calls ────────────────────────────────────────────────
+        if (callee.type === 'Identifier') {
+          const { name } = callee;
+          if (name === 'setTimeout') {
+            context.report({ node, messageId: 'preferTimer' });
+            return;
+          }
+          if (name === 'setInterval') {
+            context.report({ node, messageId: 'preferInterval' });
+            return;
+          }
+          if (name === 'clearTimeout' || name === 'clearInterval') {
+            context.report({ node, messageId: 'preferUnsubscribe', data: { name } });
+            return;
+          }
+        }
+
+        // ── Member calls: .addEventListener / .removeEventListener ────────────
+        if (callee.type === 'MemberExpression' && callee.property.type === 'Identifier') {
+          const methodName = callee.property.name;
+          if (methodName === 'addEventListener') {
+            context.report({ node, messageId: 'preferFromEvent' });
+            return;
+          }
+          if (methodName === 'removeEventListener') {
+            context.report({ node, messageId: 'preferFromEventRemove' });
+          }
+        }
+      },
+    };
+  },
+};
+
+module.exports = preferRxjsTimer;

package/src/rules/prefer-scroll-state.js

@@ -0,0 +1,158 @@
+// @ts-check
+'use strict';
+
+/**
+ * Prefers signalElementScrollState / signalHostElementScrollState from @ethlete/core
+ * over imperatively reading scroll position properties inside reactive contexts,
+ * and disallows adding raw scroll event listeners in favour of the same signal utilities.
+ *
+ * The signal utilities:
+ * - Set up a scroll event listener that keeps a reactive signal in sync
+ * - Clean up automatically when the component is destroyed
+ * - Provide debouncing and direction tracking built in
+ *
+ * NOTE: The property-read check is a WARNING — imperative one-shot reads of
+ * scrollTop/scrollLeft are fine in event handlers and animations; only flag
+ * inside effect() / computed().
+ *
+ * BAD (reactive context):
+ *   effect(() => {
+ *     const top = this.el.nativeElement.scrollTop;  // stale snapshot ❌
+ *   });
+ *
+ * BAD (scroll listeners — always wrong):
+ *   el.addEventListener('scroll', fn);              // ❌
+ *   fromEvent(el, 'scroll').subscribe(fn);          // ❌
+ *   el.onscroll = fn;                               // ❌
+ *
+ * GOOD:
+ *   scrollState = signalHostElementScrollState();        // from @ethlete/core
+ *   scrollDir = signalHostElementLastScrollDirection();  // from @ethlete/core
+ *   // Or use <et-scrollable> / ScrollableComponent for list scrolling
+ */
+
+/** Scroll position properties read from DOM elements. */
+const SCROLL_PROPS = new Set(['scrollTop', 'scrollLeft', 'scrollY', 'scrollX']);
+
+/**
+ * Returns the name of the wrapping reactive context ('effect' | 'computed') if
+ * the node is inside one, crossing at least one function boundary.
+ * @param {import('eslint').Rule.Node} node
+ * @returns {string | null}
+ */
+const getReactiveContext = (node) => {
+  let crossedFunctionBoundary = false;
+  let current = node.parent;
+
+  while (current) {
+    if (current.type === 'ArrowFunctionExpression' || current.type === 'FunctionExpression') {
+      crossedFunctionBoundary = true;
+    }
+
+    if (
+      crossedFunctionBoundary &&
+      current.type === 'CallExpression' &&
+      current.callee.type === 'Identifier' &&
+      (current.callee.name === 'effect' || current.callee.name === 'computed')
+    ) {
+      return current.callee.name;
+    }
+
+    current = current.parent;
+  }
+
+  return null;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const preferScrollState = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        "Prefer 'signalElementScrollState()' / 'signalHostElementScrollState()' from '@ethlete/core' over reading scroll position properties inside reactive contexts.",
+      recommended: true,
+    },
+    messages: {
+      preferScrollState:
+        "Avoid reading '{{prop}}' inside {{context}}() — it creates a stale snapshot. Use 'signalElementScrollState(elementRef)' or 'signalHostElementScrollState()' from '@ethlete/core' instead. For scroll direction, use 'signalElementLastScrollDirection()' / 'signalHostElementLastScrollDirection()'.",
+      noScrollListener:
+        "Do not add 'scroll' event listeners directly. Use 'signalElementScrollState(elementRef)' / 'signalHostElementScrollState()' for scroll position or state, 'signalElementLastScrollDirection(elementRef)' / 'signalHostElementLastScrollDirection()' for scroll direction, or the 'ScrollableComponent' (et-scrollable) from '@ethlete/cdk' for scrollable lists. All are imported from '@ethlete/core' or '@ethlete/cdk'.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+        const args = node.arguments;
+
+        // ── el.addEventListener('scroll', fn) / window.addEventListener('scroll', fn) ──
+        if (
+          callee.type === 'MemberExpression' &&
+          callee.property.type === 'Identifier' &&
+          callee.property.name === 'addEventListener' &&
+          args[0]?.type === 'Literal' &&
+          args[0].value === 'scroll'
+        ) {
+          context.report({ node, messageId: 'noScrollListener' });
+          return;
+        }
+
+        // ── fromEvent(el, 'scroll') ──────────────────────────────────────────
+        if (
+          callee.type === 'Identifier' &&
+          callee.name === 'fromEvent' &&
+          args[1]?.type === 'Literal' &&
+          args[1].value === 'scroll'
+        ) {
+          context.report({ node, messageId: 'noScrollListener' });
+          return;
+        }
+
+        // ── renderer.listen(el, 'scroll', fn) ───────────────────────────────
+        if (
+          callee.type === 'MemberExpression' &&
+          callee.property.type === 'Identifier' &&
+          callee.property.name === 'listen' &&
+          args[1]?.type === 'Literal' &&
+          args[1].value === 'scroll'
+        ) {
+          context.report({ node, messageId: 'noScrollListener' });
+        }
+      },
+
+      AssignmentExpression(node) {
+        // ── el.onscroll = fn ────────────────────────────────────────────────
+        const { left } = node;
+        if (
+          left.type === 'MemberExpression' &&
+          left.property.type === 'Identifier' &&
+          left.property.name === 'onscroll'
+        ) {
+          context.report({ node, messageId: 'noScrollListener' });
+        }
+      },
+
+      MemberExpression(node) {
+        if (node.property.type !== 'Identifier') return;
+        if (!SCROLL_PROPS.has(node.property.name)) return;
+
+        // Only flag reads (not assignments like el.scrollTop = 0).
+        const parent = node.parent;
+        if (parent && parent.type === 'AssignmentExpression' && parent.left === node) return;
+
+        const reactiveCtx = getReactiveContext(node);
+        if (!reactiveCtx) return;
+
+        context.report({
+          node,
+          messageId: 'preferScrollState',
+          data: { prop: node.property.name, context: reactiveCtx },
+        });
+      },
+    };
+  },
+};
+
+module.exports = preferScrollState;

package/src/rules/prefer-viewport-size.js

@@ -0,0 +1,75 @@
+// @ts-check
+'use strict';
+
+/**
+ * Prefers injectViewportSize() from @ethlete/core over reading raw viewport
+ * dimensions from the global window object.
+ *
+ * injectViewportSize() returns a reactive signal that:
+ * - Updates automatically when the viewport is resized
+ * - Works on the server (SSR-safe)
+ * - Participates in Angular's change detection
+ *
+ * BAD:
+ *   const w = window.innerWidth;
+ *   document.defaultView?.innerHeight
+ *
+ * GOOD:
+ *   const viewport = injectViewportSize(); // from @ethlete/core
+ *   const w = viewport().width;
+ *   const h = viewport().height;
+ */
+
+/** Properties on window that report viewport dimensions. */
+const VIEWPORT_PROPERTIES = new Set([
+  'innerWidth',
+  'innerHeight',
+  'outerWidth',
+  'outerHeight',
+  'screen', // window.screen.width / window.screen.height
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const preferViewportSize = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: "Prefer 'injectViewportSize()' from '@ethlete/core' over direct window dimension properties.",
+      recommended: true,
+    },
+    messages: {
+      preferViewportSize:
+        "Avoid reading '{{prop}}' directly from window. Use 'injectViewportSize()' from '@ethlete/core' — it returns a reactive signal that stays up to date as the viewport resizes.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (node.property.type !== 'Identifier') return;
+        if (!VIEWPORT_PROPERTIES.has(node.property.name)) return;
+
+        // Only flag when the object is clearly a window-like reference.
+        const obj = node.object;
+        const objText = context.sourceCode.getText(obj).toLowerCase();
+
+        const isWindowRef =
+          objText === 'window' ||
+          objText.endsWith('.defaultview') ||
+          objText.endsWith('?.defaultview') ||
+          // document.defaultView without optional chain
+          /defaultview$/.test(objText);
+
+        if (!isWindowRef) return;
+
+        context.report({
+          node,
+          messageId: 'preferViewportSize',
+          data: { prop: node.property.name },
+        });
+      },
+    };
+  },
+};
+
+module.exports = preferViewportSize;

package/src/rules/require-dollar-suffix.js

@@ -0,0 +1,123 @@
+// @ts-check
+'use strict';
+
+/**
+ * Requires observable variables and class properties to be suffixed with `$`.
+ *
+ * Detection is heuristic — a binding is assumed to be an Observable if its
+ * initializer matches one of:
+ *   - a `.pipe(...)` call  (most reliable signal)
+ *   - `new Subject / BehaviorSubject / ReplaySubject / AsyncSubject / Observable()`
+ *   - a call to a known RxJS creator: from, of, interval, timer, fromEvent,
+ *     fromEventPattern, combineLatest, merge, concat, forkJoin, race, zip,
+ *     defer, iif, throwError, using, partition
+ *
+ * ❌ const myData = someObs.pipe(map(...));
+ * ❌ const clicks = fromEvent(el, 'click');
+ * ❌ class Foo { stream = this.src.pipe(filter(...)); }
+ *
+ * ✅ const myData$ = someObs.pipe(map(...));
+ * ✅ const clicks$ = fromEvent(el, 'click');
+ * ✅ class Foo { stream$ = this.src.pipe(filter(...)); }
+ */
+
+const RXJS_CREATORS = new Set([
+  'from',
+  'of',
+  'interval',
+  'timer',
+  'fromEvent',
+  'fromEventPattern',
+  'combineLatest',
+  'merge',
+  'concat',
+  'forkJoin',
+  'race',
+  'zip',
+  'defer',
+  'iif',
+  'throwError',
+  'using',
+  'partition',
+]);
+
+const RXJS_SUBJECT_CTORS = new Set(['Subject', 'BehaviorSubject', 'ReplaySubject', 'AsyncSubject', 'Observable']);
+
+/**
+ * Returns true if the expression looks like an Observable.
+ * @param {any} node
+ */
+const isObservableInit = (node) => {
+  if (!node) return false;
+
+  // someObs.pipe(...)
+  if (
+    node.type === 'CallExpression' &&
+    node.callee.type === 'MemberExpression' &&
+    node.callee.property.type === 'Identifier' &&
+    node.callee.property.name === 'pipe'
+  ) {
+    return true;
+  }
+
+  // from(...), of(...), interval(...), etc.
+  if (node.type === 'CallExpression' && node.callee.type === 'Identifier' && RXJS_CREATORS.has(node.callee.name)) {
+    return true;
+  }
+
+  // new Subject(), new BehaviorSubject(...), etc.
+  if (node.type === 'NewExpression' && node.callee.type === 'Identifier' && RXJS_SUBJECT_CTORS.has(node.callee.name)) {
+    return true;
+  }
+
+  return false;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require observable variables and class properties to use the $ suffix.',
+    },
+    schema: [],
+    messages: {
+      missingSuffix: "Observable '{{ name }}' must end with '$' (e.g. '{{ name }}$').",
+    },
+  },
+  create(context) {
+    /**
+     * @param {string} name
+     * @param {any} reportNode
+     * @param {any} initNode
+     */
+    const checkBinding = (name, reportNode, initNode) => {
+      if (!isObservableInit(initNode)) return;
+      if (name.endsWith('$')) return;
+
+      context.report({
+        node: reportNode,
+        messageId: 'missingSuffix',
+        data: { name },
+      });
+    };
+
+    return {
+      // const myObs = ...
+      VariableDeclarator(node) {
+        const n = /** @type {any} */ (node);
+        if (n.id.type !== 'Identifier') return;
+        checkBinding(n.id.name, n.id, n.init);
+      },
+
+      // class Foo { myObs = ... }
+      PropertyDefinition(node) {
+        const n = /** @type {any} */ (node);
+        if (n.key.type !== 'Identifier') return;
+        checkBinding(n.key.name, n.key, n.value);
+      },
+    };
+  },
+};
+
+module.exports = rule;