Add --starlark_coverage_report

If the new flag `--starlark_coverage_report` is set to a non-empty
value, the Starlark coverage recorder will be enabled for all `.bzl`
files under the output base executed during the Blaze command. At the
end of the command, the collected coverage data will be emitted to the
file path given as the flag argument in LCOV format.

src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandDispatcher.java

@@ -67,6 +67,7 @@
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.OutputStream;
+import java.io.PrintWriter;
 import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
@@ -371,6 +372,12 @@ private BlazeCommandResult execExclusively(
             message, FailureDetails.Command.Code.STARLARK_CPU_PROFILING_INITIALIZATION_FAILURE);
       }
     }
+    if (!commonOptions.starlarkCoverageReport.isEmpty()) {
+      // Record coverage for all `.bzl` files, excluding the built-ins, which don't have paths that
+      // could be resolved when a human-readable coverage report is generated.
+      Starlark.startCoverageCollection(
+          path -> !path.startsWith("/virtual_builtins_bzl") && path.endsWith(".bzl"));
+    }
 
     BlazeCommandResult result =
         createDetailedCommandResult(
@@ -603,6 +610,18 @@ private BlazeCommandResult execExclusively(
           }
         }
       }
+      if (!commonOptions.starlarkCoverageReport.isEmpty()) {
+        FileOutputStream out;
+        try {
+          out = new FileOutputStream(commonOptions.starlarkCoverageReport);
+        } catch (IOException ex) {
+          String message = "Starlark coverage recorder: " + ex.getMessage();
+          outErr.printErrLn(message);
+          return createDetailedCommandResult(
+              message, FailureDetails.Command.Code.STARLARK_COVERAGE_REPORT_DUMP_FAILURE);
+        }
+        Starlark.dumpCoverage(new PrintWriter(out));
+      }
 
       needToCallAfterCommand = false;
       return runtime.afterCommand(env, result);

src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java

@@ -293,6 +293,14 @@ public String getTypeDescription() {
       help = "Writes into the specified file a pprof profile of CPU usage by all Starlark threads.")
   public String starlarkCpuProfile;
 
+  @Option(
+      name = "starlark_coverage_report",
+      defaultValue = "",
+      documentationCategory = OptionDocumentationCategory.LOGGING,
+      effectTags = {OptionEffectTag.BAZEL_MONITORING},
+      help = "Writes into the specified file an lcov coverage report for all Starlark files.")
+  public String starlarkCoverageReport;
+
   @Option(
       name = "record_full_profiler_data",
       defaultValue = "false",

src/main/protobuf/failure_details.proto

@@ -533,6 +533,7 @@ message Command {
     NOT_IN_WORKSPACE = 12 [(metadata) = { exit_code: 2 }];
     SPACES_IN_WORKSPACE_PATH = 13 [(metadata) = { exit_code: 36 }];
     IN_OUTPUT_DIRECTORY = 14 [(metadata) = { exit_code: 2 }];
+    STARLARK_COVERAGE_REPORT_DUMP_FAILURE = 15 [(metadata) = { exit_code: 36 }];
   }
 
   Code code = 1;