@ethlete/eslint-plugin 0.1.0-beta.5

package/src/rules/class-member-order.js

@@ -0,0 +1,431 @@
+// @ts-check
+'use strict';
+
+/** @typedef {'inject' | 'input' | 'output' | 'query' | 'property' | 'constructor' | 'method' | 'private-method'} TMemberGroup */
+/** @typedef {{ dependencies: Set<string>; group: TMemberGroup; groupIndex: number; name: string; node: any; originalIndex: number }} TMemberEntry */
+/** @typedef {TMemberEntry & { segmentText: string }} TSegmentEntry */
+
+const INPUT_APIS = new Set(['input', 'model']);
+const OUTPUT_APIS = new Set(['output', 'outputFromObservable']);
+const QUERY_APIS = new Set(['viewChild', 'viewChildren', 'contentChild', 'contentChildren']);
+
+/** @type {TMemberGroup[]} */
+const MEMBER_GROUP_ORDER = [
+  'inject',
+  'input',
+  'output',
+  'query',
+  'property',
+  'constructor',
+  'method',
+  'private-method',
+];
+
+const MEMBER_GROUP_ORDER_TEXT =
+  'inject() members, inputs/model(), outputs, view/content queries, other properties, constructor, public methods, private methods';
+
+const MEMBER_GROUP_INDEX = new Map(
+  MEMBER_GROUP_ORDER.map(/** @param {TMemberGroup} group @param {number} index */ (group, index) => [group, index]),
+);
+
+/**
+ * @param {any} key
+ */
+const getMemberNameFromKey = (key) => {
+  if (!key) return null;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' && typeof key.value === 'string') return key.value;
+  if (key.type === 'PrivateIdentifier') return key.name;
+
+  return null;
+};
+
+/**
+ * @param {any} node
+ */
+const getMemberName = (node) => {
+  if (node.type === 'MethodDefinition' && node.kind === 'constructor') {
+    return 'constructor';
+  }
+
+  return getMemberNameFromKey(node.key);
+};
+
+/**
+ * @param {any} value
+ */
+const getCallRootName = (value) => {
+  if (!value || value.type !== 'CallExpression') return null;
+
+  const { callee } = value;
+
+  if (callee.type === 'Identifier') {
+    return callee.name;
+  }
+
+  if (callee.type === 'MemberExpression' && !callee.computed && callee.object.type === 'Identifier') {
+    return callee.object.name;
+  }
+
+  return null;
+};
+
+/**
+ * @param {any} node
+ * @param {Set<string>} apiNames
+ */
+const isPropertyInitializedWith = (node, apiNames) => {
+  if (node.type !== 'PropertyDefinition') return false;
+
+  const apiName = getCallRootName(node.value);
+  return apiName !== null && apiNames.has(apiName);
+};
+
+/**
+ * @param {any} node
+ * @returns {TMemberGroup | null}
+ */
+const getMemberGroup = (node) => {
+  if (node.static) return null;
+
+  if (node.type === 'PropertyDefinition') {
+    if (isPropertyInitializedWith(node, new Set(['inject']))) {
+      return 'inject';
+    }
+
+    if (isPropertyInitializedWith(node, INPUT_APIS)) {
+      return 'input';
+    }
+
+    if (isPropertyInitializedWith(node, OUTPUT_APIS)) {
+      return 'output';
+    }
+
+    if (isPropertyInitializedWith(node, QUERY_APIS)) {
+      return 'query';
+    }
+
+    return 'property';
+  }
+
+  if (node.type === 'MethodDefinition') {
+    if (node.kind === 'constructor') {
+      return 'constructor';
+    }
+
+    if (node.accessibility === 'private') {
+      return 'private-method';
+    }
+
+    return 'method';
+  }
+
+  return null;
+};
+
+/**
+ * @param {any} node
+ * @param {Set<string>} references
+ */
+const collectThisReferences = (node, references) => {
+  if (!node || typeof node !== 'object') return;
+
+  if (Array.isArray(node)) {
+    for (const entry of node) {
+      collectThisReferences(entry, references);
+    }
+
+    return;
+  }
+
+  if (
+    node.type === 'MemberExpression' &&
+    !node.computed &&
+    node.object?.type === 'ThisExpression' &&
+    (node.property?.type === 'Identifier' || node.property?.type === 'PrivateIdentifier')
+  ) {
+    references.add(node.property.name);
+  }
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'parent' || key === 'range' || key === 'loc') continue;
+    if (!value || typeof value !== 'object') continue;
+
+    collectThisReferences(value, references);
+  }
+};
+
+/**
+ * @param {any} node
+ */
+const getInitializerDependencies = (node) => {
+  if (node.type !== 'PropertyDefinition' || !node.value) {
+    return new Set();
+  }
+
+  const dependencies = new Set();
+  collectThisReferences(node.value, dependencies);
+
+  const memberName = getMemberName(node);
+
+  if (memberName !== null) {
+    dependencies.delete(memberName);
+  }
+
+  return dependencies;
+};
+
+/**
+ * @param {any} node
+ * @param {number} originalIndex
+ * @returns {TMemberEntry | null}
+ */
+const toMemberEntry = (node, originalIndex) => {
+  const group = getMemberGroup(node);
+  const name = getMemberName(node);
+
+  if (group === null || name === null) {
+    return null;
+  }
+
+  return {
+    dependencies: getInitializerDependencies(node),
+    group,
+    groupIndex: MEMBER_GROUP_INDEX.get(group),
+    name,
+    node,
+    originalIndex,
+  };
+};
+
+/**
+ * @param {TMemberEntry} currentMember
+ * @param {TMemberEntry} earlierMember
+ */
+const getOrderingConflict = (currentMember, earlierMember) => {
+  if (currentMember.dependencies.has(earlierMember.name)) {
+    return null;
+  }
+
+  if (earlierMember.dependencies.has(currentMember.name)) {
+    return {
+      type: 'dependency',
+      blockingMember: earlierMember,
+    };
+  }
+
+  if (currentMember.groupIndex < earlierMember.groupIndex) {
+    return {
+      type: 'group',
+      blockingMember: earlierMember,
+    };
+  }
+
+  return null;
+};
+
+/**
+ * @param {TMemberEntry[]} members
+ */
+const sortMembers = (members) => {
+  /** @type {TMemberEntry[]} */
+  const remainingMembers = [...members];
+  /** @type {TMemberEntry[]} */
+  const sortedMembers = [];
+
+  while (remainingMembers.length > 0) {
+    const readyMembers = remainingMembers
+      .filter((member) =>
+        [...member.dependencies].every(
+          (dependencyName) => !remainingMembers.some((remainingMember) => remainingMember.name === dependencyName),
+        ),
+      )
+      .sort((left, right) => {
+        if (left.groupIndex !== right.groupIndex) {
+          return left.groupIndex - right.groupIndex;
+        }
+
+        return left.originalIndex - right.originalIndex;
+      });
+
+    const nextMember = readyMembers[0];
+
+    if (!nextMember) {
+      return null;
+    }
+
+    sortedMembers.push(nextMember);
+
+    const nextMemberIndex = remainingMembers.indexOf(nextMember);
+    remainingMembers.splice(nextMemberIndex, 1);
+  }
+
+  return sortedMembers;
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} classBodyNode
+ * @param {TMemberEntry[]} members
+ */
+const getSegmentEntries = (sourceCode, classBodyNode, members) => {
+  const openingBrace = sourceCode.getFirstToken(classBodyNode);
+  const closingBrace = sourceCode.getLastToken(classBodyNode);
+
+  if (!openingBrace || !closingBrace || openingBrace.value !== '{' || closingBrace.value !== '}') {
+    return null;
+  }
+
+  let segmentStart = openingBrace.range[1];
+
+  const segmentEntries = members.map((member) => {
+    const segmentText = sourceCode.text.slice(segmentStart, member.node.range[1]);
+    segmentStart = member.node.range[1];
+
+    return {
+      ...member,
+      segmentText,
+    };
+  });
+
+  const suffix = sourceCode.text.slice(segmentStart, closingBrace.range[0]);
+
+  return {
+    closingBrace,
+    openingBrace,
+    segmentEntries,
+    suffix,
+  };
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} classBodyNode
+ * @param {TMemberEntry[]} members
+ */
+const buildClassOrderFix = (sourceCode, classBodyNode, members) => {
+  if (classBodyNode.body.length !== members.length) {
+    return null;
+  }
+
+  const sortedMembers = sortMembers(members);
+
+  if (!sortedMembers) {
+    return null;
+  }
+
+  const segments = getSegmentEntries(sourceCode, classBodyNode, members);
+
+  if (!segments) {
+    return null;
+  }
+
+  const { closingBrace, openingBrace, segmentEntries, suffix } = segments;
+  const segmentEntriesByOriginalIndex = new Map(
+    segmentEntries.map(
+      /** @param {TSegmentEntry} segmentEntry */ (segmentEntry) => [segmentEntry.originalIndex, segmentEntry],
+    ),
+  );
+  const sortedSegmentEntries = sortedMembers.map((member) => segmentEntriesByOriginalIndex.get(member.originalIndex));
+
+  if (sortedSegmentEntries.some((entry) => entry === undefined)) {
+    return null;
+  }
+
+  const isAlreadySorted = sortedSegmentEntries.every((entry, index) => entry === segmentEntries[index]);
+
+  if (isAlreadySorted) {
+    return null;
+  }
+
+  const reorderedBody = sortedSegmentEntries.map((entry) => entry.segmentText).join('') + suffix;
+
+  return (fixer) => fixer.replaceTextRange([openingBrace.range[1], closingBrace.range[0]], reorderedBody);
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const classMemberOrder = {
+  meta: {
+    type: 'layout',
+    fixable: 'code',
+    docs: {
+      description:
+        'Require class members to follow the styleguide order for inject members, inputs, outputs, queries, properties, constructor, and methods.',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      dependencyOrder:
+        "'{{name}}' should be declared before '{{dependentName}}' because '{{dependentName}}' references it in an initializer.",
+      groupOrder:
+        "'{{name}}' should be declared before '{{blockingName}}'. Class members should be ordered as: {{order}}.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      ClassBody(node) {
+        const members = node.body
+          .map(
+            /** @param {any} member @param {number} originalIndex */ (member, originalIndex) =>
+              toMemberEntry(member, originalIndex),
+          )
+          .filter(Boolean);
+
+        if (members.length < 2) {
+          return;
+        }
+
+        const fix = buildClassOrderFix(sourceCode, node, members);
+        let hasAttachedFix = false;
+
+        for (let currentIndex = 1; currentIndex < members.length; currentIndex++) {
+          const currentMember = members[currentIndex];
+
+          for (let earlierIndex = currentIndex - 1; earlierIndex >= 0; earlierIndex--) {
+            const earlierMember = members[earlierIndex];
+            const conflict = getOrderingConflict(currentMember, earlierMember);
+
+            if (!conflict) {
+              continue;
+            }
+
+            if (conflict.type === 'dependency') {
+              context.report({
+                node: currentMember.node,
+                messageId: 'dependencyOrder',
+                data: {
+                  name: currentMember.name,
+                  dependentName: conflict.blockingMember.name,
+                },
+                fix: !hasAttachedFix ? fix : null,
+              });
+
+              hasAttachedFix = hasAttachedFix || Boolean(fix);
+
+              break;
+            }
+
+            context.report({
+              node: currentMember.node,
+              messageId: 'groupOrder',
+              data: {
+                name: currentMember.name,
+                blockingName: conflict.blockingMember.name,
+                order: MEMBER_GROUP_ORDER_TEXT,
+              },
+              fix: !hasAttachedFix ? fix : null,
+            });
+
+            hasAttachedFix = hasAttachedFix || Boolean(fix);
+
+            break;
+          }
+        }
+      },
+    };
+  },
+};
+
+module.exports = classMemberOrder;

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,93 @@
+// @ts-check
+'use strict';
+
+const { getMemberName, isReferencedFromTemplateOrHost } = require('./internals/angular-member-visibility');
+
+/**
+ * @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
+ * @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, protected when referenced from an Angular template or host binding, and allow explicit public when intentionally exposing an external API.',
+      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. Use public only when it intentionally exposes an external API across class boundaries.',
+    },
+  },
+  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 isTemplateOrHostVisible = isReferencedFromTemplateOrHost(classNode, memberName, context);
+
+        if (isTemplateOrHostVisible) {
+          if (node.accessibility === 'protected' || node.accessibility === 'public') 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;