[lint] unnecessary_underscores core implementation

(TODO: follow-up w/ improved documentation.)

Bug: #56595
Change-Id: I000ccf9012c659d7fbc942d8bc0fafce87dafc5a
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/403201
Reviewed-by: Brian Wilkerson <[email protected]>

Author: pq

pkg/analysis_server/lib/src/services/correction/error_fix_status.yaml

@@ -2455,6 +2455,8 @@ LintCode.unnecessary_this:
   status: hasFix
 LintCode.unnecessary_to_list_in_spreads:
   status: hasFix
+LintCode.unnecessary_underscores:
+  status: needsFix  
 LintCode.unreachable_from_main:
   status: hasFix
 LintCode.unrelated_type_equality_checks_in_expression:

pkg/analyzer/tool/diagnostics/diagnostics.md

@@ -29211,6 +29211,32 @@ List<String> toLowercase(List<String> strings) {
 }
 ```
 
+### unnecessary_underscores
+
+_Unnecessary use of multiple underscores._
+
+#### Description
+
+The analyzer produces this diagnostic when an unused variable is named
+with mutiple underscores (for example `__`). A single `_` wildcard variable
+can be used instead.
+
+#### Example
+
+The following code produces this diagnostic because the `__` parameter is unused:
+
+```dart
+void function(int [!__!]) { }
+```
+
+#### Common fixes
+
+Replace the name with a single underscore:
+
+```dart
+void function(int _) { }
+```
+
 ### unrelated_type_equality_checks
 
 _The type of the operand ('{0}') isn't a subtype or a supertype of the value

pkg/linter/CHANGELOG.md

@@ -1,5 +1,6 @@
 # 3.7.0-wip
 
+- new lint: `unnecessary_underscores`
 - removed lint: `package_api_docs`
 - removed lint: `unsafe_html`
 - _(soon to be)_ deprecated lint: `avoid_null_checks_in_equality_operators`

pkg/linter/example/all.yaml

@@ -205,6 +205,7 @@ linter:
     - unnecessary_string_interpolations
     - unnecessary_this
     - unnecessary_to_list_in_spreads
+    - unnecessary_underscores
     - unreachable_from_main
     - unrelated_type_equality_checks
     - unsafe_variance

pkg/linter/lib/src/lint_codes.g.dart

@@ -1757,6 +1757,12 @@ class LinterLintCode extends LintCode {
     hasPublishedDocs: true,
   );
 
+  static const LintCode unnecessary_underscores = LinterLintCode(
+    LintNames.unnecessary_underscores,
+    "Unnecessary use of multiple underscores.",
+    correctionMessage: "Try using '_'.",
+  );
+
   static const LintCode unreachable_from_main = LinterLintCode(
     LintNames.unreachable_from_main,
     "Unreachable member '{0}' in an executable library.",

pkg/linter/lib/src/lint_names.g.dart

@@ -541,6 +541,8 @@ abstract final class LintNames {
   static const String unnecessary_to_list_in_spreads =
       'unnecessary_to_list_in_spreads';
 
+  static const String unnecessary_underscores = 'unnecessary_underscores';
+
   static const String unreachable_from_main = 'unreachable_from_main';
 
   static const String unrelated_type_equality_checks =

pkg/linter/lib/src/rules.dart

@@ -223,6 +223,7 @@ import 'rules/unnecessary_string_escapes.dart';
 import 'rules/unnecessary_string_interpolations.dart';
 import 'rules/unnecessary_this.dart';
 import 'rules/unnecessary_to_list_in_spreads.dart';
+import 'rules/unnecessary_underscores.dart';
 import 'rules/unreachable_from_main.dart';
 import 'rules/unrelated_type_equality_checks.dart';
 import 'rules/unsafe_html.dart';
@@ -470,6 +471,7 @@ void registerLintRules() {
     ..registerLintRule(UnnecessaryStringInterpolations())
     ..registerLintRule(UnnecessaryThis())
     ..registerLintRule(UnnecessaryToListInSpreads())
+    ..registerLintRule(UnnecessaryUnderscores())
     ..registerLintRule(UnreachableFromMain())
     ..registerLintRule(UnrelatedTypeEqualityChecks())
     ..registerLintRule(UnsafeHtml())

pkg/linter/lib/src/rules/unnecessary_underscores.dart

@@ -0,0 +1,91 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:analyzer/dart/analysis/features.dart';
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:analyzer/dart/element/element2.dart';
+// ignore: implementation_imports
+import 'package:analyzer/src/utilities/extensions/collection.dart';
+
+import '../analyzer.dart';
+import '../extensions.dart';
+import '../util/ascii_utils.dart';
+
+const _desc = r'Unnecessary underscores can be removed.';
+
+class UnnecessaryUnderscores extends LintRule {
+  UnnecessaryUnderscores()
+      : super(
+          name: LintNames.unnecessary_underscores,
+          description: _desc,
+        );
+
+  @override
+  LintCode get lintCode => LinterLintCode.unnecessary_underscores;
+
+  @override
+  void registerNodeProcessors(
+      NodeLintRegistry registry, LinterContext context) {
+    if (!context.isEnabled(Feature.wildcard_variables)) return;
+    var visitor = _Visitor(this);
+    registry.addFormalParameterList(this, visitor);
+    registry.addVariableDeclaration(this, visitor);
+  }
+}
+
+class _BodyVisitor extends RecursiveAstVisitor<void> {
+  final Set<Element2> referencedElements = <Element2>{};
+
+  _BodyVisitor();
+
+  @override
+  void visitSimpleIdentifier(SimpleIdentifier node) {
+    referencedElements.addIfNotNull(node.element);
+  }
+}
+
+class _Visitor extends SimpleAstVisitor<void> {
+  final LintRule rule;
+
+  _Visitor(this.rule);
+
+  @override
+  void visitFormalParameterList(FormalParameterList node) {
+    late Set<Element2> referencedElements = collectReferences(node.parent);
+
+    for (var parameter in node.parameters) {
+      var element = parameter.declaredFragment?.element;
+      var name = element?.name3;
+      if (isJustUnderscores(name)) {
+        if (!referencedElements.contains(element)) {
+          rule.reportLintForToken(parameter.name);
+        }
+      }
+    }
+  }
+
+  @override
+  void visitVariableDeclaration(VariableDeclaration node) {
+    var element = node.declaredFragment?.element;
+    if (element is FieldElement2 || element is TopLevelVariableElement2) return;
+
+    if (isJustUnderscores(node.name.lexeme)) {
+      var parent = node.thisOrAncestorOfType<FunctionBody>();
+      if (!collectReferences(parent).contains(node.declaredFragment?.element)) {
+        rule.reportLintForToken(node.name);
+      }
+    }
+  }
+
+  static Set<Element2> collectReferences(AstNode? node) {
+    if (node == null) return {};
+    var visitor = _BodyVisitor();
+    node.accept(visitor);
+    return visitor.referencedElements;
+  }
+
+  static bool isJustUnderscores(String? name) =>
+      name != null && name.length > 1 && name.isJustUnderscores;
+}

pkg/linter/messages.yaml

@@ -13005,6 +13005,49 @@ LintCode:
         ...['foo', 'bar', 'baz'].map((String s) => Text(s)),
       ]
       ```
+  unnecessary_underscores:
+    problemMessage: "Unnecessary use of multiple underscores."
+    correctionMessage: "Try using '_'."
+    state:
+      experimental: "3.7"
+    categories: [brevity, style]
+    hasPublishedDocs: false
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when an unused variable is named
+      with mutiple underscores (for example `__`). A single `_` wildcard variable
+      can be used instead.
+
+      #### Example
+
+      The following code produces this diagnostic because the `__` parameter is unused:
+
+      ```dart
+      void function(int [!__!]) { }
+      ```
+
+      #### Common fixes
+
+      Replace the name with a single underscore:
+
+      ```dart
+      void function(int _) { }
+      ```
+    deprecatedDetails: |-
+      **AVOID** using multiple underscores when a single wildcard will do.
+
+      **BAD:**
+      ```dart
+      void function(int __) { }
+      ```
+
+      **GOOD:**
+      ```dart
+      void function(int _) { }
+      ```
+
+
   unreachable_from_main:
     problemMessage: "Unreachable member '{0}' in an executable library."
     correctionMessage: "Try referencing the member or removing it."

pkg/linter/test/rules/all.dart

@@ -286,6 +286,7 @@ import 'unnecessary_string_interpolations_test.dart'
 import 'unnecessary_this_test.dart' as unnecessary_this;
 import 'unnecessary_to_list_in_spreads_test.dart'
     as unnecessary_to_list_in_spreads;
+import 'unnecessary_underscores_test.dart' as unnecessary_underscores;
 import 'unreachable_from_main_test.dart' as unreachable_from_main;
 import 'unrelated_type_equality_checks_test.dart'
     as unrelated_type_equality_checks;
@@ -358,8 +359,8 @@ void main() {
   avoid_relative_lib_imports.main();
   avoid_renaming_method_parameters.main();
   avoid_return_types_on_setters.main();
-  avoid_returning_null.main();
   avoid_returning_null_for_void.main();
+  avoid_returning_null.main();
   avoid_returning_this.main();
   avoid_setters_without_getters.main();
   avoid_shadowing_type_parameters.main();
@@ -530,6 +531,7 @@ void main() {
   unnecessary_string_interpolations.main();
   unnecessary_this.main();
   unnecessary_to_list_in_spreads.main();
+  unnecessary_underscores.main();
   unreachable_from_main.main();
   unrelated_type_equality_checks.main();
   unsafe_variance.main();

pkg/linter/test/rules/unnecessary_underscores_test.dart

@@ -0,0 +1,131 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:test_reflective_loader/test_reflective_loader.dart';
+
+import '../rule_test_support.dart';
+
+main() {
+  defineReflectiveSuite(() {
+    defineReflectiveTests(UnnecessaryUnderscoresTest);
+  });
+}
+
+@reflectiveTest
+class UnnecessaryUnderscoresTest extends LintRuleTest {
+  @override
+  String get lintRule => 'unnecessary_underscores';
+
+  test_field_unused() async {
+    await assertDiagnostics(r'''
+class C {
+  int __ = 0;
+}
+''', [
+      // No lint.
+      error(WarningCode.UNUSED_FIELD, 16, 2),
+    ]);
+  }
+
+  test_forPart_unused() async {
+    await assertDiagnostics(r'''
+void f() {
+  for (var __ = 0; ; ) {}
+}
+''', [
+      lint(22, 2),
+    ]);
+  }
+
+  test_forPart_used() async {
+    await assertNoDiagnostics(r'''
+void f() {
+  for (var __ = 0; ; ++__) {}
+}
+''');
+  }
+
+  test_function_parameter_unused() async {
+    await assertDiagnostics(r'''
+void f(int _, int __) {}
+''', [
+      lint(18, 2),
+    ]);
+  }
+
+  test_function_parameter_unused_preWildcards() async {
+    await assertNoDiagnostics(r'''
+// @dart = 3.6
+
+void f(int _, int __) {} 
+''');
+  }
+
+  test_function_parameter_used() async {
+    await assertNoDiagnostics(r'''
+void f(int _, int __) {
+  print(__);
+} 
+''');
+  }
+
+  test_local_unused() async {
+    await assertDiagnostics(r'''
+void f() {
+  var __ = 0;
+}
+''', [
+      lint(17, 2),
+    ]);
+  }
+
+  test_local_used() async {
+    await assertNoDiagnostics(r'''
+void f() {
+  var __ = 0;
+  print(__);
+}
+''');
+  }
+
+  test_localFunction_unused() async {
+    await assertDiagnostics(r'''
+f() {
+  __() {}
+}
+''', [
+      // No lint.
+      error(WarningCode.UNUSED_ELEMENT, 8, 2),
+    ]);
+  }
+
+  test_method_unused() async {
+    await assertDiagnostics(r'''
+class A {
+  __() {}
+}
+''', [
+      // No lint.
+      error(WarningCode.UNUSED_ELEMENT, 12, 2),
+    ]);
+  }
+
+  test_topLevelFunction_unused() async {
+    await assertDiagnostics(r'''
+__() {}
+''', [
+      // No lint.
+      error(WarningCode.UNUSED_ELEMENT, 0, 2),
+    ]);
+  }
+
+  test_topLevelVariable_unused() async {
+    await assertDiagnostics(r'''
+int __ = 0;
+''', [
+      // No lint.
+      error(WarningCode.UNUSED_ELEMENT, 4, 2),
+    ]);
+  }
+}