bencher.scorecard.render
========================

.. py:module:: bencher.scorecard.render

.. autoapi-nested-parse::

   Render the benchmark health scorecard to a single HTML page.

   Discovers every ``*.summary.json`` under the reports directory, groups them by
   category, builds one row per benchmark and one column per (aliased) scalar
   metric, and renders a bundled Jinja template. Each cell shows a verdict-colored
   value, a Δ, and a noise sparkline; benchmarks with only image reports are listed
   as plain links so they stay reachable from this page.



Attributes
----------

.. autoapisummary::

   bencher.scorecard.render.TEMPLATE_DIR
   bencher.scorecard.render._SAFE_URL_RE
   bencher.scorecard.render._CONTROL_CHARS_RE


Functions
---------

.. autoapisummary::

   bencher.scorecard.render._sanitize_url
   bencher.scorecard.render.generate_scorecard


Module Contents
---------------

.. py:data:: TEMPLATE_DIR

.. py:data:: _SAFE_URL_RE

.. py:data:: _CONTROL_CHARS_RE

.. py:function:: _sanitize_url(url: str) -> str

   Return *url* only if it is a clean http(s) link, else an empty string.

   Chrome links may originate from CI environment variables, so treat them as
   untrusted: strip surrounding whitespace, reject any embedded control
   characters (which could smuggle a second scheme or break out of the href),
   and require an ``http(s)://`` scheme with no internal whitespace.


.. py:function:: generate_scorecard(reports_dir: pathlib.Path | str, config: bencher.scorecard.config.ScorecardConfig | None = None, *, chrome: bencher.scorecard.config.Chrome | None = None, output_name: str = 'index.html') -> pathlib.Path

   Render the scorecard for all summaries under *reports_dir*.

   :param reports_dir: Directory containing ``<layout.root>/<tag>/*.summary.json``.
   :param config: Project specifics (registry, aliases, layout, ...). Defaults to a
                  zero-config :class:`ScorecardConfig` (auto-named benchmarks).
   :param chrome: Optional page header / CI nav content.
   :param output_name: File written under *reports_dir* (the scorecard is usually
                       published as ``index.html`` so it is the landing page).

   :returns: The path to the written HTML file.