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

package/src/rules/angular-decorator-property-order.js

@@ -0,0 +1,217 @@
+// @ts-check
+'use strict';
+
+/** @typedef {'Component' | 'Directive'} TDecoratorName */
+/** @typedef {{ order: string[]; orderText: string }} TDecoratorConfig */
+/** @typedef {{ range: [number, number] }} TNodeWithRange */
+/** @typedef {import('estree').Property & TNodeWithRange} TPropertyNode */
+/** @typedef {import('estree').SpreadElement & TNodeWithRange} TSpreadElementNode */
+/** @typedef {import('estree').ObjectExpression & TNodeWithRange & { properties: Array<TPropertyNode | TSpreadElementNode> }} TObjectExpressionNode */
+/** @typedef {{ hasComma: boolean; originalIndex: number; orderIndex: number; property: TPropertyNode; segmentText: string }} TPropertyEntry */
+
+/** @type {Record<TDecoratorName, TDecoratorConfig>} */
+const DECORATOR_CONFIG = {
+  Component: {
+    order: [
+      'selector',
+      'template',
+      'styleUrl',
+      'encapsulation',
+      'changeDetection',
+      'imports',
+      'providers',
+      'viewProviders',
+      'animations',
+      'hostDirectives',
+      'host',
+      'styles',
+      'inputs',
+      'outputs',
+      'queries',
+      'preserveWhitespaces',
+      'standalone',
+      'schemas',
+      'jit',
+      'exportAs',
+    ],
+    orderText:
+      'selector, template/templateUrl, styleUrl/styleUrls, encapsulation, changeDetection, imports, providers, viewProviders, animations, hostDirectives, host, styles, inputs, outputs, queries, preserveWhitespaces, standalone, schemas, jit, exportAs',
+  },
+  Directive: {
+    order: [
+      'selector',
+      'exportAs',
+      'providers',
+      'inputs',
+      'outputs',
+      'queries',
+      'hostDirectives',
+      'host',
+      'standalone',
+      'jit',
+    ],
+    orderText: 'selector, exportAs, providers, inputs, outputs, queries, hostDirectives, host, standalone, jit',
+  },
+};
+
+/**
+ * @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 {string | null} propertyName
+ */
+const getOrderKey = (decoratorName, propertyName) => {
+  if (propertyName === null) return null;
+
+  if (decoratorName === 'Component') {
+    if (propertyName === 'template' || propertyName === 'templateUrl') return 'template';
+    if (propertyName === 'styleUrl' || propertyName === 'styleUrls') return 'styleUrl';
+  }
+
+  return propertyName;
+};
+
+/**
+ * @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;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const angularDecoratorPropertyOrder = {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Require a consistent property order in Angular @Component and @Directive metadata objects.',
+    },
+    fixable: 'code',
+    messages: {
+      outOfOrder: '{{decorator}} metadata properties should be ordered as: {{order}}.',
+    },
+    schema: [],
+  },
+  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 = /** @type {TObjectExpressionNode | undefined} */ (expression.arguments[0]);
+        if (!metadata || metadata.type !== 'ObjectExpression' || metadata.properties.length < 2) return;
+
+        if (
+          metadata.properties.some(
+            /** @param {TPropertyNode | TSpreadElementNode} property */ (property) => property.type !== 'Property',
+          )
+        )
+          return;
+
+        const config = DECORATOR_CONFIG[decoratorName];
+        const orderIndexMap = new Map(
+          config.order.map(/** @param {string} value @param {number} index */ (value, index) => [value, index]),
+        );
+        const openingBrace = sourceCode.getFirstToken(metadata);
+        const closingBrace = sourceCode.getLastToken(metadata);
+
+        if (!openingBrace || !closingBrace || openingBrace.value !== '{' || closingBrace.value !== '}') return;
+
+        let segmentStart = openingBrace.range[1];
+
+        const entries = metadata.properties.map(
+          /** @param {TPropertyNode | TSpreadElementNode} property @param {number} originalIndex @returns {TPropertyEntry} */
+          (property, originalIndex) => {
+            const propertyNode = /** @type {TPropertyNode} */ (property);
+            const propertyName = getPropertyName(propertyNode.key);
+            const orderKey = getOrderKey(decoratorName, propertyName);
+            const orderIndex =
+              orderKey === null ? config.order.length : (orderIndexMap.get(orderKey) ?? config.order.length);
+            const tokenAfter = sourceCode.getTokenAfter(propertyNode);
+            const hasComma = Boolean(tokenAfter && tokenAfter.type === 'Punctuator' && tokenAfter.value === ',');
+            const segmentEnd = hasComma && tokenAfter ? tokenAfter.range[0] : propertyNode.range[1];
+            const segmentText = sourceCode.text.slice(segmentStart, segmentEnd);
+
+            if (hasComma && tokenAfter) {
+              segmentStart = tokenAfter.range[1];
+            } else {
+              segmentStart = propertyNode.range[1];
+            }
+
+            return {
+              hasComma,
+              originalIndex,
+              orderIndex,
+              property: propertyNode,
+              segmentText,
+            };
+          },
+        );
+
+        const trailingComma = entries[entries.length - 1].hasComma;
+        const suffix = sourceCode.text.slice(segmentStart, closingBrace.range[0]);
+        const sortedEntries = [...entries].sort(
+          /** @param {TPropertyEntry} left @param {TPropertyEntry} right */ (left, right) => {
+            if (left.orderIndex !== right.orderIndex) return left.orderIndex - right.orderIndex;
+            return left.originalIndex - right.originalIndex;
+          },
+        );
+
+        const isSorted = entries.every(
+          /** @param {TPropertyEntry} entry @param {number} index */ (entry, index) =>
+            entry.property === sortedEntries[index].property,
+        );
+        if (isSorted) return;
+
+        const firstMismatch = entries.find(
+          /** @param {TPropertyEntry} entry @param {number} index */ (entry, index) =>
+            entry.property !== sortedEntries[index].property,
+        );
+
+        context.report({
+          node: firstMismatch ? firstMismatch.property : metadata,
+          messageId: 'outOfOrder',
+          data: {
+            decorator: `@${decoratorName}`,
+            order: config.orderText,
+          },
+          fix(fixer) {
+            const reorderedBody =
+              sortedEntries
+                .map(
+                  (entry, index) =>
+                    `${entry.segmentText}${index < sortedEntries.length - 1 || trailingComma ? ',' : ''}`,
+                )
+                .join('') + suffix;
+
+            return fixer.replaceTextRange([openingBrace.range[1], closingBrace.range[0]], reorderedBody);
+          },
+        });
+      },
+    };
+  },
+};
+
+module.exports = angularDecoratorPropertyOrder;

package/src/rules/enforce-routing-view-naming.js

@@ -0,0 +1,84 @@
+// @ts-check
+'use strict';
+
+/**
+ * Checks that a `loadComponent:` route property:
+ *  1. Imports from a path containing "-view"
+ *  2. Accesses a class name ending in "ViewComponent" in the .then() callback
+ *
+ * Valid pattern:
+ *   loadComponent: () => import('./items-list-view/items-list-view.component').then((m) => m.ItemsListViewComponent)
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const enforceRoutingViewNaming = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Routing components must import from a path containing "-view" and use a class name ending in "ViewComponent".',
+    },
+    messages: {
+      pathMustContainView: 'Routing import path must contain "-view". Got: "{{path}}".',
+      classMustEndWithViewComponent: 'Routing component class must end with "ViewComponent". Got: "{{name}}".',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      Property(node) {
+        const key = /** @type {any} */ (node).key;
+        if (key.type !== 'Identifier' || key.name !== 'loadComponent') return;
+
+        // Must be an arrow function: () => import(...).then(m => m.XxxViewComponent)
+        const arrow = /** @type {any} */ (node).value;
+        if (!arrow || arrow.type !== 'ArrowFunctionExpression') return;
+
+        const body = arrow.body;
+        if (!body || body.type !== 'CallExpression') return;
+
+        const callee = body.callee;
+        if (!callee || callee.type !== 'MemberExpression') return;
+        if (callee.property.type !== 'Identifier' || callee.property.name !== 'then') return;
+
+        // Check the import path contains "-view"
+        const importExpr = callee.object;
+        if (importExpr && importExpr.type === 'ImportExpression') {
+          const source = importExpr.source;
+          if (source && source.type === 'Literal' && typeof source.value === 'string') {
+            if (!source.value.includes('-view')) {
+              context.report({
+                node: source,
+                messageId: 'pathMustContainView',
+                data: { path: source.value },
+              });
+            }
+          }
+        }
+
+        // Check the class name in .then(m => m.XxxViewComponent)
+        const args = body.arguments;
+        if (!args || args.length === 0) return;
+
+        const callback = args[0];
+        if (!callback || callback.type !== 'ArrowFunctionExpression') return;
+
+        const cbBody = callback.body;
+        if (!cbBody || cbBody.type !== 'MemberExpression') return;
+
+        const prop = cbBody.property;
+        if (!prop || prop.type !== 'Identifier') return;
+
+        if (!prop.name.endsWith('ViewComponent')) {
+          context.report({
+            node: prop,
+            messageId: 'classMustEndWithViewComponent',
+            data: { name: prop.name },
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = enforceRoutingViewNaming;

package/src/rules/guard-return-newline.js

@@ -0,0 +1,81 @@
+// @ts-check
+'use strict';
+
+/**
+ * Enforces an empty line before a `return` statement that is the last statement
+ * in a multi-statement if-block (guard clause pattern).
+ *
+ * ❌ if (!allFilled) {
+ *      this.selectFirstUnfilledGuidedSlot();
+ *      return;
+ *    }
+ *
+ * ✅ if (!allFilled) {
+ *      this.selectFirstUnfilledGuidedSlot();
+ *
+ *      return;
+ *    }
+ *
+ * ✅ Single-line guards are exempt: if (!slot) return;
+ *
+ * @type {import('eslint').Rule.RuleModule}
+ */
+const rule = {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Require an empty line before a return in a multi-statement if-block (guard clause).',
+    },
+    fixable: 'whitespace',
+    schema: [],
+    messages: {
+      missingEmptyLine: 'Add an empty line before the return statement inside a multi-statement if-block.',
+    },
+  },
+  create(context) {
+    return {
+      ReturnStatement(node) {
+        const blockParent = node.parent;
+
+        // Must be directly inside a BlockStatement
+        if (!blockParent || blockParent.type !== 'BlockStatement') return;
+
+        // The block's parent must be an IfStatement's consequent
+        const ifStatement = blockParent.parent;
+        if (!ifStatement || ifStatement.type !== 'IfStatement') return;
+        if (ifStatement.consequent !== blockParent) return;
+
+        // Block must have more than one statement (multi-statement guard)
+        if (blockParent.body.length <= 1) return;
+
+        // The return must be the last statement in the block
+        if (blockParent.body[blockParent.body.length - 1] !== node) return;
+
+        const prevStatement = blockParent.body[blockParent.body.length - 2];
+
+        if (!node.loc || !prevStatement.loc) return;
+
+        const prevEndLine = prevStatement.loc.end.line;
+        const returnStartLine = node.loc.start.line;
+
+        // Need at least one empty line (gap of 2+ lines) between prev statement and return
+        if (returnStartLine - prevEndLine >= 2) return;
+
+        const sourceCode = context.sourceCode;
+
+        context.report({
+          node,
+          messageId: 'missingEmptyLine',
+          fix(fixer) {
+            const prevToken = sourceCode.getLastToken(/** @type {import('eslint').Rule.Node} */ (prevStatement));
+            if (!prevToken) return null;
+
+            return fixer.insertTextAfter(prevToken, '\n');
+          },
+        });
+      },
+    };
+  },
+};
+
+module.exports = rule;

package/src/rules/inject-member-accessibility.js

@@ -0,0 +1,286 @@
+// @ts-check
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @param {string} value
+ */
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * @param {any} decorator
+ */
+const getDecoratorCall = (decorator) => {
+  if (!decorator || decorator.type !== 'Decorator') return null;
+
+  const expression = decorator.expression;
+  if (expression.type !== 'CallExpression') return null;
+  if (expression.callee.type !== 'Identifier') return null;
+  if (expression.arguments.length === 0) return null;
+
+  const metadata = expression.arguments[0];
+  if (!metadata || metadata.type !== 'ObjectExpression') return null;
+
+  return {
+    name: expression.callee.name,
+    metadata,
+  };
+};
+
+/**
+ * @param {any} property
+ */
+const getPropertyKeyName = (property) => {
+  if (!property || property.computed) return null;
+
+  const key = property.key;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' && typeof key.value === 'string') return key.value;
+
+  return null;
+};
+
+/**
+ * @param {any} metadata
+ * @param {string} propertyName
+ */
+const getMetadataProperty = (metadata, propertyName) => {
+  for (const property of metadata.properties) {
+    if (!property || property.type !== 'Property' || property.computed) continue;
+
+    const keyName = getPropertyKeyName(property);
+
+    if (keyName === propertyName) {
+      return property;
+    }
+  }
+
+  return null;
+};
+
+/**
+ * @param {any} node
+ */
+const getStringValue = (node) => {
+  if (!node) return null;
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value;
+
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0 && node.quasis.length === 1) {
+    return node.quasis[0].value.cooked || '';
+  }
+
+  return null;
+};
+
+/**
+ * @param {string} filePath
+ */
+const readFileIfExists = (filePath) => {
+  try {
+    if (fs.existsSync(filePath)) {
+      return fs.readFileSync(filePath, 'utf8');
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+};
+
+/**
+ * @param {string} memberName
+ * @param {string | null} template
+ */
+const templateReferencesMember = (memberName, template) => {
+  if (!template) return false;
+
+  const escapedName = escapeRegExp(memberName);
+  const patterns = [
+    new RegExp(`\\{\\{[\\s\\S]*?\\b${escapedName}\\b[\\s\\S]*?\\}\\}`, 'u'),
+    new RegExp(`@[a-zA-Z]+\\s*\\([\\s\\S]*?\\b${escapedName}\\b[\\s\\S]*?\\)`, 'u'),
+    new RegExp(`\\[[^\\]]+\\]\\s*=\\s*"[^"]*\\b${escapedName}\\b[^"]*"`, 'u'),
+    new RegExp(`\\[[^\\]]+\\]\\s*=\\s*'[^']*\\b${escapedName}\\b[^']*'`, 'u'),
+    new RegExp(`\\([^\\)]+\\)\\s*=\\s*"[^"]*\\b${escapedName}\\b[^"]*"`, 'u'),
+    new RegExp(`\\([^\\)]+\\)\\s*=\\s*'[^']*\\b${escapedName}\\b[^']*'`, 'u'),
+  ];
+
+  return patterns.some((pattern) => pattern.test(template));
+};
+
+/**
+ * @param {string | null} keyName
+ */
+const isDynamicHostBindingKey = (keyName) => {
+  if (!keyName) return false;
+
+  return keyName.startsWith('[') || keyName.startsWith('(') || keyName.startsWith('@');
+};
+
+/**
+ * @param {any} classNode
+ * @param {import('eslint').Rule.RuleContext} context
+ */
+const getAngularMetadata = (classNode, context) => {
+  for (const decorator of classNode.decorators || []) {
+    const call = getDecoratorCall(decorator);
+    if (!call) continue;
+
+    if (call.name === 'Component' || call.name === 'Directive') {
+      return call;
+    }
+  }
+
+  return null;
+};
+
+/**
+ * @param {string} memberName
+ * @param {string | null} text
+ */
+const textReferencesMember = (memberName, text) => {
+  if (!text) return false;
+
+  const pattern = new RegExp(`\\b${escapeRegExp(memberName)}\\b`, 'u');
+  return pattern.test(text);
+};
+
+/**
+ * @param {string} memberName
+ * @param {any} metadata
+ * @param {import('eslint').Rule.RuleContext} context
+ */
+const isReferencedFromTemplateOrHost = (memberName, metadata, context) => {
+  const templateProperty = getMetadataProperty(metadata, 'template');
+  if (templateProperty && templateReferencesMember(memberName, getStringValue(templateProperty.value))) {
+    return true;
+  }
+
+  const templateUrlProperty = getMetadataProperty(metadata, 'templateUrl');
+  if (templateUrlProperty) {
+    const templateUrl = getStringValue(templateUrlProperty.value);
+    if (templateUrl) {
+      const templatePath = path.resolve(path.dirname(context.filename), templateUrl);
+      const templateText = readFileIfExists(templatePath);
+      if (templateReferencesMember(memberName, templateText)) {
+        return true;
+      }
+    }
+  }
+
+  const hostProperty = getMetadataProperty(metadata, 'host');
+  if (hostProperty && hostProperty.value.type === 'ObjectExpression') {
+    for (const property of hostProperty.value.properties) {
+      if (!property || property.type !== 'Property') continue;
+      if (!isDynamicHostBindingKey(getPropertyKeyName(property))) continue;
+
+      if (textReferencesMember(memberName, getStringValue(property.value))) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+};
+
+/**
+ * @param {any} node
+ */
+const isInjectCall = (node) => {
+  if (!node || node.type !== 'PropertyDefinition' || !node.value) return false;
+  if (node.value.type !== 'CallExpression') return false;
+  return node.value.callee.type === 'Identifier' && node.value.callee.name === 'inject';
+};
+
+/**
+ * @param {any} node
+ */
+const getMemberName = (node) => {
+  if (node.key.type === 'Identifier') return node.key.name;
+  if (node.key.type === 'Literal' && typeof node.key.value === 'string') return node.key.value;
+  return null;
+};
+
+/**
+ * @param {any} node
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {'private' | 'protected'} expectedAccessibility
+ */
+const buildFix = (node, sourceCode, expectedAccessibility) => {
+  const keyToken = sourceCode.getFirstToken(node.key);
+  if (!keyToken) return null;
+
+  if (node.accessibility) {
+    const firstToken = sourceCode.getFirstToken(node);
+    if (!firstToken) return null;
+
+    return (fixer) => fixer.replaceText(firstToken, expectedAccessibility);
+  }
+
+  return (fixer) => fixer.insertTextBefore(keyToken, `${expectedAccessibility} `);
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const injectMemberAccessibility = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require injected class members to be private by default, and protected when referenced from an Angular template or host binding.',
+      recommended: true,
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      shouldBePrivate:
+        'Injected member `{{name}}` should be private. Use protected only when it is referenced from a template or host binding.',
+      shouldBeProtected:
+        'Injected member `{{name}}` should be protected because it is referenced from a template or host binding.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      PropertyDefinition(node) {
+        if (!isInjectCall(node)) return;
+
+        const classNode = node.parent && node.parent.type === 'ClassBody' ? node.parent.parent : null;
+        if (!classNode || (classNode.type !== 'ClassDeclaration' && classNode.type !== 'ClassExpression')) return;
+
+        const memberName = getMemberName(node);
+        if (!memberName) return;
+
+        const angularMetadata = getAngularMetadata(classNode, context);
+        const isTemplateOrHostVisible = angularMetadata
+          ? isReferencedFromTemplateOrHost(memberName, angularMetadata.metadata, context)
+          : false;
+
+        if (isTemplateOrHostVisible) {
+          if (node.accessibility === 'protected') return;
+
+          context.report({
+            node,
+            messageId: 'shouldBeProtected',
+            data: { name: memberName },
+            fix: buildFix(node, sourceCode, 'protected'),
+          });
+
+          return;
+        }
+
+        if (node.accessibility === 'private' || node.accessibility === 'public') return;
+
+        context.report({
+          node,
+          messageId: 'shouldBePrivate',
+          data: { name: memberName },
+          fix: buildFix(node, sourceCode, 'private'),
+        });
+      },
+    };
+  },
+};
+
+module.exports = injectMemberAccessibility;