[tool] Switch custom analysis allowance to local config

.ci/scripts/analyze_legacy.sh

@@ -15,8 +15,7 @@ set -e
 # since only the packages changed by 'make-deps-path-based' need to be
 # re-checked.
 .ci/scripts/tool_runner.sh analyze --lib-only \
-    --skip-if-not-supporting-flutter-version="$CHANNEL" \
-    --custom-analysis=script/configs/custom_analysis.yaml
+    --skip-if-not-supporting-flutter-version="$CHANNEL"
 
 # Restore the tree to a clean state, to avoid accidental issues if
 # other script steps are added to the enclosing task.

.ci/scripts/analyze_pathified.sh

@@ -17,7 +17,7 @@ set -e
 # failure regardless.
 dart ./script/tool/bin/flutter_plugin_tools.dart analyze --run-on-dirty-packages \
     --skip-if-resolving-fails \
-    --log-timing --custom-analysis=script/configs/custom_analysis.yaml
+    --log-timing
 # Restore the tree to a clean state, to avoid accidental issues if
 # other script steps are added to the enclosing task.
 git checkout .

.ci/targets/analyze.yaml

@@ -12,9 +12,7 @@ tasks:
     infra_step: true
   - name: analyze
     script: .ci/scripts/tool_runner.sh
-    # DO NOT change the custom-analysis argument here without changing the Dart repo.
-    # See the comment in script/configs/custom_analysis.yaml for details.
-    args: ["analyze", "--custom-analysis=script/configs/custom_analysis.yaml"]
+    args: ["analyze"]
     # Re-run analysis with path-based dependencies to ensure that publishing
     # the changes won't break analysis of other packages in the respository
     # that depend on it.

.ci/targets/analyze_downgraded.yaml

@@ -7,4 +7,4 @@ tasks:
   # those APIs are introduced.
   - name: analyze - downgraded
     script: .ci/scripts/tool_runner.sh
-    args: ["analyze", "--downgrade", "--custom-analysis=script/configs/custom_analysis.yaml"]
+    args: ["analyze", "--downgrade"]

packages/animations/ci_config.yaml

@@ -0,0 +1,3 @@
+# Opts out of unawaited_futures, matching flutter/flutter's disabling due
+# to interactions with animation.
+allow_custom_analysis_options: true

packages/camera/camera_android_camerax/ci_config.yaml

@@ -1 +1,3 @@
 analyze_skills: true
+# Uses custom analysis to enable the cyclomatic complexity linter plugin.
+allow_custom_analysis_options: true

packages/cupertino_ui/ci_config.yaml

@@ -2,3 +2,7 @@
 exempt_from_excerpts: true
 release:
   batch: false
+
+# Temporarily ignore tests that have yet to have their cross imports fixed.
+# See https://github.com/flutter/flutter/issues/177028.
+allow_custom_analysis_options: true

packages/flutter_lints/ci_config.yaml

@@ -0,0 +1,2 @@
+# Deliberately uses flutter_lints, as that's what it is demonstrating.
+allow_custom_analysis_options: true

packages/go_router/ci_config.yaml

@@ -1,2 +1,6 @@
 release:
   batch: true
+
+# Has some test files that are intentionally broken to conduct dart fix tests.
+# Also opts out of unawaited_futures, matching flutter/flutter.
+allow_custom_analysis_options: true

packages/go_router_builder/ci_config.yaml

@@ -1,3 +1,7 @@
 release:
   # TODO(chunhtai): Opt in when ready.
   batch: false
+
+# Uses default formatter settings instead of custom repo settings since it
+# serves as a golden for builder output tests.
+allow_custom_analysis_options: true

packages/material_ui/ci_config.yaml

@@ -2,3 +2,7 @@
 exempt_from_excerpts: true
 release:
   batch: false
+
+# Temporarily ignore tests that have yet to have their cross imports fixed.
+# See https://github.com/flutter/flutter/issues/177028.
+allow_custom_analysis_options: true

packages/rfw/ci_config.yaml

@@ -0,0 +1,2 @@
+# Has some constructions that are currently handled poorly by dart format.
+allow_custom_analysis_options: true

packages/web_benchmarks/ci_config.yaml

@@ -0,0 +1,2 @@
+# Disables docs requirements, as it is test code.
+allow_custom_analysis_options: true

script/tool/CHANGELOG.md

@@ -1,3 +1,9 @@
+## NEXT
+
+* Deprecates the `--custom-analysis` argument to `analyze`, which is now
+  ignored, in favor of `allow_custom_analysis_options: true` in package-level
+  `ci_config.yaml` files.
+
 ## 0.14.2
 
 * Ensures that pub commands use `flutter` or `dart` depending on whether the

script/tool/lib/src/analyze_command.dart

@@ -30,14 +30,12 @@ class AnalyzeCommand extends PackageLoopingCommand {
     argParser.addFlag(platformMacOS, help: "Runs 'xcodebuild analyze' on macOS code");
 
     // Dart options.
+    // TODO(stuartmorgan): Remove this entirely once the flutter/flutter and dart-lang repo scripts
+    // that run flutter/packages analysis have been updated not to pass it.
     argParser.addMultiOption(
-      _customAnalysisFlag,
-      help:
-          'Directories (comma separated) that are allowed to have their own '
-          'analysis options.\n\n'
-          'Alternately, a list of one or more YAML files that contain a list '
-          'of allowed directories.',
-      defaultsTo: <String>[],
+      'custom-analysis',
+      help: 'Ignored; exists for legacy compatibility only.',
+      hide: true,
     );
     argParser.addOption(
       _analysisSdk,
@@ -85,7 +83,6 @@ class AnalyzeCommand extends PackageLoopingCommand {
   }
 
   static const String _dartFlag = 'dart';
-  static const String _customAnalysisFlag = 'custom-analysis';
   static const String _downgradeFlag = 'downgrade';
   static const String _libOnlyFlag = 'lib-only';
   static const String _analysisSdk = 'analysis-sdk';
@@ -95,8 +92,6 @@ class AnalyzeCommand extends PackageLoopingCommand {
 
   late String _dartBinaryPath;
 
-  Set<String> _allowedCustomAnalysisDirectories = const <String>{};
-
   @override
   final String name = 'analyze';
 
@@ -105,8 +100,8 @@ class AnalyzeCommand extends PackageLoopingCommand {
       'Analyzes all packages using dart analyze.\n\n'
       'This command requires "dart" and "flutter" to be in your path.';
 
-  /// Checks that there are no unexpected analysis_options.yaml files.
-  bool _hasUnexpectedAnalysisOptions(RepositoryPackage package) {
+  /// Checks that there are no package-local analysis_options.yaml files.
+  bool _hasLocalAnalysisOptions(RepositoryPackage package) {
     final List<FileSystemEntity> files = package.directory.listSync(
       recursive: true,
       followLinks: false,
@@ -121,19 +116,12 @@ class AnalyzeCommand extends PackageLoopingCommand {
         continue;
       }
 
-      final bool allowed = _allowedCustomAnalysisDirectories.any(
-        (String directory) =>
-            directory.isNotEmpty &&
-            path.isWithin(packagesDir.childDirectory(directory).path, file.path),
-      );
-      if (allowed) {
-        continue;
-      }
-
-      printError('Found an extra analysis_options.yaml at ${file.absolute.path}.');
+      printError('Found an unexpected analysis_options.yaml at ${file.absolute.path}.');
       printError(
-        'If this was deliberate, pass the package to the analyze command '
-        'with the --$_customAnalysisFlag flag and try again.',
+        'If this is an intentional exception to the general repository guidance against having '
+        'custom analysis_options.yaml files, add a ci_config.yaml to this package that '
+        'sets "allow_custom_analysis_options: true", with a comment explaining why an exception '
+        'is needed.',
       );
       return true;
     }
@@ -170,8 +158,6 @@ class AnalyzeCommand extends PackageLoopingCommand {
 
   @override
   Future<void> initializeRun() async {
-    _allowedCustomAnalysisDirectories = getYamlListArg(_customAnalysisFlag);
-
     // Use the Dart SDK override if one was passed in.
     final dartSdk = argResults![_analysisSdk] as String?;
     _dartBinaryPath = dartSdk == null ? 'dart' : path.join(dartSdk, 'bin', 'dart');
@@ -303,7 +289,10 @@ class AnalyzeCommand extends PackageLoopingCommand {
       }
     }
 
-    if (_hasUnexpectedAnalysisOptions(package)) {
+    // Require an explicit opt-in to use custom analysis options, since it's very easy to
+    // accidentally introduce them to the repo (e.g., with 'flutter create').
+    if (!(package.parseCIConfig()?.allowCustomAnalysisOptions ?? false) &&
+        _hasLocalAnalysisOptions(package)) {
       return PackageResult.fail(<String>['Unexpected local analysis options']);
     }
     final int mainExitCode = await processRunner.runAndStream(_dartBinaryPath, <String>[

script/tool/lib/src/common/ci_config.dart

@@ -4,13 +4,20 @@
 
 import 'package:yaml/yaml.dart';
 
+const String _releaseModeKey = 'release';
+const String _isBatchModeKey = 'batch';
+const String _exemptFromExcerptsKey = 'exempt_from_excerpts';
+const String _analyzeSkillsKey = 'analyze_skills';
+const String _allowCustomAnalysisOptionsKey = 'allow_custom_analysis_options';
+
 /// A class representing the parsed content of a `ci_config.yaml` file.
 class CIConfig {
   /// Creates a [CIConfig] from a parsed YAML map.
   CIConfig._({
     required this.isBatchRelease,
     required this.requiresExcerpts,
     required this.analyzeSkills,
+    required this.allowCustomAnalysisOptions,
   });
 
   /// Parses a [CIConfig] from a YAML string.
@@ -25,30 +32,34 @@ class CIConfig {
     _checkCIConfigEntries(loaded, syntax: _validCIConfigSyntax);
 
     var isBatchRelease = false;
-    final Object? release = loaded['release'];
+    final Object? release = loaded[_releaseModeKey];
     if (release is Map) {
-      isBatchRelease = release['batch'] == true;
+      isBatchRelease = release[_isBatchModeKey] == true;
     }
 
     // Any package that hasn't been explicitly exempted is assumed to require
     // excerpts.
-    final requiresExcerpts = loaded['exempt_from_excerpts'] != true;
+    final requiresExcerpts = loaded[_exemptFromExcerptsKey] != true;
+
+    final analyzeSkills = loaded[_analyzeSkillsKey] == true;
 
-    final analyzeSkills = loaded['analyze_skills'] == true;
+    final allowCustomAnalysisOptions = loaded[_allowCustomAnalysisOptionsKey] == true;
 
     return CIConfig._(
       isBatchRelease: isBatchRelease,
       requiresExcerpts: requiresExcerpts,
       analyzeSkills: analyzeSkills,
+      allowCustomAnalysisOptions: allowCustomAnalysisOptions,
     );
   }
 
   static const Map<String, Object?> _validCIConfigSyntax = <String, Object?>{
-    'release': <String, Object?>{
-      'batch': <bool>{true, false},
+    _releaseModeKey: <String, Object?>{
+      _isBatchModeKey: <bool>{true, false},
     },
-    'exempt_from_excerpts': <bool>{true, false},
-    'analyze_skills': <bool>{true, false},
+    _exemptFromExcerptsKey: <bool>{true, false},
+    _analyzeSkillsKey: <bool>{true, false},
+    _allowCustomAnalysisOptionsKey: <bool>{true, false},
   };
 
   /// Returns true if the package is configured for batch release.
@@ -60,6 +71,9 @@ class CIConfig {
   /// Returns true if the package has its agent skills analyzed.
   final bool analyzeSkills;
 
+  /// Returns true if the package is allowed to have its own analysis options.
+  final bool allowCustomAnalysisOptions;
+
   static void _checkCIConfigEntries(
     YamlMap config, {
     required Map<String, Object?> syntax,