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

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({

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

@@ -47,7 +47,6 @@ 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'"],
 ]);
@@ -81,47 +80,103 @@ const noAngularRouterApi = {
       isImportedAs(sourceCode, call.callee, 'inject') &&
       isImportedAs(sourceCode, call.arguments[0], token, ANGULAR_ROUTER);
 
+    /** @type {WeakMap<any, Set<string>>} */
+    const classRouterMembers = new WeakMap();
+
     /**
-     * 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>}
+     * @param {any} classBody
      */
-    const routerBindings = new Set();
+    const getClassRouterMembers = (classBody) => {
+      let members = classRouterMembers.get(classBody);
 
-    return {
-      // ── Track inject(Router) bindings ──────────────────────────────────────
-      // const router = inject(Router);
-      VariableDeclarator(node) {
-        if (isInjectOf(node.init, 'Router') && node.id.type === 'Identifier') {
-          routerBindings.add(node.id.name);
+      if (!members) {
+        members = new Set();
+
+        for (const member of classBody.body) {
+          if (member.type === 'PropertyDefinition' && member.key.type === 'Identifier' && !member.computed) {
+            if (isInjectOf(member.value, 'Router')) members.add(member.key.name);
+          }
         }
-      },
 
-      // ── Track class property assignments: router = inject(Router) ──────────
-      PropertyDefinition(node) {
-        if (isInjectOf(node.value, 'Router') && node.key.type === 'Identifier') {
-          routerBindings.add(node.key.name);
+        classRouterMembers.set(classBody, members);
+      }
+
+      return members;
+    };
+
+    /**
+     * @param {any} thisExpression
+     */
+    const getThisClassBody = (thisExpression) => {
+      let current = thisExpression.parent;
+
+      while (current) {
+        if (current.type === 'ClassBody') return current;
+
+        if (current.type === 'FunctionExpression' || current.type === 'FunctionDeclaration') {
+          const parent = current.parent;
+          const isMember = parent?.type === 'MethodDefinition' || parent?.type === 'PropertyDefinition';
+          if (!isMember) return null;
         }
-      },
 
-      // ── Detect router.{stateProp} access ───────────────────────────────────
+        current = current.parent;
+      }
+
+      return null;
+    };
+
+    /**
+     * @param {any} identifier
+     */
+    const isRouterVariable = (identifier) => {
+      /** @type {import('eslint').Scope.Scope | null} */
+      let scope = sourceCode.getScope(identifier);
+
+      while (scope) {
+        const variable = scope.set.get(identifier.name);
+
+        if (variable) {
+          const definition = /** @type {any} */ (variable.defs[0]);
+
+          return (
+            definition?.type === 'Variable' &&
+            definition.node.id.type === 'Identifier' &&
+            isInjectOf(definition.node.init, 'Router')
+          );
+        }
+
+        scope = scope.upper;
+      }
+
+      return false;
+    };
+
+    /**
+     * @param {any} object
+     */
+    const isRouterReference = (object) => {
+      if (object.type === 'Identifier') return isRouterVariable(object);
+
+      if (
+        object.type !== 'MemberExpression' ||
+        object.computed ||
+        object.object.type !== 'ThisExpression' ||
+        object.property.type !== 'Identifier'
+      ) {
+        return false;
+      }
+
+      const classBody = getThisClassBody(object.object);
+
+      return !!classBody && getClassRouterMembers(classBody).has(object.property.name);
+    };
+
+    return {
       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;
+        if (!isRouterReference(node.object)) return;
 
         context.report({
           node,
@@ -130,7 +185,6 @@ const noAngularRouterApi = {
         });
       },
 
-      // ── ActivatedRoute import ───────────────────────────────────────────────
       [MODULE_REFERENCE_SELECTOR](node) {
         const reference = getModuleReference(node);
         if (reference?.source !== ANGULAR_ROUTER) return;
@@ -139,7 +193,6 @@ const noAngularRouterApi = {
         }
       },
 
-      // ── inject(ActivatedRoute) ──────────────────────────────────────────────
       CallExpression(node) {
         if (isInjectOf(node, 'ActivatedRoute')) {
           context.report({ node, messageId: 'noActivatedRoute' });

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

@@ -36,6 +36,7 @@ const rule = {
     type: 'suggestion',
     docs: {
       description: "Disallow Angular's Title/Meta services. Use @ethlete/core SEO utilities instead.",
+      recommended: true,
     },
     schema: [],
     messages: {

package/src/rules/no-async-await.js

@@ -19,7 +19,7 @@
  *   }
  */
 
-/** Storybook's play function is called by the test runner and has to be a promise. */
+/** Storybook's play function is called by the test runner and has to be a promise; only exempt in story files. */
 const isStorybookPlayFunction = (node) => {
   const { parent } = node;
 
@@ -49,7 +49,11 @@ const noAsyncAwait = {
     schema: [],
   },
   create(context) {
+    const isStoryFile = /\.stories\.[cm]?[jt]sx?$/.test(context.filename);
+
     const isExempt = (node) => {
+      if (!isStoryFile) return false;
+
       for (let current = node; current; current = current.parent) {
         if (isStorybookPlayFunction(current)) return true;
       }

package/src/rules/no-cdk-import.js

@@ -26,17 +26,33 @@ const CDK_PACKAGE = '@ethlete/cdk';
 const MIGRATION_MAP = '@ethlete/cdk/migration-map.json';
 const DEFAULT_DOCS_BASE_URL = 'https://ethlete-sdk-docs.web.app';
 
-/** @type {Map<string, Record<string, { kind: string, to?: string, package?: string, docs?: string, note?: string }> | null>} */
+/** @typedef {Record<string, { kind: string, to?: string, package?: string, docs?: string, note?: string }>} TMigrationMap */
+
+/** @type {Map<string, { mtimeMs: number | null, map: TMigrationMap }>} */
 const mapCache = new Map();
 
+/**
+ * @param {string} path
+ */
+const getMtimeMs = (path) => {
+  try {
+    return fs.statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+};
+
 /**
  * @param {string | undefined} mapPath
  * @param {string} cwd
+ * @returns {TMigrationMap | null}
  */
 const loadMigrationMap = (mapPath, cwd) => {
-  const cacheKey = mapPath ? path.resolve(cwd, mapPath) : MIGRATION_MAP;
+  const cacheKey = mapPath ? path.resolve(cwd, mapPath) : `${cwd}:${MIGRATION_MAP}`;
+  const mtimeMs = mapPath ? getMtimeMs(cacheKey) : null;
+  const cached = mapCache.get(cacheKey);
 
-  if (mapCache.has(cacheKey)) return mapCache.get(cacheKey) ?? null;
+  if (cached && cached.mtimeMs === mtimeMs) return cached.map;
 
   let map;
 
@@ -45,14 +61,23 @@ const loadMigrationMap = (mapPath, cwd) => {
       ? JSON.parse(fs.readFileSync(cacheKey, 'utf8'))
       : createRequire(path.join(cwd, 'noop.js'))(MIGRATION_MAP);
   } catch {
-    map = null;
+    return null;
   }
 
-  mapCache.set(cacheKey, map);
+  mapCache.set(cacheKey, { mtimeMs, map });
 
   return map;
 };
 
+/**
+ * @param {string} note
+ */
+const formatNote = (note) => {
+  const sentence = note.charAt(0).toUpperCase() + note.slice(1);
+
+  return /[.!?]$/u.test(sentence) ? sentence : `${sentence}.`;
+};
+
 /** @type {import('eslint').Rule.RuleModule} */
 const noCdkImport = {
   meta: {
@@ -86,7 +111,7 @@ const noCdkImport = {
     const map = loadMigrationMap(options.migrationMapPath, context.cwd);
 
     /** @param {string} name */
-    const entryFor = (name) => map?.[name] ?? null;
+    const entryFor = (name) => (map && Object.hasOwn(map, name) ? map[name] : null);
 
     return {
       [MODULE_REFERENCE_SELECTOR](node) {
@@ -135,7 +160,7 @@ const noCdkImport = {
               to: entry.to,
               package: entry.package ?? '@ethlete/components',
               docs: entry.docs ? `${docsBaseUrl}${entry.docs}` : migrationDocs,
-              note: entry.note ? ` ${entry.note}.` : '',
+              note: entry.note ? ` ${formatNote(entry.note)}` : '',
             },
           });
         }