Improve Plugins That Reference V1 Embedding Error Message (#160890)

Improved the error message that appears when using plugins that
reference v1 embedding. The new error message explains why the error
appears and how to fix it.

Fixes #160204

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

---------

Co-authored-by: Gray Mackall <34871572+gmackall@users.noreply.github.com>

packages/flutter_tools/lib/src/android/gradle_errors.dart

@@ -78,6 +78,7 @@ final List<GradleHandledError> gradleErrors = <GradleHandledError>[
   remoteTerminatedHandshakeHandler,
   couldNotOpenCacheDirectoryHandler,
   incompatibleCompileSdk35AndAgpVersionHandler,
+  usageOfV1EmbeddingReferencesHandler,
   jlinkErrorWithJava21AndSourceCompatibility,
   incompatibleKotlinVersionHandler, // This handler should always be last, as its key log output is sometimes in error messages with other root causes.
 ];
@@ -681,6 +682,31 @@ ${_getAgpLocation(project)}''', title: _boxTitle);
   eventLabel: 'r8-dexing-bug-in-AGP-7.3',
 );
 
+// Handler for when an outdated plugin is still using v1 embedding references that
+// were possibly removed in more recent plugin versions.
+@visibleForTesting
+final GradleHandledError usageOfV1EmbeddingReferencesHandler = GradleHandledError(
+  test:
+      (String line) => line.contains('io.flutter.plugin.common.PluginRegistry.Registrar registrar'),
+  handler: ({
+    required String line,
+    required FlutterProject project,
+    required bool usesAndroidX,
+  }) async {
+    globals.printBox(
+      '''
+${globals.logger.terminal.warningMark} Consult the error logs above to identify any broken plugins, specifically those containing "error: cannot find symbol..."
+This issue is likely caused by v1 embedding removal and the plugin's continued usage of removed references to the v1 embedding.
+To fix this error, please upgrade your current package's dependencies to latest versions by running `flutter pub upgrade`.
+If that does not work, please file an issue for the problematic plugin(s) here: https://github.com/flutter/flutter/issues''',
+      title: _boxTitle,
+    );
+
+    return GradleBuildStatus.exit;
+  },
+  eventLabel: 'usage-of-v1-embedding-references',
+);
+
 @visibleForTesting
 final GradleHandledError jlinkErrorWithJava21AndSourceCompatibility = GradleHandledError(
   test: (String line) => line.contains('> Error while executing process') && line.contains('jlink'),

packages/flutter_tools/test/general.shard/android/gradle_errors_test.dart

@@ -52,6 +52,7 @@ void main() {
           remoteTerminatedHandshakeHandler,
           couldNotOpenCacheDirectoryHandler,
           incompatibleCompileSdk35AndAgpVersionHandler,
+          usageOfV1EmbeddingReferencesHandler,
           jlinkErrorWithJava21AndSourceCompatibility,
           incompatibleKotlinVersionHandler,
         ]),
@@ -1485,6 +1486,50 @@ ERROR:/Users/mackall/.gradle/caches/transforms-3/bd2c84591857c6d4c308221ffece862
     },
   );
 
+  testUsingContext(
+    'Usage of removed v1 embedding references',
+    () async {
+      const String errorExample = r'''
+/Users/jesswon/.pub-cache/hosted/pub.dev/video_player_android-2.5.0/android/src/main/java/io/flutter/plugins/videoplayer/VideoPlayerPlugin.java:42: error: cannot find symbol
+  private VideoPlayerPlugin(io.flutter.plugin.common.PluginRegistry.Registrar registrar) {
+                                                                   ^
+  symbol:   class Registrar
+  location: interface PluginRegistry
+1 error
+
+FAILURE: Build failed with an exception.
+    ''';
+
+      final FlutterProject project = FlutterProject.fromDirectoryTest(fileSystem.currentDirectory);
+      await usageOfV1EmbeddingReferencesHandler.handler(
+        line: errorExample,
+        project: project,
+        usesAndroidX: true,
+      );
+
+      // Main fix text.
+      expect(
+        testLogger.statusText,
+        contains(
+          "To fix this error, please upgrade your current package's dependencies to latest versions by",
+        ),
+      );
+      expect(testLogger.statusText, contains('running `flutter pub upgrade`.'));
+      // Text and link to file an issue.
+      expect(
+        testLogger.statusText,
+        contains('If that does not work, please file an issue for the problematic plugin(s) here:'),
+      );
+      expect(testLogger.statusText, contains('https://github.com/flutter/flutter/issues'));
+    },
+    overrides: <Type, Generator>{
+      GradleUtils: () => FakeGradleUtils(),
+      Platform: () => fakePlatform('android'),
+      FileSystem: () => fileSystem,
+      ProcessManager: () => processManager,
+    },
+  );
+
   testUsingContext(
     'Java 21 and jlink bug',
     () async {