Updates the repo tooling to Dart 3, now that the N-2 version has Dart 3, which allows us to use Dart 3 features (e.g., records) going forward.
To allow the update:
- Removes `break` commands from `switch`es (all done automatically with `dart fix --apply`)
- Replaces mocking of `ProcessResult` with just creating an actual `ProcessResult` since it's a `final` data class and thus can't (but also doesn't need to be) mocked.
⦠to `update-excerpts` tool
Need this tool to recognize `.java`, `.gradle`, and `.sh` files in order to complete [flutter/flutter#102679](https://github.com/flutter/flutter/issues/102679). The `README.md` for the `espresso` package contains code from `.java`, `.gradle`, and `.sh` files.
Support for `.m` files was requested by @tarrinneal.
Moves the check that README snippets using code excerpting are up to date to LUCI. Now that the check has been rewritten to be extremely fast, it's folded into the existing repo checks instead of being a separate task.
Also adjusts the tooling slightly so that it logs the count of snippets checked, for auditability in CI, like the old version of the excerpt update tooling did.
Part of https://github.com/flutter/flutter/issues/114373
* Allows excerpts to come from any package, not just examples.
* Fixes a bug in the excerpting logic that was causing a stray `}` to appear in one example.
* Removes the need for `build.excerpt.yaml` files.
* Remove the dependency on build_runner for excerpts.
* Reduces the time to generate the excerpts from about 10 minutes to about 5 seconds.
* Almost certainly fixes https://github.com/flutter/flutter/issues/107180 (untested).
The new logic is not quite backwards compatible; the `path-base` feature now specifies a real path to the actual source directories, rather than a path into the invisible generated `excerpts/` directory with its special structure. Also, a number of features from the previous package that were not actually used in this repository are no longer supported (such as having multiple section names per `#docregion` pragma).
Refactors colorization to a centralized utility file, and makes it all conditional on `stdout` having ANSI escape support. This makes the output more readable on LUCI, which unlike the Cirrus log display doesn't handle ANSI.
Fixes https://github.com/flutter/flutter/issues/89392
Since the tool only needs to support back to Flutter 3.3 (the oldest version we still run CI with), this updates the tool to the corresponding minimum Dart version.
This allows the use of `super` parameters, so `dart fix --apply` was run to convert them all (and remove all the includes that were only needed for setting default values).
Also opportunistically cleans up a bunch of unnecessary, very old `dart:async` includes. (Other than those removals, the changes here are all `dart fix`-generated.)
Extracts common logic for running `pub get`, and switches commands to use it. The common logic always uses `flutter pub get` for Flutter packages, rather than `dart pub get`, since the latter will fail if someone has a non-Flutter `dart` in their path before `flutter` (e.g., Dart team members contributing PRs).
It can be useful in debugging snippet setup to look at the extraction output, but the tool cleans that up automatically. Running the extraction manually is complicated due to the on-the-fly pubspec modifications, so this adds a `--no-cleanup` flag that can be used to skip the deletion of the extraction output, and instead log its location to the terminal.
Updates `update-excerpts` to support any top-level .md file (other than CHANGELOG.md), rather than just README.md. This is useful for supplemental content, such as migration guides linked from the main README file.
Also makes some small improvements to the error messaging:
- The list of incorrect files is now relative to, and restricted to, the package. This makes the error message simpler, and ensures that changed files in other packages don't get listed.
- Adds a link to the relevant wiki docs, since this has been a source of confusion for newer contributors.
When determining whether or not to fail with `--fail-on-change`, only
look at .md files. In some cases, running the necessary commands (e.g.,
`flutter pub get`) may change unrelated files, causing fales positive
failures. Only changed documentation files should be flagged.
Also log the specific files that were detected as changed, to aid in
debugging any future false positives.
Fixes https://github.com/flutter/flutter/issues/111592
Fixes https://github.com/flutter/flutter/issues/111590
