feat: add prefer-enums-by-name rule (#919)

* feat: add prefer-enums-by-name rule

* chore: fix analyzer issues

* docs: add rule docs

* docs: update docs

Co-authored-by: Dmitry Krutskikh <dmitry.krutskikh@gmail.com>

Author: incendial

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 * feat: add static code diagnostic [`avoid-duplicate-exports`](https://dartcodemetrics.dev/docs/rules/common/avoid-duplicate-exports).
+* feat: add static code diagnostic [`prefer-enums-by-name`](https://dartcodemetrics.dev/docs/rules/common/prefer-enums-by-name).
 
 ## 4.17.0-dev.1
 

lib/src/analyzers/lint_analyzer/rules/rules_factory.dart

@@ -42,6 +42,7 @@ import 'rules_list/prefer_conditional_expressions/prefer_conditional_expressions
 import 'rules_list/prefer_const_border_radius/prefer_const_border_radius_rule.dart';
 import 'rules_list/prefer_correct_identifier_length/prefer_correct_identifier_length_rule.dart';
 import 'rules_list/prefer_correct_type_name/prefer_correct_type_name_rule.dart';
+import 'rules_list/prefer_enums_by_name/prefer_enums_by_name_rule.dart';
 import 'rules_list/prefer_extracting_callbacks/prefer_extracting_callbacks_rule.dart';
 import 'rules_list/prefer_first/prefer_first_rule.dart';
 import 'rules_list/prefer_immediate_return/prefer_immediate_return_rule.dart';
@@ -105,6 +106,7 @@ final _implementedRules = <String, Rule Function(Map<String, Object>)>{
   PreferCorrectIdentifierLengthRule.ruleId:
       PreferCorrectIdentifierLengthRule.new,
   PreferCorrectTypeNameRule.ruleId: PreferCorrectTypeNameRule.new,
+  PreferEnumsByNameRule.ruleId: PreferEnumsByNameRule.new,
   PreferExtractingCallbacksRule.ruleId: PreferExtractingCallbacksRule.new,
   PreferFirstRule.ruleId: PreferFirstRule.new,
   PreferImmediateReturnRule.ruleId: PreferImmediateReturnRule.new,

lib/src/analyzers/lint_analyzer/rules/rules_list/prefer_enums_by_name/prefer_enums_by_name_rule.dart

@@ -0,0 +1,46 @@
+// ignore_for_file: public_member_api_docs
+
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:analyzer/dart/element/element.dart';
+
+import '../../../../../utils/node_utils.dart';
+import '../../../lint_utils.dart';
+import '../../../models/internal_resolved_unit_result.dart';
+import '../../../models/issue.dart';
+import '../../../models/severity.dart';
+import '../../models/common_rule.dart';
+import '../../rule_utils.dart';
+
+part 'visitor.dart';
+
+class PreferEnumsByNameRule extends CommonRule {
+  static const ruleId = 'prefer-enums-by-name';
+  static const _warningMessage = 'Prefer using values.byName';
+
+  PreferEnumsByNameRule([Map<String, Object> config = const {}])
+      : super(
+          id: ruleId,
+          severity: readSeverity(config, Severity.style),
+          excludes: readExcludes(config),
+        );
+
+  @override
+  Iterable<Issue> check(InternalResolvedUnitResult source) {
+    final visitor = _Visitor();
+
+    source.unit.visitChildren(visitor);
+
+    return visitor.invocations
+        .map((invocation) => createIssue(
+              rule: this,
+              location: nodeLocation(
+                node: invocation,
+                source: source,
+                withCommentOrMetadata: false,
+              ),
+              message: _warningMessage,
+            ))
+        .toList(growable: false);
+  }
+}

lib/src/analyzers/lint_analyzer/rules/rules_list/prefer_enums_by_name/visitor.dart

@@ -0,0 +1,27 @@
+part of 'prefer_enums_by_name_rule.dart';
+
+class _Visitor extends RecursiveAstVisitor<void> {
+  final _invocations = <MethodInvocation>[];
+
+  Iterable<MethodInvocation> get invocations => _invocations;
+
+  @override
+  void visitMethodInvocation(MethodInvocation node) {
+    super.visitMethodInvocation(node);
+
+    final target = node.target;
+    if (target is PrefixedIdentifier) {
+      if (_isEnum(target.prefix) && _hasValuesTarget(target.identifier)) {
+        if (node.methodName.name == 'firstWhere') {
+          _invocations.add(node);
+        }
+      }
+    }
+  }
+
+  bool _isEnum(SimpleIdentifier prefix) =>
+      prefix.staticElement?.kind == ElementKind.ENUM;
+
+  bool _hasValuesTarget(SimpleIdentifier identifier) =>
+      identifier.name == 'values';
+}

test/src/analyzers/lint_analyzer/rules/rules_list/prefer_enums_by_name/examples/example.dart

@@ -0,0 +1,12 @@
+import 'dart:async';
+
+void main() async {
+  SomeEnums.values.byName('first');
+  // LINT
+  SomeEnums.values.firstWhere((element) => element.name == 'first');
+  // LINT
+  SomeEnums.values
+      .firstWhere((element) => element.name == 'second', orElse: () => null);
+}
+
+enum SomeEnums { first, second }

test/src/analyzers/lint_analyzer/rules/rules_list/prefer_enums_by_name/prefer_enums_by_name_rule_test.dart

@@ -0,0 +1,42 @@
+import 'package:dart_code_metrics/src/analyzers/lint_analyzer/models/severity.dart';
+import 'package:dart_code_metrics/src/analyzers/lint_analyzer/rules/rules_list/prefer_enums_by_name/prefer_enums_by_name_rule.dart';
+import 'package:test/test.dart';
+
+import '../../../../../helpers/rule_test_helper.dart';
+
+const _examplePath = 'prefer_enums_by_name/examples/example.dart';
+
+void main() {
+  group('PreferEnumsByNameRule', () {
+    test('initialization', () async {
+      final unit = await RuleTestHelper.resolveFromFile(_examplePath);
+      final issues = PreferEnumsByNameRule().check(unit);
+
+      RuleTestHelper.verifyInitialization(
+        issues: issues,
+        ruleId: 'prefer-enums-by-name',
+        severity: Severity.style,
+      );
+    });
+
+    test('reports about found issues', () async {
+      final unit = await RuleTestHelper.resolveFromFile(_examplePath);
+      final issues = PreferEnumsByNameRule().check(unit);
+
+      RuleTestHelper.verifyIssues(
+        issues: issues,
+        startLines: [6, 8],
+        startColumns: [3, 3],
+        locationTexts: [
+          "SomeEnums.values.firstWhere((element) => element.name == 'first')",
+          'SomeEnums.values\n'
+              "      .firstWhere((element) => element.name == 'second', orElse: () => null)",
+        ],
+        messages: [
+          'Prefer using values.byName',
+          'Prefer using values.byName',
+        ],
+      );
+    });
+  });
+}

website/docs/rules/common/no-magic-number.md

@@ -14,7 +14,7 @@ Warning
 
 Warns against using number literals outside of named constants or variables. Exceptions are made for common constants (by default: -1, 0 and 1) and for literals inside `DateTime` constructor as there is no way to create `const DateTime` and extracting each `int` argument to separate named constant is far too inconvenient.
 
-## Example {#example}
+### Example {#example}
 
 Bad:
 

website/docs/rules/common/no-object-declaration.md

@@ -12,7 +12,7 @@ Style
 
 Warns when a class member is declared with Object type.
 
-## Example {#example}
+### Example {#example}
 
 Bad:
 

website/docs/rules/common/prefer-enums-by-name.md

@@ -0,0 +1,32 @@
+# Prefer enums byName
+
+## Rule id {#rule-id}
+
+prefer-enums-by-name
+
+## Severity {#severity}
+
+Style
+
+## Description {#description}
+
+Since Dart 2.15 it's possible to use `byName` method on enum `values` prop instead of searching the value with `firstWhere`.
+
+**Note:** `byName` will throw an exception if the enum does not contain a value for the given name.
+
+### Example {#example}
+
+Bad:
+
+```dart
+// LINT
+final styleDefinition = StyleDefinition.values.firstWhere(
+  (def) => def.name == json['styleDefinition'],
+);
+```
+
+Good:
+
+```dart
+final styleDefinition = StyleDefinition.values.byName(json['styleDefinition']);
+```

website/docs/rules/overview.md

@@ -147,6 +147,10 @@ Rules configuration is [described here](../getting-started/configuration#configu
 
     Type name should only contain alphanumeric characters, start with an uppercase character and span between min-length and max-length characters in length.
 
+- [prefer-enums-by-name](./common/prefer-enums-by-name.md)
+
+    Since Dart 2.15 it's possible to use `byName` method on enum `values` prop instead of searching the value with `firstWhere`.
+
 - [prefer-first](./common/prefer-first.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success)
 
     Use `first` to gets the first element.