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

package/src/rules/prefer-concise-angular-host-directives.js

@@ -0,0 +1,225 @@
+// @ts-check
+'use strict';
+
+/** @typedef {'Component' | 'Directive'} TDecoratorName */
+/** @typedef {import('estree').Property & { range: [number, number] }} TPropertyNode */
+/** @typedef {import('estree').ArrayExpression & { elements: Array<import('estree').Expression | import('estree').SpreadElement | null> }} TArrayExpressionNode */
+/** @typedef {import('estree').ObjectExpression & { properties: Array<TPropertyNode | import('estree').SpreadElement> }} TObjectExpressionNode */
+/** @typedef {{ hasComma: boolean; originalIndex: number; orderIndex: number; property: TPropertyNode; segmentText: string }} TPropertyEntry */
+
+const HOST_DIRECTIVE_PROPERTY_ORDER = ['directive', 'inputs', 'outputs'];
+
+/**
+ * @param {import('eslint').Rule.Node} node
+ */
+const getDecoratorName = (node) => {
+  const decorator = /** @type {any} */ (node);
+  if (decorator.type !== 'Decorator') return null;
+
+  const expression = decorator.expression;
+  if (expression.type === 'CallExpression') {
+    return expression.callee.type === 'Identifier' ? expression.callee.name : null;
+  }
+
+  return expression.type === 'Identifier' ? expression.name : null;
+};
+
+/**
+ * @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 {TDecoratorName} decoratorName
+ * @param {import('estree').Node} node
+ */
+const getHostDirectivesArray = (decoratorName, node) => {
+  const decorator = /** @type {any} */ (node);
+  const expression = decorator.expression;
+  if (expression.type !== 'CallExpression' || expression.arguments.length === 0) return null;
+
+  const metadata = expression.arguments[0];
+  if (!metadata || metadata.type !== 'ObjectExpression') return null;
+
+  for (const property of metadata.properties) {
+    if (!property || property.type !== 'Property') continue;
+    if (getPropertyName(property.key) !== 'hostDirectives') continue;
+    if (property.value.type !== 'ArrayExpression') return null;
+
+    return /** @type {TArrayExpressionNode} */ (property.value);
+  }
+
+  return null;
+};
+
+/**
+ * @param {TObjectExpressionNode} node
+ */
+const getHostDirectiveConfigProperties = (node) => {
+  if (
+    node.properties.some(
+      /** @param {TPropertyNode | import('estree').SpreadElement} property */ (property) =>
+        property.type !== 'Property',
+    )
+  ) {
+    return null;
+  }
+
+  const properties = /** @type {TPropertyNode[]} */ (node.properties);
+  const names = properties.map((property) => getPropertyName(property.key));
+
+  if (names.some((name) => name === null || !HOST_DIRECTIVE_PROPERTY_ORDER.includes(name))) {
+    return null;
+  }
+
+  return properties;
+};
+
+/**
+ * @param {TObjectExpressionNode} node
+ * @param {import('eslint').SourceCode} sourceCode
+ */
+const buildSortedObjectText = (node, sourceCode) => {
+  const properties = getHostDirectiveConfigProperties(node);
+  if (!properties || properties.length < 2) return null;
+
+  const openingBrace = sourceCode.getFirstToken(node);
+  const closingBrace = sourceCode.getLastToken(node);
+  if (!openingBrace || !closingBrace || openingBrace.value !== '{' || closingBrace.value !== '}') return null;
+
+  let segmentStart = openingBrace.range[1];
+  const orderIndexMap = new Map(HOST_DIRECTIVE_PROPERTY_ORDER.map((value, index) => [value, index]));
+
+  const entries = properties.map(
+    /** @param {TPropertyNode} property @param {number} originalIndex @returns {TPropertyEntry} */
+    (property, originalIndex) => {
+      const tokenAfter = sourceCode.getTokenAfter(property);
+      const hasComma = Boolean(tokenAfter && tokenAfter.type === 'Punctuator' && tokenAfter.value === ',');
+      const segmentEnd = hasComma && tokenAfter ? tokenAfter.range[0] : property.range[1];
+      const segmentText = sourceCode.text.slice(segmentStart, segmentEnd);
+
+      if (hasComma && tokenAfter) {
+        segmentStart = tokenAfter.range[1];
+      } else {
+        segmentStart = property.range[1];
+      }
+
+      return {
+        hasComma,
+        originalIndex,
+        orderIndex: orderIndexMap.get(getPropertyName(property.key)) ?? HOST_DIRECTIVE_PROPERTY_ORDER.length,
+        property,
+        segmentText,
+      };
+    },
+  );
+
+  const trailingComma = entries[entries.length - 1].hasComma;
+  const suffix = sourceCode.text.slice(segmentStart, closingBrace.range[0]);
+  const sortedEntries = [...entries].sort((left, right) => {
+    if (left.orderIndex !== right.orderIndex) return left.orderIndex - right.orderIndex;
+    return left.originalIndex - right.originalIndex;
+  });
+
+  const isSorted = entries.every((entry, index) => entry.property === sortedEntries[index].property);
+  if (isSorted) return null;
+
+  return (
+    '{' +
+    sortedEntries
+      .map((entry, index) => `${entry.segmentText}${index < sortedEntries.length - 1 || trailingComma ? ',' : ''}`)
+      .join('') +
+    suffix +
+    '}'
+  );
+};
+
+/**
+ * @param {TObjectExpressionNode} node
+ */
+const hasOnlyDirectiveProperty = (node) => {
+  const properties = getHostDirectiveConfigProperties(node);
+  if (!properties || properties.length !== 1) return false;
+
+  return getPropertyName(properties[0].key) === 'directive';
+};
+
+/**
+ * @param {TObjectExpressionNode} node
+ */
+const getDirectiveValueNode = (node) => {
+  const properties = getHostDirectiveConfigProperties(node);
+  if (!properties || properties.length !== 1) return null;
+
+  const property = properties[0];
+  if (getPropertyName(property.key) !== 'directive') return null;
+
+  return property.value;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const preferConciseAngularHostDirectives = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Prefer shorthand hostDirectives entries when only directive is needed, and keep extended host directive configs ordered as directive, inputs, outputs.',
+      recommended: true,
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      preferShorthand: 'Use the directive directly in hostDirectives when no inputs or outputs are forwarded.',
+      hostDirectiveOrder: 'Extended hostDirectives entries should order properties as directive, inputs, outputs.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      Decorator(node) {
+        const decoratorName = getDecoratorName(node);
+        if (decoratorName !== 'Component' && decoratorName !== 'Directive') return;
+
+        const hostDirectives = getHostDirectivesArray(decoratorName, node);
+        if (!hostDirectives) return;
+
+        for (const element of hostDirectives.elements) {
+          if (!element || element.type !== 'ObjectExpression') continue;
+
+          const config = /** @type {TObjectExpressionNode} */ (element);
+          const properties = getHostDirectiveConfigProperties(config);
+          if (!properties) continue;
+
+          if (hasOnlyDirectiveProperty(config)) {
+            const directiveValue = getDirectiveValueNode(config);
+            if (!directiveValue) continue;
+
+            context.report({
+              node: config,
+              messageId: 'preferShorthand',
+              fix: (fixer) => fixer.replaceText(config, sourceCode.getText(directiveValue)),
+            });
+
+            continue;
+          }
+
+          const sortedObjectText = buildSortedObjectText(config, sourceCode);
+          if (!sortedObjectText) continue;
+
+          context.report({
+            node: config,
+            messageId: 'hostDirectiveOrder',
+            fix: (fixer) => fixer.replaceText(config, sortedObjectText),
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = preferConciseAngularHostDirectives;

package/src/rules/prefer-concise-angular-style-metadata.js

@@ -0,0 +1,108 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('estree').Property} TPropertyNode */
+/** @typedef {import('estree').Expression | import('estree').SpreadElement | null} TArrayElement */
+
+/**
+ * @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';
+};
+
+/**
+ * @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 {TPropertyNode} property
+ * @returns {import('estree').Expression | null}
+ */
+const getSingleArrayElement = (property) => {
+  if (property.value.type !== 'ArrayExpression' || property.value.elements.length !== 1) return null;
+
+  const firstElement = /** @type {TArrayElement} */ (property.value.elements[0]);
+  if (!firstElement || firstElement.type === 'SpreadElement') return null;
+
+  return firstElement;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const preferConciseAngularStyleMetadata = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Prefer `styleUrl` over single-item `styleUrls`, and avoid wrapping a single `styles` entry in an array.',
+    },
+    fixable: 'code',
+    messages: {
+      preferStyleUrl: 'Use `styleUrl` instead of `styleUrls` when there is only one style path.',
+      preferSingleStyle: 'Use `styles: <value>` instead of a single-item `styles` array.',
+    },
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      /** @param {import('eslint').Rule.Node} node */
+      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;
+
+        for (const property of metadata.properties) {
+          if (property.type !== 'Property') continue;
+
+          const propertyName = getPropertyName(property.key);
+          if (propertyName !== 'styleUrls' && propertyName !== 'styles') continue;
+
+          const singleElement = getSingleArrayElement(property);
+          if (!singleElement) continue;
+
+          if (propertyName === 'styleUrls') {
+            context.report({
+              node: property,
+              messageId: 'preferStyleUrl',
+              fix(fixer) {
+                return fixer.replaceText(property, `styleUrl: ${sourceCode.getText(singleElement)}`);
+              },
+            });
+
+            continue;
+          }
+
+          context.report({
+            node: property,
+            messageId: 'preferSingleStyle',
+            fix(fixer) {
+              return fixer.replaceText(property, `styles: ${sourceCode.getText(singleElement)}`);
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = preferConciseAngularStyleMetadata;

package/src/rules/prefer-element-dimensions.js

@@ -0,0 +1,128 @@
+// @ts-check
+'use strict';
+
+/**
+ * Prefers signalElementDimensions / signalHostElementDimensions from @ethlete/core
+ * over imperatively reading element size properties inside reactive contexts
+ * (effect(), computed(), or signal initializers).
+ *
+ * Why: reading `.getBoundingClientRect()`, `.offsetWidth`, `.clientWidth`, etc.
+ * inside a reactive context creates a one-shot snapshot that never updates. The
+ * signal utilities set up a ResizeObserver-backed reactive signal that stays in
+ * sync automatically and cleans itself up when the component is destroyed.
+ *
+ * NOTE: This rule is a WARNING (not an error) because imperative one-shot reads
+ * (e.g. inside animation callbacks, event handlers) are perfectly valid. The rule
+ * only fires when the read is inside a reactive context.
+ *
+ * BAD (reactive context):
+ *   effect(() => {
+ *     const w = this.el.nativeElement.offsetWidth;   // stale after resize ❌
+ *   });
+ *
+ *   computed(() => someEl.getBoundingClientRect().width);  // ❌
+ *
+ * GOOD:
+ *   dimensions = signalHostElementDimensions();  // from @ethlete/core
+ *   // or
+ *   dimensions = signalElementDimensions(inject(ElementRef));
+ *   // Then:
+ *   effect(() => { const w = this.dimensions().rect.width; }); // ✅ reactive
+ */
+
+/** Size-related properties read from DOM elements. */
+const ELEMENT_SIZE_PROPS = new Set([
+  'offsetWidth',
+  'offsetHeight',
+  'clientWidth',
+  'clientHeight',
+  'scrollWidth',
+  'scrollHeight',
+]);
+
+/** Size-related methods called on DOM elements. */
+const ELEMENT_SIZE_METHODS = new Set(['getBoundingClientRect', 'getClientRects']);
+
+/**
+ * Returns the name of the wrapping reactive context ('effect' | 'computed') if
+ * the node is inside one, crossing exactly 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 preferElementDimensions = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        "Prefer 'signalElementDimensions()' or 'signalHostElementDimensions()' from '@ethlete/core' over reading element size properties inside reactive contexts.",
+      recommended: true,
+    },
+    messages: {
+      preferElementDimensions:
+        "Avoid reading '{{prop}}' inside {{context}}() — it creates a stale snapshot. Use 'signalElementDimensions(elementRef)' or 'signalHostElementDimensions()' from '@ethlete/core' instead — they provide a reactive signal backed by ResizeObserver.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      // el.offsetWidth, el.clientWidth, etc.
+      MemberExpression(node) {
+        if (node.property.type !== 'Identifier') return;
+        if (!ELEMENT_SIZE_PROPS.has(node.property.name)) return;
+
+        const reactiveCtx = getReactiveContext(node);
+        if (!reactiveCtx) return;
+
+        context.report({
+          node,
+          messageId: 'preferElementDimensions',
+          data: { prop: node.property.name, context: reactiveCtx },
+        });
+      },
+
+      // el.getBoundingClientRect(), el.getClientRects()
+      CallExpression(node) {
+        const { callee } = node;
+        if (callee.type !== 'MemberExpression') return;
+        if (callee.property.type !== 'Identifier') return;
+        if (!ELEMENT_SIZE_METHODS.has(callee.property.name)) return;
+
+        const reactiveCtx = getReactiveContext(node);
+        if (!reactiveCtx) return;
+
+        context.report({
+          node,
+          messageId: 'preferElementDimensions',
+          data: { prop: callee.property.name + '()', context: reactiveCtx },
+        });
+      },
+    };
+  },
+};
+
+module.exports = preferElementDimensions;

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;