analyzer: Warn about doc-import combinators and prefixes

Change-Id: I1104cc41198ce5e6db7cf01b089fc562380e8636
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/410445
Commit-Queue: Samuel Rawlins <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>
Reviewed-by: Konstantin Shcheglov <[email protected]>

Author: srawlins

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

@@ -3498,8 +3498,12 @@ WarningCode.DOC_DIRECTIVE_UNKNOWN:
   status: noFix
 WarningCode.DOC_IMPORT_CANNOT_BE_DEFERRED:
   status: needsFix
+WarningCode.DOC_IMPORT_CANNOT_HAVE_COMBINATORS:
+  status: needsFix
 WarningCode.DOC_IMPORT_CANNOT_HAVE_CONFIGURATIONS:
   status: needsFix
+WarningCode.DOC_IMPORT_CANNOT_HAVE_PREFIX:
+  status: needsFix
 WarningCode.DUPLICATE_EXPORT:
   status: needsFix
   notes: |-

pkg/analyzer/lib/src/error/codes.g.dart

@@ -6462,12 +6462,24 @@ class WarningCode extends ErrorCode {
     correctionMessage: "Try removing the 'deferred' keyword.",
   );
 
+  static const WarningCode DOC_IMPORT_CANNOT_HAVE_COMBINATORS = WarningCode(
+    'DOC_IMPORT_CANNOT_HAVE_COMBINATORS',
+    "Doc imports can't have show or hide combinators.",
+    correctionMessage: "Try removing the combinator.",
+  );
+
   static const WarningCode DOC_IMPORT_CANNOT_HAVE_CONFIGURATIONS = WarningCode(
     'DOC_IMPORT_CANNOT_HAVE_CONFIGURATIONS',
     "Doc imports can't have configurations.",
     correctionMessage: "Try removing the configurations.",
   );
 
+  static const WarningCode DOC_IMPORT_CANNOT_HAVE_PREFIX = WarningCode(
+    'DOC_IMPORT_CANNOT_HAVE_PREFIX',
+    "Doc imports can't have prefixes.",
+    correctionMessage: "Try removing the prefix.",
+  );
+
   ///  Duplicate exports.
   ///
   ///  No parameters.

pkg/analyzer/lib/src/error/doc_comment_verifier.dart

@@ -48,6 +48,28 @@ class DocCommentVerifier {
         errorCode: WarningCode.DOC_IMPORT_CANNOT_HAVE_CONFIGURATIONS,
       );
     }
+
+    // TODO(srawlins): Support combinators.
+    var combinators = docImport.import.combinators;
+    if (combinators.isNotEmpty) {
+      _errorReporter.atOffset(
+        offset: combinators.first.offset,
+        length: combinators.last.end - combinators.first.offset,
+        errorCode: WarningCode.DOC_IMPORT_CANNOT_HAVE_COMBINATORS,
+      );
+    }
+
+    // TODO(srawlins): Support prefixes. This was done temporarily with
+    // https://dart-review.googlesource.com/c/sdk/+/387861, but this was
+    // reverted as it increased memory usage.
+    var prefix = docImport.import.prefix;
+    if (prefix != null) {
+      _errorReporter.atOffset(
+        offset: prefix.offset,
+        length: prefix.end - prefix.offset,
+        errorCode: WarningCode.DOC_IMPORT_CANNOT_HAVE_PREFIX,
+      );
+    }
   }
 
   void validateArgumentCount(DocDirectiveTag tag) {

pkg/analyzer/lib/src/error/error_code_values.g.dart

@@ -999,7 +999,9 @@ const List<ErrorCode> errorCodeValues = [
   WarningCode.DOC_DIRECTIVE_MISSING_TWO_ARGUMENTS,
   WarningCode.DOC_DIRECTIVE_UNKNOWN,
   WarningCode.DOC_IMPORT_CANNOT_BE_DEFERRED,
+  WarningCode.DOC_IMPORT_CANNOT_HAVE_COMBINATORS,
   WarningCode.DOC_IMPORT_CANNOT_HAVE_CONFIGURATIONS,
+  WarningCode.DOC_IMPORT_CANNOT_HAVE_PREFIX,
   WarningCode.DUPLICATE_EXPORT,
   WarningCode.DUPLICATE_HIDDEN_NAME,
   WarningCode.DUPLICATE_IGNORE,

pkg/analyzer/messages.yaml

@@ -23749,10 +23749,18 @@ WarningCode:
     problemMessage: "Doc imports can't be deferred."
     correctionMessage: Try removing the 'deferred' keyword.
     hasPublishedDocs: false
+  DOC_IMPORT_CANNOT_HAVE_COMBINATORS:
+    problemMessage: "Doc imports can't have show or hide combinators."
+    correctionMessage: Try removing the combinator.
+    hasPublishedDocs: false
   DOC_IMPORT_CANNOT_HAVE_CONFIGURATIONS:
     problemMessage: "Doc imports can't have configurations."
     correctionMessage: Try removing the configurations.
     hasPublishedDocs: false
+  DOC_IMPORT_CANNOT_HAVE_PREFIX:
+    problemMessage: "Doc imports can't have prefixes."
+    correctionMessage: Try removing the prefix.
+    hasPublishedDocs: false
   DUPLICATE_EXPORT:
     problemMessage: Duplicate export.
     correctionMessage: Try removing all but one export of the library.

pkg/analyzer/test/src/diagnostics/doc_import_cannot_be_deferred_test.dart

@@ -21,12 +21,13 @@ class DocImportCannotBeDeferredTest extends PubPackageResolutionTest {
 class C {}
 ''', [
       error(WarningCode.DOC_IMPORT_CANNOT_BE_DEFERRED, 27, 8),
+      error(WarningCode.DOC_IMPORT_CANNOT_HAVE_PREFIX, 39, 4),
     ]);
   }
 
   test_notDeferred() async {
     await assertNoErrorsInCode('''
-/// @docImport 'dart:math' as math;
+/// @docImport 'dart:math';
 class C {}
 ''');
   }

pkg/analyzer/test/src/diagnostics/doc_import_cannot_have_combinators_test.dart

@@ -0,0 +1,33 @@
+// 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/src/error/codes.g.dart';
+import 'package:test_reflective_loader/test_reflective_loader.dart';
+
+import '../dart/resolution/context_collection_resolution.dart';
+
+void main() {
+  defineReflectiveSuite(() {
+    defineReflectiveTests(DocImportCannotHaveCombinatorsTest);
+  });
+}
+
+@reflectiveTest
+class DocImportCannotHaveCombinatorsTest extends PubPackageResolutionTest {
+  test_configurations() async {
+    await assertErrorsInCode('''
+/// @docImport 'dart:math' show max;
+class C {}
+''', [
+      error(WarningCode.DOC_IMPORT_CANNOT_HAVE_COMBINATORS, 27, 8),
+    ]);
+  }
+
+  test_noConfigurations() async {
+    await assertNoErrorsInCode('''
+/// @docImport 'dart:math';
+class C {}
+''');
+  }
+}

pkg/analyzer/test/src/diagnostics/doc_import_cannot_have_prefix_test.dart

@@ -0,0 +1,33 @@
+// 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/src/error/codes.g.dart';
+import 'package:test_reflective_loader/test_reflective_loader.dart';
+
+import '../dart/resolution/context_collection_resolution.dart';
+
+void main() {
+  defineReflectiveSuite(() {
+    defineReflectiveTests(DocImportCannotHavePrefixTest);
+  });
+}
+
+@reflectiveTest
+class DocImportCannotHavePrefixTest extends PubPackageResolutionTest {
+  test_configurations() async {
+    await assertErrorsInCode('''
+/// @docImport 'dart:math' as math;
+class C {}
+''', [
+      error(WarningCode.DOC_IMPORT_CANNOT_HAVE_PREFIX, 30, 4),
+    ]);
+  }
+
+  test_noConfigurations() async {
+    await assertNoErrorsInCode('''
+/// @docImport 'dart:math';
+class C {}
+''');
+  }
+}

pkg/analyzer/test/src/diagnostics/test_all.dart

@@ -201,8 +201,12 @@ import 'doc_directive_missing_two_arguments_test.dart'
     as doc_directive_missing_two_arguments;
 import 'doc_import_cannot_be_deferred_test.dart'
     as doc_import_cannot_be_deferred;
+import 'doc_import_cannot_have_combinators_test.dart'
+    as doc_import_cannot_have_combinators;
 import 'doc_import_cannot_have_configurations_test.dart'
     as doc_import_cannot_have_configurations;
+import 'doc_import_cannot_have_prefix_test.dart'
+    as doc_import_cannot_have_prefix;
 import 'duplicate_constructor_default_test.dart'
     as duplicate_constructor_default;
 import 'duplicate_constructor_name_test.dart' as duplicate_constructor_name;
@@ -1060,7 +1064,9 @@ main() {
     doc_directive_missing_three_arguments.main();
     doc_directive_missing_two_arguments.main();
     doc_import_cannot_be_deferred.main();
+    doc_import_cannot_have_combinators.main();
     doc_import_cannot_have_configurations.main();
+    doc_import_cannot_have_prefix.main();
     duplicate_constructor_default.main();
     duplicate_constructor_name.main();
     duplicate_definition.main();