blob: ccfeea0e473238b982b8f3e0d9acb6b195e6ed36 [file] [log] [blame]
// Copyright 2013 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'dart:async';
import 'package:colorize/colorize.dart';
import 'package:file/file.dart';
import 'package:git/git.dart';
import 'package:path/path.dart' as p;
import 'package:platform/platform.dart';
import 'package:pub_semver/pub_semver.dart';
import 'core.dart';
import 'package_command.dart';
import 'process_runner.dart';
import 'repository_package.dart';
/// Enumeration options for package looping commands.
enum PackageLoopingType {
/// Only enumerates the top level packages, without including any of their
/// subpackages.
/// Enumerates the top level packages and any example packages they contain.
/// Enumerates all packages recursively, including both example and
/// non-example subpackages.
/// Possible outcomes of a command run for a package.
enum RunState {
/// The command succeeded for the package.
/// The command was skipped for the package.
/// The command was skipped for the package because it was explicitly excluded
/// in the command arguments.
/// The command failed for the package.
/// The result of a [runForPackage] call.
class PackageResult {
/// A successful result.
PackageResult.success() : this._(RunState.succeeded);
/// A run that was skipped as explained in [reason].
PackageResult.skip(String reason)
: this._(RunState.skipped, <String>[reason]);
/// A run that was excluded by the command invocation.
PackageResult.exclude() : this._(RunState.excluded);
/// A run that failed.
/// If [errors] are provided, they will be listed in the summary, otherwise
/// the summary will simply show that the package failed.[List<String> errors = const <String>[]])
: this._(RunState.failed, errors);
const PackageResult._(this.state, [this.details = const <String>[]]);
/// The state the package run completed with.
final RunState state;
/// Information about the result:
/// - For `succeeded`, this is empty.
/// - For `skipped`, it contains a single entry describing why the run was
/// skipped.
/// - For `failed`, it contains zero or more specific error details to be
/// shown in the summary.
final List<String> details;
/// An abstract base class for a command that iterates over a set of packages
/// controlled by a standard set of flags, running some actions on each package,
/// and collecting and reporting the success/failure of those actions.
abstract class PackageLoopingCommand extends PackageCommand {
/// Creates a command to operate on [packagesDir] with the given environment.
Directory packagesDir, {
ProcessRunner processRunner = const ProcessRunner(),
Platform platform = const LocalPlatform(),
GitDir? gitDir,
}) : super(packagesDir,
processRunner: processRunner, platform: platform, gitDir: gitDir) {
help: 'Skip any packages that require a Flutter version newer than '
'the provided version.',
help: 'Skip any packages that require a Dart version newer than '
'the provided version.',
static const String _skipByFlutterVersionArg =
static const String _skipByDartVersionArg =
/// Packages that had at least one [logWarning] call.
final Set<PackageEnumerationEntry> _packagesWithWarnings =
/// Number of warnings that happened outside of a [runForPackage] call.
int _otherWarningCount = 0;
/// The package currently being run by [runForPackage].
PackageEnumerationEntry? _currentPackageEntry;
/// Called during [run] before any calls to [runForPackage]. This provides an
/// opportunity to fail early if the command can't be run (e.g., because the
/// arguments are invalid), and to set up any run-level state.
Future<void> initializeRun() async {}
/// Returns the packages to process. By default, this returns the packages
/// defined by the standard tooling flags and the [inculdeSubpackages] option,
/// but can be overridden for custom package enumeration.
/// Note: Consistent behavior across commands whenever possibel is a goal for
/// this tool, so this should be overridden only in rare cases.
Stream<PackageEnumerationEntry> getPackagesToProcess() async* {
switch (packageLoopingType) {
case PackageLoopingType.topLevelOnly:
yield* getTargetPackages(filterExcluded: false);
case PackageLoopingType.includeExamples:
await for (final PackageEnumerationEntry packageEntry
in getTargetPackages(filterExcluded: false)) {
yield packageEntry;
yield* Stream<PackageEnumerationEntry>.fromIterable(packageEntry
.map((RepositoryPackage package) => PackageEnumerationEntry(
excluded: packageEntry.excluded)));
case PackageLoopingType.includeAllSubpackages:
yield* getTargetPackagesAndSubpackages(filterExcluded: false);
/// Runs the command for [package], returning a list of errors.
/// Errors may either be an empty string if there is no context that should
/// be included in the final error summary (e.g., a command that only has a
/// single failure mode), or strings that should be listed for that package
/// in the final summary. An empty list indicates success.
Future<PackageResult> runForPackage(RepositoryPackage package);
/// Called during [run] after all calls to [runForPackage]. This provides an
/// opportunity to do any cleanup of run-level state.
Future<void> completeRun() async {}
/// If [captureOutput], this is called just before exiting with all captured
/// [output].
Future<void> handleCapturedOutput(List<String> output) async {}
/// Whether or not the output (if any) of [runForPackage] is long, or short.
/// This changes the logging that happens at the start of each package's
/// run; long output gets a banner-style message to make it easier to find,
/// while short output gets a single-line entry.
/// When this is false, runForPackage output should be indented if possible,
/// to make the output structure easier to follow.
bool get hasLongOutput => true;
/// Whether to loop over top-level packages only, or some or all of their
/// sub-packages as well.
PackageLoopingType get packageLoopingType => PackageLoopingType.topLevelOnly;
/// The text to output at the start when reporting one or more failures.
/// This will be followed by a list of packages that reported errors, with
/// the per-package details if any.
/// This only needs to be overridden if the summary should provide extra
/// context.
String get failureListHeader => 'The following packages had errors:';
/// The text to output at the end when reporting one or more failures. This
/// will be printed immediately after the a list of packages that reported
/// errors.
/// This only needs to be overridden if the summary should provide extra
/// context.
String get failureListFooter => 'See above for full details.';
/// The summary string used for a successful run in the final overview output.
String get successSummaryMessage => 'ran';
/// If true, all printing (including the summary) will be redirected to a
/// buffer, and provided in a call to [handleCapturedOutput] at the end of
/// the run.
/// Capturing output will disable any colorizing of output from this base
/// class.
bool get captureOutput => false;
// ----------------------------------------
/// Logs that a warning occurred, and prints `warningMessage` in yellow.
/// Warnings are not surfaced in CI summaries, so this is only useful for
/// highlighting something when someone is already looking though the log
/// messages. DO NOT RELY on someone noticing a warning; instead, use it for
/// things that might be useful to someone debugging an unexpected result.
void logWarning(String warningMessage) {
_printColorized(warningMessage, Styles.YELLOW);
if (_currentPackageEntry != null) {
} else {
/// Returns the relative path from [from] to [entity] in Posix style.
/// This should be used when, for example, printing package-relative paths in
/// status or error messages.
String getRelativePosixPath(
FileSystemEntity entity, {
required Directory from,
}) =>
p.posix.joinAll(path.split(path.relative(entity.path, from: from.path)));
/// The suggested indentation for printed output.
String get indentation => hasLongOutput ? '' : ' ';
// ----------------------------------------
Future<void> run() async {
bool succeeded;
if (captureOutput) {
final List<String> output = <String>[];
final ZoneSpecification logSwitchSpecification = ZoneSpecification(
print: (Zone self, ZoneDelegate parent, Zone zone, String message) {
succeeded = await runZoned<Future<bool>>(_runInternal,
zoneSpecification: logSwitchSpecification);
await handleCapturedOutput(output);
} else {
succeeded = await _runInternal();
if (!succeeded) {
throw ToolExit(exitCommandFoundErrors);
Future<bool> _runInternal() async {
_otherWarningCount = 0;
_currentPackageEntry = null;
final String minFlutterVersionArg = getStringArg(_skipByFlutterVersionArg);
final Version? minFlutterVersion = minFlutterVersionArg.isEmpty
? null
: Version.parse(minFlutterVersionArg);
final String minDartVersionArg = getStringArg(_skipByDartVersionArg);
final Version? minDartVersion =
minDartVersionArg.isEmpty ? null : Version.parse(minDartVersionArg);
final DateTime runStart =;
await initializeRun();
final List<PackageEnumerationEntry> targetPackages =
await getPackagesToProcess().toList();
final Map<PackageEnumerationEntry, PackageResult> results =
<PackageEnumerationEntry, PackageResult>{};
for (final PackageEnumerationEntry entry in targetPackages) {
final DateTime packageStart =;
_currentPackageEntry = entry;
_printPackageHeading(entry, startTime: runStart);
// Command implementations should never see excluded packages; they are
// included at this level only for logging.
if (entry.excluded) {
results[entry] = PackageResult.exclude();
PackageResult result;
try {
result = await _runForPackageIfSupported(entry.package,
minFlutterVersion: minFlutterVersion,
minDartVersion: minDartVersion);
} catch (e, stack) {
result =<String>['Unhandled exception']);
if (result.state == RunState.skipped) {
_printColorized('${indentation}SKIPPING: ${result.details.first}',
results[entry] = result;
// Only log an elapsed time for long output; for short output, comparing
// the relative timestamps of successive entries should be trivial.
if (shouldLogTiming && hasLongOutput) {
final Duration elapsedTime =;
'\n[${entry.package.displayName} completed in '
'${elapsedTime.inMinutes}m ${elapsedTime.inSeconds % 60}s]',
_currentPackageEntry = null;
// If there were any errors reported, summarize them and exit.
if (results.values
.any((PackageResult result) => result.state == RunState.failed)) {
_printFailureSummary(targetPackages, results);
return false;
// Otherwise, print a summary of what ran for ease of auditing that all the
// expected tests ran.
_printRunSummary(targetPackages, results);
_printSuccess('No issues found!');
return true;
/// Returns the result of running [runForPackage] if the package is supported
/// by any run constraints, or a skip result if it is not.
Future<PackageResult> _runForPackageIfSupported(
RepositoryPackage package, {
Version? minFlutterVersion,
Version? minDartVersion,
}) async {
if (minFlutterVersion != null) {
final Pubspec pubspec = package.parsePubspec();
final VersionConstraint? flutterConstraint =
if (flutterConstraint != null &&
!flutterConstraint.allows(minFlutterVersion)) {
return PackageResult.skip(
'Does not support Flutter $minFlutterVersion');
if (minDartVersion != null) {
final Pubspec pubspec = package.parsePubspec();
final VersionConstraint? dartConstraint = pubspec.environment?['sdk'];
if (dartConstraint != null && !dartConstraint.allows(minDartVersion)) {
return PackageResult.skip('Does not support Dart $minDartVersion');
return runForPackage(package);
void _printSuccess(String message) {
captureOutput ? print(message) : printSuccess(message);
void _printError(String message) {
captureOutput ? print(message) : printError(message);
/// Prints the status message indicating that the command is being run for
/// [package].
/// Something is always printed to make it easier to distinguish between
/// a command running for a package and producing no output, and a command
/// not having been run for a package.
void _printPackageHeading(PackageEnumerationEntry entry,
{required DateTime startTime}) {
final String packageDisplayName = entry.package.displayName;
String heading = entry.excluded
? 'Not running for $packageDisplayName; excluded'
: 'Running for $packageDisplayName';
if (shouldLogTiming) {
final Duration relativeTime =;
final String timeString = _formatDurationAsRelativeTime(relativeTime);
heading =
hasLongOutput ? '$heading [@$timeString]' : '[$timeString] $heading';
if (hasLongOutput) {
heading = '''
|| $heading
} else if (!entry.excluded) {
heading = '$heading...';
_printColorized(heading, entry.excluded ? Styles.DARK_GRAY : Styles.CYAN);
/// Prints a summary of packges run, packages skipped, and warnings.
void _printRunSummary(List<PackageEnumerationEntry> packages,
Map<PackageEnumerationEntry, PackageResult> results) {
final Set<PackageEnumerationEntry> skippedPackages = results.entries
.where((MapEntry<PackageEnumerationEntry, PackageResult> entry) =>
entry.value.state == RunState.skipped)
.map((MapEntry<PackageEnumerationEntry, PackageResult> entry) =>
final int skipCount = skippedPackages.length +
.where((PackageEnumerationEntry package) => package.excluded)
// Split the warnings into those from packages that ran, and those that
// were skipped.
final Set<PackageEnumerationEntry> skippedPackagesWithWarnings =
final int skippedWarningCount = skippedPackagesWithWarnings.length;
final int runWarningCount =
_packagesWithWarnings.length - skippedWarningCount;
final String runWarningSummary =
runWarningCount > 0 ? ' ($runWarningCount with warnings)' : '';
final String skippedWarningSummary =
runWarningCount > 0 ? ' ($skippedWarningCount with warnings)' : '';
if (hasLongOutput) {
_printPerPackageRunOverview(packages, skipped: skippedPackages);
'Ran for ${packages.length - skipCount} package(s)$runWarningSummary');
if (skipCount > 0) {
print('Skipped $skipCount package(s)$skippedWarningSummary');
if (_otherWarningCount > 0) {
print('$_otherWarningCount warnings not associated with a package');
/// Prints a one-line-per-package overview of the run results for each
/// package.
void _printPerPackageRunOverview(
List<PackageEnumerationEntry> packageEnumeration,
{required Set<PackageEnumerationEntry> skipped}) {
print('Run overview:');
for (final PackageEnumerationEntry entry in packageEnumeration) {
final bool hadWarning = _packagesWithWarnings.contains(entry);
Styles style;
String summary;
if (entry.excluded) {
summary = 'excluded';
style = Styles.DARK_GRAY;
} else if (skipped.contains(entry)) {
summary = 'skipped';
style = hadWarning ? Styles.LIGHT_YELLOW : Styles.DARK_GRAY;
} else {
summary = successSummaryMessage;
style = hadWarning ? Styles.YELLOW : Styles.GREEN;
if (hadWarning) {
summary += ' (with warning)';
if (!captureOutput) {
summary = (Colorize(summary)..apply(style)).toString();
print(' ${entry.package.displayName} - $summary');
/// Prints a summary of all of the failures from [results].
void _printFailureSummary(List<PackageEnumerationEntry> packageEnumeration,
Map<PackageEnumerationEntry, PackageResult> results) {
const String indentation = ' ';
for (final PackageEnumerationEntry entry in packageEnumeration) {
final PackageResult result = results[entry]!;
if (result.state == RunState.failed) {
final String errorIndentation = indentation * 2;
String errorDetails = '';
if (result.details.isNotEmpty) {
errorDetails =
/// Prints [message] in [color] unless [captureOutput] is set, in which case
/// it is printed without color.
void _printColorized(String message, Styles color) {
if (captureOutput) {
} else {
/// Returns a duration [d] formatted as minutes:seconds. Does not use hours,
/// since time logging is primarily intended for CI, where durations should
/// always be less than an hour.
String _formatDurationAsRelativeTime(Duration d) {
return '${d.inMinutes}:${(d.inSeconds % 60).toString().padLeft(2, '0')}';