Add a custom lint to sanity check the analyzer public API.

The new lint, called `analyzer_public_api`, verifies that the analyzer
public API satisfies the following properties:

- No method, function, getter, setter, or supertype in the public API
  refers to a non-public type.

- No `export` declaration in the public API shows a non-public name.

- No declaration in the public API has a name ending in `Impl`.

- No file in the public API has a `part` declaration that points to a
  file that's not in the public API. (If it did, then the other checks
  could be circumvented.)

A new annotation is added, `@AnalyzerPublicApi()`, allowing
declarations in `package:analyzer/src` or
`package:_fe_analyzer_shared/src` to be marked as part of the analyzer
public API. This is necessary because some parts of the analyzer
public API need to be declared elsewhere and then exported by the
analyzer.

A few lint violations have been ignored using `ignore:` comments. I
will try to clean these up in follow-up CLs.

Fixes #60058.

Bug: #60058
Change-Id: I0047a73dec8a29e2ffe03dd3a90f7e41ca2e27b6
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/409763
Reviewed-by: Brian Wilkerson <[email protected]>
Reviewed-by: Johnni Winther <[email protected]>
Commit-Queue: Paul Berry <[email protected]>

Author: stereotype441

pkg/_fe_analyzer_shared/analysis_options.yaml

@@ -6,6 +6,7 @@ include: analysis_options_no_lints.yaml
 
 linter:
   rules:
+    - analyzer_public_api
     - annotate_overrides
     - collection_methods_unrelated_type
     - curly_braces_in_flow_control_structures

pkg/_fe_analyzer_shared/lib/src/base/analyzer_public_api.dart

@@ -0,0 +1,27 @@
+// 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.
+
+/// Annotation for top level elements within a library that are part of the
+/// analyzer's public API, even though they might not appear to be (e.g., due to
+/// being implemented inside a `src` directory but re-exported in `lib`, or due
+/// to being a supertype of a public type).
+///
+/// This annotation is intended to be used inside the `src` subdirectories of
+/// the `_fe_analyzer_shared` and `analyzer` packages.
+///
+/// Applying this annotation to an element lets developers know that
+/// modifications to the element should be carefully reviewed for backward
+/// compatibility, and to make sure they don't unduly expose private
+/// implementation details.
+///
+/// The `analyzer_public_api` lint rules use this annotation to tell:
+/// - Which elements are safe to export in the analyzer's `lib` directory
+/// - Which classes and mixins are safe to use as supertypes of a public type
+class AnalyzerPublicApi {
+  /// Explanation of why this element is part of the public API, in spite of not
+  /// being in the analyzer's `lib` folder.
+  final String message;
+
+  const AnalyzerPublicApi({required this.message});
+}

pkg/_fe_analyzer_shared/lib/src/base/errors.dart

@@ -4,12 +4,15 @@
 
 import 'dart:math';
 
+import 'package:_fe_analyzer_shared/src/base/analyzer_public_api.dart';
+
 import 'customized_codes.dart';
 
 /// An error code associated with an `AnalysisError`.
 ///
 /// Generally, messages should follow the [Guide for Writing
 /// Diagnostics](https://github.com/dart-lang/sdk/blob/main/pkg/front_end/lib/src/base/diagnostics.md).
+@AnalyzerPublicApi(message: 'exported by package:analyzer/error/error.dart')
 abstract class ErrorCode {
   /// Regular expression for identifying positional arguments in error messages.
   static final RegExp _positionalArgumentRegExp = new RegExp(r'{(\d+)\}');
@@ -117,6 +120,7 @@ abstract class ErrorCode {
 /**
  * The severity of an [ErrorCode].
  */
+@AnalyzerPublicApi(message: 'exported by package:analyzer/error/error.dart')
 class ErrorSeverity implements Comparable<ErrorSeverity> {
   /**
    * The severity representing a non-error. This is never used for any error
@@ -189,6 +193,7 @@ class ErrorSeverity implements Comparable<ErrorSeverity> {
 /**
  * The type of an [ErrorCode].
  */
+@AnalyzerPublicApi(message: 'exported by package:analyzer/error/error.dart')
 class ErrorType implements Comparable<ErrorType> {
   /**
    * Task (todo) comments in user code.

pkg/_fe_analyzer_shared/lib/src/base/syntactic_entity.dart

@@ -2,10 +2,14 @@
 // 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:_fe_analyzer_shared/src/base/analyzer_public_api.dart';
+
 /**
  * Interface representing a syntactic entity (either a token or an AST node)
  * which has a location and extent in the source file.
  */
+@AnalyzerPublicApi(
+    message: 'exported by package:analyzer/dart/ast/syntactic_entity.dart')
 abstract class SyntacticEntity {
   /**
    * Return the offset from the beginning of the file to the character after the

pkg/_fe_analyzer_shared/lib/src/scanner/token.dart

@@ -2,6 +2,8 @@
 // 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:_fe_analyzer_shared/src/base/analyzer_public_api.dart';
+
 /**
  * Defines the tokens that are produced by the scanner, used by the parser, and
  * referenced from the [AST structure](ast.dart).
@@ -68,6 +70,7 @@ class BeginToken extends SimpleToken {
 /**
  * A token representing a comment.
  */
+@AnalyzerPublicApi(message: 'exported by package:analyzer/dart/ast/token.dart')
 class CommentToken extends StringToken {
   /**
    * The token that contains this comment.
@@ -92,6 +95,7 @@ class DocumentationCommentToken extends CommentToken {
   DocumentationCommentToken(super.type, super.value, super.offset);
 }
 
+@AnalyzerPublicApi(message: 'exposed by Keyword.keywordStyle')
 enum KeywordStyle {
   reserved,
   builtIn,
@@ -103,6 +107,7 @@ enum KeywordStyle {
  *
  * Clients may not extend, implement or mix-in this class.
  */
+@AnalyzerPublicApi(message: 'exported by package:analyzer/dart/ast/token.dart')
 class Keyword extends TokenType {
   static const Keyword ABSTRACT = const Keyword(
       /* index = */ 82, "abstract", "ABSTRACT", KeywordStyle.builtIn,
@@ -501,6 +506,7 @@ class KeywordToken extends SimpleToken {
  * A specialized comment token representing a language version
  * (e.g. '// @dart = 2.1').
  */
+@AnalyzerPublicApi(message: 'exported by package:analyzer/dart/ast/token.dart')
 class LanguageVersionToken extends CommentToken {
   /**
    * The major language version.
@@ -520,6 +526,8 @@ class LanguageVersionToken extends CommentToken {
  * A token that was scanned from the input. Each token knows which tokens
  * precede and follow it, acting as a link in a doubly linked list of tokens.
  */
+@AnalyzerPublicApi(
+    message: 'exposed by CommentToken.parent and StringToken (superclass)')
 class SimpleToken implements Token {
   /**
    * The type of the token.
@@ -708,6 +716,7 @@ class SimpleToken implements Token {
 /**
  * A token whose value is independent of it's type.
  */
+@AnalyzerPublicApi(message: 'exposed by CommentToken (superclass)')
 class StringToken extends SimpleToken {
   /**
    * The lexeme represented by this token.
@@ -836,6 +845,7 @@ class ReplacementToken extends SyntheticToken {
  *
  * Clients may not extend, implement or mix-in this class.
  */
+@AnalyzerPublicApi(message: 'exported by package:analyzer/dart/ast/token.dart')
 abstract class Token implements SyntacticEntity {
   /**
    * Initialize a newly created token to have the given [type] and [offset].
@@ -1226,6 +1236,7 @@ class TokenClass {
  *
  * Clients may not extend, implement or mix-in this class.
  */
+@AnalyzerPublicApi(message: 'exported by package:analyzer/dart/ast/token.dart')
 class TokenType {
   static const TokenType UNUSED = const TokenType(
       /* index = */ 255, '', 'UNUSED', NO_PRECEDENCE, EOF_TOKEN);

pkg/_fe_analyzer_shared/lib/src/type_inference/nullability_suffix.dart

@@ -2,6 +2,8 @@
 // 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:_fe_analyzer_shared/src/base/analyzer_public_api.dart';
+
 /// Suffix indicating the nullability of a type.
 ///
 /// This enum describes whether a `?` or `*` would be used at the end of the
@@ -12,6 +14,9 @@
 ///
 /// This enum is exposed through the analyzer API, so it should not be modified
 /// without considering the impact on analyzer clients.
+@AnalyzerPublicApi(
+    message:
+        'exported by package:analyzer/dart/element/nullability_suffix.dart')
 enum NullabilitySuffix {
   /// An indication that the canonical representation of the type under
   /// consideration ends with `?`.  Types having this nullability suffix should

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

@@ -1853,6 +1853,14 @@ LintCode.always_specify_types_split_to_types:
   status: hasFix
 LintCode.always_use_package_imports:
   status: hasFix
+LintCode.analyzer_public_api_bad_part_directive:
+  status: noFix
+LintCode.analyzer_public_api_bad_type:
+  status: noFix
+LintCode.analyzer_public_api_exports_non_public_name:
+  status: noFix
+LintCode.analyzer_public_api_impl_in_public_api:
+  status: noFix
 LintCode.analyzer_use_new_elements:
   status: noFix
 LintCode.annotate_overrides:

pkg/analyzer/analysis_options.yaml

@@ -46,6 +46,7 @@ analyzer:
 linter:
   rules:
     - always_use_package_imports
+    - analyzer_public_api
     - analyzer_use_new_elements
     - avoid_dynamic_calls
     - avoid_redundant_argument_values

pkg/analyzer/lib/dart/analysis/analysis_options.dart

@@ -44,6 +44,7 @@ abstract class AnalysisOptions {
 
   /// A list of the lint rules that are to be run in an analysis context if
   /// [lint] is `true`.
+  // ignore: analyzer_public_api_bad_type
   List<LintRule> get lintRules;
 
   /// The plugin configurations for each plugin which is configured in analysis
@@ -123,11 +124,13 @@ final class PluginConfiguration {
   final PluginSource source;
 
   /// The list of specified [DiagnosticConfig]s.
+  // ignore: analyzer_public_api_bad_type
   final Map<String, DiagnosticConfig> diagnosticConfigs;
 
   /// Whether the plugin is enabled.
   final bool isEnabled;
 
+  // ignore: analyzer_public_api_bad_type
   PluginConfiguration({
     required this.name,
     required this.source,

pkg/analyzer/lib/dart/analysis/context_root.dart

@@ -45,6 +45,7 @@ abstract class ContextRoot {
   Folder get root;
 
   /// Return the workspace that contains this context root.
+  // ignore: analyzer_public_api_bad_type
   Workspace get workspace;
 
   /// Return the absolute, normalized paths of all of the files that are

pkg/analyzer/lib/dart/element/element.dart

@@ -38,6 +38,7 @@
 /// represented by an element.
 library;
 
+import 'package:_fe_analyzer_shared/src/base/analyzer_public_api.dart';
 import 'package:analyzer/dart/analysis/features.dart';
 import 'package:analyzer/dart/analysis/session.dart';
 import 'package:analyzer/dart/constant/value.dart';
@@ -2637,6 +2638,8 @@ abstract class VariableElement implements Element, ConstantEvaluationTarget {
 
 /// This class exists to provide non-nullable overrides for existing elements,
 /// as opposite to artificial "multiply defined" element.
+@AnalyzerPublicApi(
+    message: 'Exposed because it is implemented by various elements')
 abstract class _ExistingElement implements Element {
   @override
   Element get declaration;

pkg/analyzer/lib/src/dart/analysis/experiments_impl.dart

@@ -2,6 +2,7 @@
 // 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:_fe_analyzer_shared/src/base/analyzer_public_api.dart';
 import 'package:analyzer/dart/analysis/features.dart';
 import 'package:analyzer/src/dart/analysis/experiments.dart';
 import 'package:meta/meta.dart';
@@ -287,6 +288,7 @@ class EnabledDisabledFlags {
 
 /// Information about a single experimental flag that the user might use to
 /// request that a feature be enabled (or disabled).
+@AnalyzerPublicApi(message: 'Exposed by static fields in the Feature class.')
 class ExperimentalFeature implements Feature {
   /// Index of the flag in the private data structure maintained by
   /// [ExperimentStatus].