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

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-on-push-change-detection.js

@@ -0,0 +1,271 @@
+// @ts-check
+'use strict';
+
+const COMPONENT_ORDER = ['selector', 'template', 'styleUrl', 'encapsulation', 'changeDetection'];
+
+/**
+ * @param {import('estree').Property['key']} key
+ */
+const getPropertyName = (key) => {
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' && typeof key.value === 'string') return key.value;
+  return null;
+};
+
+/**
+ * @param {string | null} propertyName
+ */
+const getOrderKey = (propertyName) => {
+  if (propertyName === 'template' || propertyName === 'templateUrl') return 'template';
+  if (propertyName === 'styleUrl' || propertyName === 'styleUrls') return 'styleUrl';
+  return propertyName;
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {import('eslint').AST.Token | import('eslint').Rule.Node} node
+ */
+const getIndent = (sourceCode, node) => {
+  if (!node.loc) return '';
+
+  const line = sourceCode.lines[node.loc.start.line - 1] ?? '';
+  return line.slice(0, node.loc.start.column);
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} property
+ */
+const hasTrailingComma = (sourceCode, property) => {
+  const tokenAfter = sourceCode.getTokenAfter(property);
+  return Boolean(tokenAfter && tokenAfter.type === 'Punctuator' && tokenAfter.value === ',');
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ */
+const findAngularCoreImport = (sourceCode) =>
+  sourceCode.ast.body.find(
+    (node) =>
+      node.type === 'ImportDeclaration' && node.source.type === 'Literal' && node.source.value === '@angular/core',
+  ) ?? null;
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} importNode
+ */
+const buildAngularCoreImportFix = (sourceCode, importNode) => {
+  const specifiers = importNode.specifiers ?? [];
+  const hasChangeDetectionStrategy = specifiers.some(
+    (specifier) =>
+      specifier.type === 'ImportSpecifier' &&
+      specifier.imported.type === 'Identifier' &&
+      specifier.imported.name === 'ChangeDetectionStrategy',
+  );
+  if (hasChangeDetectionStrategy) return null;
+
+  const defaultSpecifier = specifiers.find((specifier) => specifier.type === 'ImportDefaultSpecifier') ?? null;
+  const namespaceSpecifier = specifiers.find((specifier) => specifier.type === 'ImportNamespaceSpecifier') ?? null;
+  const namedSpecifiers = specifiers.filter((specifier) => specifier.type === 'ImportSpecifier');
+
+  if (namespaceSpecifier) {
+    return (fixer) => fixer.insertTextAfter(importNode, `\nimport { ChangeDetectionStrategy } from '@angular/core';`);
+  }
+
+  const importParts = [];
+  if (defaultSpecifier) {
+    importParts.push(sourceCode.getText(defaultSpecifier));
+  }
+
+  const namedTexts = namedSpecifiers.map((specifier) => sourceCode.getText(specifier));
+  importParts.push(`{ ${[...namedTexts, 'ChangeDetectionStrategy'].join(', ')} }`);
+
+  return (fixer) => fixer.replaceText(importNode, `import ${importParts.join(', ')} from '@angular/core';`);
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ */
+const buildMissingAngularCoreImportFix = (sourceCode) => {
+  const importDeclarations = sourceCode.ast.body.filter((node) => node.type === 'ImportDeclaration');
+  const lastImport = importDeclarations[importDeclarations.length - 1] ?? null;
+
+  return lastImport
+    ? (fixer) => fixer.insertTextAfter(lastImport, `\nimport { ChangeDetectionStrategy } from '@angular/core';`)
+    : (fixer) =>
+        fixer.replaceTextRange(
+          [0, sourceCode.ast.range[0]],
+          `import { ChangeDetectionStrategy } from '@angular/core';\n\n`,
+        );
+};
+
+/**
+ * @param {any} metadata
+ */
+const getChangeDetectionInsertionTarget = (metadata) => {
+  const changeDetectionIndex = COMPONENT_ORDER.indexOf('changeDetection');
+
+  return (
+    metadata.properties.find((property) => {
+      if (property.type !== 'Property') return false;
+
+      const propertyName = getOrderKey(getPropertyName(property.key));
+      const propertyIndex = propertyName === null ? COMPONENT_ORDER.length : COMPONENT_ORDER.indexOf(propertyName);
+      return propertyIndex > changeDetectionIndex || propertyIndex === -1;
+    }) ?? null
+  );
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} metadata
+ */
+const buildMetadataFix = (sourceCode, metadata) => {
+  const changeDetectionText = 'changeDetection: ChangeDetectionStrategy.OnPush';
+  const properties = metadata.properties.filter((property) => property.type === 'Property');
+  const insertionTarget = getChangeDetectionInsertionTarget(metadata);
+  const isMultiline = Boolean(metadata.loc && metadata.loc.start.line !== metadata.loc.end.line);
+
+  if (properties.length === 0) {
+    return (fixer) => fixer.replaceText(metadata, `{ ${changeDetectionText} }`);
+  }
+
+  if (insertionTarget) {
+    if (isMultiline) {
+      const propertyIndent = getIndent(sourceCode, insertionTarget);
+      return (fixer) => fixer.insertTextBefore(insertionTarget, `${changeDetectionText},\n${propertyIndent}`);
+    }
+
+    return (fixer) => fixer.insertTextBefore(insertionTarget, `${changeDetectionText}, `);
+  }
+
+  const lastProperty = properties[properties.length - 1];
+  const closingBrace = sourceCode.getLastToken(metadata);
+  if (!lastProperty || !closingBrace) return null;
+
+  if (isMultiline) {
+    const closingIndent = getIndent(sourceCode, closingBrace);
+    const propertyIndent = getIndent(sourceCode, lastProperty);
+    const separator = hasTrailingComma(sourceCode, lastProperty) ? '' : ',';
+    const rangeStart =
+      separator === ''
+        ? (sourceCode.getTokenAfter(lastProperty)?.range[1] ?? lastProperty.range[1])
+        : lastProperty.range[1];
+
+    return (fixer) =>
+      fixer.replaceTextRange(
+        [rangeStart, closingBrace.range[0]],
+        `${separator}\n${propertyIndent}${changeDetectionText}\n${closingIndent}`,
+      );
+  }
+
+  const separator = hasTrailingComma(sourceCode, lastProperty) ? '' : ',';
+  return (fixer) =>
+    fixer.replaceTextRange([lastProperty.range[1], closingBrace.range[0]], `${separator} ${changeDetectionText} `);
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} metadata
+ * @param {any} valueNode
+ */
+const buildFix = (sourceCode, metadata, valueNode) => {
+  const fixes = [];
+  const angularCoreImport = findAngularCoreImport(sourceCode);
+  const importFix = angularCoreImport
+    ? buildAngularCoreImportFix(sourceCode, angularCoreImport)
+    : buildMissingAngularCoreImportFix(sourceCode);
+
+  if (importFix) fixes.push(importFix);
+
+  if (valueNode) {
+    fixes.push((fixer) => fixer.replaceText(valueNode, 'ChangeDetectionStrategy.OnPush'));
+  } else {
+    const metadataFix = buildMetadataFix(sourceCode, metadata);
+    if (metadataFix) fixes.push(metadataFix);
+  }
+
+  return (fixer) => fixes.map((applyFix) => applyFix(fixer));
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const requireOnPushChangeDetection = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require `changeDetection: ChangeDetectionStrategy.OnPush` in all @Component decorators.',
+    },
+    fixable: 'code',
+    messages: {
+      missing:
+        'Add `changeDetection: ChangeDetectionStrategy.OnPush` to @Component. Default change detection is not allowed.',
+      notOnPush: '`changeDetection` must be `ChangeDetectionStrategy.OnPush`. Got `ChangeDetectionStrategy.{{value}}`.',
+    },
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    /**
+     * @param {import('eslint').Rule.Node} node
+     */
+    const isComponentDecorator = (node) => {
+      const decorator = /** @type {any} */ (node);
+      if (decorator.type !== 'Decorator') return false;
+
+      const expression = decorator.expression;
+      if (expression.type === 'CallExpression') {
+        return expression.callee.type === 'Identifier' && expression.callee.name === 'Component';
+      }
+
+      return expression.type === 'Identifier' && expression.name === 'Component';
+    };
+
+    return {
+      Decorator(node) {
+        if (!isComponentDecorator(node)) return;
+
+        const decorator = /** @type {any} */ (node);
+        const expression = decorator.expression;
+        if (expression.type !== 'CallExpression' || expression.arguments.length === 0) return;
+
+        const metadata = expression.arguments[0];
+        if (!metadata || metadata.type !== 'ObjectExpression') return;
+
+        const changeDetectionProp = metadata.properties.find(
+          (property) =>
+            property.type === 'Property' &&
+            property.key.type === 'Identifier' &&
+            property.key.name === 'changeDetection',
+        );
+
+        if (!changeDetectionProp) {
+          context.report({
+            node: metadata,
+            messageId: 'missing',
+            fix: buildFix(sourceCode, metadata, null),
+          });
+          return;
+        }
+
+        const value = changeDetectionProp.value;
+        if (
+          value.type === 'MemberExpression' &&
+          value.object.type === 'Identifier' &&
+          value.object.name === 'ChangeDetectionStrategy' &&
+          value.property.type === 'Identifier' &&
+          value.property.name !== 'OnPush'
+        ) {
+          context.report({
+            node: value,
+            messageId: 'notOnPush',
+            data: { value: value.property.name },
+            fix: buildFix(sourceCode, metadata, value),
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = requireOnPushChangeDetection;