You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
(a) The Markdown legend is emitted at heading level 3 — write_legend(&mut out, 3, …) (big-code-analysis-cli/src/markdown_report.rs:636) — so ### Legend nests under the last language's ## section, though it defines columns for every language.
(b) The HTML legend is a <details> collapsed by default at the page bottom (big-code-analysis-cli/src/html_report.rs:878), while the stated rationale for adding it was that tooltips are "hover-only and invisible to print, mobile, and screen readers" (html_report.rs:855-857). A collapsed <details> is equally invisible in print.
(c) The global header's PLOC: / Comments: / Comment ratio: labels are defined nowhere: legend_entries() (markdown_report/hotspot.rs:529-536) covers only hotspot columns, and PLOC has no HTML tooltip either.
Why it's a UX problem
(a) misleads outline-based navigation and TOCs; (b) defeats the legend's own stated purpose for the print case; (c) leaves the very first numbers a reader sees unexplained.
Proposed 2.0 design
Emit the legend at ## so it gets its own TOC entry; render <details open> or add print CSS that forces it open; add header-stat entries to the legend, or rename the labels to self-explanatory words (Code lines (PLOC)).
Breaking
Minor structure: heading level and HTML markup change; report bytes/snapshots shift. No wire-shape change.
Found by the 2026-06 follow-up 2.0 UX audit. Rolls up under #505.
Related: #611, #610
Resolution Plan
Decisions settled (design audit, 2026-06-10)
(a) Emit the Markdown legend at ## (not ###) so it gets its own TOC
entry and stops nesting under the last language's section. Determinate.
(b) HTML legend = <details open> — expanded by default on screen, in
print, and for screen readers; no fragile print-CSS. It's at the page bottom,
so the extra vertical space is harmless. Fixes the "invisible in print" gap
that motivated the legend.
(c) Add legend entries for the header stats (PLOC / Comments / Comment
ratio) and the missing PLOC HTML tooltip, keeping short header labels —
consistent with the short-form+legend pattern (refactor(api)!: cross-surface metric-name alignment for 2.0 (umbrella) #587) and completing the legend
so it defines everything on the page.
Steps
Change write_legend(&mut out, 3, …) → level 2
(markdown_report.rs:636) so it renders ## Legend.
HTML: render the legend <details open> (html_report.rs:878).
Current behavior
Three related legend problems:
(a) The Markdown legend is emitted at heading level 3 —
write_legend(&mut out, 3, …)(big-code-analysis-cli/src/markdown_report.rs:636) — so### Legendnests under the last language's##section, though it defines columns for every language.(b) The HTML legend is a
<details>collapsed by default at the page bottom (big-code-analysis-cli/src/html_report.rs:878), while the stated rationale for adding it was that tooltips are "hover-only and invisible to print, mobile, and screen readers" (html_report.rs:855-857). A collapsed<details>is equally invisible in print.(c) The global header's
PLOC:/Comments:/Comment ratio:labels are defined nowhere:legend_entries()(markdown_report/hotspot.rs:529-536) covers only hotspot columns, and PLOC has no HTML tooltip either.Why it's a UX problem
(a) misleads outline-based navigation and TOCs; (b) defeats the legend's own stated purpose for the print case; (c) leaves the very first numbers a reader sees unexplained.
Proposed 2.0 design
Emit the legend at
##so it gets its own TOC entry; render<details open>or add print CSS that forces it open; add header-stat entries to the legend, or rename the labels to self-explanatory words (Code lines (PLOC)).Breaking
Minor structure: heading level and HTML markup change; report bytes/snapshots shift. No wire-shape change.
Found by the 2026-06 follow-up 2.0 UX audit. Rolls up under #505.
Related: #611, #610
Resolution Plan
Decisions settled (design audit, 2026-06-10)
##(not###) so it gets its own TOCentry and stops nesting under the last language's section. Determinate.
<details open>— expanded by default on screen, inprint, and for screen readers; no fragile print-CSS. It's at the page bottom,
so the extra vertical space is harmless. Fixes the "invisible in print" gap
that motivated the legend.
ratio) and the missing PLOC HTML tooltip, keeping short header labels —
consistent with the short-form+legend pattern (refactor(api)!: cross-surface metric-name alignment for 2.0 (umbrella) #587) and completing the legend
so it defines everything on the page.
Steps
write_legend(&mut out, 3, …)→ level2(
markdown_report.rs:636) so it renders## Legend.<details open>(html_report.rs:878).legend_entries()(markdown_report/hotspot.rs:529-536) to cover theheader stats PLOC/Comments/Comment ratio; add the PLOC HTML tooltip (overlaps
fix(output): HTML SLOC tooltip describes PLOC, not SLOC #610/fix(output): HTML tooltip catalogue — add PLOC entry; distinct bus-factor Files tooltip #693 — coordinate so PLOC is defined once).
CLI crate + submodule report snapshots if present).
## [Unreleased]: entry (heading level + HTML markup change; nowire-shape change).
make pre-commit.Related
feat(output): link legend entries and column headers to the hosted metric docs #675 (legend links), refactor(output): move the Actionable Summary to the top of each language section #678/feat(output): HTML TOC should include the h3 hotspot sections #685 (TOC). Rolls up under track(2.0): breaking-change roadmap for the 2.x major bump #505.
Assessment