|
| 1 | +// Copyright 2013 The Flutter Authors. All rights reserved. |
| 2 | +// Use of this source code is governed by a BSD-style license that can be |
| 3 | +// found in the LICENSE file. |
| 4 | + |
| 5 | +import 'package:colorize/colorize.dart'; |
| 6 | +import 'package:file/file.dart'; |
| 7 | +import 'package:git/git.dart'; |
| 8 | +import 'package:path/path.dart' as p; |
| 9 | + |
| 10 | +import 'core.dart'; |
| 11 | +import 'plugin_command.dart'; |
| 12 | +import 'process_runner.dart'; |
| 13 | + |
| 14 | +/// An abstract base class for a command that iterates over a set of packages |
| 15 | +/// controlled by a standard set of flags, running some actions on each package, |
| 16 | +/// and collecting and reporting the success/failure of those actions. |
| 17 | +abstract class PackageLoopingCommand extends PluginCommand { |
| 18 | + /// Creates a command to operate on [packagesDir] with the given environment. |
| 19 | + PackageLoopingCommand( |
| 20 | + Directory packagesDir, { |
| 21 | + ProcessRunner processRunner = const ProcessRunner(), |
| 22 | + GitDir? gitDir, |
| 23 | + }) : super(packagesDir, processRunner: processRunner, gitDir: gitDir); |
| 24 | + |
| 25 | + /// Called during [run] before any calls to [runForPackage]. This provides an |
| 26 | + /// opportunity to fail early if the command can't be run (e.g., because the |
| 27 | + /// arguments are invalid), and to set up any run-level state. |
| 28 | + Future<void> initializeRun() async {} |
| 29 | + |
| 30 | + /// Runs the command for [package], returning a list of errors. |
| 31 | + /// |
| 32 | + /// Errors may either be an empty string if there is no context that should |
| 33 | + /// be included in the final error summary (e.g., a command that only has a |
| 34 | + /// single failure mode), or strings that should be listed for that package |
| 35 | + /// in the final summary. An empty list indicates success. |
| 36 | + Future<List<String>> runForPackage(Directory package); |
| 37 | + |
| 38 | + /// Whether or not the output (if any) of [runForPackage] is long, or short. |
| 39 | + /// |
| 40 | + /// This changes the logging that happens at the start of each package's |
| 41 | + /// run; long output gets a banner-style message to make it easier to find, |
| 42 | + /// while short output gets a single-line entry. |
| 43 | + /// |
| 44 | + /// When this is false, runForPackage output should be indented if possible, |
| 45 | + /// to make the output structure easier to follow. |
| 46 | + bool get hasLongOutput => true; |
| 47 | + |
| 48 | + /// Whether to loop over all packages (e.g., including example/), rather than |
| 49 | + /// only top-level packages. |
| 50 | + bool get includeSubpackages => false; |
| 51 | + |
| 52 | + /// The text to output at the start when reporting one or more failures. |
| 53 | + /// This will be followed by a list of packages that reported errors, with |
| 54 | + /// the per-package details if any. |
| 55 | + /// |
| 56 | + /// This only needs to be overridden if the summary should provide extra |
| 57 | + /// context. |
| 58 | + String get failureListHeader => 'The following packages had errors:'; |
| 59 | + |
| 60 | + /// The text to output at the end when reporting one or more failures. This |
| 61 | + /// will be printed immediately after the a list of packages that reported |
| 62 | + /// errors. |
| 63 | + /// |
| 64 | + /// This only needs to be overridden if the summary should provide extra |
| 65 | + /// context. |
| 66 | + String get failureListFooter => 'See above for full details.'; |
| 67 | + |
| 68 | + // ---------------------------------------- |
| 69 | + |
| 70 | + /// A convenience constant for [runForPackage] success that's more |
| 71 | + /// self-documenting than the value. |
| 72 | + static const List<String> success = <String>[]; |
| 73 | + |
| 74 | + /// A convenience constant for [runForPackage] failure without additional |
| 75 | + /// context that's more self-documenting than the value. |
| 76 | + static const List<String> failure = <String>['']; |
| 77 | + |
| 78 | + /// Prints a message using a standard format indicating that the package was |
| 79 | + /// skipped, with an explanation of why. |
| 80 | + void printSkip(String reason) { |
| 81 | + print(Colorize('SKIPPING: $reason')..darkGray()); |
| 82 | + } |
| 83 | + |
| 84 | + /// Returns the identifying name to use for [package]. |
| 85 | + /// |
| 86 | + /// Implementations should not expect a specific format for this string, since |
| 87 | + /// it uses heuristics to try to be precise without being overly verbose. If |
| 88 | + /// an exact format (e.g., published name, or basename) is required, that |
| 89 | + /// should be used instead. |
| 90 | + String getPackageDescription(Directory package) { |
| 91 | + String packageName = p.relative(package.path, from: packagesDir.path); |
| 92 | + final List<String> components = p.split(packageName); |
| 93 | + // For the common federated plugin pattern of `foo/foo_subpackage`, drop |
| 94 | + // the first part since it's not useful. |
| 95 | + if (components.length == 2 && |
| 96 | + components[1].startsWith('${components[0]}_')) { |
| 97 | + packageName = components[1]; |
| 98 | + } |
| 99 | + return packageName; |
| 100 | + } |
| 101 | + |
| 102 | + // ---------------------------------------- |
| 103 | + |
| 104 | + @override |
| 105 | + Future<void> run() async { |
| 106 | + await initializeRun(); |
| 107 | + |
| 108 | + final List<Directory> packages = includeSubpackages |
| 109 | + ? await getPackages().toList() |
| 110 | + : await getPlugins().toList(); |
| 111 | + |
| 112 | + final Map<Directory, List<String>> results = <Directory, List<String>>{}; |
| 113 | + for (final Directory package in packages) { |
| 114 | + _printPackageHeading(package); |
| 115 | + results[package] = await runForPackage(package); |
| 116 | + } |
| 117 | + |
| 118 | + // If there were any errors reported, summarize them and exit. |
| 119 | + if (results.values.any((List<String> failures) => failures.isNotEmpty)) { |
| 120 | + const String indentation = ' '; |
| 121 | + printError(failureListHeader); |
| 122 | + for (final Directory package in packages) { |
| 123 | + final List<String> errors = results[package]!; |
| 124 | + if (errors.isNotEmpty) { |
| 125 | + final String errorIndentation = indentation * 2; |
| 126 | + String errorDetails = errors.join('\n$errorIndentation'); |
| 127 | + if (errorDetails.isNotEmpty) { |
| 128 | + errorDetails = ':\n$errorIndentation$errorDetails'; |
| 129 | + } |
| 130 | + printError( |
| 131 | + '$indentation${getPackageDescription(package)}$errorDetails'); |
| 132 | + } |
| 133 | + } |
| 134 | + printError(failureListFooter); |
| 135 | + throw ToolExit(exitCommandFoundErrors); |
| 136 | + } |
| 137 | + |
| 138 | + printSuccess('\n\nNo issues found!'); |
| 139 | + } |
| 140 | + |
| 141 | + /// Prints the status message indicating that the command is being run for |
| 142 | + /// [package]. |
| 143 | + /// |
| 144 | + /// Something is always printed to make it easier to distinguish between |
| 145 | + /// a command running for a package and producing no output, and a command |
| 146 | + /// not having been run for a package. |
| 147 | + void _printPackageHeading(Directory package) { |
| 148 | + String heading = 'Running for ${getPackageDescription(package)}'; |
| 149 | + if (hasLongOutput) { |
| 150 | + heading = ''' |
| 151 | +
|
| 152 | +============================================================ |
| 153 | +|| $heading |
| 154 | +============================================================ |
| 155 | +'''; |
| 156 | + } else { |
| 157 | + heading = '$heading...'; |
| 158 | + } |
| 159 | + print(Colorize(heading)..cyan()); |
| 160 | + } |
| 161 | +} |
0 commit comments