[web] hide the --web-renderer option in the tool (#152683)

Hide the `--web-renderer` option in the Flutter Tool. The defaults already cover all fully supported modes:

- `flutter build web` provides canvaskit + dart2js
- `flutter build web --wasm` provides skwasm + dart2wasm

We do not want to encourage production usage of any other permutations (e.g. `auto` or `html`), in particular those that simply do not work (e.g. `skwasm` + dart2js).

Fixes https://github.com/flutter/flutter/issues/140096
Fixes https://github.com/flutter/flutter/issues/151786

packages/flutter_tools/lib/src/runner/flutter_command.dart

@@ -707,11 +707,28 @@ abstract class FlutterCommand extends Command<void> {
     );
   }
 
+  // This option is deprecated and is no longer publicly supported, and
+  // therefore is hidden.
+  //
+  // The option still exists for internal testing, and to give existing users
+  // time to migrate off the HTML renderer, but it is no longer advertised as a
+  // supported mode.
+  //
+  // See also:
+  //   * https://github.com/flutter/flutter/issues/151786
+  //   * https://github.com/flutter/flutter/issues/145954
   void usesWebRendererOption() {
     argParser.addOption(
+      hide: true,
       FlutterOptions.kWebRendererFlag,
       allowed: WebRendererMode.values.map((WebRendererMode e) => e.name),
-      help: 'The renderer implementation to use when building for the web.',
+      help: 'This option is deprecated and will be removed in a future Flutter '
+            'release.\n'
+            'Selects the renderer implementation to use when building for the '
+            'web. The supported renderers are "canvaskit" when compiling to '
+            'JavaScript, and "skwasm" when compiling to WebAssembly. Other '
+            'renderer and compiler combinations are no longer supported. '
+            'Consider migrating your app to a supported renderer.',
       allowedHelp: CliEnum.allowedHelp(WebRendererMode.values)
     );
   }

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

@@ -377,6 +377,44 @@ void main() {
     FileSystem: () => fileSystem,
     ProcessManager: () => processManager,
   });
+
+  testUsingContext('flutter build web option visibility', () async {
+    final TestWebBuildCommand buildCommand = TestWebBuildCommand(fileSystem: fileSystem);
+    createTestCommandRunner(buildCommand);
+    final BuildWebCommand command = buildCommand.subcommands.values.single as BuildWebCommand;
+
+    void expectVisible(String option) {
+      expect(command.argParser.options.keys, contains(option));
+      expect(command.argParser.options[option]!.hide, isFalse);
+      expect(command.usage, contains(option));
+    }
+
+    void expectHidden(String option) {
+      expect(command.argParser.options.keys, contains(option));
+      expect(command.argParser.options[option]!.hide, isTrue);
+      expect(command.usage, isNot(contains(option)));
+    }
+
+    expectVisible('pwa-strategy');
+    expectVisible('web-resources-cdn');
+    expectVisible('optimization-level');
+    expectVisible('source-maps');
+    expectVisible('csp');
+    expectVisible('dart2js-optimization');
+    expectVisible('dump-info');
+    expectVisible('no-frequency-based-minification');
+    expectVisible('wasm');
+    expectVisible('strip-wasm');
+    expectVisible('base-href');
+
+    expectHidden('web-renderer');
+  }, overrides: <Type, Generator>{
+    Platform: () => fakePlatform,
+    FileSystem: () => fileSystem,
+    FeatureFlags: () => TestFeatureFlags(isWebEnabled: true),
+    ProcessManager: () => processManager,
+  });
+
 }
 
 void setupFileSystemForEndToEndTest(FileSystem fileSystem) {

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

@@ -227,10 +227,28 @@ void verifyOptions(String? command, Iterable<Option> options) {
       expect(option.name, matches(_allowedArgumentNamePattern), reason: '$_header$target--${option.name}" is not a valid name for a command line argument. (Is it all lowercase? Does it use hyphens rather than underscores?)');
     }
     expect(option.name, isNot(matches(_bannedArgumentNamePattern)), reason: '$_header$target--${option.name}" is not a valid name for a command line argument. (We use "--foo-url", not "--foo-uri", for example.)');
-    // The flag --sound-null-safety is deprecated
-    if (option.name != FlutterOptions.kNullSafety && option.name != FlutterOptions.kNullAssertions) {
-      expect(option.hide, isFalse, reason: '${_header}Help for $target--${option.name}" is always hidden. $_needHelp');
+
+    // Deprecated options and flags should be hidden but still have help text.
+    const List<String> deprecatedOptions = <String>[
+      FlutterOptions.kNullSafety,
+      FlutterOptions.kNullAssertions,
+      FlutterOptions.kWebRendererFlag,
+    ];
+    final bool isOptionDeprecated = deprecatedOptions.contains(option.name);
+    if (!isOptionDeprecated) {
+      expect(
+        option.hide,
+        isFalse,
+        reason: '${_header}Option "--${option.name}" for "flutter $command" should not be hidden. $_needHelp',
+      );
+    } else {
+      expect(
+        option.hide,
+        isTrue,
+        reason: '${_header}Deprecated option "--${option.name}" for "flutter $command" should be hidden. $_needHelp',
+      );
     }
+
     expect(option.help, isNotNull, reason: '${_header}Help for $target--${option.name}" has null help. $_needHelp');
     expect(option.help, isNotEmpty, reason: '${_header}Help for $target--${option.name}" has empty help. $_needHelp');
     expect(option.help, isNot(matches(_bannedLeadingPatterns)), reason: '${_header}A line in the help for $target--${option.name}" starts with a lowercase letter. For stylistic consistency, all help messages must start with a capital letter.');