ui_guardrails 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 792f503cf353ceaa71b9e45e39a4c3f9ae9255b40f4ecf361a207048074857e8
-  data.tar.gz: ff563d0927467149ddc42011500457c7c637db11fc9770566db64e3a0a4427e2
+  metadata.gz: a78df8763f35470a40ab6c8c8dcc6daf1351d35e733772a33afde5d1b7af1a54
+  data.tar.gz: a1f8aa3366f9a350673c55ff4200716e6c37db2f777592b914ada3236f67682e
 SHA512:
-  metadata.gz: 3eb224a5d378469571b727813ac68adcacd95576c63bade906a29e4119f9c0b28e972dbbbcf3710acbb6d7647684b14250a28b61c0a52ca65fd2c96e4f435d3a
-  data.tar.gz: 62c132501303b6cc6bcd5ffa8bf566955fc82cf6c4ed30ea3d1ad678ff4270841a57b636daf635035a38681a2e8797ab1e0018ceb62685a144aa840dc3aed238
+  metadata.gz: f16927ab59ea1e9e89fe51203d3a0ca0f14331956fdcce4ca1e957642579129ba143651d066d9bb763f85fb4b2f3e5afd93a657a9266550b8435e0159478c659
+  data.tar.gz: 7f4dfebecd72b184a84258ca90f48f978c603eb01739d3217f8cad8b24d0ab7991f2d8a79dc53834e7e67002b0da74219cf68e3aee0ca60c344febb1e3e722e0

data/README.md

@@ -1,10 +1,10 @@
-# Guardrails
+# UI-Guardrails
 
 A Rails toolset that prevents UI drift in AI-assisted applications. Static audits over your views, components, stylesheets, JS controllers, and tokens — surfacing the kinds of inconsistencies that compound silently as an AI assistant ships code faster than design-system discipline can keep up.
 
 Built and maintained by [Meticulous](https://meticulous.com).
 
-**Current release:** 1.0.0 — V0 + V1 + V2 complete, published on [RubyGems.org as `ui_guardrails`](https://rubygems.org/gems/ui_guardrails). The Ruby module stays `Guardrails` (so `require "guardrails"` is unchanged) — only the gem package name on rubygems carries the `ui_` prefix, to clear RubyGems' similarity rule against the unrelated [`guard-rails`](https://rubygems.org/gems/guard-rails) gem. See [`doc/ROADMAP.md`](doc/ROADMAP.md) for status, [`CHANGELOG.md`](CHANGELOG.md) for the full naming rationale.
+**Current release:** 1.3.0 — V0 + V1 + V2 complete, published on [RubyGems.org as `ui_guardrails`](https://rubygems.org/gems/ui_guardrails). The Ruby module stays `Guardrails` (so `require "guardrails"` is unchanged) — only the gem package name on rubygems carries the `ui_` prefix, to clear RubyGems' similarity rule against the unrelated [`guard-rails`](https://rubygems.org/gems/guard-rails) gem. See [`doc/ROADMAP.md`](doc/ROADMAP.md) for status, [`CHANGELOG.md`](CHANGELOG.md) for the full naming rationale.
 
 ---
 
@@ -92,6 +92,7 @@ APPLY=1 bundle exec rake guardrails:audit
 |---|---|
 | `guardrails:init` | Stack detection, writes `guardrails.yml`, scaffolds prefers-color-scheme / prefers-contrast media queries. Refuses to overwrite an existing config — `FORCE=1` overrides. |
 | `guardrails:audit` | Runs every detector — view drift, stimulus, partial similarity, view-components, a11y, cross-codebase patterns, class-itis. Exits 1 on violations. |
+| `guardrails:tui` | The same audit, browsable: a severity roll-up you drill into (category → finding → source), regroup by file, filter, and jump from into your editor or the HTML report. See [Browsing findings](#browsing-findings). |
 | `guardrails:icons` | Generates an SVG sprite from `app/assets/images/icons/`, flags inline `<svg>` in views, reports unused icons. |
 | `guardrails:tokens` | Parses your color and type-scale tokens (CSS vars / SCSS vars / Tailwind v3 config / Tailwind v4 `@theme`), reports hex literals in stylesheets that should reference a token. |
 | `guardrails:a11y:deep` | Reads axe-core JSON output and folds it into the unified report. Doesn't run axe itself (no Capybara / headless Chrome runtime deps) — point it at axe output your existing tooling produces. |
@@ -195,7 +196,22 @@ Every task prints a human-readable text report by default and exits 1 when viola
 FORMAT=json bundle exec rake guardrails:audit > findings.json
 ```
 
-The JSON payload has a `summary:` block with finding counts per category plus per-detector arrays — see the rake task source for the exact shape.
+The JSON payload has a `summary:` block with finding counts per category plus per-detector arrays — see `Guardrails::Report::Run#to_h` for the exact shape.
+
+### Browsing findings
+
+On a real codebase the text report is long (one of our test apps produces 981 findings). Two ways to navigate it instead of scrolling it:
+
+```bash
+bundle exec rake guardrails:tui                 # interactive, in the terminal
+FORMAT=html bundle exec rake guardrails:audit   # one self-contained HTML file
+```
+
+**`guardrails:tui`** opens on the same severity roll-up the text report leads with. `⏎` drills in — category → findings → a single finding with its suggestion, every location, and the source around it. `tab` regroups the whole thing by file (the files with the most findings first), `/` filters across category, title, suggestion, and path, `o` opens the highlighted location in your editor at the right line, `w` writes and opens the HTML report, `r` re-runs the audit, `?` lists the rest. It takes the same env vars as `guardrails:audit` except `APPLY` and `SUGGEST` — browsing never rewrites files. No new dependencies: it's built on Ruby's bundled `io/console`.
+
+The editor is `$GUARDRAILS_EDITOR`, then `$VISUAL`, then `$EDITOR`. VS Code-family, Zed, Sublime, TextMate, JetBrains, Helix, and vim/nvim/nano/emacs all open at the finding's line; anything else gets the file path. With no editor set, it falls back to `open` / `xdg-open`.
+
+**`FORMAT=html`** writes `tmp/guardrails/audit.html` (override with `OUTPUT=path`): the roll-up, every finding with its suggestion, locations, and snippet, a live filter, and severity toggles. Everything is inline — no server, no assets, no network — so it works opened from disk or uploaded as a CI artifact. File locations become editor links once you pick your editor from the menu in the header (remembered per browser). Note the file embeds absolute paths from the machine that generated it; that's what makes the editor links work.
 
 ### Common env vars
 
@@ -204,6 +220,8 @@ The JSON payload has a `summary:` block with finding counts per category plus pe
 | `SUGGEST=1` | Write the markdown checklist alongside the text report. |
 | `APPLY=1` | Auto-fix raw_color + tailwind_arbitrary where tokens match. |
 | `FORMAT=json` | Emit one JSON document to stdout (all other audit output is suppressed). |
+| `FORMAT=html` / `OUTPUT=path` | Write the self-contained HTML report (default `tmp/guardrails/audit.html`). |
+| `GUARDRAILS_EDITOR=cmd` | Editor `guardrails:tui` opens locations in. Falls back to `$VISUAL`, then `$EDITOR`. |
 | `FORCE=1` | Bypass `init`'s refuse-to-overwrite default. |
 | `AXE_JSON=path` | Fold axe-core findings into the unified report. |
 | `VISUAL_DIFF=1` | Fold visual-diff findings into `guardrails:audit`. Embedded installs can flip this on permanently via `Guardrails.configure { \|c\| c.visual_diff.enabled = true }`. |

data/doc/RESEARCH-visual-diff.md

@@ -0,0 +1,226 @@
+# Visual-diff integration — research memo
+
+> Status: research, not implementation. Closes the V2 visual-diff item's "evaluate a stable visual-regression target" prerequisite before any code lands.
+>
+> Last updated: 2026-05-10
+
+## Executive summary
+
+**Recommendation: ship a `Guardrails::VisualDiff` parser that consumes screenshot-diff tool output, the same way `Guardrails::A11yDeep` consumes axe-core JSON.** Don't bundle Chromium / Playwright / Capybara as runtime deps — that was the constraint that originally parked this item, and it hasn't changed.
+
+The cleanest external producers to support, in priority order:
+
+1. **`snap_diff-capybara`** (formerly `capybara-screenshot-diff`) — the Rails-native default. Active gem (1.12.0 released April 2026), commits baselines to git, no cloud dep. Highest fit-for-purpose.
+2. **BackstopJS** — fully OSS, clean JSON output. Worth a second adapter for non-Rails-monolith projects (the Avo dogfood pattern).
+3. **Percy / Chromatic** — SaaS, vendor-locked. Defer until a user actually asks; webhook ingestion is the integration shape if they do.
+
+The talk narrative writes itself: **static analysis catches the source, visual diff catches what the rendered DOM does next.** Pair this with `ClassItis` — AI-generated 8-class soup looks plausible in the source but pixel-shifts the baseline once a single utility is wrong.
+
+---
+
+## The constraint that shaped A11yDeep applies here too
+
+When deferring deep a11y in the original roadmap, the call was:
+
+> axe-core wrapper with `--deep` mode NOT shipped — would require Capybara + headless Chrome runtime deps.
+
+Then in 0.6.0 we shipped `A11yDeep` as a **parser** for axe JSON output: zero new runtime deps, user runs axe however they already do, Guardrails provides the merge + report + exit-code contract. The same calculus applies to visual diff. Bundling Playwright/Chromium would balloon `bundle install` for users who don't run system tests; bundling Selenium would tie us to Ruby browser-driver decay. The right move is to consume what existing tools emit.
+
+**Acceptance criteria for any candidate tool**, in priority order:
+
+1. **Emits a machine-readable diff summary** — JSON, JUnit XML, or a parseable HTML/filesystem layout. We need per-scenario: name, baseline path, current path, diff path (if any), mismatch % or pass/fail, optionally the URL/component selector.
+2. **Runs without Guardrails being involved.** The user's existing test toolchain runs the tool; we ingest the output. No shelling out to `npx`, no requiring the tool be present at audit time.
+3. **OSS-friendly licensing** *or* a stable public API for SaaS tools.
+4. **Active maintenance.** Sub-12-month release cadence and >50 GitHub stars as a rough proxy.
+
+---
+
+## Per-tool brief
+
+### snap_diff-capybara (Rails-native) — **PRIMARY RECOMMENDATION**
+
+- **What it is:** Ruby gem (formerly `capybara-screenshot-diff`, now maintained at `github.com/snap-diff/snap_diff-capybara` by `donv` and `jetthoughts`). Latest 1.12.0, April 2026. MIT-licensed. ~770k total downloads.
+- **How it works:** `screenshot "name"` inside Capybara system tests. Baselines live at `doc/screenshots/` and are **committed to git** — UI changes get reviewed in PR like code. No external auth, no cloud.
+- **Diff artifacts:**
+  - `*.png` baseline
+  - `*.diff.png` (changed pixels highlighted red)
+  - `*.heatmap.diff.png` (pixel-variance density)
+  - **`snap_diff_report.html`** — interactive multi-view dashboard
+- **CI flow:** Tests fail on baseline mismatch. There's a reusable GitHub Actions workflow that uploads the HTML report and posts PR comments. Ships its own baseline-update flow.
+- **Runtime:** Ruby 3.2+, any Capybara-compatible driver (Selenium / Playwright / Cuprite). libvips 8.9+ for fast comparisons, falls back to ChunkyPNG.
+- **For Guardrails to consume:** the HTML report has a fixed structure, but the gem doesn't (yet) emit a top-level JSON summary. **Either:**
+  - **(a)** ask upstream for a `snap_diff_report.json` companion to the HTML — small ask, this is the maintained gem
+  - **(b)** walk `doc/screenshots/` ourselves: pair `name.png` with `name.diff.png`, treat presence of the diff file as a failing finding
+- **Fit:** ★★★★★. Same ecosystem (Ruby/Rails/Capybara), no new deps for users already running system tests, baselines-in-git matches the Guardrails ethos of "the source is the source of truth."
+
+### BackstopJS
+
+- **What it is:** Node CLI, MIT-licensed, actively maintained, the dominant OSS visual-regression tool outside the Storybook ecosystem.
+- **How it works:** `backstop init`, `backstop test`, `backstop approve`. Configured via `backstop.json` (scenarios = URL × viewport × selector). Headless Chrome via Puppeteer or Firefox/WebKit via Playwright. All artifacts local under `backstop_data/`.
+- **Output:** HTML interactive report, **JSON report**, JUnit XML, CLI text. Exit 0/1.
+- **For Guardrails to consume:** The JSON report already exists and is the canonical machine-readable output. Per-scenario: name, label, mismatch percentage, pass/fail, paths to reference + test + diff images.
+- **Fit:** ★★★★☆. Native machine-readable output, no SaaS dep, but Node-only — Ruby/Rails shops would have a parallel toolchain. Justifiable for the "Rails frontend that already runs JS tooling" subset (any non-trivial Rails app).
+
+### Playwright `toHaveScreenshot` / `toMatchSnapshot`
+
+- **What it is:** Built-in Playwright assertion. The team that maintains Playwright also maintains Chromatic (Microsoft → Storybook acquisition), so it's becoming the de facto cross-tool snapshot mechanism.
+- **How it works:** `await expect(page).toHaveScreenshot()`. Stores baselines in `__screenshots__/`. Updates via `--update-snapshots`.
+- **Output:** JUnit / JSON via Playwright's reporter API; HTML report; per-test pass/fail in CI.
+- **For Guardrails to consume:** Playwright JSON reporter emits a structured test-result document; each failure includes `attachments` with the diff image path. Parseable, but the schema is "Playwright test results" not "visual diff" — we'd be extracting the visual subset.
+- **Fit:** ★★★☆☆. Future-proof and increasingly canonical, but the integration is heavier (have to filter Playwright results for screenshot-specific failures). Worth supporting in v2 of the adapter.
+
+### Percy (BrowserStack)
+
+- **What it is:** SaaS, all builds go through Percy's cloud. Originally a standalone product, BrowserStack-acquired in 2020.
+- **Ruby story:** `percy-capybara` gem exists. Latest release v5.0.0 — July 2021 — i.e. **maintenance-stale**. 4+ years without a meaningful release; the active surface is the JS SDKs.
+- **Output:** Dashboard URL + per-build webhook. No local artifacts beyond the snapshot upload.
+- **Pricing:** Pricing page is gated behind BrowserStack's product navigation; no clear OSS-free tier surfaced via the public site. Assume paid-only for non-trial use.
+- **For Guardrails to consume:** `build-finished` webhook payload is the integration shape — but that requires a receiver, which Guardrails-the-gem isn't. Could ship a parser for the webhook JSON that users POST to their CI.
+- **Fit:** ★★☆☆☆. Stale Ruby SDK, vendor-locked, no clear OSS pricing. Defer until a user asks specifically.
+
+### Chromatic
+
+- **What it is:** SaaS, made by the Storybook team. The standard visual-regression for Storybook-based component libraries; expanded to Playwright + Cypress in 2024–25.
+- **Ruby story:** None. JS-ecosystem only. No Lookbook integration despite Lookbook being the Rails-shaped Storybook equivalent.
+- **Output:** Cloud dashboard, web API for build status, no local artifacts.
+- **Pricing:** Free tier (5,000 snapshots/month, Chrome-only) — generous. Paid starts at $179/mo. "Building in the open?" OSS plan available on application.
+- **Fit:** ★★☆☆☆ for Rails apps without Storybook. ★★★★☆ for ViewComponent shops who use Storybook for non-Rails components alongside. Pair-of-tools story is workable but indirect; Lookbook integration would be the missing link, and that's a Lookbook upstream ask, not a Guardrails one.
+
+### Honorable mentions
+
+- **Loki** — Storybook-only, narrow audience for Rails-flavored Guardrails. Skip.
+- **`reg-suit`** — Cloud or self-hosted, language-agnostic, JSON report. Reasonable BackstopJS-alternative; not common enough in Rails shops to justify a dedicated adapter at v1.
+
+---
+
+## Fit table
+
+| Tool | OSS | Rails-native | Machine-readable output | Cloud dep | Active | Fit score |
+|---|---|---|---|---|---|---|
+| snap_diff-capybara | ✅ MIT | ✅ Ruby gem | 🟡 HTML report (no JSON yet) | ❌ baselines in git | ✅ active | ★★★★★ |
+| BackstopJS | ✅ MIT | ❌ Node | ✅ JSON report | ❌ local FS | ✅ active | ★★★★☆ |
+| Playwright snapshots | ✅ Apache | ❌ Node | ✅ JSON via reporter | ❌ local FS | ✅ active | ★★★☆☆ |
+| Percy | 🔒 SaaS | 🟡 stale gem (2021) | ✅ webhook | ✅ required | 🟡 webhooks active, SDK stale | ★★☆☆☆ |
+| Chromatic | 🔒 SaaS | ❌ JS-only | ✅ API | ✅ required | ✅ active | ★★☆☆☆ |
+
+---
+
+## Proposed integration shape (mirrors A11yDeep)
+
+```
+lib/guardrails/visual_diff.rb           — parser + report
+lib/guardrails/visual_diff/snap_diff.rb — adapter for snap_diff-capybara
+lib/guardrails/visual_diff/backstop.rb  — adapter for BackstopJS JSON
+spec/guardrails/visual_diff_spec.rb
+spec/guardrails/visual_diff/snap_diff_spec.rb
+spec/guardrails/visual_diff/backstop_spec.rb
+```
+
+Normalized `Finding` shape (across both adapters):
+
+```ruby
+Finding = Struct.new(
+  :scenario,        # "homepage", "checkout_cart"
+  :viewport,        # "desktop"; nil if not applicable
+  :mismatch_ratio,  # Float 0.0..1.0 (or nil for snap_diff which is pass/fail)
+  :baseline_path,   # relative path on disk
+  :current_path,    # relative path on disk
+  :diff_path,       # relative path to .diff.png, nil if pass
+  :url,             # optional, BackstopJS scenarios have URLs
+  :selector,        # optional
+  keyword_init: true
+)
+```
+
+Rake task (mirrors `guardrails:a11y:deep`):
+
+```bash
+# Either auto-detect from `doc/screenshots/` (snap_diff convention) ...
+bundle exec rake guardrails:visual:deep
+
+# ... or point at an explicit producer:
+SNAP_DIFF_DIR=doc/screenshots bundle exec rake guardrails:visual:deep
+BACKSTOP_JSON=backstop_data/html_report/jsonReport.json bundle exec rake guardrails:visual:deep
+```
+
+Folded into `guardrails:audit` via `VISUAL_DIFF=...` env var, same shape as `AXE_JSON`.
+
+JSON output extends the existing audit payload:
+
+```json
+{
+  "summary": { "...": "...", "visual_diff": 3 },
+  "visual_diff": [
+    { "scenario": "checkout/cart", "mismatch_ratio": 0.082,
+      "baseline_path": "doc/screenshots/checkout_cart.png",
+      "diff_path": "doc/screenshots/checkout_cart.diff.png" }
+  ]
+}
+```
+
+Exit-code contract: a finding's `mismatch_ratio > threshold` (configurable, default `0.0` — any diff fails) bumps the audit to exit 1. For snap_diff (pass/fail), any failure is a fail.
+
+---
+
+## What this buys the gem (and the talk)
+
+1. **Closes V2.** Roadmap is fully shipped on the three core items.
+2. **Talk narrative is now four layers deep:**
+   - *Static AST drift* (V0): the source-level mistakes.
+   - *Structural drift* (V2 cross-codebase + class-itis): the patterns the source shouldn't have.
+   - *Runtime a11y drift* (V1.6 deep a11y): what the static checks can't see.
+   - *Visual drift* (V2 visual-diff): what the rendered DOM does next.
+
+   AI assistants fail at each layer differently. Each Guardrails detector maps to a specific failure mode.
+
+3. **Same install/run story as everything else.** No new install footprint. Users keep their preferred screenshot tool; Guardrails provides the unified report.
+
+---
+
+## Open decisions for the morning
+
+1. **Primary adapter: snap_diff or BackstopJS?**
+   - My read: snap_diff-capybara, since (a) Rails-native, (b) we'd be working with the maintainers of a small focused gem who'd likely accept a JSON-output PR upstream, and (c) baselines-in-git matches Guardrails' "source is canonical" ethos.
+   - The risk: snap_diff doesn't currently emit JSON, so v0.8.0 might need an upstream contribution. We could ship the filesystem-walking adapter first (look at `doc/screenshots/*.diff.png`) and contribute the JSON emitter separately.
+
+2. **Scope: ship one adapter or two?**
+   - One (snap_diff) keeps the PR small and proves the pattern.
+   - Two (snap_diff + BackstopJS) covers the Avo / non-Rails-monolith case from day one.
+   - I'd ship one and tag, then add BackstopJS in a follow-up if there's signal.
+
+3. **Threshold default: `0.0` (any diff fails) or something more lenient?**
+   - A11yDeep defaulted to "any non-nil impact fails". The visual-diff equivalent is "any pixel mismatch fails" — strict, but visual diff is opt-in (you set up baselines deliberately), so strict is the right default.
+   - Per-call override via `VISUAL_DIFF_THRESHOLD=0.01` env or `visual_diff.threshold` in `guardrails.yml`.
+
+4. **Where does this surface in the Lookbook panel?**
+   - `ComponentReport#for` could add `visual_diff: [...]` showing per-component baseline mismatches. Pulls together: "this component drifted statically (raw_color) AND visually (3% mismatch on the desktop viewport)."
+   - Probably out of scope for v0.8.0 — first land the audit/CI integration, layer Lookbook in v0.9.0.
+
+5. **Is this 0.8.0 or 1.0.0?**
+   - Argument for 0.8.0: matches the pattern of every other increment.
+   - Argument for 1.0.0: with this shipped, all three V0–V2 column-headers are done. We could draw the "ready for serious use" line here and tag a 1.0.0.
+   - My read: 0.8.0 for the visual-diff feature, then a separate 1.0.0 release after dogfooding the full V2 surface against Patchvault/Talos/Forem/Avo. The 0.2.x→0.7.x cadence already moved through dogfood-driven patches; another round before 1.0.0 fits.
+
+---
+
+## Out of scope
+
+- **Running the screenshot tool ourselves.** Not now, possibly not ever — the gem's ethos is parse-only.
+- **Hosted baseline storage.** Baselines stay in the user's repo (snap_diff convention) or wherever their existing tool puts them.
+- **Image-diff algorithm work.** Pixel comparison is a solved problem with multiple good libraries; we don't add value by reinventing it.
+- **Real-browser rendering.** Same as the headless Chrome reasoning in A11yDeep.
+
+---
+
+## What's needed to start
+
+If we go with snap_diff-capybara as the primary adapter:
+
+1. Decide if we file an upstream PR to add `snap_diff_report.json` emission, or build the filesystem-walking adapter first.
+2. Add `snap_diff-capybara` to `examples/demo/Gemfile` and seed a couple of system tests so the integration spec has something to verify against.
+3. Roughly 3 slices, mirroring the A11yDeep PR:
+   - Slice 1: `VisualDiff` parser + `Finding` struct + snap_diff adapter + spec
+   - Slice 2: rake task wiring (standalone + `guardrails:audit` fold-in) + JSON output extension
+   - Slice 3: docs (new `doc/VISUAL-DIFF.md` mirroring `doc/A11Y.md`) + ROADMAP + CHANGELOG → 0.8.0
+
+Estimated scope: a single PR, comparable to 0.6.0's `A11yDeep` (~17 specs, ~400 LOC). Could be shipped same day as kick-off if no upstream blocker.

data/lib/guardrails/a11y_audit.rb

@@ -4,6 +4,7 @@ require "pathname"
 require "set"
 require_relative "erb_parser"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   # Static a11y checks that don't require a browser — element-level rules
@@ -43,8 +44,32 @@ module Guardrails
       findings
     end
 
+    # Detector-agnostic view of `findings` (see Report::Finding).
+    def categories(findings)
+      return [] if findings.empty?
+
+      [Report::Category.new(
+        name: "a11y (static)", severity: :error, framing: FRAMING.join(" "),
+        findings: findings.map { |f|
+          Report::Finding.new(
+            category: "a11y (static)", severity: :error,
+            title: "#{f.rule}: #{f.snippet.to_s[0, 60]}",
+            suggestion: SUGGESTION_FOR_RULE[f.rule.to_s],
+            locations: [Report::Location.new(file: f.file, line: f.line, column: f.column)],
+            snippet: f.snippet
+          )
+        }
+      )]
+    end
+
     private
 
+    FRAMING = [
+      "Element-level a11y rules answerable from view source — missing alt text,",
+      "unnamed buttons, unlabeled inputs, link without name. Full WCAG coverage",
+      "needs runtime checks; layer axe-core via AXE_JSON= for that."
+    ].freeze
+
     def view_files
       SCAN_PATTERNS
         .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
@@ -249,9 +274,7 @@ module Guardrails
       noun = findings.length == 1 ? "issue" : "issues"
       @output.puts ""
       @output.puts @style.section_heading(:error, "a11y (#{findings.length} static #{noun})")
-      @output.puts "  Element-level a11y rules answerable from view source — missing alt text,"
-      @output.puts "  unnamed buttons, unlabeled inputs, link without name. Full WCAG coverage"
-      @output.puts "  needs runtime checks; layer axe-core via AXE_JSON= for that."
+      FRAMING.each { |line| @output.puts "  #{line}" }
 
       findings.each do |f|
         @output.puts ""

data/lib/guardrails/a11y_deep.rb

@@ -4,6 +4,7 @@ require "json"
 require "pathname"
 require "set"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   # Consumes axe-core JSON output and folds the findings into Guardrails'
@@ -64,8 +65,33 @@ module Guardrails
       findings.any? { |f| @failing_impacts.include?(f.impact.to_s) }
     end
 
+    # Detector-agnostic view of `findings` (see Report::Finding). These
+    # come from a live page, not a source file, so there are no
+    # locations — url and selector ride along as details. Severity is
+    # per finding, mapped from axe's impact.
+    def categories(findings)
+      return [] if findings.empty?
+
+      [Report::Category.new(
+        name: "a11y (deep)", severity: :error, framing: FRAMING.join(" "),
+        findings: findings.map { |f|
+          Report::Finding.new(
+            category: "a11y (deep)", severity: impact_to_severity(f.impact),
+            title: "[#{f.impact || 'unknown'}] #{f.rule}: #{f.description}",
+            suggestion: f.help_url && "see #{f.help_url}",
+            details: [["url", f.url], ["selector", f.selector], ["help", f.help_url]].reject { |_, v| v.nil? }
+          )
+        }
+      )]
+    end
+
     private
 
+    FRAMING = [
+      "Runtime accessibility issues axe-core caught against your live pages.",
+      "Each links to dequeuniversity.com for the canonical remediation."
+    ].freeze
+
     def parse_input
       raw = @input.is_a?(Hash) || @input.is_a?(Array) ? @input : JSON.parse(File.read(@input.to_s, encoding: Encoding::UTF_8))
       parse(raw)
@@ -110,8 +136,7 @@ module Guardrails
         :error,
         "a11y deep (#{findings.length} #{noun} from axe-core)"
       )
-      @output.puts "  Runtime accessibility issues axe-core caught against your live pages."
-      @output.puts "  Each links to dequeuniversity.com for the canonical remediation."
+      FRAMING.each { |line| @output.puts "  #{line}" }
 
       grouped.each do |url, page_findings|
         @output.puts ""

data/lib/guardrails/audit.rb

@@ -6,6 +6,7 @@ require "stringio"
 require "yaml"
 require_relative "erb_parser"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   class Audit
@@ -88,6 +89,32 @@ module Guardrails
       remaining
     end
 
+    # Detector-agnostic view of `violations` (see Report::Finding) for
+    # front-ends that list and link findings rather than print them.
+    # One Category per violation type, in the text report's order.
+    def categories(violations)
+      by_type = violations.group_by(&:type)
+      (TYPE_ORDER + (by_type.keys - TYPE_ORDER)).filter_map do |type|
+        list = by_type[type]
+        next if list.nil? || list.empty?
+
+        severity = SEVERITY_FOR_TYPE.fetch(type, :warning)
+        auto_fix = AUTO_FIXABLE_TYPES.include?(type)
+        Report::Category.new(
+          name: type.to_s, severity: severity, framing: FRAMING_FOR_TYPE[type], auto_fix: auto_fix,
+          findings: list.map { |v|
+            Report::Finding.new(
+              category: type.to_s, severity: severity, auto_fix: auto_fix,
+              title: "#{type}: #{format_value(v)}",
+              suggestion: suggestion_for_violation(v),
+              locations: [Report::Location.new(file: v.file, line: v.line, column: v.column)],
+              snippet: v.snippet
+            )
+          }
+        )
+      end
+    end
+
     private
 
     def load_audit_config
@@ -459,10 +486,8 @@ module Guardrails
       # (a suggestion-shaped warning) and a11y (errors but grouped
       # separately because A11yAudit owns them — the audit rake task
       # threads them in via this same method).
-      type_order = %i[inline_style raw_color tailwind_arbitrary helper_recommended
-                      image_alt button_name link_name input_label]
       by_type = violations.group_by(&:type)
-      ordered = type_order + (by_type.keys - type_order)
+      ordered = TYPE_ORDER + (by_type.keys - TYPE_ORDER)
 
       ordered.each do |type|
         list = by_type[type] || []
@@ -472,6 +497,9 @@ module Guardrails
       end
     end
 
+    TYPE_ORDER = %i[inline_style raw_color tailwind_arbitrary helper_recommended
+                    image_alt button_name link_name input_label].freeze
+
     SEVERITY_FOR_TYPE = {
       inline_style: :warning,
       raw_color: :error,

data/lib/guardrails/class_itis.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require_relative "erb_parser"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   # Finds repeating "class soup" — the same long class list applied to
@@ -98,8 +99,36 @@ module Guardrails
         .sort_by { |c| [-c.count, -c.class_count] }
     end
 
+    # Detector-agnostic view of `clusters` (see Report::Finding). One
+    # finding per cluster, carrying every occurrence and the full
+    # class list (the text report truncates both for terminal width).
+    def categories(clusters)
+      return [] if clusters.empty?
+
+      [Report::Category.new(
+        name: "class-itis", severity: :suggestion, framing: framing_lines.join(" "),
+        findings: clusters.map { |cluster|
+          Report::Finding.new(
+            category: "class-itis", severity: :suggestion,
+            title: "<#{cluster.tag}> with #{cluster.class_count} classes, #{cluster.count} occurrences",
+            suggestion: suggestion_for(cluster),
+            locations: cluster.occurrences.map { |occ| Report::Location.new(file: occ.file, line: occ.line, column: occ.column) },
+            details: [["class", cluster.classes.join(" ")]]
+          )
+        }
+      )]
+    end
+
     private
 
+    def framing_lines
+      [
+        "The same multi-class list applied to the same tag in many places —",
+        "classic AI-paste pattern. Consider extracting a shared component or",
+        "an @apply rule. Threshold: >= #{@min_classes} classes, >= #{@min_occurrences} occurrences."
+      ]
+    end
+
     def view_files
       paths = VIEW_PATTERNS.flat_map { |g| Dir.glob(@root.join(g)) }.map { |p| Pathname(p) }.uniq
       paths.reject { |p| ignored?(p) }
@@ -174,9 +203,7 @@ module Guardrails
         :suggestion,
         "class-itis (#{clusters.length} #{noun}, #{total_occurrences} occurrences)"
       )
-      @output.puts "  The same multi-class list applied to the same tag in many places —"
-      @output.puts "  classic AI-paste pattern. Consider extracting a shared component or"
-      @output.puts "  an @apply rule. Threshold: >= #{@min_classes} classes, >= #{@min_occurrences} occurrences."
+      framing_lines.each { |line| @output.puts "  #{line}" }
 
       clusters.each do |cluster|
         @output.puts ""

data/lib/guardrails/cross_codebase_patterns.rb

@@ -5,6 +5,7 @@ require "digest"
 require "set"
 require_relative "erb_parser"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   # Finds recurring structural patterns across the codebase — element
@@ -98,8 +99,36 @@ module Guardrails
       dedupe_nested(patterns)
     end
 
+    # Detector-agnostic view of `patterns` (see Report::Finding). One
+    # finding per shape, carrying every occurrence — the text report
+    # caps the list for terminal width; this doesn't.
+    def categories(patterns)
+      return [] if patterns.empty?
+
+      [Report::Category.new(
+        name: "cross-codebase patterns", severity: :suggestion, framing: framing_lines.join(" "),
+        findings: patterns.map { |pattern|
+          Report::Finding.new(
+            category: "cross-codebase patterns", severity: :suggestion,
+            title: "shape: #{truncate_shape(pattern.shape)} (#{pattern.size} elements, #{pattern.count} occurrences)",
+            suggestion: suggestion_for(pattern),
+            locations: pattern.occurrences.map { |occ| Report::Location.new(file: occ.file, line: occ.line, column: occ.column) },
+            details: [["shape", pattern.shape]]
+          )
+        }
+      )]
+    end
+
     private
 
+    def framing_lines
+      [
+        "These element subtrees repeat #{@min_occurrences}+ times across your views and",
+        "components. Each is a candidate for extracting into a shared partial or",
+        "ViewComponent. Threshold: >= #{@min_size} elements, >= #{@min_occurrences} occurrences."
+      ]
+    end
+
     # Drop redundant inner shapes. When a table repeats N times, three
     # patterns end up with identical counts:
     #
@@ -222,9 +251,7 @@ module Guardrails
         :suggestion,
         "cross-codebase patterns (#{patterns.length} #{noun}, #{total_occurrences} occurrences)"
       )
-      @output.puts "  These element subtrees repeat #{@min_occurrences}+ times across your views and"
-      @output.puts "  components. Each is a candidate for extracting into a shared partial or"
-      @output.puts "  ViewComponent. Threshold: >= #{@min_size} elements, >= #{@min_occurrences} occurrences."
+      framing_lines.each { |line| @output.puts "  #{line}" }
 
       patterns.each do |pattern|
         @output.puts ""

data/lib/guardrails/partial_similarity.rb

@@ -4,6 +4,7 @@ require "pathname"
 require "set"
 require_relative "erb_parser"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   class PartialSimilarity
@@ -176,8 +177,36 @@ module Guardrails
       groups.sort_by { |g| -g[:files].size }
     end
 
+    # Detector-agnostic view of `findings` (see Report::Finding). One
+    # finding per pair — the unit the summary counts — rather than per
+    # connected group the way the text report condenses them.
+    def categories(findings)
+      return [] if findings.empty?
+
+      [Report::Category.new(
+        name: "similar partials", severity: :suggestion, framing: framing_lines.join(" "),
+        findings: findings.map { |f|
+          Report::Finding.new(
+            category: "similar partials", severity: :suggestion,
+            title: "#{format('%.2f', f.score)} similar: #{f.file_a} ↔ #{f.file_b}",
+            suggestion: suggestion_for_pair({ score_max: f.score }),
+            locations: [Report::Location.new(file: f.file_a), Report::Location.new(file: f.file_b)],
+            details: [["tags", "#{f.tag_count_a} / #{f.tag_count_b}"]]
+          )
+        }
+      )]
+    end
+
     private
 
+    def framing_lines
+      [
+        "Templates with >= #{@threshold} structural similarity. Likely duplicates;",
+        "consider extracting the common shape into a partial or parameterizing",
+        "one with locals to subsume the others."
+      ]
+    end
+
     def collect_partials
       PARTIAL_PATTERNS
         .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
@@ -212,9 +241,7 @@ module Guardrails
         :suggestion,
         "similar partials (#{groups.length} #{group_noun}, #{findings.length} pairs, #{total_files} files)"
       )
-      @output.puts "  Templates with >= #{@threshold} structural similarity. Likely duplicates;"
-      @output.puts "  consider extracting the common shape into a partial or parameterizing"
-      @output.puts "  one with locals to subsume the others."
+      framing_lines.each { |line| @output.puts "  #{line}" }
 
       groups.each do |group|
         @output.puts ""