Skip to content

fix(cli): report rendering defects, overview column spec, native sort buttons - #1841

Merged
dekobon merged 8 commits into
mainfrom
fix/report-rendering
Nov 7, 2026
Merged

dekobon merged 8 commits into
mainfrom
fix/report-rendering

Conversation

@dekobon

@dekobon dekobon commented Nov 7, 2026

Copy link
Copy Markdown
Owner

Closes #1840.

What this does

Fixes the defects found reviewing the published bca report output, then lands two structural follow-ups from that review. Eight commits, each self-contained and green under make pre-commit; read them in order.

Commit Change
9170f8cb GFM table cells escape < & * _ ~ [ ]as well as\ |— a path likea.pyno longer becomes an element,init.pyno longer renders bold. Shared by the report,check --summary-fileandexemptions`.
a991057e HTML: numeric headers right-aligned like their cells; blank cells sort last in both directions (the comparator is now a total preorder); keyboard sorting. Adds the Node DOM-stub harness that executes INLINE_JS.
a12aa933 CI installs Node before every job running the CLI crate's tests, since the harness test fails (not skips) under CI without Node ≥ 22.7.
56499a23 Shared Markdown notes render backticks as <code> in HTML via one note_html policy; VCS wire keys spelled as code spans.
01b499bc Heat bands graded against every ranked file, not the rendered top-N (--top 1 painted the riskiest file green); Hotspot formatted with thousands separators; the pointer names `bca vcs --format csv
1e844868 Legends define the overview columns (Avg MI is the unclamped SLOC-weighted average and can be negative — correctly); Exits/Methods/WMC/NPA/NPM say subtree sum; Comments says trailing comments count; the CC note is ;-joined (MD075). A test pins that no legend definition carries markup the two renderers read apart.
66e4f92b Refactor: the Per-language overview on one OverviewColumn spec (markdown_report/overview.rs); deletes the string-keyed write_table/write_table_classed/header_tooltip path. Byte-identical — no snapshot moves — pinned by hand-written column/tooltip tests and a full-LANG display-name escaping sweep.
19e5b3e6 Feature: WAI-ARIA APG sortable headers — the label is a native <button> (Enter/Space, no tabindex/key handling), aria-sort on the th, arrow in an aria-hidden span, doc link a ? with a title (not an aria-label, which would join the column's accessible name), button carries the cell padding, scope="col", sort hint on the standalone VCS page too.

Review trail

Each stage went through independent review (astra-review at each checkpoint; a six-agent pass — review, code-review max, performance, architecture, under-reviewed areas, astra — on the fix series; a four-agent code-review max --fix pass on the two follow-ups). Every finding is either applied in the commit it belongs to or recorded as a follow-up on #1840. Perturbation sweeps verified each new test fails on the defect it claims to catch (recording the heat-band count after truncation; binding the sort listener on the th; dropping type="button"; removing an overview column; blanking a tooltip; a script that re-sorts every table).

Not in this PR

Checklist

  • make pre-commit passes on every commit (BCA_GATE: pass)
  • .bca-baseline.toml refreshed in the commits that moved a metric
  • CHANGELOG [Unreleased] entries (### Fixed, ### Changed); no public library API change
  • Book (commands/report.md, commands/vcs.md) updated to match the rendered output

`escape_gfm_cell` escaped only `\`, `|` and newlines, so a path's
other metacharacters reached the rendered table as markup: an
`a<img src=x onerror=…>.py` became an element under a non-sanitising
GFM renderer, `a&amp;b.py` displayed as `a&b.py`, and `__init__.py`
rendered as bold `init.py`. The helper is the one GFM escaper for the
report, `check`'s `--summary-file` digest and `exemptions`, so every
table shares the widened set: `< & ` * _ ~ [ ]` each take a
backslash, which GFM renders as the literal character. The buffer is
pre-sized by the escape count, since `_` is in most identifiers and
the plain `s.len()` guess reallocated on most cells.

The two existing tests that spelled a symbol with `_` now expect the
escaped form; a new unit test and a report-level test pin the
rendered output for each metacharacter.
Three defects in the inline CSS/JS every report page carries. Every
`th` was `text-align:left` while `td.numeric` was right-aligned, so a
numeric column's header sat flush-left over its numbers; numeric
headers now take the same alignment, keyed on the `data-numeric`
attribute the sorter already emits. The sort comparator mapped an
empty cell to +Infinity, which placed it last ascending but first
descending (and any other non-numeric text fell through to a
comparator that returned 0 against every number — not a total
preorder); a blank now parses to NaN and sorts last in both
directions. And sorting was click-only on a non-focusable `th`:
headers now carry `tabindex="0"`, sort on Enter / Space, show a
focus ring, and both handlers ignore an event whose target is the
header's documentation link, so Enter on the link (and the `click` a
browser synthesizes to activate it) navigates instead of sorting. The
sort decorates each row's key once rather than parsing per
comparison.

The script is tested by executing it: `tests/fixtures/
sort_script_harness.mjs` runs `INLINE_JS` under Node against a DOM
stub whose collections carry the browser's method surface (`NodeList`
has `forEach`, `HTMLCollection` neither), with a pre-ranked header and
a child link, and the Rust test asserts the orders and event outcomes.
It needs Node >= 22.7 (the `make plugin-test` floor), skips with a
note locally and fails under `CI`. The book's claim that blanks sort
"as positive infinity" is corrected and the on-page hint names the
keyboard path.
The inline-sort-script test fails under `CI` when Node >= 22.7 is
absent rather than skipping, since under nextest a skipped test's
stderr is never shown and a skip would read as a pass. `test` ran
nextest before its `setup-node` step, and the `coverage` and the two
`(cli)` `feature-matrix` legs had none, so each would have passed or
failed on whatever Node the runner image happened to ship. Node is
now provisioned ahead of the test run in all three jobs.
…kticks

Notes written once as Markdown prose and emitted by both renderers
reached the HTML page HTML-escaped but otherwise verbatim, so the
advisory provenance read "sourced from the `bca.toml` `[thresholds]`
table" with literal backticks. `note_html` escapes, then turns each
paired backtick span into `<code>`; an odd count leaves the note
untouched. It is the one policy for every crate-authored note and
legend definition — the provenance line, `MI_NOTE`, the actionable and
fully-suppressed captions, the VCS shallow-clone note and every legend
`<dd>` — so a backtick added to a tooltip tomorrow renders the same
way.

The Markdown legend writer now emits definitions as-is rather than
through the table-cell escaper, which the widened escape set would
have turned `commits_recent` into `commits\_recent`; the VCS wire keys
are spelled as code spans instead, so both renderers show them
literally.
@dekobon dekobon added bug Something isn't working cli bca CLI surface output Report / serialization output surface ux User-experience finding (2.0 UX audit) labels Nov 7, 2026
@codecov

codecov Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.58308% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.39%. Comparing base (aba21b1) to head (b85a3cb).
⚠️ Report is 8 commits behind head on main.

Files with missing lines Patch % Lines
big-code-analysis-cli/src/html_report.rs 95.11% 6 Missing and 5 partials ⚠️
big-code-analysis-cli/src/markdown_report.rs 97.35% 2 Missing and 2 partials ⚠️
big-code-analysis-cli/src/vcs_report.rs 99.18% 0 Missing and 1 partial ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #1841      +/-   ##
==========================================
- Coverage   98.40%   98.39%   -0.01%     
==========================================
  Files         396      397       +1     
  Lines      120869   121287     +418     
  Branches   120434   120852     +418     
==========================================
+ Hits       118937   119342     +405     
- Misses       1217     1223       +6     
- Partials      715      722       +7     
Flag Coverage Δ
python 100.00% <ø> (ø)
rust 98.39% <97.58%> (-0.01%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
big-code-analysis-cli/src/check_format.rs 96.17% <100.00%> (+0.09%) ⬆️
big-code-analysis-cli/src/html_report/sections.rs 98.92% <100.00%> (-0.03%) ⬇️
big-code-analysis-cli/src/html_report/styling.rs 100.00% <100.00%> (ø)
...-code-analysis-cli/src/markdown_report/advisory.rs 100.00% <ø> (ø)
...g-code-analysis-cli/src/markdown_report/hotspot.rs 97.80% <100.00%> (+0.01%) ⬆️
...-code-analysis-cli/src/markdown_report/overview.rs 100.00% <100.00%> (ø)
...-code-analysis-cli/src/markdown_report/sections.rs 100.00% <100.00%> (ø)
big-code-analysis-cli/src/vcs_command.rs 93.75% <100.00%> (+0.16%) ⬆️
big-code-analysis-cli/src/vcs_report.rs 99.25% <99.18%> (+0.08%) ⬆️
big-code-analysis-cli/src/markdown_report.rs 98.99% <97.35%> (-0.13%) ⬇️
... and 1 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Three defects in the `--vcs` section. The HTML severity-heat band
graded each row by its rank among the rows rendered, so a `--top 50`
table painted the repository's 41st–50th riskiest files green and
`--top 1` painted its single riskiest file green; `Report` now
carries the pre-truncation population (`ranked_total`, never
serialized) and `rank()` records it before `rank_by_risk` cuts. The
`Hotspot` column rendered `748436.0` beside thousands-separated
siblings for a score that is always an integer product; it goes
through the shared count formatter. And the Markdown pointer under the
table told a `bca report --vcs` reader to re-run with `--format csv`,
which `report` rejects; it names `bca vcs --format csv|json` (no
Hotspot column) and `bca metrics --vcs`.

Each is pinned: an end-to-end `--top 1` test on a three-file
repository for both `vcs --format html` and `report --vcs` (recording
the count after truncation fails it), a unit test over the population,
the rich fixture's score raised to prove the separator, and a test
that parses every command the pointer names through the real clap
definition and shows `report --format csv` is rejected.
The Per-language overview's `Avg MI` is the SLOC-weighted *unclamped*
Visual Studio value (#725), so it reads negative for an unmaintainable
codebase — correctly — while the Markdown legend had no entry for it
and its per-file `MI` entry said "clamped to 0–100" three tables
above. Both legends now define `Files`, `Functions`, `Avg MI`, `Avg
CC` and `Avg Cognitive` from one `OVERVIEW_LEGEND` list (which also
feeds the HTML tooltips, retiring the separate `AST_OVERVIEW_TOOLTIPS`
copy); `MI` points at the unclamped average; and `Avg CC` names its
population, since the CC note's `Average CC` covers a different set
(CC above 0, by default not suppressed, before the top-N cut).

Several legend entries described a different quantity from the one
the column shows: `Exits`, `Methods`, `WMC`, `NPA` and `NPM` said
"out of the function" / "declared on the class" while the columns are
subtree sums (`nexits_sum`, `nom.total`, … — the deliberate #709
accessor split), and `Comments` said "lines that are entirely
comment" while `cloc()` counts trailing comments too.

The CC note's fields are joined by `;` rather than `|`: directly
under a table the `|`-joined line is an orphaned table row to rumdl
0.2.2 (MD075, four hits on the published report).

A new test walks every legend entry both reports can render and
asserts no definition carries a character Markdown and HTML would
read apart outside a code span, which is what lets the Markdown
legend emit them unescaped.
The Per-language overview was the one spec-less table in the two
renderers: its header and alignment lists were written twice,
byte-identical, in `markdown_report.rs` and `html_report/sections.rs`,
and its tooltips lived in a third place (`hotspot::OVERVIEW_LEGEND`),
joined to the headers by string lookup through `styling::
header_tooltip` and the HTML `write_table` / `write_table_classed`
pair that existed only to serve that path. A new overview column with
no legend entry was caught by nothing automatic.

`markdown_report/overview.rs` now holds the seven columns as
`OVERVIEW_SPECS` — header, alignment, cell projector and tooltip, the
shape `hotspot::SPECS` and `vcs_report::VCS_SPECS` already have — with
`LangOverview` carrying the per-language aggregates the two folds
compute (moved verbatim from `markdown_report.rs`) and the five
overview tooltip consts moved out of `hotspot.rs`. Both renderers
build the row from `LangOverview::cells()`; the HTML side goes through
`write_table_with_tooltips` like every other table, and the three
deleted helpers take their string-keyed lookup with them.
`Cell::Text` carries the `Language` display name (a `Path` in all but
name; `Name` would add a code span), and `Cell::into_text` replaces
the or-pattern two consumers had each spelled out.

Output is byte-identical: no snapshot moves. The Markdown overview's
`Language` cell is now GFM-escaped where before it was written raw,
and a test sweeping every `LANG` display name pins that none needs
it, so a future name that does changes that test rather than a
snapshot. Two further tests pin the seven headers, the alignment row,
both fixture data rows and the five tooltips by hand against each
renderer's output — independently of the spec, since a test that
derives its expectations from `OVERVIEW_SPECS` drops an assertion
along with whatever was removed — and read a header's label as its
first text run, so a control wrapping it does not move them.
The previous sortable header was a `<th tabindex="0">` with a `keydown`
handler: reachable from the keyboard, but announced as a plain column
header with no cue that Enter sorts, and with the label doubling as
the documentation link, so clicking the text navigated while clicking
the padding sorted — the ambiguity two `e.target` guards papered over.

Each header is now the WAI-ARIA APG sortable-column shape. The label
is a `<button type="button" class="sort">`, natively focusable and
activated by Enter / Space, so the script binds `click` on the button
alone and carries no key handling or target guards; `aria-sort` and
`title` stay on the `<th>`, where ARIA defines them, with the `title`
repeated on the button since a focused element's description comes
from itself, not an ancestor; the sort arrow is an empty `aria-hidden`
span inside the button that the CSS fills from the parent's
`aria-sort`, so it never joins the button's accessible name; and the
documentation link is a small `?` after the label. That link carries a
`title`, not an `aria-label`: a column header's name is computed from
its content, descending into the link, so a label there would be read
with the column name on every cell a screen reader crosses. The button
carries the cell's padding, so the whole header area still sorts, the
target stays above WCAG's 24-pixel minimum, and the old header hover
tint moves onto it. Every `<th>` carries `scope="col"`. The "click a
column header's label" hint is shared with the standalone `bca vcs
--format html` page, whose headers sort the same way and which had no
hint; there it sits under the provenance summary and only when a table
follows.

The DOM-stub harness builds headers as the page renders them, with a
second table, and the test asserts the button carries the one listener
and the header none, that a click on the icon reaches the button, that
a click targeting the documentation link or the cell itself does not
sort, and that sorting one table leaves the other as rendered — a
baseline read before the script runs at all, so a script that sorted
at load time would fail it too. A header-shape test walks every `<th>`
on the AST page, the standalone change-history page with and without
its Hotspot column, and the embedded section, asserting the shape
positively: button first, icon span closing it, at most one trailing
link. Tests that selected a header by `>Label</th>` read it through
one `header_cells` extractor keyed on the button's label, so the
attribute order, icon and glyph around it are not what they pin.
@dekobon
dekobon force-pushed the fix/report-rendering branch from 19e5b3e to b85a3cb Compare November 7, 2026 20:37
@dekobon
dekobon merged commit b85a3cb into main Nov 7, 2026
58 checks passed
@dekobon
dekobon deleted the fix/report-rendering branch November 7, 2026 20:47

This branch was previously deployed

1 inactive deployment
github-pages — b85a3cb5 Deployed Nov 7, 2026 by dekobon via deploy to GitHub Pages #1001
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working cli bca CLI surface output Report / serialization output surface ux User-experience finding (2.0 UX audit)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bca report: header alignment, escaping, heat-band and legend defects in the published reports

1 participant