[flutter_tools] refactor CLI argument architecture with typed option descriptors and bundles (PoC) (#191018)
Exploring a type-safe, declarative argument parsing foundation for
`flutter_tools`, validated end-to-end against `flutter build web`.
Today, `flutter_tools` subcommands rely heavily on imperative option
registration methods scattered across `FlutterCommand` (~48 `uses*` /
`add*` methods) and loose string-based argument extraction
(`stringArg('foo')`, `boolArg('bar')`), which leads to high boilerplate,
runtime string typos, and difficulty refactoring CLI flags.
### Key Changes
1. **Typed Option Descriptors
(`lib/src/runner/options/option_descriptor.dart`)**:
- Introduces metadata-rich `OptionDescriptor<T>`,
`StringOptionDescriptor`, `FlagOptionDescriptor`,
`NullableFlagOptionDescriptor`, and `MultiOptionDescriptor`.
- Option definitions are strongly typed `const` declarations owning
their name, abbreviations, defaults, help text, allowed values, and
`verboseOnly` dynamic visibility.
2. **Domain Option Bundles
(`lib/src/runner/options/option_bundle.dart`)**:
- `OptionBundle` allows cohesive grouping of related options into
reusable compile-time `const` units with automatic section header
separators in `--help` output (via `title` and `subBundles`).
- Automatically auto-wires `command.verboseHelp` down to all child
descriptors during registration.
- Introduces foundational bundles in `common_options.dart`
(`CommonBuildOptionsBundle`, `BuildModeOptionsBundle`,
`DartCompileOptionsBundle`).
3. **Type-Safe Argument Access
(`lib/src/runner/options/safe_arg_results.dart`)**:
- Adds a single generic `T getValue<T>(OptionDescriptor<T> descriptor)`
on `FlutterCommand` that leverages Dart type inference to return
non-nullable `bool`, `bool?`, `List<String>`, or `String?` without type
casting or null-coalescing noise.
- Adds `wasProvided()` (aliased `wasParsed()`) for explicit presence
queries.
4. **Vertical Slice Validation on `BuildWebCommand`**:
- Replaced ~160 lines of imperative constructor setup in
`BuildWebCommand` with 4 declarative `const` bundles.
- Modularized 18 web options into `WebCoreOptionsBundle`,
`WebJsOptionsBundle`, and `WebWasmOptionsBundle` in
`lib/src/web/web_options.dart`.
### Verification
- Whole-package `dart analyze` across `packages/flutter_tools`: **0
issues**.
- Unit and hermetic tests (`option_descriptor_test.dart`,
`build_web_test.dart`, `compile_web_test.dart`): **51/51 tests
passing**. K
Kevin Moore committed
3479680076e5a996a5d76c3415c4b7854d28a0a3
Parent: 4bb854b
Committed by GitHub <noreply@github.com>
on 8/21/2026, 6:58:10 PM