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

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-empty-angular-metadata-arrays.js

@@ -0,0 +1,104 @@
+// @ts-check
+'use strict';
+
+/** @typedef {'Component' | 'Directive'} TDecoratorName */
+
+/**
+ * @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 {import('eslint').Rule.Node} node
+ * @returns {TDecoratorName | null}
+ */
+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('eslint').SourceCode} sourceCode
+ * @param {any} metadata
+ * @param {any} property
+ */
+const getRemovalRange = (sourceCode, metadata, property) => {
+  const properties = metadata.properties.filter((entry) => entry.type === 'Property');
+  const propertyIndex = properties.indexOf(property);
+  const openingBrace = sourceCode.getFirstToken(metadata);
+  const closingBrace = sourceCode.getLastToken(metadata);
+
+  if (!openingBrace || !closingBrace) return property.range;
+  if (properties.length === 1) return [openingBrace.range[1], closingBrace.range[0]];
+  if (propertyIndex < properties.length - 1) return [property.range[0], properties[propertyIndex + 1].range[0]];
+
+  return [properties[propertyIndex - 1].range[1], property.range[1]];
+};
+
+const MESSAGE_IDS = {
+  hostDirectives: 'noEmptyHostDirectives',
+  imports: 'noEmptyImports',
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noEmptyAngularMetadataArrays = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow empty Angular metadata arrays such as imports: [] and hostDirectives: [].',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      noEmptyImports: 'Remove empty imports: [] from Angular metadata.',
+      noEmptyHostDirectives: 'Remove empty hostDirectives: [] from Angular metadata.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      /** @param {import('eslint').Rule.Node} node */
+      Decorator(node) {
+        const decoratorName = getDecoratorName(node);
+        if (decoratorName !== 'Component' && decoratorName !== 'Directive') 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 !== 'imports' && propertyName !== 'hostDirectives') continue;
+          if (property.value.type !== 'ArrayExpression' || property.value.elements.length > 0) continue;
+
+          context.report({
+            node: property,
+            messageId: MESSAGE_IDS[propertyName],
+            fix(fixer) {
+              return fixer.replaceTextRange(getRemovalRange(sourceCode, metadata, property), '');
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noEmptyAngularMetadataArrays;

package/src/rules/no-empty-newlines-between-imports.js

@@ -0,0 +1,45 @@
+// @ts-check
+'use strict';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noEmptyNewlinesBetweenImports = {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Disallow empty blank lines between consecutive import declarations.',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      noEmptyLine: 'Remove empty blank lines between import declarations.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      Program(node) {
+        const importDeclarations = node.body.filter((statement) => statement.type === 'ImportDeclaration');
+
+        for (let index = 1; index < importDeclarations.length; index += 1) {
+          const previousImport = importDeclarations[index - 1];
+          const currentImport = importDeclarations[index];
+          const textBetween = sourceCode.text.slice(previousImport.range[1], currentImport.range[0]);
+
+          if (/\S/.test(textBetween)) continue;
+          if (!/\n\s*\n/.test(textBetween)) continue;
+
+          context.report({
+            node: currentImport,
+            messageId: 'noEmptyLine',
+            fix(fixer) {
+              return fixer.replaceTextRange([previousImport.range[1], currentImport.range[0]], '\n');
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noEmptyNewlinesBetweenImports;

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;