Add a 'bot.dart' executable to the gardening tools.

tools/gardening/bin/compare_failures.dart

 // Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /// Compares the test log of a build step with previous builds.
 ///
 /// Use this to detect flakiness of failures, especially timeouts.
 
 import 'dart:async';
 import 'dart:io';
 
 import 'package:args/args.dart';
 import 'package:gardening/src/buildbot_structures.dart';
 import 'package:gardening/src/buildbot_loading.dart';
 import 'package:gardening/src/util.dart';
 
+void help(ArgParser argParser) {
+  print('Given a <log-uri> finds all failing tests in that stdout. Then ');
+  print('fetches earlier runs of the same bot and compares the results.');
+  print('This tool is particularly useful to detect flakes and their ');
+  print('frequency.');
+  print('Usage: compare_failures [options] <log-uri>');
+  print('where <log-uri> is the uri the stdio output of a failing test step');
+  print('and options are:');
+  print(argParser.usage);
+}
+
 main(List<String> args) async {
   ArgParser argParser = createArgParser();
+  argParser.addOption("run-count",
+      defaultsTo: "10", help: "How many previous runs should be fetched");
   ArgResults argResults = argParser.parse(args);
   processArgResults(argResults);
-  if (argResults.rest.length != 1) {
-    print('Usage: compare_failures [options] <log-uri>');
-    print('where <log-uri> is the uri the stdio output of a failing test step');
-    print('and options are:');
-    print(argParser.usage);
+  var runCount = int.parse(argResults['run-count'], onError: (_) => null);
+
+  if (argResults.rest.length != 1 || argResults['help'] || runCount == null) {
+    help(argParser);
+    if (argResults['help']) return;
     exit(1);
   }
   String url = argResults.rest.first;
   if (!url.endsWith('/text')) {
     // Use the text version of the stdio log.
     url += '/text';
   }
   Uri uri = Uri.parse(url);
   HttpClient client = new HttpClient();
   BuildUri buildUri = new BuildUri(uri);
-  List<BuildResult> results = await readBuildResults(client, buildUri);
+  List<BuildResult> results =
+      await readBuildResults(client, buildUri, runCount);
   print(generateBuildResultsSummary(buildUri, results));
   client.close();
 }
 
 /// Creates a [BuildResult] for [buildUri] and, if it contains failures, the
 /// [BuildResult]s for the previous 5 builds.
 Future<List<BuildResult>> readBuildResults(
-    HttpClient client, BuildUri buildUri) async {
+    HttpClient client, BuildUri buildUri, int runCount) async {
   List<BuildResult> summaries = <BuildResult>[];
   BuildResult firstSummary = await readBuildResult(client, buildUri);
   summaries.add(firstSummary);
   if (firstSummary.hasFailures) {
-    for (int i = 0; i < 10; i++) {
+    for (int i = 0; i < runCount; i++) {
       buildUri = buildUri.prev();
       summaries.add(await readBuildResult(client, buildUri));
     }
   }
   return summaries;
 }
 
 /// Generate a summary of the timeouts and other failures in [results].
 String generateBuildResultsSummary(
     BuildUri buildUri, List<BuildResult> results) {
@@ skipping 76 matching lines @@
           sb.write(' / ');
           sb.write(padRight('-- OK --', 10));
         }
         sb.write('\n');
       }
       sb.write('\n');
     });
   }
   return sb.toString();
 }