[llvm-cov] Add a project coverage summary above the index page.

[MaggieYi]

Summary

Currently, the project coverage summary is given in the bottom row of the index table. If there are a large number of source files listed in the index table, the summary row is not immediately visible. This patch adds the project coverage summary above the index page to improve the report readability. I have also added the project directory to the summary.

In addition, filenames are only shown as a part of path name in the filename column of the index page. If the file path includes many directory levels, this column doesnÎéÎ÷t look nice. This patch separates the filename and path into two columns, and the path is shown the relative to the project directory specified in the summary, which also improves clarity.

[vsk]

Currently, the project coverage summary is given in the bottom row of the index table. If there are a large number of source files listed in the index table, the summary row is not immediately visible. This patch adds the project coverage summary above the index page to improve the report readability.

I'd prefer to just tackle this issue in this patch. IMO it would be better to drop (or at least defer) the other changes.

I have also added the project directory to the summary.

I don't think this clarifies anything, and would prefer not to add it.

In addition, filenames are only shown as a part of path name in the filename column of the index page. If the file path includes many directory levels, this column doesnÎéÎ÷t look nice.

This is intentional and it matches the behavior of the text reports. The longest-common prefix of the path names are stripped away to make it easier to see the filename. This prefix is visually distracting and doesn't convey any useful information.

[MaggieYi]

In D24687#546833, @vsk wrote:

I'd prefer to just tackle this issue in this patch. IMO it would be better to drop (or at least defer) the other changes.

Ok, I have updated the patch following your advice.

This is intentional and it matches the behavior of the text reports. The longest-common prefix of the path names are stripped away to make it easier to see the filename. This prefix is visually distracting and doesn't convey any useful information.

If the project is branched, the longest-common prefix of the path (I called the project directory) will show the branch name. The project directory will tell the user where the source code come from.

[vsk]

If the project is branched, the longest-common prefix of the path (I called the project directory) will show the branch name. The project directory will tell the user where the source code come from.

It would be easier for me to understand the motivation behind this if you could upload an example report with your changes. I still don't understand what it is about the current scheme that makes it difficult for readers to figure out where some source file comes from.

tools/llvm-cov/SourceCoverageViewHTML.cpp

462

This patch still seems larger than it needs to be. Can't we get the entire desired functional change by just inserting another emitFileSummary(OSRef, "Totals", Totals, /*IsTotals=*/true) here?

test/tools/llvm-cov/multiple-files.test

 // RUN: llvm-profdata merge %S/Inputs/multiple-files.proftext -o %t.profdata
 // RUN: llvm-cov report %S/Inputs/multiple-files.covmapping -instr-profile %t.profdata | FileCheck %s
 
 // CHECK: Filename
 // CHECK-NEXT: ---
 // CHECK-NEXT: {{^}}a{{[/\\]}}f2.c
 // CHECK-NEXT: {{^}}b{{[/\\]}}c{{[/\\]}}f4.c
 // CHECK-NEXT: {{^}}b{{[/\\]}}f3.c
 // CHECK-NEXT: {{^}}f1.c
+
+// RUN: llvm-cov show -format=html %S/Inputs/multiple-files.covmapping -instr-profile=%t.profdata -o %t.dir
+// RUN: FileCheck -check-prefixes=HTML-INDEX -input-file=%t.dir/index.html %s
+
+// HTML-INDEX: <td><pre>Project directory:</pre></td>
+// HTML-INDEX: <td><pre>{{[/\\]}}tmp{{[/\\]}}coverage</pre></td>
+// HTML-INDEX: <td><pre>Function coverage:</pre></td>
+// HTML-INDEX: <td><pre>Line coverage:</pre></td>
+// HTML-INDEX: <td><pre>{{[/\\]}}a</pre></td>
+// HTML-INDEX: <td><pre>{{[/\\]}}b{{[/\\]}}c</pre></td>
+// HTML-INDEX: <td><pre>{{[/\\]}}b</pre></td>
+// HTML-INDEX: <td><pre>{{[/\\]}}</pre></td>

test/tools/llvm-cov/native_separators.c

 // To create the covmapping for this file on Linux, copy this file to /tmp
 // cd into /tmp. Use llvm-cov convert-for-testing to extract the covmapping.
 // This test is Windows-only. It checks that all paths, which are generated
 // in the index and source coverage reports, are native path. For example,
 // on Windows all '/' are converted to '\'.
 // REQUIRES: system-windows
 
 // RUN: llvm-profdata merge %S/Inputs/double_dots.proftext -o %t.profdata
 // RUN: llvm-cov show %S/Inputs/native_separators.covmapping -instr-profile=%t.profdata -o %t.dir
 // RUN: FileCheck -check-prefixes=TEXT-INDEX -input-file=%t.dir/index.txt %s
 // RUN: llvm-cov show -format=html %S/Inputs/native_separators.covmapping -instr-profile=%t.profdata -filename-equivalence ../llvm-"config"/../llvm-"cov"/native_separators.c -o %t.dir
 // RUN: FileCheck -check-prefixes=HTML-INDEX -input-file=%t.dir/index.html %s
 // RUN: llvm-cov show -format=html %S/Inputs/native_separators.covmapping -instr-profile=%t.profdata -filename-equivalence %s -o %t.dir
 // RUN: FileCheck -check-prefixes=HTML -input-file=%t.dir/coverage/tmp/native_separators.c.html %s
 
 // TEXT-INDEX: \tmp\native_separators.c
-// HTML-INDEX: >tmp\native_separators.c</a>
+// HTML-INDEX: >native_separators.c</a>
 // HTML: <pre>\tmp\native_separators.c (Binary: native_separators.covmapping)</pre>
 
 int main() {}

test/tools/llvm-cov/showLineExecutionCounts.cpp

 // HTML-INDEX: <td class='column-entry'>Region Coverage</td>
 // HTML-INDEX: <a href='coverage{{.*}}showLineExecutionCounts.cpp.html'{{.*}}showLineExecutionCounts.cpp</a>
 // HTML-INDEX: <td class='column-entry-green'>
 // HTML-INDEX: 100.00% (1/1)
 // HTML-INDEX: <td class='column-entry-yellow'>
 // HTML-INDEX: 80.00% (16/20)
 // HTML-INDEX: <td class='column-entry-red'>
 // HTML-INDEX: 70.00% (7/10)
-// HTML-INDEX: TOTALS
+// HTML-INDEX: Totals

tools/llvm-cov/SourceCoverageViewHTML.h

Error createIndexFile(ArrayRef<StringRef> SourceFiles,
                         const coverage::CoverageMapping &Coverage) override;
 
   CoveragePrinterHTML(const CoverageViewOptions &Opts)
       : CoveragePrinter(Opts) {}
 
 private:
   void emitFileSummary(raw_ostream &OS, StringRef SF,
                        const FileCoverageSummary &FCS,
-                       bool IsTotals = false) const;
+                       const StringRef ProjectDir, bool IsTotals = false) const;
+
+  void emitProjectSummary(raw_ostream &OS, StringRef ProjectDir,
+                          const FileCoverageSummary &PCS) const;
 };
 
 /// \brief A code coverage view which supports html-based rendering.
 class SourceCoverageViewHTML : public SourceCoverageView {
   void renderViewHeader(raw_ostream &OS) override;
 
   void renderViewFooter(raw_ostream &OS) override;
 

tools/llvm-cov/SourceCoverageViewHTML.cpp

 void CoveragePrinterHTML::closeViewFile(OwnedStream OS) {
   emitEpilog(*OS.get());
 }
 
 /// Emit column labels for the table in the index.
 static void emitColumnLabelsForIndex(raw_ostream &OS) {
   SmallVector<std::string, 4> Columns;
   Columns.emplace_back(tag("td", "Filename", "column-entry-left"));
+  Columns.emplace_back(tag("td", "File Directory", "column-entry-left"));
   for (const char *Label :
        {"Function Coverage", "Line Coverage", "Region Coverage"})
     Columns.emplace_back(tag("td", Label, "column-entry"));
   OS << tag("tr", join(Columns.begin(), Columns.end(), ""));
 }
 
-/// Render a file coverage summary (\p FCS) in a table row. If \p IsTotals is
-/// false, link the summary to \p SF.
-void CoveragePrinterHTML::emitFileSummary(raw_ostream &OS, StringRef SF,
-                                          const FileCoverageSummary &FCS,
-                                          bool IsTotals) const {
-  SmallVector<std::string, 4> Columns;
+// Return the relative path from the project directory (\p ProjectDir) to the
+// file (\p Filename).
+// \code
+//   Filename: /output/dir1/dir2/dir3/test.cpp
+//   Dir: /output/dir1
+//   return string: /dir2/dir3/test.cpp
+// \endcode
+static std::string getFileDir(const StringRef Filename,
+                              const StringRef ProjectDir) {
+  assert(Filename.substr(0, ProjectDir.size()) == ProjectDir &&
+         "Filename does not start with ProjectDir.");
+  SmallString<16> FileRelativeDir(Filename);
+  sys::path::remove_filename(FileRelativeDir);
+  if (FileRelativeDir.size() > ProjectDir.size())
+    return FileRelativeDir.str().substr(ProjectDir.size());
+  return sys::path::get_separator().data();
+}
+
+// Return the common path from the list of FilePaths (\p Files).
+// \code
+//   FilePath: /output/dir1/test.cpp
+//             /output/dir1/dir2/dir3/test1.cpp
+//   return string: /output/dir1
+// \endcode
+static std::string commonPath(const std::vector<std::string> &Files) {
+  assert(!Files.empty() && "Source file vector is empty");
+  std::string CompareString = Files[0];
+  int MaxCommonPath = CompareString.size();
+  for (auto FI = ++Files.begin(), End = Files.end(); FI != End; ++FI) {
+    auto MismatchPair =
+        std::mismatch(CompareString.begin(), CompareString.end(), FI->begin());
+    if ((MismatchPair.first - CompareString.begin()) < MaxCommonPath)
+      MaxCommonPath = MismatchPair.first - CompareString.begin() - 1;
+  }
+  // If there is no common path, return an empty string.
+  if (MaxCommonPath <= 0)
+    return std::string();
+  std::string::size_type found =
+      CompareString.rfind(sys::path::get_separator().data(), MaxCommonPath);
+  return CompareString.substr(0, found);
+}
 
-  // Format a coverage triple and add the result to the list of columns.
-  auto AddCoverageTripleToColumn = [&Columns](unsigned Hit, unsigned Total,
-                                              float Pctg) {
-    std::string S;
-    {
-      raw_string_ostream RSO{S};
-      RSO << format("%*.2f", 7, Pctg) << "% (" << Hit << '/' << Total << ')';
-    }
-    const char *CellClass = "column-entry-yellow";
-    if (Pctg < 80.0)
-      CellClass = "column-entry-red";
-    else if (Hit == Total)
-      CellClass = "column-entry-green";
-    Columns.emplace_back(tag("td", tag("pre", S), CellClass));
-  };
+/// Get the HTML for a coverage triple.
+static std::string getCoverageTriple(unsigned Hit, unsigned Total, float Pctg) {
+  return tag("td", tag("pre", RSO.str()), CellClass);
+}
+
+/// Render a file coverage summary (\p FCS) in a table row. If \p IsTotals is
+/// false, link the summary to \p SF.
+void CoveragePrinterHTML::emitFileSummary(raw_ostream &OS, StringRef SF,
+                                          const FileCoverageSummary &FCS,
+                                          const StringRef ProjectDir,
+                                          bool IsTotals) const {
+  SmallVector<std::string, 5> Columns;
 
   // Simplify the display file path, and wrap it in a link if requested.
   std::string Filename;
-  SmallString<128> LinkTextStr(sys::path::relative_path(FCS.Name));
-  sys::path::remove_dots(LinkTextStr, /*remove_dot_dots=*/true);
-  sys::path::native(LinkTextStr);
-  std::string LinkText = escape(LinkTextStr, Opts);
+  std::string FileDir;
+  std::string LinkText = escape(sys::path::filename(SF), Opts);
   if (IsTotals) {
+    FileDir = std::string();
     Filename = LinkText;
   } else {
+    FileDir = getFileDir(SF, ProjectDir);
     std::string LinkTarget =
         escape(getOutputPath(SF, "html", /*InToplevel=*/false), Opts);
     Filename = a(LinkTarget, LinkText);
   }
 
   Columns.emplace_back(tag("td", tag("pre", Filename)));
-  AddCoverageTripleToColumn(FCS.FunctionCoverage.Executed,
-                            FCS.FunctionCoverage.NumFunctions,
-                            FCS.FunctionCoverage.getPercentCovered());
-  AddCoverageTripleToColumn(
+  Columns.emplace_back(tag("td", tag("pre", FileDir)));
+  Columns.emplace_back(getCoverageTriple(
+      FCS.FunctionCoverage.Executed, FCS.FunctionCoverage.NumFunctions,
+      FCS.FunctionCoverage.getPercentCovered()));
+  Columns.emplace_back(getCoverageTriple(
       FCS.LineCoverage.NumLines - FCS.LineCoverage.NotCovered,
-      FCS.LineCoverage.NumLines, FCS.LineCoverage.getPercentCovered());
-  AddCoverageTripleToColumn(
+      FCS.LineCoverage.NumLines, FCS.LineCoverage.getPercentCovered()));
+  Columns.emplace_back(getCoverageTriple(
       FCS.RegionCoverage.NumRegions - FCS.RegionCoverage.NotCovered,
-      FCS.RegionCoverage.NumRegions, FCS.RegionCoverage.getPercentCovered());
-
+      FCS.RegionCoverage.NumRegions, FCS.RegionCoverage.getPercentCovered()));
   OS << tag("tr", join(Columns.begin(), Columns.end(), ""), "light-row");
 }
 
+/// Render the project coverage summary (\p PCS) and the project directory (\p
+/// ProjectDir) above the index table.
+void CoveragePrinterHTML::emitProjectSummary(
+    raw_ostream &OS, StringRef ProjectDir,
+    const FileCoverageSummary &PCS) const {
+
+  OS << "<table border=\"0\">"
+     << "<tbody>";
+
+  // Add a coverage row to the coverage summary table.
+  auto AddCoverageSummaryRow = [&OS](StringRef CoverageTitle,
+                                     StringRef CoverageValue) {
+    OS << tag("tr", tag("td", tag("pre", CoverageTitle)) + CoverageValue.str());
+  };
+
+  AddCoverageSummaryRow("Project directory:",
+                        tag("td", tag("pre", ProjectDir)));
+  AddCoverageSummaryRow(
+      "Function coverage:",
+      getCoverageTriple(PCS.FunctionCoverage.Executed,
+                        PCS.FunctionCoverage.NumFunctions,
+                        PCS.FunctionCoverage.getPercentCovered()));
+  AddCoverageSummaryRow(
+      "Line coverage:",
+      getCoverageTriple(PCS.LineCoverage.NumLines - PCS.LineCoverage.NotCovered,
+                        PCS.LineCoverage.NumLines,
+                        PCS.LineCoverage.getPercentCovered()));
+  AddCoverageSummaryRow(
+      "Region coverage:",
+      getCoverageTriple(PCS.RegionCoverage.NumRegions -
+                            PCS.RegionCoverage.NotCovered,
+                        PCS.RegionCoverage.NumRegions,
+                        PCS.RegionCoverage.getPercentCovered()));
+
+  OS << "</tbody>"
+     << "</table>" << "<br>";
+}
+
 Error CoveragePrinterHTML::createIndexFile(
     ArrayRef<StringRef> SourceFiles,
     const coverage::CoverageMapping &Coverage) {
   // Emit the default stylesheet.
   auto CSSOrErr = createOutputStream("style", "css", /*InToplevel=*/true);
   if (Error E = CSSOrErr.takeError())
     return E;
 
Error CoveragePrinterHTML::createIndexFile(
 
   // Emit some basic information about the coverage report.
   if (Opts.hasProjectTitle())
     OSRef << tag(ProjectTitleTag, escape(Opts.ProjectTitle, Opts));
   OSRef << tag(ReportTitleTag, "Coverage Report");
   if (Opts.hasCreatedTime())
     OSRef << tag(CreatedTimeTag, escape(Opts.CreatedTimeStr, Opts));
 
-  // Emit a table containing links to reports for each file in the covmapping.
+  // Emit a table containing the project coverage summary.
   CoverageReport Report(Opts, Coverage);
-  OSRef << BeginCenteredDiv << BeginTable;
-  emitColumnLabelsForIndex(OSRef);
   FileCoverageSummary Totals("TOTALS");
   auto FileReports = Report.prepareFileReports(Totals, SourceFiles);
+  std::vector<std::string> NativeFiles;
+  for (const auto &SourceFile : SourceFiles) {
+    SmallString<256> NativeFile(SourceFile);
+    sys::path::remove_dots(NativeFile, /* remove_dot_dot */ true);
+    sys::path::native(NativeFile);
+    NativeFiles.push_back(NativeFile.c_str());
+  }
+  std::string ProjectDir = commonPath(NativeFiles);
+  emitProjectSummary(OSRef, ProjectDir, Totals);
+
+  // Emit a table containing links to reports for each file in the covmapping.
+  OSRef << BeginCenteredDiv << BeginTable;
+  emitColumnLabelsForIndex(OSRef);
   for (unsigned I = 0, E = FileReports.size(); I < E; ++I)
-    emitFileSummary(OSRef, SourceFiles[I], FileReports[I]);
-  emitFileSummary(OSRef, "Totals", Totals, /*IsTotals=*/true);
+    emitFileSummary(OSRef, NativeFiles[I], FileReports[I], ProjectDir);
+  emitFileSummary(OSRef, "Totals", Totals, ProjectDir, /*IsTotals=*/true);
   OSRef << EndTable << EndCenteredDiv
         << tag("h5", escape(Opts.getLLVMVersionString(), Opts));
   emitEpilog(OSRef);
 
   return Error::success();
 }
 
 void SourceCoverageViewHTML::renderViewHeader(raw_ostream &OS) {