[flutter_tools] Suggest actions to fix failing `FlutterValidator` (#106355)

packages/flutter_tools/lib/src/base/user_messages.dart

@@ -18,11 +18,22 @@ class UserMessages {
       'Channel ${channel ?? 'unknown'}, ${version ?? 'Unknown'}, on $os, locale $locale';
   String flutterVersion(String version, String channel, String flutterRoot) =>
       'Flutter version $version on channel $channel at $flutterRoot';
+  String get flutterUnknownChannel =>
+    'Currently on an unknown channel. Run `flutter channel` to switch to an official channel.\n'
+    "If that doesn't fix the issue, reinstall Flutter by following instructions at https://flutter.dev/docs/get-started/install.";
+  String get flutterUnknownVersion =>
+    'Cannot resolve current version, possibly due to local changes.\n'
+    'Reinstall Flutter by following instructions at https://flutter.dev/docs/get-started/install.';
   String flutterRevision(String revision, String age, String date) =>
     'Framework revision $revision ($age), $date';
   String flutterUpstreamRepositoryUrl(String url) => 'Upstream repository $url';
+  String get flutterUpstreamRepositoryUnknown =>
+    'Unknown upstream repository.\n'
+    'Reinstall Flutter by following instructions at https://flutter.dev/docs/get-started/install.';
   String flutterUpstreamRepositoryUrlEnvMismatch(String url) => 'Upstream repository $url is not the same as FLUTTER_GIT_URL';
-  String flutterUpstreamRepositoryUrlNonStandard(String url) => 'Upstream repository $url is not a standard remote';
+  String flutterUpstreamRepositoryUrlNonStandard(String url) =>
+    'Upstream repository $url is not a standard remote.\n'
+    'Set environment variable "FLUTTER_GIT_URL" to $url to dismiss this error.';
   String flutterGitUrl(String url) => 'FLUTTER_GIT_URL = $url';
   String engineRevision(String revision) => 'Engine revision $revision';
   String dartRevision(String revision) => 'Dart version $revision';
@@ -36,6 +47,9 @@ class UserMessages {
       'On Debian/Ubuntu/Mint: sudo apt-get install lib32stdc++6\n'
       'On Fedora: dnf install libstdc++.i686\n'
       'On Arch: pacman -S lib32-gcc-libs';
+  String get flutterValidatorErrorIntentional =>
+      'If those were intentional, you can disregard the above warnings; however it is '
+      'recommended to use "git" directly to perform update checks and upgrades.';
 
   // Messages used in NoIdeValidator
   String get noIdeStatusInfo => 'No supported IDEs installed';

packages/flutter_tools/lib/src/doctor.dart

@@ -535,9 +535,18 @@ class FlutterValidator extends DoctorValidator {
       messages.add(ValidationMessage.error(buffer.toString()));
     }
 
-    final ValidationType valid = messages.every((ValidationMessage message) => message.isInformation)
-      ? ValidationType.installed
-      : ValidationType.partial;
+    ValidationType valid;
+    if (messages.every((ValidationMessage message) => message.isInformation)) {
+      valid = ValidationType.installed;
+    } else {
+      // The issues for this validator stem from broken git configuration of the local install;
+      // in that case, make it clear that it is fine to continue, but freshness check/upgrades
+      // won't be supported.
+      valid = ValidationType.partial;
+      messages.add(
+        ValidationMessage(_userMessages.flutterValidatorErrorIntentional),
+      );
+    }
 
     return ValidationResult(
       valid,
@@ -552,17 +561,23 @@ class FlutterValidator extends DoctorValidator {
   }
 
   ValidationMessage _getFlutterVersionMessage(String frameworkVersion, String versionChannel) {
-    final String flutterVersionMessage = _userMessages.flutterVersion(frameworkVersion, versionChannel, _flutterRoot());
+    String flutterVersionMessage = _userMessages.flutterVersion(frameworkVersion, versionChannel, _flutterRoot());
 
     // The tool sets the channel as "unknown", if the current branch is on a
     // "detached HEAD" state or doesn't have an upstream, and sets the
     // frameworkVersion as "0.0.0-unknown" if  "git describe" on HEAD doesn't
     // produce an expected format to be parsed for the frameworkVersion.
-    if (versionChannel == 'unknown' || frameworkVersion == '0.0.0-unknown') {
-      return ValidationMessage.hint(flutterVersionMessage);
-    }
+    if (versionChannel != 'unknown' && frameworkVersion != '0.0.0-unknown') {
       return ValidationMessage(flutterVersionMessage);
     }
+    if (versionChannel == 'unknown') {
+      flutterVersionMessage = '$flutterVersionMessage\n${_userMessages.flutterUnknownChannel}';
+    }
+    if (frameworkVersion == '0.0.0-unknown') {
+      flutterVersionMessage = '$flutterVersionMessage\n${_userMessages.flutterUnknownVersion}';
+    }
+    return ValidationMessage.hint(flutterVersionMessage);
+  }
 
   ValidationMessage _getFlutterUpstreamMessage(FlutterVersion version) {
     final String? repositoryUrl = version.repositoryUrl;
@@ -572,7 +587,7 @@ class FlutterValidator extends DoctorValidator {
     if (upstreamValidationError != null) {
       final String errorMessage = upstreamValidationError.message;
       if (errorMessage.contains('could not determine the remote upstream which is being tracked')) {
-        return ValidationMessage.hint(_userMessages.flutterUpstreamRepositoryUrl('unknown'));
+        return ValidationMessage.hint(_userMessages.flutterUpstreamRepositoryUnknown);
       }
       // At this point, repositoryUrl must not be null
       if (errorMessage.contains('Flutter SDK is tracking a non-standard remote')) {

packages/flutter_tools/test/general.shard/flutter_validator_test.dart

@@ -191,6 +191,10 @@ void main() {
       messages: containsAll(const <ValidationMessage>[
         ValidationMessage.hint('Upstream repository https://github.com/flutter/flutter.git is not the same as FLUTTER_GIT_URL'),
         ValidationMessage('FLUTTER_GIT_URL = https://githubmirror.com/flutter.git'),
+        ValidationMessage(
+          'If those were intentional, you can disregard the above warnings; however it is '
+          'recommended to use "git" directly to perform update checks and upgrades.'
+        ),
       ]),
     ));
   });
@@ -214,7 +218,17 @@ void main() {
     expect(await flutterValidator.validate(), _matchDoctorValidation(
       validationType: ValidationType.partial,
       statusInfo: 'Channel unknown, 1.0.0, on Linux, locale en_US.UTF-8',
-      messages: contains(const ValidationMessage.hint('Flutter version 1.0.0 on channel unknown at sdk/flutter')),
+      messages: containsAll(<ValidationMessage>[
+        const ValidationMessage.hint(
+          'Flutter version 1.0.0 on channel unknown at sdk/flutter\n'
+          'Currently on an unknown channel. Run `flutter channel` to switch to an official channel.\n'
+          "If that doesn't fix the issue, reinstall Flutter by following instructions at https://flutter.dev/docs/get-started/install."
+        ),
+        const ValidationMessage(
+          'If those were intentional, you can disregard the above warnings; however it is '
+          'recommended to use "git" directly to perform update checks and upgrades.'
+        ),
+      ]),
     ));
   });
 
@@ -237,7 +251,17 @@ void main() {
     expect(await flutterValidator.validate(), _matchDoctorValidation(
       validationType: ValidationType.partial,
       statusInfo: 'Channel beta, 0.0.0-unknown, on Linux, locale en_US.UTF-8',
-      messages: contains(const ValidationMessage.hint('Flutter version 0.0.0-unknown on channel beta at sdk/flutter')),
+      messages: containsAll(<ValidationMessage>[
+        const ValidationMessage.hint(
+          'Flutter version 0.0.0-unknown on channel beta at sdk/flutter\n'
+          'Cannot resolve current version, possibly due to local changes.\n'
+          'Reinstall Flutter by following instructions at https://flutter.dev/docs/get-started/install.'
+        ),
+        const ValidationMessage(
+          'If those were intentional, you can disregard the above warnings; however it is '
+          'recommended to use "git" directly to perform update checks and upgrades.'
+        ),
+      ]),
     ));
   });
 
@@ -285,7 +309,17 @@ void main() {
       expect(await flutterValidator.validate(), _matchDoctorValidation(
         validationType: ValidationType.partial,
         statusInfo: 'Channel beta, 1.0.0, on Linux, locale en_US.UTF-8',
-        messages: contains(const ValidationMessage.hint('Upstream repository https://githubmirror.com/flutter.git is not a standard remote')),
+        messages: containsAll(<ValidationMessage>[
+          const ValidationMessage.hint(
+            'Upstream repository https://githubmirror.com/flutter.git is not a standard remote.\n'
+            'Set environment variable "FLUTTER_GIT_URL" to '
+            'https://githubmirror.com/flutter.git to dismiss this error.'
+          ),
+          const ValidationMessage(
+            'If those were intentional, you can disregard the above warnings; however it is '
+            'recommended to use "git" directly to perform update checks and upgrades.'
+          ),
+        ]),
       ));
     });
 
@@ -309,10 +343,47 @@ void main() {
       expect(await flutterValidator.validate(), _matchDoctorValidation(
         validationType: ValidationType.partial,
         statusInfo: 'Channel beta, 1.0.0, on Linux, locale en_US.UTF-8',
-        messages: contains(const ValidationMessage.hint('Upstream repository unknown')),
+        messages: containsAll(<ValidationMessage>[
+          const ValidationMessage.hint(
+            'Unknown upstream repository.\n'
+            'Reinstall Flutter by following instructions at https://flutter.dev/docs/get-started/install.'
+          ),
+          const ValidationMessage(
+            'If those were intentional, you can disregard the above warnings; however it is '
+            'recommended to use "git" directly to perform update checks and upgrades.'
+          ),
+        ]),
       ));
     });
   });
+
+  testWithoutContext('Do not show the message for intentional errors if FlutterValidator passes', () async {
+    final FlutterValidator flutterValidator = FlutterValidator(
+      platform: FakePlatform(localeName: 'en_US.UTF-8'),
+      flutterVersion: () => FakeFlutterVersion(
+        frameworkVersion: '1.0.0',
+        channel: 'beta'
+      ),
+      devToolsVersion: () => '2.8.0',
+      userMessages: UserMessages(),
+      artifacts: Artifacts.test(),
+      fileSystem: MemoryFileSystem.test(),
+      processManager: FakeProcessManager.any(),
+      operatingSystemUtils: FakeOperatingSystemUtils(name: 'Linux'),
+      flutterRoot: () => 'sdk/flutter',
+    );
+
+    expect(await flutterValidator.validate(), _matchDoctorValidation(
+      validationType: ValidationType.installed,
+      statusInfo: 'Channel beta, 1.0.0, on Linux, locale en_US.UTF-8',
+      messages: isNot(
+        contains(const ValidationMessage(
+          'If those were intentional, you can disregard the above warnings; however it is '
+          'recommended to use "git" directly to perform update checks and upgrades.'
+        )),
+      ),
+    ));
+  });
 }
 
 class FakeOperatingSystemUtils extends Fake implements OperatingSystemUtils {