feat: add Markdown block report generation for CLI

Generally intended to resemble the original reports that were removed
from DVSim as closely as possible.

Note the TODOs - currently the progress table is missing because this
information is not being computed nor captured correctly here. Also the
stage/overall totals in the result table are not correct, but this is
because the SimCfg calculations are not correct, instead of the Markdown
presentation logic being incorrect.

Signed-off-by: Alex Jones <alex.jones@lowrisc.org>

Author: AlexJones0

src/dvsim/sim/data.py

@@ -156,6 +156,18 @@ def empty(self) -> bool:
             v is None for v in self.model_dump(exclude_unset=True, exclude={"code"}).values()
         )
 
+    def flattened(self) -> dict[str, float | None]:
+        """Convert the coverage metrics to a flattened dictionary.
+
+        This dictionary will contain all the stored metrics, and a computed "total" average item.
+        """
+        average = self.average
+        items = {} if average is None else {"total": average}
+        if self.code:
+            items.update(self.code.model_dump(exclude_none=True))
+        items.update(self.model_dump(exclude={"code"}))
+        return items
+
 
 class FlowResults(BaseModel):
     """Flow results data."""

src/dvsim/sim/report.py

@@ -4,13 +4,19 @@
 
 """Generate reports."""
 
-from collections.abc import Callable
+from collections import defaultdict
+from collections.abc import Callable, Collection, Iterable
+from datetime import datetime
 from pathlib import Path
-from typing import Protocol, TypeAlias
+from typing import Any, Protocol, TypeAlias
+
+from tabulate import tabulate
 
 from dvsim.logging import log
+from dvsim.report.data import IPMeta
 from dvsim.sim.data import SimFlowResults, SimResultsSummary
 from dvsim.templates.render import render_static, render_template
+from dvsim.utils import TS_FORMAT_LONG
 
 __all__ = (
     "HtmlReportRenderer",
@@ -22,6 +28,18 @@
     "write_report",
 )
 
+
+def _plural(item: str, n: int | Collection[Any], suffix: str = "s") -> str:
+    if not isinstance(n, int):
+        n = len(n)
+    return item if n == 1 else item + suffix
+
+
+def _indent_by_levels(lines: Iterable[tuple[int, str]], indent_spaces: int = 4) -> str:
+    """Format per-line indentation of (0-indexed level, msg) log messages."""
+    return "\n".join(" " * lvl * indent_spaces + msg for lvl, msg in lines)
+
+
 # Report rendering returns mappings of relative report paths to (string) contents.
 ReportArtifacts: TypeAlias = dict[str, str]
 
@@ -131,6 +149,9 @@ class MarkdownReportRenderer:
 
     format_name = "markdown"
 
+    MAX_TESTS_PER_BUCKET = 5
+    MAX_RESEEDS_PER_BUCKETED_TEST = 2
+
     def render(self, summary: SimResultsSummary, outdir: Path | None = None) -> ReportArtifacts:
         """Render a Markdown report of the sim flow results."""
         if outdir is not None:
@@ -150,8 +171,195 @@ def render(self, summary: SimResultsSummary, outdir: Path | None = None) -> Repo
 
     def render_block(self, results: SimFlowResults) -> ReportArtifacts:
         """Render a Markdown report of the sim flow results for a given block/flow."""
-        _results = results
-        return {"report.md": "TODO: Markdown block report"}
+        # Generate block result metadata information
+        report_md = self.render_metadata(results.block, results.timestamp, results.build_seed)
+        testplan_ref = (results.testplan_ref or "").strip()
+        if len(results.stages) > 0 and testplan_ref:
+            report_md += f"\n### [Testplan]({testplan_ref})"
+        report_md += f"\n### Simulator: {results.tool.name.upper()}"
+
+        # Record a summary of the simulation results, coverage, and failure buckets, if applicable.
+        result_summary = self.render_block_results(results)
+        if result_summary:
+            report_md += "\n\n" + result_summary
+
+        return {"report.md": report_md}
+
+    def render_metadata(
+        self,
+        scope: IPMeta,
+        timestamp: datetime,
+        seed: int | None,
+        title: str = "Simulation Results",
+    ) -> str:
+        """Generate a Markdown string summary of the result metadata.
+
+        Args:
+            scope: The scope (block/top) to generate metadata from.
+            timestamp: The timestamp metadata info to include.
+            seed: The build seed, if one was used in this run.
+            title: The title to use as a suffix (to "NAME %s"). Defaults to "Simulation Results".
+
+        """
+        name = scope.variant_name(sep="/")
+        report_md = f"## {name.upper()} {title}"
+        report_md += f"\n### {timestamp.strftime(TS_FORMAT_LONG)}"
+
+        revision = (scope.revision_info or "").strip()
+        if not revision:
+            revision = f"Github Revision: [`{scope.commit_short}`]({scope.url})"
+        report_md += f"\n### {revision}"
+        report_md += f"\n### Branch: {scope.branch}"
+
+        if seed is not None:
+            report_md += f"\n### Build randomization enabled with --build-seed {seed}"
+
+        return report_md
+
+    def render_block_results(self, results: SimFlowResults) -> str:
+        """Generate a Markdown string covering the results, coverage and failure buckets."""
+        report_md = self.render_result_table(results) if results.total else "No results to display."
+
+        # TODO: need to optionally generate a progress table if `--map-full-testplan` was set.
+        # This can be passed through and set when instantiating the markdown renderer, but
+        # right now we don't record the correct information for testplan progress in the sim
+        # results, so we leave this incomplete for now.
+
+        if results.coverage:
+            coverage_table = self.render_coverage_table(results)
+            if coverage_table:
+                report_md += "\n\n" + coverage_table
+
+        if results.failed_jobs.buckets:
+            bucket_summary = self.render_bucket_summary(results)
+            if bucket_summary:
+                report_md += "\n\n" + bucket_summary
+
+        return report_md
+
+    def render_result_table(self, results: SimFlowResults) -> str:
+        """Generate a Markdown string containing a table of the testplan results."""
+        column_info = [
+            ("Stage", "center"),
+            ("Name", "center"),
+            ("Tests", "left"),
+            ("Max Job Runtime", "center"),
+            ("Simulated Time", "center"),
+            ("Passing", "center"),
+            ("Total", "center"),
+            ("Pass Rate", "center"),
+        ]
+        table = []
+        hidden_names = ("n.a.", "unmapped")
+
+        for stage_key, stage in results.stages.items():
+            # Coalesce result information to default values if necessary
+            stage_name = "" if stage_key.lower() in hidden_names else stage_key
+
+            for tp_key, tp in stage.testpoints.items():
+                tp_name = "" if tp_key.lower() in hidden_names else tp_key
+                for test_name, result in tp.tests.items():
+                    job_runtime = "" if result.max_time is None else f"{result.max_time:.3f}s"
+                    sim_time = "" if result.sim_time is None else f"{result.sim_time:.3f}us"
+                    pass_rate = "-- %" if result.total == 0 else f"{result.percent:.2f} %"
+
+                    row = [
+                        stage_name,
+                        tp_name,
+                        test_name,
+                        job_runtime,
+                        sim_time,
+                        result.passed,
+                        result.total,
+                        pass_rate,
+                    ]
+                    table.append(row)
+
+            pass_rate = "-- %" if stage.total == 0 else f"{stage.percent:.2f} %"
+            # TODO: note the calculated stage totals are currently not correct.
+            table.append(
+                [stage_name, None, "**TOTAL**", None, None, stage.passed, stage.total, pass_rate]
+            )
+
+        # TODO: note the calculated overall totals are currently not correct.
+        pass_rate = "-- %" if results.total == 0 else f"{results.percent:.2f} %"
+        table.append(
+            [None, None, "**TOTAL**", None, None, results.passed, results.total, pass_rate]
+        )
+
+        if not table:
+            return ""
+
+        return "### Test Results\n\n" + tabulate(
+            table,
+            headers=[c[0] for c in column_info],
+            tablefmt="pipe",
+            colalign=[c[1] for c in column_info],
+        )
+
+    def render_coverage_table(self, results: SimFlowResults) -> str:
+        """Generate a Markdown string containing a table of the coverage results."""
+        if results.coverage is None:
+            return ""
+
+        cov_results = {
+            k.upper().replace("_", "/"): f"{v:.2f} %"
+            for k, v in results.coverage.flattened().items()
+            if v is not None
+        }
+        if not cov_results and not results.cov_report_page:
+            return ""
+
+        report_md = "## Coverage Results"
+        if results.cov_report_page:
+            report_md += f"\n### [Coverage Dashboard]({results.cov_report_page})"
+        if cov_results:
+            colalign = ("center",) * len(cov_results)
+            report_md += "\n\n" + tabulate(
+                [cov_results], headers="keys", tablefmt="pipe", colalign=colalign
+            )
+
+        return report_md
+
+    def render_bucket_summary(self, results: SimFlowResults) -> str:
+        """Generate a Markdown string with a summary of the buckets (failures/killed)."""
+        lines = [(0, "## Failure Buckets")]
+
+        for bucket, tests in sorted(
+            results.failed_jobs.buckets.items(),
+            key=lambda kv: len(kv[1]),
+            reverse=True,
+        ):
+            lines.append((0, f"* `{bucket}` has {len(tests)} {_plural('failure', tests)}:"))
+
+            grouped_tests = defaultdict(list)
+            for job in tests:
+                grouped_tests[job.name].append(job)
+
+            displayed = list(grouped_tests.items())[: self.MAX_TESTS_PER_BUCKET]
+            for name, reseeds in displayed:
+                lines.append(
+                    (1, f"* Test {name} has {len(reseeds)} {_plural('failure', reseeds)}.")
+                )
+
+                for failure in reseeds[: self.MAX_RESEEDS_PER_BUCKETED_TEST]:
+                    lines.append((2, f"* {failure.qual_name}\\"))
+                    line_context = "Log" if failure.line is None else f"Line {failure.line}, in log"
+                    lines.append((2, f"  {line_context} {failure.log_path}"))
+                    if failure.log_context:
+                        lines.append((0, ""))
+                        lines.extend((4, line.rstrip()) for line in failure.log_context)
+                    lines.append((0, ""))
+
+                extra = len(reseeds) - self.MAX_RESEEDS_PER_BUCKETED_TEST
+                if extra > 0:
+                    lines.append((2, f"* ... and {extra} more {_plural('failure', extra)}."))
+
+            extra = len(grouped_tests) - self.MAX_TESTS_PER_BUCKET
+            if extra > 0:
+                lines.append((2, f"* ... and {extra} more {_plural('test', extra)}."))
+
+        return _indent_by_levels(lines)
 
     def render_summary(self, summary: SimResultsSummary) -> ReportArtifacts:
         """Render a Markdown report of a summary of the sim flow results (overall)."""