Skip to content

D136 — Run report rendered from the route summary alone

Context

Candidate D3 of doc 18 (milestone M20): one file a designer can read to audit a run, covering what was routed, what is open and why, which rules were read and which were not, the signal-integrity audit, the DRC comparison, the options and the seed. Its gate asks that every number in it be traceable to a JSON field. The pieces existed as separate outputs (--json, --stuck-report, warnings in the log, tracemaker drc).

Decision

  • route --report FILE writes the report: HTML, or Markdown when FILE ends in .md. tracemaker report SUMMARY.json -o FILE renders it again from a saved summary. Off by default.
  • The report is a pure function of the summary. report::render (src/report/render.cpp) reads only the JSON and does no arithmetic; every number and name it prints is a field, and the HTML marks each with its JSON pointer (data-src, a hover title and a "show the JSON field" switch). The Markdown gives pointers as footnotes, as a column of key/value tables, and as the row source of other tables. With --report and no --json, the summary is written beside the report as FILE.json.
  • --report adds sections to the summary: rules (files found, minimums, net classes with net counts, custom rules, and not_read: the project reader's, rule engine's and board reader's warnings), stuck (the stuck report of doc 17 §3 for the final result, without its advisor parts), and drc (TraceMaker's DRC of the board the router started from and of the board as written, zones refilled when the board has copper zones, counts by type, routing errors added, and the unconnected items after the route with both ends).
  • Every summary gains open, completion_pct, time_limited and run (version, board, paths, date, seed, work budget, time limit, variants, threads, and the options as given on the command line and in --config).
  • RouteResult::time_limited: set when the wall-clock limit, not the work budget, ended a search (or, in a portfolio, any variant's or the rounds'). The router never reads it. The route logs a warning and the report says the result depends on machine speed.

Alternatives

  • A report built from the router's in-memory state: faster to write, but nothing would make its numbers checkable afterwards, and the gate would rest on review alone.
  • Calling kicad-cli for the DRC comparison: it is the judge of the benchmarks, but not installed where hobbyists run the plugin, and slow. The engine's DRC gives KiCad's names and, for routing rules, KiCad's results (doc 03 §6); the report says to sign off with kicad-cli.
  • Instance matching of violations as bench/drc_judge.py does: more exact, but its normalisation is tuned to kicad-cli's text. Counts by type are stated as such.
  • PDF output: a dependency for little gain; the HTML prints.

Consequences

  • Reports for seven of the eight plane boards (bench/records/m20-run-report): no routing error added on any. The unconnected count after the refill equals the report's own DRC count on every board, two independent paths agreeing. A unit test parses the HTML and checks every value against its pointer, and that the renderer's own text carries no number.
  • The first runs showed why time_limited matters: under load, the default 120 s limit, not the work, ended runs, and results moved between runs (RoyalBlue54L-Feather 102 and 37 connections). A designer now sees it.
  • Options off: quick tier byte-identical to main (30/30).
  • Open: interf_u spends more than 20 minutes on one core after its portfolio with main's binary too (27 s in the 14 October records), so it has no report; the gate's review by someone who did not write the report; the KiCad plugin and the Python module do not pass --report yet.