@ethlete/eslint-plugin 0.1.0-beta.5

package/src/rules/no-trivial-wrapper-method.js

@@ -0,0 +1,120 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows trivial wrapper methods that do nothing but forward all their
+ * arguments to another call.
+ *
+ * These methods add an extra layer of indirection without adding any value.
+ * Call sites should invoke the target directly.
+ *
+ * BAD:
+ *   setValue(val: string) { this.value.set(val); }           // just delegates
+ *   getItem(key: string) { return this.store.get(key); }     // just delegates
+ *   doThing(a: string, b: number) { this.impl.doThing(a, b); }
+ *
+ * GOOD:
+ *   // Call this.value.set(val) directly at the call sites.
+ *   // If the method wraps something non-trivially (transforms args, adds logic), it is fine.
+ */
+
+/**
+ * Returns true when the param is a plain identifier (no default, no destructuring, no rest).
+ * @param {import('@typescript-eslint/types').TSESTree.Parameter} param
+ */
+const isSimpleParam = (param) => param.type === 'Identifier';
+
+/**
+ * Returns the single CallExpression in the method body when the method is a
+ * trivial all-args-forwarding wrapper, or null otherwise.
+ *
+ * Matches both void wrappers:
+ *   setValue(val) { this.value.set(val); }
+ * and return wrappers:
+ *   get(key) { return this.store.get(key); }
+ *
+ * @param {import('eslint').Rule.Node} methodNode  MethodDefinition node
+ * @returns {import('eslint').Rule.Node | null}
+ */
+const getTrivialCallExpr = (methodNode) => {
+  const fnValue = methodNode.value;
+  if (!fnValue) return null;
+
+  const params = fnValue.params;
+  // Require at least one parameter — zero-param delegate methods are deliberate API surface.
+  if (params.length === 0) return null;
+  // All params must be simple identifiers (no destructuring, defaults, or rest).
+  if (!params.every(isSimpleParam)) return null;
+
+  const body = fnValue.body;
+  if (!body || body.type !== 'BlockStatement') return null;
+  if (body.body.length !== 1) return null;
+
+  const stmt = body.body[0];
+
+  let callExpr = null;
+  if (stmt.type === 'ExpressionStatement') {
+    callExpr = stmt.expression;
+  } else if (stmt.type === 'ReturnStatement' && stmt.argument) {
+    callExpr = stmt.argument;
+  }
+
+  if (!callExpr || callExpr.type !== 'CallExpression') return null;
+  if (callExpr.arguments.length !== params.length) return null;
+
+  // All arguments must be the method's own param names in the same order.
+  const allMatch = params.every((param, i) => {
+    const arg = callExpr.arguments[i];
+    return arg.type === 'Identifier' && arg.name === param.name;
+  });
+
+  return allMatch ? callExpr : null;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noTrivialWrapperMethod = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow trivial wrapper methods that only forward all arguments to another call.',
+      recommended: true,
+    },
+    messages: {
+      noTrivialWrapperMethod:
+        "'{{name}}' is a trivial wrapper — it only forwards all its arguments to '{{target}}'. Remove it and call '{{target}}' directly at each call site.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      MethodDefinition(node) {
+        // Skip constructors, getters, and setters — they commonly delegate for good reasons.
+        if (node.kind === 'constructor' || node.kind === 'get' || node.kind === 'set') return;
+
+        const callExpr = getTrivialCallExpr(node);
+        if (!callExpr) return;
+
+        const methodName = node.key.type === 'Identifier' ? node.key.name : null;
+        if (!methodName) return;
+
+        const callee = callExpr.callee;
+        const targetName =
+          callee.type === 'MemberExpression'
+            ? context.sourceCode.getText(callee)
+            : callee.type === 'Identifier'
+              ? callee.name
+              : null;
+
+        if (!targetName) return;
+
+        context.report({
+          node,
+          messageId: 'noTrivialWrapperMethod',
+          data: { name: methodName, target: targetName },
+        });
+      },
+    };
+  },
+};
+
+module.exports = noTrivialWrapperMethod;

package/src/rules/no-type-only-import.js

@@ -0,0 +1,79 @@
+// @ts-check
+'use strict';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noTypeOnlyImport = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow `import type { Foo }` and `import { type Foo }` — use a regular value import instead.',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      noTypeImportDeclaration:
+        "Do not use `import type`. Use a regular import instead: `import { {{specifiers}} } from '{{source}}';`.",
+      noInlineTypeSpecifier:
+        "Do not use inline `type` on import specifiers. Use a regular import instead: `import { {{specifiers}} } from '{{source}}';`.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        const decl = /** @type {any} */ (node);
+        if (decl.importKind === 'type') {
+          const source = /** @type {string} */ (node.source.value);
+          const specifiers = node.specifiers.map((s) => s.local.name).join(', ');
+
+          context.report({
+            node,
+            messageId: 'noTypeImportDeclaration',
+            data: { specifiers, source },
+            fix(fixer) {
+              const specifierText = node.specifiers.map((s) => s.local.name).join(', ');
+              return fixer.replaceText(node, `import { ${specifierText} } from '${source}';`);
+            },
+          });
+
+          return;
+        }
+
+        for (const specifier of node.specifiers) {
+          const spec = /** @type {any} */ (specifier);
+          if (specifier.type === 'ImportSpecifier' && spec.importKind === 'type') {
+            const source = /** @type {string} */ (node.source.value);
+            const allSpecifiers = node.specifiers
+              .map((s) => {
+                if (s.type === 'ImportSpecifier') {
+                  const imported = s.imported.type === 'Identifier' ? s.imported.name : s.imported.value;
+                  return s.local.name === imported ? imported : `${imported} as ${s.local.name}`;
+                }
+                return s.local.name;
+              })
+              .join(', ');
+
+            context.report({
+              node: specifier,
+              messageId: 'noInlineTypeSpecifier',
+              data: { specifiers: allSpecifiers, source },
+              fix(fixer) {
+                const sourceCode = context.sourceCode;
+                const tokenBefore = sourceCode.getTokenBefore(specifier.imported ?? specifier.local);
+                if (tokenBefore && tokenBefore.value === 'type') {
+                  const tokenAfter = sourceCode.getTokenAfter(tokenBefore);
+                  if (tokenAfter) {
+                    return fixer.removeRange([tokenBefore.range[0], tokenAfter.range[0]]);
+                  }
+                }
+                return null;
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+module.exports = noTypeOnlyImport;

package/src/rules/no-typed-injected-element-ref.js

@@ -0,0 +1,88 @@
+// @ts-check
+'use strict';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noTypedInjectedElementRef = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Require that inject(ElementRef) uses a generic type parameter on inject() itself, not on ElementRef.',
+      recommended: true,
+    },
+    messages: {
+      missingGeneric:
+        'Provide a generic type on inject() itself: `inject<ElementRef<HTMLElement>>(ElementRef)`. Passing a type argument on ElementRef directly is also disallowed.',
+    },
+    schema: [],
+    fixable: 'code',
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== 'Identifier' || node.callee.name !== 'inject') {
+          return;
+        }
+
+        const firstArg = node.arguments[0];
+        if (!firstArg) return;
+
+        const isPlainElementRef = firstArg.type === 'Identifier' && firstArg.name === 'ElementRef';
+        const isInstantiatedElementRef =
+          firstArg.type === 'TSInstantiationExpression' &&
+          firstArg.expression &&
+          firstArg.expression.type === 'Identifier' &&
+          firstArg.expression.name === 'ElementRef';
+
+        if (!isPlainElementRef && !isInstantiatedElementRef) return;
+
+        const src = context.sourceCode;
+        const existingTypeParams = node.typeParameters || node.typeArguments;
+        const hasInjectTypeParam =
+          existingTypeParams && existingTypeParams.params && existingTypeParams.params.length > 0;
+
+        if (isPlainElementRef && !hasInjectTypeParam) {
+          // inject(ElementRef) → inject<ElementRef<HTMLElement>>(ElementRef)
+          context.report({
+            node,
+            messageId: 'missingGeneric',
+            fix(fixer) {
+              return fixer.insertTextAfter(node.callee, '<ElementRef<HTMLElement>>');
+            },
+          });
+          return;
+        }
+
+        if (isInstantiatedElementRef) {
+          // Capture the type args text from the token, e.g. "<HTMLElement>"
+          const tokenTypeParamText = src.getText(firstArg.typeParameters || firstArg.typeArguments);
+
+          if (!hasInjectTypeParam) {
+            // inject(ElementRef<HTMLElement>) → inject<ElementRef<HTMLElement>>(ElementRef)
+            context.report({
+              node,
+              messageId: 'missingGeneric',
+              fix(fixer) {
+                return [
+                  fixer.insertTextAfter(node.callee, `<ElementRef${tokenTypeParamText}>`),
+                  fixer.replaceText(firstArg, 'ElementRef'),
+                ];
+              },
+            });
+          } else {
+            // inject<X>(ElementRef<Y>) — token must not carry type args; keep inject's type param
+            context.report({
+              node,
+              messageId: 'missingGeneric',
+              fix(fixer) {
+                return fixer.replaceText(firstArg, 'ElementRef');
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+module.exports = noTypedInjectedElementRef;

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;