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

package/src/rules/no-angular-router-api.js

@@ -0,0 +1,158 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows injecting Angular's ActivatedRoute (fully replaced),
+ * and disallows reading route state directly from an injected Router instance.
+ *
+ * inject(Router) is allowed — it is still needed for navigation (.navigate(),
+ * .navigateByUrl(), .createUrlTree(), etc.).
+ * Reading state properties off it is NOT allowed — use the @ethlete/core signal
+ * utilities instead.
+ *
+ * ❌ ActivatedRoute (fully replaced):
+ *   inject(ActivatedRoute)
+ *   import { ActivatedRoute } from '@angular/router';
+ *
+ * ❌ Router state property reads:
+ *   this.router.url           → injectUrl()
+ *   this.router.events        → injectRouterEvent()
+ *   this.router.routerState   → injectRouterState()
+ *   this.router.snapshot      → injectRouterState()
+ *   this.router.lastSuccessfulNavigation  → injectRouterState()
+ *   this.router.currentNavigation        → injectRouterState()
+ *
+ * ✅ inject(Router) is still fine for navigation:
+ *   router.navigate(['/path'])
+ *   router.navigateByUrl('/path')
+ *   router.createUrlTree(['/path'])
+ *
+ * ✅ Use the @ethlete/core router utilities for state:
+ *   injectUrl(), injectRoute(), injectRouterEvent(), injectRouterState(),
+ *   injectIsRouterInitialized(), injectQueryParam(key), injectPathParam(key),
+ *   injectQueryParams(), injectPathParams(), injectFragment(),
+ *   injectRouteData(), injectRouteDataItem(key), injectRouteTitle(),
+ *   injectQueryParamChanges(), injectPathParamChanges()
+ */
+
+/**
+ * Router properties that expose route state and must not be read directly.
+ * @type {Map<string, string>}
+ */
+const ROUTER_STATE_PROPS = new Map([
+  ['url', "injectUrl() from '@ethlete/core'"],
+  ['events', "injectRouterEvent() from '@ethlete/core'"],
+  ['routerState', "injectRouterState() from '@ethlete/core'"],
+  ['snapshot', "injectRouterState() from '@ethlete/core'"],
+  ['lastSuccessfulNavigation', "injectRouterState() from '@ethlete/core'"],
+  ['currentNavigation', "injectRouterState() from '@ethlete/core'"],
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noAngularRouterApi = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        "Disallow injecting 'ActivatedRoute' (fully replaced) and reading state properties off an injected 'Router'.",
+      recommended: true,
+    },
+    messages: {
+      noActivatedRoute:
+        "Do not inject 'ActivatedRoute'. Use reactive signal utilities from '@ethlete/core' instead: 'injectQueryParam(key)', 'injectPathParam(key)', 'injectQueryParams()', 'injectPathParams()', 'injectFragment()', 'injectRouteData()', 'injectRouteDataItem(key)', or 'injectRouteTitle()'. All return reactive signals and are SSR-safe.",
+      noRouterStateProp:
+        "Do not read 'router.{{prop}}' directly. Use {{replacement}} instead — it returns a reactive signal and is SSR-safe. Use inject(Router) only for navigation (.navigate(), .navigateByUrl()).",
+    },
+    schema: [],
+  },
+  create(context) {
+    /**
+     * Names of variables/properties assigned from inject(Router).
+     * We track identifiers whose initializer is inject(Router) so we can
+     * detect property access on them anywhere in the file.
+     * @type {Set<string>}
+     */
+    const routerBindings = new Set();
+
+    return {
+      // ── Track inject(Router) bindings ──────────────────────────────────────
+      // const router = inject(Router);
+      VariableDeclarator(node) {
+        if (
+          node.init?.type === 'CallExpression' &&
+          node.init.callee.type === 'Identifier' &&
+          node.init.callee.name === 'inject' &&
+          node.init.arguments[0]?.type === 'Identifier' &&
+          node.init.arguments[0].name === 'Router' &&
+          node.id.type === 'Identifier'
+        ) {
+          routerBindings.add(node.id.name);
+        }
+      },
+
+      // ── Track class property assignments: router = inject(Router) ──────────
+      PropertyDefinition(node) {
+        if (
+          node.value?.type === 'CallExpression' &&
+          node.value.callee.type === 'Identifier' &&
+          node.value.callee.name === 'inject' &&
+          node.value.arguments[0]?.type === 'Identifier' &&
+          node.value.arguments[0].name === 'Router' &&
+          node.key.type === 'Identifier'
+        ) {
+          routerBindings.add(node.key.name);
+        }
+      },
+
+      // ── Detect router.{stateProp} access ───────────────────────────────────
+      MemberExpression(node) {
+        if (node.property.type !== 'Identifier') return;
+        const prop = node.property.name;
+        if (!ROUTER_STATE_PROPS.has(prop)) return;
+
+        // Check object is a known router binding (direct: router.url)
+        // or a this.router.url / self.router.url pattern
+        const obj = node.object;
+        const isDirectBinding = obj.type === 'Identifier' && routerBindings.has(obj.name);
+        const isThisBinding =
+          obj.type === 'MemberExpression' &&
+          obj.object.type === 'ThisExpression' &&
+          obj.property.type === 'Identifier' &&
+          routerBindings.has(obj.property.name);
+
+        if (!isDirectBinding && !isThisBinding) return;
+
+        context.report({
+          node,
+          messageId: 'noRouterStateProp',
+          data: { prop, replacement: ROUTER_STATE_PROPS.get(prop) },
+        });
+      },
+
+      // ── ActivatedRoute import ───────────────────────────────────────────────
+      ImportDeclaration(node) {
+        if (node.source.value !== '@angular/router') return;
+        for (const specifier of node.specifiers) {
+          if (specifier.type !== 'ImportSpecifier') continue;
+          if (specifier.imported.name === 'ActivatedRoute') {
+            context.report({ node, messageId: 'noActivatedRoute' });
+            return;
+          }
+        }
+      },
+
+      // ── inject(ActivatedRoute) ──────────────────────────────────────────────
+      CallExpression(node) {
+        const { callee } = node;
+        if (callee.type !== 'Identifier' || callee.name !== 'inject') return;
+        const arg = node.arguments[0];
+        if (arg?.type !== 'Identifier') return;
+        if (arg.name === 'ActivatedRoute') {
+          context.report({ node, messageId: 'noActivatedRoute' });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noAngularRouterApi;

package/src/rules/no-angular-seo-services.js

@@ -0,0 +1,82 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows injecting Angular's `Title` and `Meta` services from
+ * `@angular/platform-browser` and importing them from that module.
+ *
+ * These services manipulate the document `<title>` and `<meta>` tags
+ * imperatively. The Ethlete platform requires going through the reactive SEO
+ * utilities in `@ethlete/core` instead, which integrate with the priority-based
+ * head-binding system and work correctly with SSR.
+ *
+ * ❌ Direct injection:
+ *   const title = inject(Title);
+ *   const meta  = inject(Meta);
+ *
+ * ❌ Import (without injection — still signals intent to use them):
+ *   import { Title, Meta } from '@angular/platform-browser';
+ *
+ * ✅ Use the @ethlete/core SEO utilities:
+ *   import { injectTitleBinding, injectMetaBinding } from '@ethlete/core';
+ *   const titleBinding = injectTitleBinding();
+ *   const metaBinding  = injectMetaBinding();
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: "Disallow Angular's Title/Meta services. Use @ethlete/core SEO utilities instead.",
+    },
+    schema: [],
+    messages: {
+      noInjectTitle: "Do not inject Angular's Title service. Use injectTitleBinding() from '@ethlete/core' instead.",
+      noInjectMeta: "Do not inject Angular's Meta service. Use injectMetaBinding() from '@ethlete/core' instead.",
+      noImportTitle:
+        "Do not import Title from '@angular/platform-browser'. Use injectTitleBinding() from '@ethlete/core' instead.",
+      noImportMeta:
+        "Do not import Meta from '@angular/platform-browser'. Use injectMetaBinding() from '@ethlete/core' instead.",
+    },
+  },
+  create(context) {
+    /**
+     * Returns the first argument identifier name of an inject() call, or null.
+     * @param {any} node - CallExpression
+     * @returns {string | null}
+     */
+    const injectTokenName = (node) => {
+      if (node.type !== 'CallExpression') return null;
+      if (node.callee.type !== 'Identifier' || node.callee.name !== 'inject') return null;
+      const firstArg = node.arguments[0];
+      if (!firstArg) return null;
+      if (firstArg.type === 'Identifier') return firstArg.name;
+      return null;
+    };
+
+    return {
+      // Detect: const x = inject(Title) / inject(Meta)
+      CallExpression(node) {
+        const token = injectTokenName(/** @type {any} */ (node));
+        if (token === 'Title') context.report({ node, messageId: 'noInjectTitle' });
+        if (token === 'Meta') context.report({ node, messageId: 'noInjectMeta' });
+      },
+
+      // Detect: import { Title, Meta } from '@angular/platform-browser'
+      ImportDeclaration(node) {
+        const decl = /** @type {any} */ (node);
+        if (decl.source.value !== '@angular/platform-browser') return;
+
+        for (const specifier of decl.specifiers) {
+          if (specifier.type !== 'ImportSpecifier') continue;
+          const imported = specifier.imported.name ?? specifier.imported.value;
+          if (imported === 'Title') context.report({ node: specifier, messageId: 'noImportTitle' });
+          if (imported === 'Meta') context.report({ node: specifier, messageId: 'noImportMeta' });
+        }
+      },
+    };
+  },
+};
+
+module.exports = rule;

package/src/rules/no-direct-dom-manipulation.js

@@ -0,0 +1,160 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows direct DOM manipulation methods. Use injectRenderer() from @ethlete/core instead.
+ *
+ * injectRenderer() is a fully-typed wrapper around Angular's Renderer2 that:
+ * - Works with server-side rendering (Angular Universal / SSR)
+ * - Works inside Web Workers
+ * - Is mockable in unit tests
+ * - Respects Angular's change detection lifecycle
+ *
+ * BAD:
+ *   this.document.createElement('div')      → renderer.createElement('div')
+ *   element.appendChild(child)              → renderer.appendChild(element, child)
+ *   element.setAttribute('disabled', '')    → renderer.setAttribute(element, 'disabled', '')
+ *   element.classList.add('active')         → renderer.addClass(element, 'active')
+ *   element.classList.remove('active')      → renderer.removeClass(element, 'active')
+ *   element.style.color = 'red'             → renderer.setStyle(element, 'color', 'red')
+ *
+ * GOOD:
+ *   private renderer = injectRenderer(); // from @ethlete/core
+ *
+ * NOTE: Calls where the receiver name contains 'renderer' (e.g. this.renderer.createElement)
+ * are excluded — that is the correct injectRenderer() usage.
+ */
+
+/**
+ * DOM creation methods and their Renderer2 equivalents.
+ * @type {Map<string, string>}
+ */
+const DOM_CREATE_METHODS = new Map([
+  ['createElement', 'renderer.createElement(tag, namespace?)'],
+  ['createTextNode', 'renderer.createText(value)'],
+  ['createComment', 'renderer.createComment(value)'],
+  ['createDocumentFragment', "renderer.createElement('div') and compose child nodes"],
+]);
+
+/**
+ * DOM mutation methods and their Renderer2 equivalents.
+ * @type {Map<string, string>}
+ */
+const DOM_MUTATION_METHODS = new Map([
+  ['appendChild', 'renderer.appendChild(parent, child)'],
+  ['removeChild', 'renderer.removeChild(parent, child)'],
+  ['insertBefore', 'renderer.insertBefore(parent, child, refNode)'],
+  ['replaceChild', 'renderer.insertBefore(parent, newChild, refNode) + renderer.removeChild(parent, oldChild)'],
+  ['setAttribute', 'renderer.setAttribute(el, name, value)'],
+  ['removeAttribute', 'renderer.removeAttribute(el, name)'],
+  ['toggleAttribute', 'renderer.setAttribute / renderer.removeAttribute with a condition'],
+  ['setProperty', 'renderer.setProperty(el, name, value)'],
+]);
+
+/**
+ * classList methods and their Renderer2 equivalents.
+ * @type {Map<string, string>}
+ */
+const CLASSLIST_METHODS = new Map([
+  ['add', 'renderer.addClass(el, className)'],
+  ['remove', 'renderer.removeClass(el, className)'],
+  ['toggle', 'renderer.addClass / renderer.removeClass with a condition'],
+  ['replace', 'renderer.removeClass(el, old) + renderer.addClass(el, new)'],
+]);
+
+/**
+ * Returns true when the receiver of a MemberExpression looks like a Renderer2 instance,
+ * which means the call is already using the correct API.
+ * @param {import('eslint').Rule.Node} objectNode
+ * @param {import('eslint').Rule.RuleContext} context
+ */
+const isRendererReceiver = (objectNode, context) => {
+  const receiverText = context.sourceCode.getText(objectNode).toLowerCase();
+  return receiverText.includes('renderer');
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noDirectDomManipulation = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: "Disallow direct DOM manipulation. Use injectRenderer() from '@ethlete/core' instead.",
+      recommended: true,
+    },
+    messages: {
+      domCreate: "Use '{{alternative}}' instead of '.{{method}}()'. Use injectRenderer() from '@ethlete/core'.",
+      domMutation: "Use '{{alternative}}' instead of '.{{method}}()'. Use injectRenderer() from '@ethlete/core'.",
+      domClassList:
+        "Use '{{alternative}}' instead of '.classList.{{method}}()'. Use injectRenderer() from '@ethlete/core'.",
+      domStyle:
+        "Use 'renderer.setStyle(el, prop, value)' instead of direct style property assignment. Use injectRenderer() from '@ethlete/core'.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+        if (callee.type !== 'MemberExpression') return;
+        if (callee.property.type !== 'Identifier') return;
+
+        const methodName = callee.property.name;
+
+        // ── classList.add / .remove / .toggle / .replace ─────────────────────
+        if (
+          callee.object.type === 'MemberExpression' &&
+          callee.object.property.type === 'Identifier' &&
+          callee.object.property.name === 'classList'
+        ) {
+          const alternative = CLASSLIST_METHODS.get(methodName);
+          if (alternative) {
+            context.report({
+              node,
+              messageId: 'domClassList',
+              data: { method: methodName, alternative },
+            });
+          }
+          return;
+        }
+
+        // Skip calls on a Renderer2 instance — those are the correct pattern.
+        if (isRendererReceiver(callee.object, context)) return;
+
+        // ── DOM creation ──────────────────────────────────────────────────────
+        if (DOM_CREATE_METHODS.has(methodName)) {
+          context.report({
+            node,
+            messageId: 'domCreate',
+            data: { method: methodName, alternative: DOM_CREATE_METHODS.get(methodName) },
+          });
+          return;
+        }
+
+        // ── DOM mutation ──────────────────────────────────────────────────────
+        if (DOM_MUTATION_METHODS.has(methodName)) {
+          context.report({
+            node,
+            messageId: 'domMutation',
+            data: { method: methodName, alternative: DOM_MUTATION_METHODS.get(methodName) },
+          });
+        }
+      },
+
+      // ── el.style.prop = value ─────────────────────────────────────────────
+      AssignmentExpression(node) {
+        const { left } = node;
+        if (
+          left.type === 'MemberExpression' &&
+          left.object.type === 'MemberExpression' &&
+          left.object.property.type === 'Identifier' &&
+          left.object.property.name === 'style' &&
+          !isRendererReceiver(left.object.object, context)
+        ) {
+          context.report({ node, messageId: 'domStyle' });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noDirectDomManipulation;

package/src/rules/no-document-cookie.js

@@ -0,0 +1,55 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows reading or writing 'document.cookie' directly.
+ *
+ * Direct access to document.cookie:
+ * - Returns / writes a raw semicolon-delimited string that is easy to misparse
+ * - Bypasses SSR guards (throws in non-browser environments)
+ * - Has no expiry, domain, path, or SameSite handling by default
+ *
+ * BAD:
+ *   document.cookie                              // read
+ *   document.cookie = 'name=value; path=/';      // write
+ *
+ * GOOD:
+ *   import { getCookie, setCookie, hasCookie, deleteCookie } from '@ethlete/core';
+ *   setCookie('name', 'value');
+ *   getCookie('name');
+ *   hasCookie('name');
+ *   deleteCookie('name');
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noDocumentCookie = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        "Disallow reading or writing 'document.cookie' directly. Use the cookie utilities from '@ethlete/core' instead.",
+      recommended: true,
+    },
+    messages: {
+      noDocumentCookie:
+        "Do not access 'document.cookie' directly. Use 'getCookie()', 'setCookie()', 'hasCookie()', or 'deleteCookie()' from '@ethlete/core' — they handle SSR, expiry, domain, path, and SameSite attributes safely.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (
+          node.object.type === 'Identifier' &&
+          node.object.name === 'document' &&
+          node.property.type === 'Identifier' &&
+          node.property.name === 'cookie'
+        ) {
+          context.report({ node, messageId: 'noDocumentCookie' });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noDocumentCookie;

package/src/rules/no-dom-query.js

@@ -0,0 +1,81 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows direct DOM query methods. Use Angular's viewChild() / viewChildren() signals instead.
+ *
+ * Direct DOM query methods bypass Angular's component model, break SSR, and are not declarative.
+ * Angular provides first-class query APIs that are reactive and work within the component lifecycle.
+ *
+ * BAD:
+ *   host.querySelector('[data-id]')          → viewChild('[data-id]')
+ *   host.querySelectorAll('.item')           → viewChildren('.item')
+ *   document.getElementById('my-id')        → viewChild('#my-id')
+ *   el.getElementsByClassName('foo')        → viewChildren('.foo')
+ *   el.closest('.parent')                   → inject(ElementRef) + traverse via Angular DI
+ *
+ * GOOD:
+ *   label = viewChild('labelRef');           // template: <span #labelRef>
+ *   items = viewChildren(ItemDirective);     // template: <et-item *ngFor="..." />
+ *   children = signalElementChildren(elementRef); // from @ethlete/core — reactive signal of child HTMLElements
+ *
+ * NOTE: In the rare case where a query is genuinely needed (e.g. third-party DOM),
+ * suppress with a targeted eslint-disable comment and document why.
+ */
+
+/**
+ * The banned DOM query method names and their Angular alternatives.
+ * @type {Map<string, string>}
+ */
+const DOM_QUERY_METHODS = new Map([
+  ['querySelector', 'viewChild() with a template reference variable, or signalElementChildren() from @ethlete/core'],
+  [
+    'querySelectorAll',
+    'viewChildren() / contentChildren() with a directive token, or signalElementChildren() from @ethlete/core for raw HTMLElement children',
+  ],
+  ['getElementById', 'viewChild() with a template reference variable (use #id on the element)'],
+  ['getElementsByClassName', 'viewChildren() with a directive token, or signalElementChildren() from @ethlete/core'],
+  [
+    'getElementsByTagName',
+    'viewChildren() with a directive / component token, or signalElementChildren() from @ethlete/core',
+  ],
+  ['getElementsByName', 'viewChildren() with a template reference variable'],
+  ['closest', 'inject(ParentDirective, { optional: true }) via Angular DI instead of DOM traversal'],
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noDomQuery = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: "Disallow direct DOM query methods. Use Angular's viewChild() / viewChildren() signals instead.",
+      recommended: true,
+    },
+    messages: {
+      noDomQuery:
+        "Avoid '{{method}}()'. Use {{alternative}} instead. Direct DOM queries bypass Angular's component model and break SSR.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+        if (callee.type !== 'MemberExpression') return;
+        if (callee.property.type !== 'Identifier') return;
+
+        const methodName = callee.property.name;
+        const alternative = DOM_QUERY_METHODS.get(methodName);
+        if (!alternative) return;
+
+        context.report({
+          node,
+          messageId: 'noDomQuery',
+          data: { method: methodName, alternative },
+        });
+      },
+    };
+  },
+};
+
+module.exports = noDomQuery;

package/src/rules/no-inject-chain.js

@@ -0,0 +1,44 @@
+// @ts-check
+'use strict';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noInjectChain = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow chaining member access directly off inject() calls.',
+      recommended: true,
+    },
+    messages: {
+      noChain:
+        'Do not chain off inject(). Assign to a const first: `const x = inject({{token}});` then use `x.{{member}}`.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        const obj = node.object;
+        if (obj.type === 'CallExpression' && obj.callee.type === 'Identifier' && obj.callee.name === 'inject') {
+          // Allow inject(X).method() — immediately-invoked patterns like
+          // inject(DestroyRef).onDestroy(...) are intentional Angular idioms.
+          const parent = node.parent;
+          if (parent && parent.type === 'CallExpression' && parent.callee === node) {
+            return;
+          }
+
+          const token = obj.arguments[0]?.type === 'Identifier' ? obj.arguments[0].name : '...';
+          const member = node.property.type === 'Identifier' ? node.property.name : '...';
+
+          context.report({
+            node,
+            messageId: 'noChain',
+            data: { token, member },
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noInjectChain;