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

package/src/rules/no-unused-class-member.js

@@ -0,0 +1,209 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows class members that are declared but never read within the class body.
+ *
+ * Only checks members that CANNOT be accessed from outside the class at compile
+ * time — so false positives (e.g. template usage) are avoided:
+ *
+ * - `private` members — always checked. Private members are only accessible
+ *   within the class body, so if they are never read there they are dead code.
+ *
+ * - `protected` members — checked only when the class has an Angular decorator
+ *   other than `@Component` (i.e. `@Directive`, `@Pipe`, `@Injectable`).
+ *   For `@Component`, protected members may be read in the HTML template file
+ *   which is invisible to static analysis, so protected is skipped there.
+ *   For plain (non-Angular) classes, protected members may be used in a
+ *   subclass in another file, so they are also skipped.
+ *
+ * Members referenced in `host:` binding expressions in the class decorator are
+ * excluded from the check for `protected` (since they are accessed by Angular
+ * at runtime via the host binding mechanism).
+ *
+ * BAD:
+ *   private document = inject(DOCUMENT); // fetched but never used
+ *   private unusedFlag = false;
+ *
+ * GOOD:
+ *   private document = inject(DOCUMENT);
+ *   createElement() { return this.document.createElement('div'); }
+ */
+
+const ANGULAR_DECORATORS = new Set(['Component', 'Directive', 'Pipe', 'Injectable']);
+
+/**
+ * Extract all identifier-like tokens from a template expression string.
+ * Used for `host:` binding values like `'myMember ? "on" : "off"'`.
+ * @param {string} str
+ * @returns {string[]}
+ */
+const extractIdentifiers = (str) => str.match(/\b[a-zA-Z_$][a-zA-Z0-9_$]*\b/g) ?? [];
+
+/**
+ * Returns info about the Angular decorators applied to a class node.
+ * @param {any} classNode
+ * @returns {{ isComponent: boolean, isAngularClass: boolean }}
+ */
+const getDecoratorInfo = (classNode) => {
+  const decorators = classNode.decorators ?? [];
+  let isComponent = false;
+  let isAngularClass = false;
+
+  for (const dec of decorators) {
+    const expr = dec.expression;
+    const name =
+      expr?.type === 'CallExpression' && expr.callee?.type === 'Identifier'
+        ? expr.callee.name
+        : expr?.type === 'Identifier'
+          ? expr.name
+          : null;
+
+    if (name && ANGULAR_DECORATORS.has(name)) {
+      isAngularClass = true;
+      if (name === 'Component') isComponent = true;
+    }
+  }
+
+  return { isComponent, isAngularClass };
+};
+
+/**
+ * Returns names of class members referenced in `host:` binding value strings
+ * found in any decorator argument on the class.
+ * @param {any} classNode
+ * @returns {Set<string>}
+ */
+const getHostBoundMembers = (classNode) => {
+  /** @type {Set<string>} */
+  const result = new Set();
+  const decorators = classNode.decorators ?? [];
+
+  for (const dec of decorators) {
+    const expr = dec.expression;
+    if (expr?.type !== 'CallExpression') continue;
+
+    const arg = expr.arguments?.[0];
+    if (!arg || arg.type !== 'ObjectExpression') continue;
+
+    const hostProp = arg.properties.find(
+      /** @param {any} p */
+      (p) => p.type === 'Property' && (p.key?.name === 'host' || p.key?.value === 'host'),
+    );
+    if (!hostProp || hostProp.value?.type !== 'ObjectExpression') continue;
+
+    for (const binding of hostProp.value.properties) {
+      if (binding.type !== 'Property') continue;
+      /** @type {any} */
+      const val = binding.value;
+      if (val?.type !== 'Literal' || typeof val.value !== 'string') continue;
+      for (const id of extractIdentifiers(val.value)) result.add(id);
+    }
+  }
+
+  return result;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noUnusedClassMember = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow class members that are declared but never read within the class body.',
+      recommended: true,
+    },
+    messages: {
+      noUnused:
+        "'{{name}}' is declared but its value is never read within this class. " +
+        'Remove it, or widen its accessibility if it is intentionally used externally.',
+    },
+    schema: [],
+  },
+  create(context) {
+    /**
+     * Stack of class frames. Each frame tracks which members are candidates and
+     * which have been seen in a `this.x` expression.
+     *
+     * @type {Array<{
+     *   classBody: import('eslint').Rule.Node,
+     *   isComponent: boolean,
+     *   isAngularClass: boolean,
+     *   hostBound: Set<string>,
+     *   candidates: Map<string, import('eslint').Rule.Node>,
+     *   usedNames: Set<string>,
+     * }>}
+     */
+    const classStack = [];
+
+    /**
+     * @param {any} node
+     */
+    const registerMember = (node) => {
+      const frame = classStack[classStack.length - 1];
+      if (!frame) return;
+      // Only register members that belong directly to this class body
+      if (node.parent !== frame.classBody) return;
+
+      if (node.static) return;
+
+      const key = node.key;
+      if (!key || key.type !== 'Identifier') return;
+      if (node.type === 'MethodDefinition' && node.kind === 'constructor') return;
+
+      const name = key.name;
+      const accessibility = node.accessibility;
+      const { isComponent, isAngularClass, hostBound } = frame;
+
+      if (accessibility === 'private') {
+        frame.candidates.set(name, node);
+      } else if (accessibility === 'protected' && isAngularClass && !isComponent) {
+        if (!hostBound.has(name)) frame.candidates.set(name, node);
+      }
+    };
+
+    return {
+      ClassBody(node) {
+        const classNode = node.parent;
+        const { isComponent, isAngularClass } = getDecoratorInfo(classNode);
+        const hostBound = getHostBoundMembers(classNode);
+        classStack.push({
+          classBody: node,
+          isComponent,
+          isAngularClass,
+          hostBound,
+          candidates: new Map(),
+          usedNames: new Set(),
+        });
+      },
+
+      'ClassBody:exit'() {
+        const frame = classStack.pop();
+        if (!frame) return;
+        for (const [name, memberNode] of frame.candidates) {
+          if (!frame.usedNames.has(name)) {
+            context.report({ node: memberNode, messageId: 'noUnused', data: { name } });
+          }
+        }
+      },
+
+      PropertyDefinition: registerMember,
+      MethodDefinition: registerMember,
+
+      MemberExpression(node) {
+        // Only care about `this.name` (non-computed direct property access)
+        if (node.computed) return;
+        if (node.object?.type !== 'ThisExpression') return;
+        if (node.property?.type !== 'Identifier') return;
+
+        // Mark used in the innermost class frame. Arrow functions don't push a
+        // new frame so they correctly share the enclosing class's `this`.
+        // Regular nested classes push a new frame so their `this.x` won't
+        // accidentally mark an outer class member as used.
+        const frame = classStack[classStack.length - 1];
+        if (frame) frame.usedNames.add(node.property.name);
+      },
+    };
+  },
+};
+
+module.exports = noUnusedClassMember;

package/src/rules/no-window-location.js

@@ -0,0 +1,109 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows reading URL state from window.location properties.
+ *
+ * window.location reads are:
+ * - Not reactive — they return a stale snapshot at call time
+ * - Not SSR-safe — window is undefined during server-side rendering
+ *
+ * @ethlete/core ships reactive signal utilities that replace all URL-reading use cases.
+ *
+ * BAD:
+ *   window.location.pathname       → injectRoute()
+ *   window.location.href           → injectUrl()
+ *   window.location.search         → injectQueryParams() / injectQueryParam(key)
+ *   window.location.hash           → injectFragment()
+ *   new URLSearchParams(window.location.search)  → injectQueryParams() / injectQueryParam(key)
+ *
+ * GOOD:
+ *   import {
+ *     injectUrl, injectRoute, injectQueryParam, injectQueryParams, injectFragment
+ *   } from '@ethlete/core';
+ *
+ * NOTE: window.location.href = url (assignment/navigation) and
+ * window.location.hostname / window.location.origin are not flagged.
+ */
+
+/** URL state properties that have reactive signal equivalents. */
+const LOCATION_STATE_PROPS = new Map([
+  ['href', "injectUrl() from '@ethlete/core'"],
+  ['pathname', "injectRoute() from '@ethlete/core'"],
+  ['search', "injectQueryParams() / injectQueryParam(key) from '@ethlete/core'"],
+  ['hash', "injectFragment() from '@ethlete/core'"],
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noWindowLocation = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        "Disallow reading URL state from 'window.location.*'. Use reactive signal utilities from '@ethlete/core' instead.",
+      recommended: true,
+    },
+    messages: {
+      noWindowLocation:
+        "Avoid reading 'window.location.{{prop}}'. Use {{replacement}} instead — it returns a reactive signal that is SSR-safe and updates on navigation.",
+      noURLSearchParams:
+        "Avoid 'new URLSearchParams(window.location.search)'. Use 'injectQueryParam(key)' or 'injectQueryParams()' from '@ethlete/core' instead — they return reactive signals and are SSR-safe.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      // ── window.location.{prop} reads ────────────────────────────────────────
+      MemberExpression(node) {
+        if (node.property.type !== 'Identifier') return;
+        const prop = node.property.name;
+
+        if (!LOCATION_STATE_PROPS.has(prop)) return;
+
+        // Must be window.location.{prop} — check the object is window.location
+        const parent = node.object;
+        if (
+          parent.type !== 'MemberExpression' ||
+          parent.object.type !== 'Identifier' ||
+          parent.object.name !== 'window' ||
+          parent.property.type !== 'Identifier' ||
+          parent.property.name !== 'location'
+        ) {
+          return;
+        }
+
+        // Skip assignments TO window.location.href (navigation redirect)
+        if (prop === 'href' && node.parent.type === 'AssignmentExpression' && node.parent.left === node) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: 'noWindowLocation',
+          data: { prop, replacement: LOCATION_STATE_PROPS.get(prop) },
+        });
+      },
+
+      // ── new URLSearchParams(window.location.search) ─────────────────────────
+      NewExpression(node) {
+        if (node.callee.type !== 'Identifier' || node.callee.name !== 'URLSearchParams') return;
+        const arg = node.arguments[0];
+        if (!arg) return;
+        if (
+          arg.type === 'MemberExpression' &&
+          arg.object.type === 'MemberExpression' &&
+          arg.object.object.type === 'Identifier' &&
+          arg.object.object.name === 'window' &&
+          arg.object.property.type === 'Identifier' &&
+          arg.object.property.name === 'location' &&
+          arg.property.type === 'Identifier' &&
+          arg.property.name === 'search'
+        ) {
+          context.report({ node, messageId: 'noURLSearchParams' });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noWindowLocation;

package/src/rules/prefer-clone-equal.js

@@ -0,0 +1,112 @@
+// @ts-check
+'use strict';
+
+/**
+ * Prefers the 'clone()' and 'equal()' utilities from '@ethlete/core' over
+ * ad-hoc deep-clone and deep-equality patterns.
+ *
+ * clone():
+ *   - Handles all JS types (Date, RegExp, Map, Set, ArrayBuffer, typed arrays)
+ *   - Preserves prototype chains
+ *   - Unlike JSON round-trip: does not drop undefined, functions, or Dates become strings
+ *   - Unlike structuredClone: no transfer semantics needed
+ *
+ * equal():
+ *   - Full deep equality (Date, RegExp, Map, Set, ArrayBuffer, typed arrays)
+ *   - No lodash dependency needed
+ *
+ * BAD:
+ *   JSON.parse(JSON.stringify(obj))          // lossy, slow, no prototype
+ *   structuredClone(obj)                     // for components: use clone()
+ *   import { cloneDeep } from 'lodash';      // unnecessary dependency
+ *   import { isEqual } from 'lodash';        // unnecessary dependency
+ *
+ * GOOD:
+ *   import { clone, equal } from '@ethlete/core';
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const preferCloneEqual = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        "Prefer 'clone()' / 'equal()' from '@ethlete/core' over JSON round-trip cloning, structuredClone, or lodash cloneDeep / isEqual.",
+      recommended: true,
+    },
+    messages: {
+      preferClone:
+        "Avoid '{{method}}' for deep cloning. Use 'clone()' from '@ethlete/core' instead — it handles all JS types, preserves prototypes, and does not lose undefined values or Dates.",
+      preferEqual:
+        "Avoid lodash '{{method}}' for deep equality. Use 'equal()' from '@ethlete/core' instead — no extra dependency needed.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+
+        // ── JSON.parse(JSON.stringify(expr)) ─────────────────────────────────
+        if (
+          callee.type === 'MemberExpression' &&
+          callee.object.type === 'Identifier' &&
+          callee.object.name === 'JSON' &&
+          callee.property.type === 'Identifier' &&
+          callee.property.name === 'parse' &&
+          node.arguments[0]?.type === 'CallExpression'
+        ) {
+          const innerCall = node.arguments[0];
+          if (
+            innerCall.callee.type === 'MemberExpression' &&
+            innerCall.callee.object.type === 'Identifier' &&
+            innerCall.callee.object.name === 'JSON' &&
+            innerCall.callee.property.type === 'Identifier' &&
+            innerCall.callee.property.name === 'stringify'
+          ) {
+            context.report({ node, messageId: 'preferClone', data: { method: 'JSON.parse(JSON.stringify(...))' } });
+            return;
+          }
+        }
+
+        // ── structuredClone(expr) ─────────────────────────────────────────────
+        if (callee.type === 'Identifier' && callee.name === 'structuredClone') {
+          context.report({ node, messageId: 'preferClone', data: { method: 'structuredClone()' } });
+        }
+      },
+
+      ImportDeclaration(node) {
+        const src = node.source.value;
+
+        // ── lodash cloneDeep / isEqual ────────────────────────────────────────
+        // import { cloneDeep } from 'lodash' / 'lodash-es'
+        // import { isEqual } from 'lodash' / 'lodash-es'
+        if (src === 'lodash' || src === 'lodash-es') {
+          for (const specifier of node.specifiers) {
+            if (specifier.type !== 'ImportSpecifier') continue;
+            const name = specifier.imported.name;
+            if (name === 'cloneDeep') {
+              context.report({ node, messageId: 'preferClone', data: { method: 'lodash cloneDeep' } });
+            } else if (name === 'isEqual') {
+              context.report({ node, messageId: 'preferEqual', data: { method: 'isEqual' } });
+            }
+          }
+          return;
+        }
+
+        // import cloneDeep from 'lodash/cloneDeep'
+        if (src === 'lodash/cloneDeep' || src === 'lodash-es/cloneDeep') {
+          context.report({ node, messageId: 'preferClone', data: { method: 'lodash cloneDeep' } });
+          return;
+        }
+
+        // import isEqual from 'lodash/isEqual'
+        if (src === 'lodash/isEqual' || src === 'lodash-es/isEqual') {
+          context.report({ node, messageId: 'preferEqual', data: { method: 'isEqual' } });
+        }
+      },
+    };
+  },
+};
+
+module.exports = preferCloneEqual;

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;