# Copyright (c) 2026. Jose Manuel Requena Plens """Turning the artefact into the Markdown the report is. The Markdown is a pure function of ``docs/conformance.json``: this module computes nothing and runs no check, it formats what the artefact already decided. That is what lets ``docs/CONFORMANCE.md`` keep a byte gate while the values behind it are compared within a tolerance - the bytes are derived from bytes that are themselves committed, so two runs on different hardware render the same file even when the underlying computation wobbles in its last digit. It is also what makes the report testable on a three-check fixture instead of only end to end on 552, and what stops the Markdown mirror and the site page from ever disagreeing: both read one document. The reader gets the headline count, the filters and weightings showcase, then one collapsible section per domain in registration order. Only the committed file also gets :data:`_DOC_HEADER`, the do-not-edit banner, so the pull-request comment stays header-free. The collapsing rule is the point of the layout: a section stays shut while every one of its rows passes and springs open the moment one fails, so a long green report reads as a single line and a regression is the only thing open on the page. The escaping in :func:`_cell` exists for the same reason - an unescaped ``|`` in a quantity written the way acousticians write it silently drops the evidence columns off the right of the row. """ from __future__ import annotations import argparse import re import sys from typing import TYPE_CHECKING, Any from . import marks from .artifact import ARTIFACT_PATH, load, write from .metrics import utilisation from .registry import ( _ROOT, Kind, ToleranceMode, Verdict, _fmt, _headroom, _snap, deviation_places, ) if TYPE_CHECKING: from collections.abc import Mapping, Sequence __all__ = ["_snap"] #: The four verdicts as the tables print them. A tick and a cross can only say #: two things, so "by design" and "not applicable" had nowhere to go and were #: carried in a display string instead; a word says all four, survives a #: plain-text diff and needs no colour to be read. _VERDICT_TEXT = { str(Verdict.PASS): "Pass", str(Verdict.FAIL): "**Fail**", str(Verdict.BY_DESIGN): "By design", str(Verdict.NOT_APPLICABLE): "n/a", } #: The ref every image in the committed report is pinned to. ``main``, because #: this file lives on ``main`` and is read there, on github.com and through #: raw: a reader browsing it has no commit in hand, and there is no commit to #: pin to at the moment the file is written, since the file is generated #: before it is committed. #: #: Two consequences to know about. A badge added on a branch 404s in this file #: until the branch lands; that is the same trade the README's figures already #: make, and the ``alt`` is the verdict, so a 404 degrades to the word. And #: nothing pinned this way may be a picture of a *number*, because a number on #: ``main`` is not the number in a branch's copy of this file - which is why #: the summary banner is not embedded here (see :func:`render_markdown`) while #: the four verdict marks, whose geometry never changes, are. _REF = "main" def _status(verdict: str) -> str: """One verdict as the table prints it: the mark, then the word. Both, and not either. The word is what survives a plain-text diff, a `raw` view and an image that never arrives; the mark is what tells a failing row from a passing one before anything is read. The image is reference-style, so the 117-character URL is written once for the whole document instead of once per row. The two land on separate lines, not side by side, and that was measured rather than intended: under GitHub's own table stylesheet the Status column settles at about 53.5 px of content box while a 16 px mark plus the word needs about 54, so almost every cell wraps the word under the mark: 566 of 566 at a 1012 px viewport in one harness and 563 in another. The exact count moves with the width the harness gives the container, so it is the wrapping and not the tally that is the finding. A non-breaking space between them changes nothing, because GitHub caps the table at the content width and the column has no room to grow into. It costs no height - the rows are already two lines tall from the Quantity column - so the stack is left alone and described here instead of being fought. """ word = _VERDICT_TEXT.get(verdict, verdict) if verdict not in marks.MARK_OF: return word return f"{marks.mark_reference(verdict)} {word}" def _marked(document: Mapping[str, Any]) -> list[str]: """The verdicts this report actually prints a mark for, in legend order. Read off the document rather than listed, so the legend explains the marks on the page and no others: a legend entry for a silhouette that appears nowhere is a promise the report does not keep, and the day a check fails the legend gains its red hexagon without anyone editing it. """ used = {check["verdict"] for check in document["checks"]} used |= {row["verdict"] for row in _panel(document, "filter-class")["rows"]} return [mark.verdict for mark in marks.MARKS if mark.verdict in used] def _used(check: Mapping[str, Any]) -> str: """How much of its published limit a check's deviation consumes. Blank where the question has no answer, which is a check that declares no tolerance or a mask bounded on one side only. """ fraction = utilisation(check) return "-" if fraction is None else f"{fraction * 100:.0f} %" def _cell(text: object) -> str: """Escape a value so it survives as a single Markdown table cell. An unescaped ``|`` reads as a column separator, so a quantity written the way acousticians write it -- ``max |diff|``, ``20 lg(|k|/k0)`` -- silently splits its row into more cells than the header has. Markdown renderers then drop the surplus from the right, which in this table means losing the computed value, the deviation and the pass mark: the row still renders, so nothing looks broken while the evidence is gone. Idempotent, so a value that already escapes its own bars is left alone. """ return re.sub(r"(? list[str]: """The domain titles, in registration order.""" source = load() if document is None else document return [domain["title"] for domain in source["domains"]] def _filter_verdict(row: Mapping[str, Any]) -> str: """The class verdict of one showcase row, as the table prints it. Marked like a conformance row, and this is the only table where a mark other than the pass disc appears today: three of the five architectures are excluded from the class mask on purpose, and a blue bar says "out of scope" where a red cross would say "wrong". """ if row["verdict"] == str(Verdict.BY_DESIGN): text = f"By design ({row['reason']})" elif "class" not in row: text = "not compliant" elif row["class"] == 1: text = "Class 1 (default)" if row["architecture"] == "butter" else "Class 1" else: text = f"Class {row['class']}" if row["verdict"] not in marks.MARK_OF: return text return f"{marks.mark_reference(row['verdict'])} {text}" def _panel(document: Mapping[str, Any], panel_id: str) -> Mapping[str, Any]: """One showcase panel by id.""" panels: list[Mapping[str, Any]] = list(document["panels"]) for panel in panels: if panel["id"] == panel_id: return panel msg = f"the artefact carries no {panel_id!r} panel." raise KeyError(msg) def _numerical_validation_section( document: Mapping[str, Any], *, filters_ok: bool ) -> str: # Collapsed like the per-domain groups so the report stays compact by # default; it springs open whenever the filters/weightings domain has a # failing row, exactly like those groups do. opened = "" if filters_ok else " open" lines: list[str] = [] lines.append(f"") lines.append( "Numerical validation - filters & " "weightings: class showcase (IEC 61260-1 · IEC 61672-1 · " "ISO 7196)" ) lines.append("") lines.append( "**IEC 61260-1:2014 class per filter architecture** (order 6, " "one-third-octave, 100 Hz-10 kHz, fs = 48 kHz). For each architecture " "the table shows, at its *binding* band, the measured relative " "attenuation and the class-1 limit it must clear, so the number and " "the range it must sit in are both visible. A positive margin means " "the acceptance limits are met with that much room." ) lines.append("") lines.append( "| Architecture | Class verdict | Binding band | Measured rel. atten. " "| Class-1 limit | Margin cl.1 | Margin cl.2 |" ) lines.append("|:---|:---:|:---:|:---:|:---:|:---:|:---:|") for row in _panel(document, "filter-class")["rows"]: bind = row["binding"] comparator = "≤" if bind["side"] == "ceil" else "≥" lines.append( f"| {row['architecture']} | {_filter_verdict(row)} " f"| {bind['frequency_hz']:.0f} Hz " f"| {bind['measured']:+.2f} dB | {comparator} {bind['limit']:+.2f} dB " f"| {row['margin_class1']:+.3f} dB | {row['margin_class2']:+.3f} dB |" ) lines.append("") lines.append( "Only **Butterworth** (the library default) and **Chebyshev-II** are " "class-compliant architectures. Chebyshev-I and elliptic trade the " "mask for passband ripple, and Bessel for a maximally-flat group delay " "(soft rolloff); they cannot satisfy the IEC 61260-1 Class 1/2 " "attenuation mask by construction, so they are labelled *By design* - " "this is expected, not a failure or regression." ) lines.append("") lines.append( "**Frequency-weighting conformance** (A/C: IEC 61672-1 Table 3; " "G: ISO 7196 A.3). The *max deviation from nominal* is informational " "(it falls at a frequency extreme where the tolerance is widest and " "asymmetric); compliance is judged at the *binding* frequency - the " "one with the least headroom - where the deviation, the applicable " "tolerance band and the headroom are shown together." ) lines.append("") lines.append( "| Curve | fs | Max dev. from nominal (info) | Binding freq " "| Deviation there | Tolerance band | Headroom |" ) lines.append("|:---|:---:|:---:|:---:|:---:|:---:|:---:|") for row in _panel(document, "weighting-deviation")["rows"]: worst, bind = row["worst"], row["binding"] band = f"[{bind['lower']:+.2f}, {bind['upper']:+.2f}] dB" lines.append( f"| {row['curve']} | {row['fs_hz'] // 1000} kHz " f"| {worst['deviation']:+.3f} dB @ {worst['frequency_hz']:.0f} Hz " f"| {bind['frequency_hz']:.0f} Hz | {bind['deviation']:+.3f} dB | {band} " f"| {row['headroom']:+.3f} dB |" ) lines.append("") lines.append("") return "\n".join(lines) #: How many rows the "closest to their limit" table prints. Ten, the same as #: the site page, because the two are the same answer to the same question and #: a reader comparing them should not have to work out which was truncated. _CLOSEST_ROWS = 10 def _closest_section(document: Mapping[str, Any]) -> str: """The checks with the least room left, ranked. The single most informative thing the artefact holds, and until now the one thing the published report did not print: the ``Used`` column already gives it per row, but spread over 566 rows inside 59 collapsed sections nobody can see which rows are near their limit. The pull-request comment has ranked them since it was written and the site page ranks ten of them; this makes the three surfaces answer the question the same way. A high figure is not a failure - it is the room the check passes with - so the caption says so, in the same words the site uses. """ ranked = sorted( ( check for check in document["checks"] if utilisation(check) is not None # nothing to be a fraction of ), key=lambda check: utilisation(check) or 0.0, reverse=True, ) if not ranked: return "" lines = [ f"**The {_CLOSEST_ROWS} checks closest to their published limit**", "", "The fraction of its published tolerance each check consumes. " "A high figure is not a failure: it is the room the check passes " "with, and it never decides the verdict, which is settled at full " "precision before any rounding. These are the rows a change is most " "likely to push over.", "", "| Standard | Quantity | Computed | Δ | Used |", "|:---|:---|:---|:---|:---:|", ] lines += [ f"| {_cell(check['reference']['cite'])} | {_cell(check['quantity'])} " f"| {_cell(computed_text(check))} | {_cell(deviation_text(check))} " f"| {_used(check)} |" for check in ranked[:_CLOSEST_ROWS] ] return "\n".join(lines) def _verdict_legend(verdicts: Sequence[str]) -> str: """The marks on this page, each beside the word it stands for. A legend of pictures alone would only be a second puzzle, so every entry pairs the mark with the word the Status column prints next to it, and the sentence says the part a picture cannot: that the silhouette carries the meaning as much as the colour does, which is what keeps the four apart in greyscale and for a reader who cannot separate the hues. """ entries = " · ".join( f"{marks.mark_reference(verdict)} {marks.MARK_OF[verdict].alt}" for verdict in verdicts ) return ( f"Verdict marks. {entries}. Every mark travels with the " "verdict in words and never replaces it, so the verdict survives an " "image that never arrives; the silhouettes differ as much as the " "colours do, so a reader who cannot separate the hues can still tell " "them apart." ) def expected_text(check: Mapping[str, Any]) -> str: """The Expected column of one row. A check that gave its normative side a label prints the label: the label is there precisely because the value alone does not say what the standard requires ("class 1", "m >= 0.5 (C.4.2 pass criterion)"). Everything else prints the value and the limit it is judged against, which is the pairing the whole report exists to show. """ side, tolerance = check["expected"], check.get("tolerance") if "label" in side: return str(side["label"]) unit = check.get("unit", "") value = _fmt(side["value"], unit, check["precision"]) if tolerance is None or "value" not in tolerance: return value if tolerance["mode"] == str(ToleranceMode.RELATIVE): return f"{value} (+/-{tolerance['value'] * 100:g}%)" return f"{value} (+/-{_fmt(tolerance['value'], unit, check['precision'])})" def computed_text(check: Mapping[str, Any]) -> str: """The Computed column of one row.""" side = check["computed"] if "label" in side: return str(side["label"]) return _fmt(side["value"], check.get("unit", ""), check["precision"]) def deviation_text(check: Mapping[str, Any]) -> str: """The delta column of one row. Four shapes, one per kind, plus the compatibility path: a check that declares no tolerance was built before the builders existed and its delta survives only as the string it was formatted as, so that string is printed rather than a number reconstructed from it. """ deviation, unit = check["deviation"], check.get("unit", "") if "tolerance" not in check: return str(deviation["label"]) kind, value = check["kind"], deviation.get("value") if kind in (str(Kind.RECORD), str(Kind.COUNT)): return "exact" if not value else f"{int(value)} differ" if kind == str(Kind.MASK): binding = check.get("binding", {}) headroom = _headroom(value, binding.get("lower"), binding.get("upper")) return f"headroom {_fmt(headroom, unit, deviation_places(check['precision']))}" return _fmt(value, unit, deviation_places(check["precision"])) def render_markdown(document: Mapping[str, Any] | None = None) -> tuple[str, int, int]: """Render the full conformance report from the artefact. :param document: The artefact; read from :data:`~conformance.artifact. ARTIFACT_PATH` when omitted. :return: The Markdown, the passing count and the total. """ source = load() if document is None else document counts = source["counts"] passed, total = counts["passing"], counts["checks"] filters_ok = all( domain["passing"] == domain["checks"] for domain in source["domains"] if domain["title"] == "Filters & weightings" ) failing = total - passed out: list[str] = [] out.append("## Numerical conformance report") out.append("") # No summary banner here, and this is the one place in the project that # goes without one. This file is regenerated from the tree it sits in and # gated byte for byte, so it claims to be *this* tree's report; the banner # can only be cited at a fixed ref (see _REF), and a picture of main's # count sitting above a sentence carrying the branch's count is a document # arguing with itself. Any pull request that adds or removes a check would # show it. The pull-request comment still leads with the banner, pinned to # the head commit, where the picture and the sentence come from one tree; # here the sentence carries every number the picture would, and two class # claims no bar can state. summary = ( f"**{passed}/{total} conformance checks pass** across " f"{counts['domains']} domains and {counts['standards']} standards" ) if filters_ok: summary += " - filters class 1 - weightings within IEC 61672-1 class 1" out.append(f"{summary}." if not failing else f"{summary} - **{failing} failing**.") out.append("") out.append( "Δ is the difference between the computed value and " "the one the standard publishes. Used is how much of that " "clause's published tolerance the difference consumes: 100 % means it " "sits exactly on the limit, 5 % means it uses a twentieth of the " "allowance, and a dash means the clause states no two-sided tolerance " "for the quantity, so there is no budget to spend. It is reported and " "never used to decide a verdict, which is settled at full precision " "before any rounding." ) out.append("") out.append( "Each row pins a standard clause to its expected normative value " "and the value the library computes. Every section below is " "collapsible and stays collapsed while all of its rows pass; a " "section with any failing row opens automatically." ) out.append("") marked = _marked(source) out.append(_verdict_legend(marked)) out.append("") closest = _closest_section(source) if closest: out.append(closest) out.append("") out.append(_numerical_validation_section(document=source, filters_ok=filters_ok)) out.append("") by_domain: dict[str, list[Mapping[str, Any]]] = {} for check in source["checks"]: by_domain.setdefault(check["domain"], []).append(check) for domain in source["domains"]: rows = by_domain.get(domain["id"], []) passed_d, total_d = domain["passing"], domain["checks"] pct = 100.0 * passed_d / total_d if total_d else 100.0 failing_d = total_d - passed_d # Each domain is a collapsible group labelled with its compliance # percentage (100 % = every row passes). Groups with any failing row are # opened by default so regressions stay visible. opened = " open" if passed_d != total_d else "" domain_html = domain["title"].replace("&", "&") out.append(f"") tail = f" - {failing_d} failing" if failing_d else "" out.append( f"{domain_html}: {pct:.0f}% " f"({passed_d}/{total_d}){tail}" ) out.append("") out.append( "| Standard | Quantity | Expected (norm) | Computed | Δ | Used | " "Status |" ) out.append("|:---|:---|:---|:---|:---|:---:|:---:|") out.extend( f"| {_cell(check['reference']['cite'])} | {_cell(check['quantity'])} " f"| {_cell(expected_text(check))} | {_cell(computed_text(check))} " f"| {_cell(deviation_text(check))} | {_used(check)} " f"| {_status(check['verdict'])} |" for check in rows ) out.append("") out.append("") out.append("") # One definition per mark, at the foot of the document. A link reference # resolves document-wide in CommonMark, which is what lets a row spend 16 # characters on its mark instead of the 117 an inline URL costs. out.extend(marks.mark_definitions(marked, _REF)) out.append("") return "\n".join(out), passed, total # Header prepended to the committed docs/CONFORMANCE.md (via `--file-header`, # used by `make conformance`). Emitted only for the committed file, not for the # CI PR-comment body, so the PR comment stays header-free. _DOC_HEADER = """ > **Auto-generated conformance report - do not hand-edit.** Produced by > `make conformance` from the library's own computations checked against the > referenced standards, and rendered from > [`docs/conformance.json`](https://github.com/jmrplens/phonometry/blob/main/docs/conformance.json), > which carries the same rows as data. CI regenerates it on every pull request > and fails if it is out of date, so edit the checks in > `scripts/conformance/domains/`, not this file. Each row pins a standard and clause to its expected normative value and > the value the library computes. Full standards list and methodology: > [Theory](https://github.com/jmrplens/phonometry/blob/main/docs/reference/theory/index.md) - > [Why phonometry](https://github.com/jmrplens/phonometry/blob/main/docs/start/why-phonometry.md). """ def main(argv: list[str] | None = None) -> int: """Run every check, refresh the artefact, and print the report. Two steps, in this order and never the other: the checks produce ``docs/conformance.json``, and the Markdown is rendered from whatever is on disk afterwards. When the fresh run agrees with the committed artefact within tolerance the file is left untouched, so the Markdown printed here is a function of committed bytes and a byte diff of it means something. """ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser.add_argument( "--file-header", action="store_true", help="prepend the do-not-edit banner (for the committed docs/ copy)", ) parser.add_argument( "--no-artifact", action="store_true", help="render from the committed artefact without running the checks", ) args = parser.parse_args(argv) document = load() if args.no_artifact else write()[0] markdown, passed, total = render_markdown(document) output = _DOC_HEADER + markdown if args.file_header else markdown print(output) print( f"\n[conformance] {passed}/{total} checks passed, artefact at " f"{ARTIFACT_PATH.relative_to(_ROOT)}", file=sys.stderr, ) return 0 if passed == total else 1 if __name__ == "__main__": raise SystemExit(main())