feat: Argus Console (TUI) + browser viewer modernization — interactive console, live intelligence, charts, formal PDF report

.ai/decisions.yaml

@@ -2454,3 +2454,89 @@ decisions:
         already covers the container case via its scanner-summary-* pattern.
 
         '
+  ADR-031:
+    title: Formal vulnerability report — UI-free model, HTML-first, server-side PDF behind [report]
+    date: '2026-06-13'
+    status: accepted
+    context: |-
+      Browser roadmap Phase B4. Stakeholders and auditors need a single,
+      authoritative artifact — "here is what we scanned, what we found, and
+      proof of which tooling/commit produced it" — that can be archived and
+      handed to a government body. The interactive dashboard is the wrong
+      shape for that: it's collapsible, filterable, and dynamically scaled.
+      A formal report must be linear, complete, and provenance-bearing.
+      Argus already records the raw provenance facts (argus version,
+      scan_context commit_sha + repo_root, the toolchain image-digest +
+      cosign-verification block from #240/#243, and the signed attestation
+      from #241/#244) — they were just never assembled into one document.
+    decision: |-
+      Build the report in three layers, mirroring the established UI-free-core
+      pattern: (1) argus/core/report.py — a pure, dependency-free ReportModel +
+      build_report() that assembles provenance, the executive summary (reusing
+      findings_view.compute_summary so counts can't diverge from the dashboard),
+      and severity-grouped findings; (2) a standalone report.html.j2 + report.css
+      (does NOT extend the app chrome — it's a print document) rendered by a
+      /report route, always available; (3) a server-side /report.pdf route that
+      renders the same HTML to PDF via WeasyPrint, behind an opt-in [report]
+      extra. The PDF is generated server-side (not via the browser print dialog)
+      so it is deterministic and one click away. WeasyPrint's edge lives in
+      argus/viewers/browser/report_pdf.py, lazily imported and raising
+      ViewerUnavailable with an install hint when absent — the same guarded-extra
+      pattern the Console epic used. Attestation status is detected from the
+      cosign bundle / in-toto statement written alongside argus-results.json.
+    consequences:
+      positive:
+      - One authoritative, archivable artifact with cryptographic-grade provenance (commit, image digests + verification, attestation status) — not just a screenshot.
+      - Report counts/severities reuse the shared findings_view logic, so the report can never disagree with the dashboard or TUI.
+      - The core model is pure and fully unit-tested without WeasyPrint installed; only the thin PDF edge needs the native stack.
+      - Graceful degradation — /report HTML is always served; without the [report] extra the browser's own Print → Save-as-PDF produces the same document, so nothing hard-breaks.
+      - WeasyPrint (heavy native Pango/cairo stack) stays isolated behind an opt-in extra, preserving the viewer's otherwise zero-new-runtime-dep posture.
+      negative:
+      - WeasyPrint can't be exercised in the default test env (not installed); the PDF success path is tested via an injected fake renderer, and live PDF rendering is only smoke-verified where the extra is present.
+      - The report's provenance is only as complete as the scan recorded — an in-memory or non-git scan shows "not recorded" fields (surfaced honestly rather than fabricated).
+    implementation: |-
+      - argus/core/report.py — ReportModel, ReportProvenance, SeverityGroup,
+        build_report(); attestation detection from sibling bundle/statement files;
+        provenance from ScanSummary.scan_context + .toolchain + argus.__version__
+        (version + timestamp injectable for deterministic tests).
+      - argus/viewers/browser/report_pdf.py — guarded WeasyPrint edge
+        (is_available(), render_pdf(html, stylesheet=, base_url=)).
+      - argus/viewers/browser/templates/report.html.j2 — standalone print doc;
+        links /static/report.css when pdf=False (strict CSP), omits the link when
+        pdf=True so WeasyPrint receives the CSS explicitly (no HTTP fetch).
+      - argus/viewers/browser/static/report.css — print-optimized, @page rules +
+        page numbers, fixed severity hues, defines --fg/--surface-alt/--fg-muted
+        so the shared inline-SVG charts render on a light document.
+      - argus/viewers/browser/app.py — /report (HTML) + /report.pdf routes; a
+        "Report" nav link in base.html.j2.
+      - pyproject.toml — [report] = ["weasyprint>=62"]; folded into [all].
+      - Tests: argus/tests/core/test_report.py (model, provenance, attestation,
+        grouping) + argus/tests/viewers/browser/test_report_route.py (HTML render,
+        PDF guard-degradation + injected success path).
+      - Docs: docs/view-browser.md (Formal report section + screenshot),
+        scripts/docsite/capture_view_browser.py (/report capture).
+    related:
+    - ADR-021
+    pr_references:
+    - '(browser Phase B4 — formal vulnerability report; merges into feat/tui-explorer-and-scan-runner)'
+    alternatives_considered:
+    - name: Client-side PDF (browser print / JS PDF library)
+      rejected_because: |-
+        Browser print is per-browser non-deterministic and pushes layout control
+        to the user's print dialog; a JS PDF lib (jsPDF/pdfmake) would add a heavy
+        front-end dependency and can't see the server-side provenance facts. A
+        server-side render is deterministic (same scan → same bytes) and is the
+        "one click" the requirement called for. Browser print is kept only as the
+        no-extra fallback.
+    - name: Bundle WeasyPrint into the [browser] extra
+      rejected_because: |-
+        WeasyPrint pulls a heavy native stack (Pango, cairo, …). Making it a hard
+        dependency of the browser viewer would punish every user who just wants
+        the dashboard. Isolating it behind [report] keeps the common install light
+        and matches the supply-chain-tool principle of minimizing its own surface.
+    - name: A new reporter plugin (argus.reporters entry-point) instead of a viewer route
+      rejected_because: |-
+        The report's value is the interactive HTML preview + one-click server-side
+        PDF in the same surface the findings are viewed in. A batch reporter would
+        not give the on-screen preview, and the provenance assembly is naturally a
+        view concern over a loaded ScanSummary, not a scan-time emit.

.pre-commit-config.yaml

@@ -61,7 +61,7 @@ repos:
           --skip=**/package-lock.json,
           --skip=pnpm-lock.yaml,
           --skip=**/pnpm-lock.yaml,
-          "--ignore-words-list=assertIn,froms,intoto",
+          "--ignore-words-list=assertIn,froms,intoto,iterm",
           -w
         ]
   # renovate: datasource=github-tags depName=adrienverge/yamllint versioning=semver