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

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;

package/src/rules/require-view-encapsulation-none.js

@@ -0,0 +1,101 @@
+// @ts-check
+'use strict';
+
+/**
+ * Requires @Component decorators to explicitly set `encapsulation: ViewEncapsulation.None`.
+ *
+ * The Ethlete styleguide mandates `ViewEncapsulation.None` for all components
+ * because styles are managed globally via design tokens and CSS custom properties.
+ * Emulated or ShadowDom encapsulation would interfere with this system.
+ *
+ * ❌ Missing the property entirely (default is Emulated):
+ *   @Component({ selector: 'my-cmp', template: '' })
+ *
+ * ❌ Explicitly set to Emulated:
+ *   @Component({ encapsulation: ViewEncapsulation.Emulated, ... })
+ *
+ * ❌ ShadowDom:
+ *   @Component({ encapsulation: ViewEncapsulation.ShadowDom, ... })
+ *
+ * ✅ Correct:
+ *   @Component({ encapsulation: ViewEncapsulation.None, ... })
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const requireViewEncapsulationNone = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require `encapsulation: ViewEncapsulation.None` in all @Component decorators.',
+    },
+    messages: {
+      missing: 'Add `encapsulation: ViewEncapsulation.None` to @Component. The default (Emulated) is not allowed.',
+      notNone: '`encapsulation` must be `ViewEncapsulation.None`. Got `ViewEncapsulation.{{value}}`.',
+    },
+    schema: [],
+  },
+  create(context) {
+    /**
+     * Returns true if the node is a @Component decorator call.
+     * @param {import('eslint').Rule.Node} node
+     */
+    const isComponentDecorator = (node) => {
+      const dec = /** @type {any} */ (node);
+      if (dec.type !== 'Decorator') return false;
+      const expr = dec.expression;
+      if (expr.type === 'CallExpression') return expr.callee.type === 'Identifier' && expr.callee.name === 'Component';
+      if (expr.type === 'Identifier') return expr.name === 'Component';
+      return false;
+    };
+
+    return {
+      Decorator(node) {
+        if (!isComponentDecorator(node)) return;
+
+        const dec = /** @type {any} */ (node);
+        const expr = dec.expression;
+        if (expr.type !== 'CallExpression') return;
+
+        const args = expr.arguments;
+        if (!args || args.length === 0) return;
+
+        const metadata = args[0];
+        if (!metadata || metadata.type !== 'ObjectExpression') return;
+
+        // Look for an `encapsulation` property
+        const encProp = metadata.properties.find(
+          (/** @type {any} */ p) =>
+            p.type === 'Property' && p.key.type === 'Identifier' && p.key.name === 'encapsulation',
+        );
+
+        if (!encProp) {
+          // Property absent — default is Emulated, which is not allowed
+          context.report({ node: metadata, messageId: 'missing' });
+          return;
+        }
+
+        // Must be ViewEncapsulation.None
+        const val = /** @type {any} */ (encProp).value;
+        if (
+          val.type === 'MemberExpression' &&
+          val.object.type === 'Identifier' &&
+          val.object.name === 'ViewEncapsulation' &&
+          val.property.type === 'Identifier'
+        ) {
+          if (val.property.name !== 'None') {
+            context.report({
+              node: val,
+              messageId: 'notNone',
+              data: { value: val.property.name },
+            });
+          }
+          // .None — valid, do nothing
+        }
+        // If it's not a MemberExpression at all we don't flag it
+        // (dynamic or unusual expression — let TypeScript catch it)
+      },
+    };
+  },
+};
+
+module.exports = requireViewEncapsulationNone;