Generate a self-contained offline HTML report from a saved map

Start with the saved-map contract in #94 and the mapdoc.Document model, then scope the new pkg/report/ package. Read the listed tests in pkg/report/ and tests/report/, beginning with byte determinism, CSP, aggregation, and no-network checks. Done means a bounded, offline HTML report is deterministic, evidence-linked, and covered by the specified tests.

User outcome

dircue map report map.json > report.html (name to be decided) produces one self-contained, offline HTML file that anyone can open, share or attach to a ticket. It contains:

• a treemap of the directory, sized by bytes or code lines and colored by language or role;
• the Linguist-style language bar;
• component, deployable and topology graphs;
• a coverage and unknowns panel with the explained-bytes meter;
• function hotspots;
• evidence drill-down to file and line for every fact.

Why

• Terminal summaries and JSON are the right automation contract, but people judge a profiling tool in the first ten seconds, usually from a screenshot. WinDirStat/SpaceSniffer (storage), GitHub's language bar (Linguist) and scc's tables are all instantly legible. No tool shows meaning (roles, components, how things connect) with proof in one view.
• A static file generated from a saved map keeps every dircue guarantee:
  • no server;
  • no network (no CDN, no fonts, no telemetry);
  • deterministic bytes for the same map;
  • no rescanning of the source.
• It becomes the canonical public demonstration: link a report of a famous repository and let readers click through the evidence themselves.

Proposal

• Input and packaging. Input is a saved map, optionally with a ledger (#97). Output is one HTML file with inlined, vendored, license-noted JS and CSS. No external requests, and a strict CSP meta tag (default-src 'none' plus inline hashes).
• Views:
  1. Overview. Identity (source, tree or content ID), size, explained bytes, language bar, role composition, top unknowns. The same facts as map --summary, rendered.
  2. Treemap. Squarified, zoomable, with size and color selectors. Summarized dependency or build trees are collapsed.
  3. Components. A table plus graph: ecosystem, languages, size, local dependencies, deployables that build or run it, interfaces, capabilities.
  4. Topology (see #103) and deployables.
  5. Hotspots. Per-function metrics from BCA, sortable, with no invented score.
  6. Coverage. Every question with its status and reasons, the analyzer coverage matrix (#78), routed follow-up tools (#79).
  7. Evidence. Every node and edge links to its evidence records: path, span, rule or provider, basis.
• Deterministic output: stable ordering, fixed number formatting, no timestamps. Byte-identical for the same input map.
• Size bounds: a default cap, with graceful aggregation beyond it (e.g. the kernel's ~92k files become a directory-level treemap, with file-level detail loaded only for the selected subtree from embedded compressed data).
• Accessibility: keyboard navigation, text alternatives, color-blind-safe palettes, a print stylesheet.

Tasks

• Choose and vendor the visualization libraries (small, audited, license-compatible), or write minimal ones. Record provenance.
• Report data-model builder from the map and ledger, with size-bounded aggregation.
• The seven views, plus navigation.
• Deterministic HTML emission and a CSP.
• Publish gallery examples (reports for a few famous public repositories) as release assets, not committed to the repo (see #88's bulky-evidence rule).

Test plan

Unit tests — new pkg/report/ package

• Byte-determinism: generate the same mapdoc.Document twice (different Go invocations, same input) and assert the HTML bytes are identical via SHA-256 comparison. Cover: stable field ordering, fixed number formatting, no time.Now() calls, no map-iteration order dependence.
• CSP correctness: parse the <meta http-equiv="Content-Security-Policy"> tag; assert default-src 'none' is present and every script-src and style-src hash matches the inlined content SHA-256.
• Aggregation bounds: a synthetic mapdoc.Document with 200 000 nodes must emit HTML under the declared size cap; a 10 000-file subtree must collapse to directory-level with a count annotation, not silently drop nodes.
• No external references: a regex scan of the generated HTML must match zero occurrences of http://, https://, //cdn, //fonts, data: URIs with external origins, or <script src=, <link href= pointing outside the document.
• Vendored-JS provenance: a unit test reads the vendored JS and CSS bytes embedded in pkg/report/ and asserts their SHA-256 values match a committed PROVENANCE.json under pkg/report/. Pattern follows internal/jsonschema/PROVENANCE.json. Any change to vendored bytes without a PROVENANCE update is a blocking failure.
• Fuzz target FuzzReportGeneration in pkg/report/fuzz_test.go (new file): feed arbitrary mapdoc.Document-shaped JSON; assert no panic, output is valid HTML5 (a structural check: <html>, <head>, <body> present), and the CSP meta tag is always present. Tie to #87.

Independent oracle / no-network proof — tests/report/ (new directory)

Tie to #84. Run headless Chromium in a --network none Docker container (a dedicated pinned image, new tests/report/Dockerfile, following the Docker harness pattern of tests/conformance/). Pinned Chromium version recorded in tests/report/PROVENANCE.json.

• Assert zero network requests logged by the browser during page load and 5 seconds of idle.
• Assert zero console errors.
• Assert the CSP <meta> tag is present and default-src 'none' is enforced (inject a fetch to an external URL via page.evaluate and confirm it is blocked).
• These checks run under workflow_dispatch only (container build is slow). A fast unit test covers the same properties structurally on every PR.

Hand-labeled ground-truth corpus — committed small maps

Tie to #75. Commit the map documents for the five existing tests/map_corpus/fixtures/ (they are already small JSON files). Do not commit reports (HTML output); reports for famous public repositories are published as release assets per the issue's own proposal, following the #88 bulky-evidence rule.

Scale fixtures — tests/report/fixtures/ (new directory)

• Kernel-sized fixture: a mapdoc.Document with ~92 000 nodes (synthetic, generated by a script in tests/report/; the script is committed, the generated file is not). Assert generation time ≤ declared budget and output size ≤ declared cap.
• 10M-entry synthetic map: generated by the same script at 10 million nodes; assert size cap is enforced and the aggregation annotation is correct. Run on-demand only (make report-scale, new target).

Accessibility — tests/report/e2e.py (new file), container-only

• Run axe-core (pinned npm version in tests/report/PROVENANCE.json) via headless Chromium on each report generated from the five tests/map_corpus/fixtures/ maps (added by #94) plus the kernel-sized synthetic map.
• Assert zero critical and zero serious axe violations.
• Runs under workflow_dispatch only.

Metamorphic invariants — tests/report/metamorphic.py (new file)

Tie to #85.

• A map with one additional unknown node must produce a report where the unknowns panel count is exactly one higher; no other section changes.
• Generating a report twice from the same map must produce byte-identical HTML (re-tests determinism at the harness level).
• Removing all function-metrics entries from the map must suppress the hotspots view entirely, not render an empty table.

Mutation-testing focus

Tie to #86. Prioritise the CSP-hash computation (a mutated hash would pass the tag-presence test but not the enforcement test) and the aggregation threshold comparison (off-by-one errors can silently drop nodes instead of collapsing them).

Performance and resource checks

Tie to #89 and #90.

• On every PR touching pkg/report/: deterministic-output test, CSP test, and vendored-JS PROVENANCE test.
• On-demand benchmark (make bench-report): run go test -bench BenchmarkReportGeneration in pkg/report/ against the kernel-sized fixture and record wall time and peak RSS to a receipt in tests/report/.

E2E script — tests/report/e2e.py (new file)

Runs under workflow_dispatch only. JSONL log fields per fixture: fixture, command, wall_seconds, html_bytes, nodes_rendered, nodes_aggregated, rss_kb, network_requests (must be 0), console_errors (must be 0), axe_critical, axe_serious, sha256. Saves screenshots as CI artifacts (actions/upload-artifact), on-demand CI only. Exits non-zero on any non-zero network_requests, console_errors, axe_critical, or axe_serious.

CI placement

• Every PR touching pkg/report/ or tests/report/: unit tests (including fuzz seed runs), byte-determinism, CSP structural check, vendored-JS PROVENANCE check. Add a report job to ci.yml or to a new report.yml (triggers: push, pull_request, workflow_dispatch; no schedule:).
• workflow_dispatch / make report-e2e only: headless Chromium no-network proof, axe-core accessibility check, scale fixtures, and screenshot artifact upload.

Regression fences

• A test that asserts the generated HTML contains zero external src or href values blocks any future accidental CDN reference.
• A test that asserts the vendored-JS SHA-256 values match PROVENANCE.json blocks silent dependency updates.
• A test that asserts page generation from the kernel-sized fixture completes in under the declared time budget blocks performance regressions.

Risks

• Vendored JavaScript. Vendored JS is supply-chain and maintenance surface. Keep it tiny and pinned.
• Huge maps. Huge maps need aggregation that doesn't hide unknowns.

Success criteria

• Reports for the corpus open offline in any modern browser with zero requests.
• They're byte-deterministic.
• Every fact is traceable to evidence.

Related: #76, #78, #79, #27, #88. Related idea issues: #97, #103, #107, #110 (the atlas's HTML summary reuses this report).

Sequencing: Depends on #94 (saved maps). It's richer with #97 (treemap sizes, hotspots) and #103, but a first version can render the map alone.

---

This proposal came out of an idea-wizard session on 2026-09-23. It isn't a release commitment, and the milestone is deliberately unset so the owner can decide per idea. It must preserve dircue's contracts:

• deterministic, offline output, with no execution of inspected content;
• the legacy Linguist-compatible CLI and output unchanged;
• unknown never rendered as absent;
• no provider findings or verdicts imported;
• CI event-driven only (no schedule:).