[tool] Emit a deprecation warning for some values of --web-renderer. (#156376)

This PR emits a blue warning text when using `flutter ... --web-renderer=html|auto`.

(The message is similar to the one that we emit at run-time)

## Issues

Fixes flutter/flutter#154878
See also: flutter/engine#55709

Author: ditman

packages/flutter_tools/lib/src/commands/build_web.dart

@@ -149,6 +149,9 @@ class BuildWebCommand extends BuildSubCommand {
     final bool sourceMaps = boolArg('source-maps');
 
     final List<WebCompilerConfig> compilerConfigs;
+    if (webRenderer != null && webRenderer.isDeprecated) {
+      globals.logger.printWarning(webRenderer.deprecationWarning);
+    }
     if (boolArg(FlutterOptions.kWebWasmFlag)) {
       if (webRenderer != null) {
         throwToolExit('"--${FlutterOptions.kWebRendererFlag}" cannot be combined with "--${FlutterOptions.kWebWasmFlag}"');

packages/flutter_tools/lib/src/commands/run.dart

@@ -655,6 +655,10 @@ class RunCommand extends RunCommandBase {
       throwToolExit('--wasm is only supported on the web platform');
     }
 
+    if (webRenderer.isDeprecated) {
+      globals.logger.printWarning(webRenderer.deprecationWarning);
+    }
+
     if (webRenderer == WebRendererMode.skwasm && !useWasm) {
       throwToolExit('Skwasm renderer requires --wasm');
     }

packages/flutter_tools/lib/src/commands/test.dart

@@ -532,6 +532,10 @@ class TestCommand extends FlutterCommand with DeviceBasedDevelopmentArtifacts {
       throwToolExit('Skwasm renderer requires --wasm');
     }
 
+    if (webRenderer.isDeprecated) {
+      globals.logger.printWarning(webRenderer.deprecationWarning);
+    }
+
     Device? integrationTestDevice;
     if (_isIntegrationTest) {
       integrationTestDevice = await findTargetDevice();

packages/flutter_tools/lib/src/web/compile.dart

@@ -199,6 +199,21 @@ enum WebRendererMode implements CliEnum {
   static const WebRendererMode defaultForJs = WebRendererMode.canvaskit;
   static const WebRendererMode defaultForWasm = WebRendererMode.skwasm;
 
+  /// Returns whether the WebRendererMode is considered deprecated or not.
+  ///
+  /// Deprecated modes: auto, html.
+  bool get isDeprecated => switch (this) {
+        auto => true,
+        canvaskit => false,
+        html => true,
+        skwasm => false
+      };
+
+  /// Returns a consistent deprecation warning for the WebRendererMode.
+  String get deprecationWarning =>
+    'The HTML Renderer is deprecated. Do not use "--web-renderer=$name".'
+    '\nSee: https://docs.flutter.dev/to/web-html-renderer-deprecation';
+
   @override
   String get cliName => kebabCase(name);
 

packages/flutter_tools/test/commands.shard/hermetic/build_web_test.dart

@@ -5,6 +5,7 @@
 import 'package:args/command_runner.dart';
 import 'package:file/memory.dart';
 import 'package:flutter_tools/src/artifacts.dart';
+import 'package:flutter_tools/src/base/common.dart';
 import 'package:flutter_tools/src/base/file_system.dart';
 import 'package:flutter_tools/src/base/logger.dart';
 import 'package:flutter_tools/src/base/platform.dart';
@@ -378,6 +379,37 @@ void main() {
     ProcessManager: () => processManager,
   });
 
+  // Tests whether using a deprecated webRenderer toggles a warningText.
+  Future<void> testWebRendererDeprecationMessage(WebRendererMode webRenderer) async {
+    testUsingContext('Using --web-renderer=${webRenderer.name} triggers a warningText.', () async {
+      // Run the command so it parses --web-renderer, but ignore all errors.
+      // We only care about the logger.
+      try {
+        final TestWebBuildCommand buildCommand = TestWebBuildCommand(fileSystem: fileSystem);
+        await createTestCommandRunner(buildCommand).run(<String>[
+          'build',
+          'web',
+          '--no-pub',
+          '--web-renderer=${webRenderer.name}',
+        ]);
+      } on ToolExit catch (error) {
+        expect(error, isA<ToolExit>());
+      }
+      expect(logger.warningText, contains(
+        'See: https://docs.flutter.dev/to/web-html-renderer-deprecation'
+      ));
+    }, overrides: <Type, Generator>{
+      Platform: () => fakePlatform,
+      FileSystem: () => fileSystem,
+      ProcessManager: () => processManager,
+      Logger: () => logger,
+    });
+  }
+  /// Do test all the deprecated WebRendererModes
+  WebRendererMode.values
+    .where((WebRendererMode mode) => mode.isDeprecated)
+    .forEach(testWebRendererDeprecationMessage);
+
   testUsingContext('flutter build web option visibility', () async {
     final TestWebBuildCommand buildCommand = TestWebBuildCommand(fileSystem: fileSystem);
     createTestCommandRunner(buildCommand);

packages/flutter_tools/test/commands.shard/hermetic/run_test.dart

@@ -1023,6 +1023,35 @@ void main() {
         DeviceManager: () => testDeviceManager,
       });
 
+      // Tests whether using a deprecated webRenderer toggles a warningText.
+      Future<void> testWebRendererDeprecationMessage(WebRendererMode webRenderer) async {
+        testUsingContext('Using --web-renderer=${webRenderer.name} triggers a warningText.', () async {
+          // Run the command so it parses --web-renderer, but ignore all errors.
+          // We only care about the logger.
+          try {
+            await createTestCommandRunner(RunCommand()).run(<String>[
+              'run',
+              '--no-pub',
+              '--web-renderer=${webRenderer.name}',
+            ]);
+          } on ToolExit catch (error) {
+            expect(error, isA<ToolExit>());
+          }
+          expect(logger.warningText, contains(
+            'See: https://docs.flutter.dev/to/web-html-renderer-deprecation'
+          ));
+        }, overrides: <Type, Generator>{
+          FileSystem: () => fileSystem,
+          ProcessManager: () => FakeProcessManager.any(),
+          Logger: () => logger,
+          DeviceManager: () => testDeviceManager,
+        });
+      }
+      /// Do test all the deprecated WebRendererModes
+      WebRendererMode.values
+        .where((WebRendererMode mode) => mode.isDeprecated)
+        .forEach(testWebRendererDeprecationMessage);
+
       testUsingContext('accepts headers with commas in them', () async {
         final RunCommand command = RunCommand();
         await expectLater(

packages/flutter_tools/test/commands.shard/hermetic/test_test.dart

@@ -1426,6 +1426,40 @@ dev_dependencies:
     });
   });
 
+  // Tests whether using a deprecated webRenderer toggles a warningText.
+  Future<void> testWebRendererDeprecationMessage(WebRendererMode webRenderer) async {
+    testUsingContext('Using --web-renderer=${webRenderer.name} triggers a warningText.', () async {
+      // Run the command so it parses --web-renderer, but ignore all errors.
+      // We only care about the logger.
+      try {
+        final FakeFlutterTestRunner testRunner = FakeFlutterTestRunner(0);
+
+        final TestCommand testCommand = TestCommand(testRunner: testRunner);
+        await createTestCommandRunner(testCommand).run(<String>[
+          'test',
+          'web',
+          '--no-pub',
+          '--platform=chrome',
+          '--web-renderer=${webRenderer.name}',
+        ]);
+      } on ToolExit catch (error) {
+        expect(error, isA<ToolExit>());
+      }
+      expect(logger.warningText, contains(
+        'See: https://docs.flutter.dev/to/web-html-renderer-deprecation'
+      ));
+    }, overrides: <Type, Generator>{
+      FileSystem: () => fs,
+      ProcessManager: () => FakeProcessManager.any(),
+      Logger: () => logger,
+    });
+  }
+  /// Do test all the deprecated WebRendererModes
+  WebRendererMode.values
+    .where((WebRendererMode mode) => mode.isDeprecated)
+    .forEach(testWebRendererDeprecationMessage);
+
+
   testUsingContext('Can test in a pub workspace',
       () async {
     final String root = fs.path.rootPrefix(fs.currentDirectory.absolute.path);