@ethlete/eslint-plugin 1.0.0-next.24 → 1.0.0-next.26

package/src/rules/consistent-type-definitions.js

@@ -0,0 +1,60 @@
+// @ts-check
+'use strict';
+
+const { rules } = require('@typescript-eslint/eslint-plugin');
+
+const upstream = rules['consistent-type-definitions'];
+
+/**
+ * `@typescript-eslint/consistent-type-definitions` with `'type'`, except that an interface inside a
+ * `declare module`, `declare global` or `namespace` block is left alone.
+ *
+ * Only an interface merges into an existing declaration. The upstream fix turns
+ * `declare module '@ethlete/core' { interface EthleteColorThemeNameRegistry { … } }` into a type
+ * alias, which merges into nothing, and under `skipLibCheck` the registration disappears without an
+ * error.
+ *
+ * BAD:
+ *   interface User { name: string }
+ *
+ * GOOD:
+ *   type User = { name: string };
+ *
+ *   declare module '@ethlete/core' {
+ *     interface EthleteColorThemeNameRegistry { name: 'brand' }
+ *   }
+ */
+
+const isInsideModuleDeclaration = (sourceCode, node) =>
+  sourceCode.getAncestors(node).some((ancestor) => ancestor.type === 'TSModuleDeclaration');
+
+/** @type {import('eslint').Rule.RuleModule} */
+const consistentTypeDefinitions = {
+  meta: {
+    ...upstream.meta,
+    docs: {
+      description:
+        'Use `type` instead of `interface`, except for an interface that augments a module or the global scope.',
+      recommended: true,
+    },
+    schema: [],
+  },
+  create(context) {
+    const { sourceCode } = context;
+
+    const filteredContext = Object.create(context, {
+      options: { value: ['type'] },
+      report: {
+        value: (descriptor) => {
+          if ('node' in descriptor && isInsideModuleDeclaration(sourceCode, descriptor.node)) return;
+
+          context.report(descriptor);
+        },
+      },
+    });
+
+    return upstream.create(filteredContext);
+  },
+};
+
+module.exports = consistentTypeDefinitions;

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

@@ -10,6 +10,8 @@
  *   loadComponent: () => import('./items-list-view/items-list-view.component').then((m) => m.ItemsListViewComponent)
  */
 
+const VIEW_PATH = /-view(?![\w-])/;
+
 /** @type {import('eslint').Rule.RuleModule} */
 const enforceRoutingViewNaming = {
   meta: {
@@ -17,6 +19,7 @@ const enforceRoutingViewNaming = {
     docs: {
       description:
         'Routing components must import from a path containing "-view" and use a class name ending in "ViewComponent".',
+      recommended: true,
     },
     messages: {
       pathMustContainView: 'Routing import path must contain "-view". Got: "{{path}}".',
@@ -25,48 +28,56 @@ const enforceRoutingViewNaming = {
     schema: [],
   },
   create(context) {
+    /** @param {any} importExpr */
+    const checkImportPath = (importExpr) => {
+      if (!importExpr || importExpr.type !== 'ImportExpression') return;
+
+      const source = importExpr.source;
+      if (source && source.type === 'Literal' && typeof source.value === 'string' && !VIEW_PATH.test(source.value)) {
+        context.report({
+          node: source,
+          messageId: 'pathMustContainView',
+          data: { path: source.value },
+        });
+      }
+    };
+
     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;
+        if (!body) return;
+
+        if (body.type === 'ImportExpression') {
+          checkImportPath(body);
+          return;
+        }
+
+        if (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;
+        checkImportPath(callee.object);
 
-        const callback = args[0];
+        const callback = body.arguments?.[0];
         if (!callback || callback.type !== 'ArrowFunctionExpression') return;
 
         const cbBody = callback.body;
-        if (!cbBody || cbBody.type !== 'MemberExpression') return;
+        const returned =
+          cbBody?.type === 'BlockStatement'
+            ? cbBody.body.find(/** @param {any} statement */ (statement) => statement.type === 'ReturnStatement')
+                ?.argument
+            : cbBody;
+        if (!returned || returned.type !== 'MemberExpression') return;
 
-        const prop = cbBody.property;
+        const prop = returned.property;
         if (!prop || prop.type !== 'Identifier') return;
 
         if (!prop.name.endsWith('ViewComponent')) {

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

@@ -25,6 +25,7 @@ const rule = {
     type: 'layout',
     docs: {
       description: 'Require an empty line before a return in a multi-statement if-block (guard clause).',
+      recommended: true,
     },
     fixable: 'whitespace',
     schema: [],
@@ -37,18 +38,14 @@ const rule = {
       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];
@@ -56,11 +53,11 @@ const rule = {
         if (!node.loc || !prevStatement.loc) return;
 
         const prevEndLine = prevStatement.loc.end.line;
-        const returnStartLine = node.loc.start.line;
+        const sourceCode = context.sourceCode;
 
-        if (returnStartLine - prevEndLine >= 2) return;
+        const textBetween = sourceCode.text.slice(prevStatement.range[1], node.range[0]);
 
-        const sourceCode = context.sourceCode;
+        if (/\n[ \t]*\r?\n/.test(textBetween)) return;
 
         context.report({
           node,

package/src/rules/internals/angular-member-visibility.js

@@ -92,6 +92,28 @@ const readFileIfExists = (filePath) => {
   return null;
 };
 
+/** @type {WeakMap<import('eslint').SourceCode, Map<string, string | null>>} */
+const TEMPLATE_TEXT_CACHE = new WeakMap();
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {string} templatePath
+ */
+const readTemplateText = (sourceCode, templatePath) => {
+  let templates = TEMPLATE_TEXT_CACHE.get(sourceCode);
+
+  if (!templates) {
+    templates = new Map();
+    TEMPLATE_TEXT_CACHE.set(sourceCode, templates);
+  }
+
+  if (!templates.has(templatePath)) {
+    templates.set(templatePath, readFileIfExists(templatePath));
+  }
+
+  return templates.get(templatePath) ?? null;
+};
+
 /**
  * @param {import('eslint').Rule.RuleContext} context
  */
@@ -183,7 +205,7 @@ const isReferencedFromTemplateOrHostMetadata = (memberName, metadata, context) =
 
     if (templateUrl && filename) {
       const templatePath = path.resolve(path.dirname(filename), templateUrl);
-      const templateText = readFileIfExists(templatePath);
+      const templateText = readTemplateText(context.sourceCode, templatePath);
       if (templateReferencesMember(memberName, templateText)) {
         return true;
       }
@@ -209,7 +231,7 @@ const isReferencedFromTemplateOrHostMetadata = (memberName, metadata, context) =
  * @param {any} node
  */
 const getMemberName = (node) => {
-  if (node.key?.type === 'Identifier') return node.key.name;
+  if (node.key?.type === 'Identifier' && !node.computed) return node.key.name;
   if (node.key?.type === 'Literal' && typeof node.key.value === 'string') return node.key.value;
 
   return null;

package/src/rules/internals/angular-metadata-fix.js

@@ -1,6 +1,236 @@
 // @ts-check
 'use strict';
 
+const { ANGULAR_CORE, getImportLocalName, resolveIdentifier } = require('./import-resolution');
+
+/** @typedef {{ property: string; importName: string; member: string }} TRequiredEnumProperty */
+
+const COMPONENT_ORDER = ['selector', 'template', 'styleUrl', 'encapsulation', 'changeDetection'];
+
+/**
+ * @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 {string | null} propertyName
+ */
+const getOrderKey = (propertyName) => {
+  if (propertyName === 'template' || propertyName === 'templateUrl') return 'template';
+  if (propertyName === 'styleUrl' || propertyName === 'styleUrls') return 'styleUrl';
+  return propertyName;
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {import('eslint').AST.Token | import('eslint').Rule.Node} node
+ */
+const getIndent = (sourceCode, node) => {
+  if (!node.loc) return '';
+
+  const line = sourceCode.lines[node.loc.start.line - 1] ?? '';
+  return line.slice(0, node.loc.start.column);
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} property
+ */
+const hasTrailingComma = (sourceCode, property) => {
+  const tokenAfter = sourceCode.getTokenAfter(property);
+  return Boolean(tokenAfter && tokenAfter.type === 'Punctuator' && tokenAfter.value === ',');
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {string} importName
+ */
+const findAngularCoreImport = (sourceCode, importName) => {
+  const imports = sourceCode.ast.body.filter(
+    (node) =>
+      node.type === 'ImportDeclaration' && node.source.type === 'Literal' && node.source.value === '@angular/core',
+  );
+
+  return (
+    imports.find((node) =>
+      node.specifiers.some(
+        (specifier) =>
+          specifier.type === 'ImportSpecifier' &&
+          specifier.imported.type === 'Identifier' &&
+          specifier.imported.name === importName,
+      ),
+    ) ??
+    imports.find((node) => node.importKind !== 'type') ??
+    null
+  );
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} importNode
+ * @param {string} importName
+ */
+const buildAngularCoreImportFix = (sourceCode, importNode, importName) => {
+  const specifiers = importNode.specifiers ?? [];
+  const hasImport = specifiers.some(
+    (specifier) =>
+      specifier.type === 'ImportSpecifier' &&
+      specifier.imported.type === 'Identifier' &&
+      specifier.imported.name === importName,
+  );
+  if (hasImport) return null;
+
+  const defaultSpecifier = specifiers.find((specifier) => specifier.type === 'ImportDefaultSpecifier') ?? null;
+  const namespaceSpecifier = specifiers.find((specifier) => specifier.type === 'ImportNamespaceSpecifier') ?? null;
+  const namedSpecifiers = specifiers.filter((specifier) => specifier.type === 'ImportSpecifier');
+
+  if (namespaceSpecifier) {
+    return (fixer) => fixer.insertTextAfter(importNode, `\nimport { ${importName} } from '@angular/core';`);
+  }
+
+  const lastNamed = namedSpecifiers.at(-1);
+
+  if (lastNamed) {
+    const isMultiline = importNode.loc.start.line !== importNode.loc.end.line;
+    const indent = /^\s*/.exec(sourceCode.lines[lastNamed.loc.start.line - 1] ?? '')?.[0] ?? '';
+    const startsLine = sourceCode.lines[lastNamed.loc.start.line - 1].trim().startsWith(sourceCode.getText(lastNamed));
+
+    return (fixer) =>
+      fixer.insertTextAfter(lastNamed, isMultiline && startsLine ? `,\n${indent}${importName}` : `, ${importName}`);
+  }
+
+  const importParts = [];
+  if (defaultSpecifier) {
+    importParts.push(sourceCode.getText(defaultSpecifier));
+  }
+
+  const namedTexts = namedSpecifiers.map((specifier) => sourceCode.getText(specifier));
+  importParts.push(`{ ${[...namedTexts, importName].join(', ')} }`);
+
+  return (fixer) => fixer.replaceText(importNode, `import ${importParts.join(', ')} from '@angular/core';`);
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {string} importName
+ */
+const buildMissingAngularCoreImportFix = (sourceCode, importName) => {
+  const importDeclarations = sourceCode.ast.body.filter((node) => node.type === 'ImportDeclaration');
+  const lastImport = importDeclarations[importDeclarations.length - 1] ?? null;
+
+  if (lastImport) {
+    return (fixer) => fixer.insertTextAfter(lastImport, `\nimport { ${importName} } from '@angular/core';`);
+  }
+
+  const firstNode = sourceCode.ast.body[0];
+  const lastComment = firstNode ? sourceCode.getCommentsBefore(firstNode).at(-1) : null;
+
+  return lastComment
+    ? (fixer) => fixer.insertTextAfter(lastComment, `\nimport { ${importName} } from '@angular/core';\n`)
+    : (fixer) =>
+        fixer.replaceTextRange([0, firstNode?.range[0] ?? 0], `import { ${importName} } from '@angular/core';\n\n`);
+};
+
+/**
+ * @param {any} metadata
+ * @param {string} propertyKey
+ */
+const getInsertionTarget = (metadata, propertyKey) => {
+  if (metadata.properties.some((property) => property.type === 'SpreadElement')) return null;
+
+  const anchorIndex = COMPONENT_ORDER.indexOf(propertyKey);
+
+  return (
+    metadata.properties.find((property) => {
+      if (property.type !== 'Property') return false;
+
+      const propertyName = getOrderKey(getPropertyName(property.key));
+      const propertyIndex = propertyName === null ? COMPONENT_ORDER.length : COMPONENT_ORDER.indexOf(propertyName);
+      return propertyIndex > anchorIndex || propertyIndex === -1;
+    }) ?? null
+  );
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} metadata
+ * @param {TRequiredEnumProperty} spec
+ */
+const buildMetadataFix = (sourceCode, metadata, spec) => {
+  const propertyText = `${spec.property}: ${getImportLocalName(sourceCode, ANGULAR_CORE, spec.importName) ?? spec.importName}.${spec.member}`;
+  const properties = metadata.properties;
+  const insertionTarget = getInsertionTarget(metadata, spec.property);
+  const isMultiline = Boolean(metadata.loc && metadata.loc.start.line !== metadata.loc.end.line);
+
+  if (properties.length === 0) {
+    return (fixer) => fixer.replaceText(metadata, `{ ${propertyText} }`);
+  }
+
+  if (insertionTarget) {
+    if (isMultiline) {
+      const propertyIndent = getIndent(sourceCode, insertionTarget);
+      return (fixer) => fixer.insertTextBefore(insertionTarget, `${propertyText},\n${propertyIndent}`);
+    }
+
+    return (fixer) => fixer.insertTextBefore(insertionTarget, `${propertyText}, `);
+  }
+
+  const lastProperty = properties[properties.length - 1];
+  const closingBrace = sourceCode.getLastToken(metadata);
+  if (!lastProperty || !closingBrace) return null;
+
+  if (isMultiline) {
+    const closingIndent = getIndent(sourceCode, closingBrace);
+    const propertyIndent = getIndent(sourceCode, lastProperty);
+    const separator = hasTrailingComma(sourceCode, lastProperty) ? '' : ',';
+    const rangeStart =
+      separator === ''
+        ? (sourceCode.getTokenAfter(lastProperty)?.range[1] ?? lastProperty.range[1])
+        : lastProperty.range[1];
+
+    return (fixer) =>
+      fixer.replaceTextRange(
+        [rangeStart, closingBrace.range[0]],
+        `${separator}\n${propertyIndent}${propertyText}\n${closingIndent}`,
+      );
+  }
+
+  const separator = hasTrailingComma(sourceCode, lastProperty) ? '' : ',';
+  return (fixer) =>
+    fixer.replaceTextRange([lastProperty.range[1], closingBrace.range[0]], `${separator} ${propertyText} `);
+};
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {any} metadata
+ * @param {any} valueNode
+ * @param {TRequiredEnumProperty} spec
+ */
+const buildRequiredEnumFix = (sourceCode, metadata, valueNode, spec) => {
+  const valueFix =
+    valueNode &&
+    ((/** @type {import('eslint').Rule.RuleFixer} */ fixer) => fixer.replaceText(valueNode.property, spec.member));
+  if (valueNode && valueNode.object.type !== 'Identifier') return valueFix;
+  if (valueNode && resolveIdentifier(sourceCode, valueNode.object)?.source) return valueFix;
+
+  const fixes = [];
+  const angularCoreImport = findAngularCoreImport(sourceCode, spec.importName);
+  const importFix = angularCoreImport
+    ? buildAngularCoreImportFix(sourceCode, angularCoreImport, spec.importName)
+    : buildMissingAngularCoreImportFix(sourceCode, spec.importName);
+
+  if (importFix) fixes.push(importFix);
+
+  const metadataFix = valueFix ?? buildMetadataFix(sourceCode, metadata, spec);
+  if (metadataFix) fixes.push(metadataFix);
+
+  return (/** @type {import('eslint').Rule.RuleFixer} */ fixer) => fixes.map((applyFix) => applyFix(fixer));
+};
+
 /**
  * @param {import('eslint').SourceCode} sourceCode
  * @param {any} metadata
@@ -19,4 +249,4 @@ const getMetadataEntryRemovalRange = (sourceCode, metadata, property) => {
   return [entries[index - 1].range[1], property.range[1]];
 };
 
-module.exports = { getMetadataEntryRemovalRange };
+module.exports = { buildRequiredEnumFix, getMetadataEntryRemovalRange, getPropertyName };

package/src/rules/internals/angular-version.js

@@ -0,0 +1,50 @@
+// @ts-check
+'use strict';
+
+const path = require('node:path');
+
+/** @type {Map<string, number | null>} */
+const cachedByDirectory = new Map();
+
+/**
+ * @param {string} directory
+ * @returns {number | null}
+ */
+const detectAngularMajor = (directory) => {
+  const cached = cachedByDirectory.get(directory);
+  if (cached !== undefined) return cached;
+
+  let result;
+
+  try {
+    const pkg = require(require.resolve('@angular/core/package.json', { paths: [directory, __dirname] }));
+    const major = Number.parseInt(String(pkg.version).split('.')[0], 10);
+    result = Number.isNaN(major) ? null : major;
+  } catch {
+    result = null;
+  }
+
+  cachedByDirectory.set(directory, result);
+
+  return result;
+};
+
+/**
+ * The Angular major installed next to the linted file (falling back to the plugin's own resolution).
+ * `settings.ethlete.angularMajor` wins over detection.
+ *
+ * @param {import('eslint').Rule.RuleContext} context
+ * @returns {number | null}
+ */
+const getAngularMajor = (context) => {
+  const settings = /** @type {any} */ (context.settings);
+  const override = settings?.ethlete?.angularMajor;
+  if (typeof override === 'number') return override;
+
+  const filename = context.filename;
+  const directory = filename && path.isAbsolute(filename) ? path.dirname(filename) : process.cwd();
+
+  return detectAngularMajor(directory);
+};
+
+module.exports = { getAngularMajor };

package/src/rules/internals/implemented-contract-members.js

@@ -5,9 +5,21 @@ const fs = require('fs');
 const path = require('path');
 const ts = require('typescript');
 
-/** @type {Map<string, import('typescript').SourceFile | null>} */
+/** @type {Map<string, { stamp: string, sourceFile: import('typescript').SourceFile | null }>} */
 const SOURCE_FILE_CACHE = new Map();
 
+/**
+ * @param {string} filePath
+ */
+const getFileStamp = (filePath) => {
+  try {
+    const stats = fs.statSync(filePath);
+    return `${stats.mtimeMs}:${stats.size}`;
+  } catch {
+    return 'missing';
+  }
+};
+
 /**
  * @param {string} filePath
  */
@@ -31,19 +43,18 @@ const getSourceFile = ({ filePath, text = null }) => {
     return ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
   }
 
-  if (SOURCE_FILE_CACHE.has(filePath)) {
-    return SOURCE_FILE_CACHE.get(filePath) ?? null;
+  const stamp = getFileStamp(filePath);
+  const cached = SOURCE_FILE_CACHE.get(filePath);
+
+  if (cached && cached.stamp === stamp) {
+    return cached.sourceFile;
   }
 
   const fileText = readFileIfExists(filePath);
+  const sourceFile =
+    fileText === null ? null : ts.createSourceFile(filePath, fileText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
 
-  if (fileText === null) {
-    SOURCE_FILE_CACHE.set(filePath, null);
-    return null;
-  }
-
-  const sourceFile = ts.createSourceFile(filePath, fileText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  SOURCE_FILE_CACHE.set(filePath, sourceFile);
+  SOURCE_FILE_CACHE.set(filePath, { stamp, sourceFile });
   return sourceFile;
 };
 
@@ -257,6 +268,10 @@ const collectMemberNamesForTypeByName = ({
  * @param {{ classNode: any, context: import('eslint').Rule.RuleContext }} config
  */
 const getImplementedContractMemberNames = ({ classNode, context }) => {
+  if (!classNode.implements?.length) {
+    return new Set();
+  }
+
   const filename = context.physicalFilename || context.filename;
   if (!filename || filename === '<input>' || filename === '<text>') {
     return new Set();
@@ -270,7 +285,7 @@ const getImplementedContractMemberNames = ({ classNode, context }) => {
   /** @type {Set<string>} */
   const memberNames = new Set();
 
-  for (const implementedType of classNode.implements || []) {
+  for (const implementedType of classNode.implements) {
     if (!implementedType.expression || implementedType.expression.type !== 'Identifier') continue;
 
     const typeMemberNames = collectMemberNamesForTypeByName({