ui_guardrails 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f34f9ff613f4b10edd128972a3ee8b268e82fee79abc499d7554d48bf834eec
-  data.tar.gz: 937199143fb681851d6493dc666ce9a381d4db83b247059e00e9b0dd91b8a901
+  metadata.gz: da306d3808653d6bd263a867d1ba0aaf159a2c3a515a6e1284276cc69e34cc8c
+  data.tar.gz: c895cef92d7cc7acf0be8ddf97079a51a9753aa434223fc3ce3e5fe28125cc39
 SHA512:
-  metadata.gz: 8e6d87b9e1bac27c0f79f941343855806c0fb3a3c55b0191cfeb1e184a0b4b5cc6b09eb88ce4df2512ac646c1572f528da269dedacc56fd269f8a4b3ac7630eb
-  data.tar.gz: d50217306f64e883988ad9184adde4d02e274fc8262560aeab3b8a0c9eecd573bae847006c0a3383222020ab3d9281ba96d1720ea9019f17c3491bf21fcf08e1
+  metadata.gz: 4c250a84dfd1ae1ce7ccf39e9e617ede812facb0dfa529bf53ef7bfe2ffd8812327d47409bbaafa4b21a712ae32a6d565ef9fa2c83b5802314793375f5b3208f
+  data.tar.gz: 6e97b1ec55de42f6083ee6590c85599445e310d0a8c9bc8d12bce1dec41f2c3becadb1a9955b4b799112e52b754657f0b6bdb0fe3bf3db036a119b0278d8eea7

data/README.md

@@ -4,7 +4,7 @@ A Rails toolset that prevents UI drift in AI-assisted applications. Static audit
 
 Built and maintained by [Meticulous](https://meticulous.com).
 
-**Current release:** 1.2.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.4.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
 
@@ -203,7 +219,10 @@ 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. |
+| `SEVERITY=error` / `SEVERITY=warning` | Severity floor. `error` checks errors only; `warning` drops suggestions; default is everything. Applies to the report, the exit code, JSON, HTML, and the TUI alike. Detectors that can only produce muted findings aren't run. An unrecognized value aborts rather than being ignored. |
 | `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 }`. |
@@ -224,6 +243,15 @@ The audit task is a single shell command:
   run: bundle exec rake guardrails:audit
 ```
 
+Adopting Guardrails on an existing codebase usually means a backlog of warnings you can't clear in one PR. Gate on errors now and ratchet down later:
+
+```yaml
+- name: Guardrails audit (errors only)
+  run: bundle exec rake guardrails:audit SEVERITY=error
+```
+
+`SEVERITY=error` exits 1 only when there are error-level findings (raw colors, arbitrary Tailwind values, a11y, visual diffs) and skips the warning- and suggestion-tier detectors entirely, so it's also the fastest way to run the audit. The report ends with a line saying what wasn't checked, so a green run can't be mistaken for a clean codebase.
+
 For richer integration:
 
 ```yaml

data/doc/ROADMAP.md

@@ -1,7 +1,7 @@
 # Guardrails — Roadmap
 
-**Status:** **1.0.0 released on RubyGems.org** — V0 ✅, V1 ✅, V2 ✅ (visual-diff via snap_diff-capybara landed 0.8.0; published as 1.0.0 once the trusted-publisher pipeline merged)
-**Last updated:** 2026-05-11
+**Status:** **1.4.0 released on RubyGems.org** — V0 ✅, V1 ✅, V2 ✅ (the originally-planned roadmap, published as 1.0.0). Post-1.0 releases have been about reading the findings rather than producing more of them: inline suggestions (1.1.0), then an interactive browser + HTML report (1.3.0).
+**Last updated:** 2026-09-19
 
 ## Context
 
@@ -116,6 +116,24 @@ This doc tracks shipped vs. planned scope and parks remaining unknowns. V0 + mos
 
 ---
 
+## Post-1.0 — Report UX
+
+The planned roadmap ended at V2. Running the gem on real codebases (Patchvault: 981 findings) showed the next problem wasn't detection, it was *reading* the output.
+
+| Item | Status | Notes |
+|---|---|---|
+| Inline suggestions + triage summary | ✅ shipped (1.1.0) | Every finding carries a `→` action; severity-grouped summary at top and bottom; `[error]` / `[warning]` / `[suggest]` tags; TTY-aware ASCII styling, `NO_COLOR` honored. |
+| Ruby 3.4 / railties 7.2 floor | ✅ shipped (1.2.0) | Compatibility-only release. Ruby 3.2/3.3 or Rails 7.1 users stay on 1.1.0. |
+| Findings data layer | ✅ shipped (1.3.0) | `Guardrails::Report::Run` runs the audit once for every front-end; `Report::Finding` / `Location` / `Category` are detector-agnostic finding data. Every detector implements `categories(result)`, sharing its title / suggestion strings with the text report. New detectors only need to implement that to show up in the TUI and HTML report. |
+| Interactive browser (`rake guardrails:tui`) | ✅ shipped (1.3.0) | Roll-up → category → finding → source, regroup by file, live filter, open in `$EDITOR` at the line, re-run. `io/console` only — no new dependencies. If the hand-rolled rendering stops being enough, swapping in a TUI library means replacing `TUI::Screen` + the loop in `tui.rb`; `TUI::State` (navigation) doesn't know about terminals. |
+| HTML report (`FORMAT=html`) | ✅ shipped (1.3.0) | One self-contained file, no server or assets — opens from disk or as a CI artifact. Generated rather than served: a mounted engine was more surface than the problem needed, and the Lookbook panel already covers in-app. |
+| File-grouped view | ✅ shipped (1.3.0) | `tab` in the TUI. Was a 1.1.0 follow-up. |
+| `SEVERITY=error\|warning` floor | ✅ shipped (1.4.0) | One severity floor across text report, exit code, JSON, HTML, and TUI. Skips detectors that can only produce muted findings. Filtered reports say what wasn't checked; unknown values abort. Supersedes the `--strict` flag dropped in V0. |
+| Lookbook panel on the new data layer | not started | The auto-registered panel still renders from its own `ComponentReport`; it could render `Report::Finding`s and pick up suggestions for free. |
+| CI test workflow | not started | Specs only run inside the release workflow, on one Ruby. A PR-time matrix (3.4 + head) would catch floor regressions before tag time. |
+
+---
+
 ## Decisions Captured
 
 | Question | Decision |

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,8 @@ require "json"
 require "pathname"
 require "set"
 require_relative "report/style"
+require_relative "report/finding"
+require_relative "report/severity"
 
 module Guardrails
   # Consumes axe-core JSON output and folds the findings into Guardrails'
@@ -38,7 +40,9 @@ module Guardrails
     # `failing_impacts:` if your rule pack emits custom severities.
     DEFAULT_FAILING_IMPACTS = %w[minor moderate serious critical].freeze
 
-    def initialize(input:, output: $stdout, failing_impacts: DEFAULT_FAILING_IMPACTS, style: nil)
+    def initialize(input:, output: $stdout, failing_impacts: DEFAULT_FAILING_IMPACTS, style: nil,
+                   min_severity: Report::Severity::DEFAULT)
+      @min_severity = min_severity
       @input = input
       @output = output
       @failing_impacts = Set.new(failing_impacts.map(&:to_s))
@@ -46,7 +50,7 @@ module Guardrails
     end
 
     def run
-      findings = parse_input
+      findings = parse_input.select { |f| Report::Severity.include?(impact_to_severity(f.impact), @min_severity) }
       print_report(findings)
       findings
     end
@@ -64,8 +68,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 +139,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,8 @@ require "stringio"
 require "yaml"
 require_relative "erb_parser"
 require_relative "report/style"
+require_relative "report/finding"
+require_relative "report/severity"
 
 module Guardrails
   class Audit
@@ -70,7 +72,9 @@ module Guardrails
       flood-color lighting-color stop-color
     ].freeze
 
-    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false, style: nil)
+    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false, style: nil,
+                   min_severity: Report::Severity::DEFAULT)
+      @min_severity = min_severity
       @root = Pathname(root)
       @output = output
       @suggest = suggest
@@ -81,13 +85,44 @@ module Guardrails
     end
 
     def run
-      violations = collect_files.flat_map { |file| scan_file(file) }
+      # Filtered before anything else sees them, so the report, the
+      # SUGGEST checklist, and the returned list (→ exit code, JSON)
+      # all agree on what this run was about.
+      violations = collect_files.flat_map { |file| scan_file(file) }.select do |v|
+        Report::Severity.include?(SEVERITY_FOR_TYPE.fetch(v.type, :warning), @min_severity)
+      end
       print_report(violations)
       remaining = @apply ? apply_auto_fixes(violations) : violations
       write_suggestions(remaining) if @suggest
       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 +494,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 +505,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 ""

data/lib/guardrails/report/finding.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Guardrails
+  module Report
+    # Where a finding lives. `line` / `column` are nil for whole-file
+    # findings (a dead Stimulus controller, a component with no preview).
+    Location = Struct.new(:file, :line, :column, keyword_init: true) do
+      def to_s
+        [file, line, column].compact.join(":")
+      end
+    end
+
+    # One detector-agnostic finding. Every detector has its own result
+    # struct shaped around what it measures (Violation, Cluster,
+    # Pattern, …); Finding is the common denominator that front-ends
+    # which list, filter, and link findings render from, so they never
+    # need to know which detector produced what.
+    #
+    # `locations` is plural because the suggestion-tier detectors
+    # report one finding spanning many places (a class list repeated
+    # in 9 files is one finding, not 9). `details` is an ordered list
+    # of [label, value] pairs for detector-specific extras — class
+    # list, axe help URL, diff image path.
+    Finding = Struct.new(:category, :severity, :title, :suggestion, :locations,
+                         :snippet, :details, :auto_fix, keyword_init: true) do
+      def locations
+        self[:locations] || []
+      end
+
+      def details
+        self[:details] || []
+      end
+
+      def location
+        locations.first
+      end
+
+      def files
+        locations.map(&:file).compact.uniq
+      end
+
+      def to_h
+        {
+          category: category, severity: severity, title: title, suggestion: suggestion,
+          locations: locations.map(&:to_h), snippet: snippet,
+          details: details.to_h, auto_fix: auto_fix || false
+        }
+      end
+    end
+
+    # A named group of findings plus the framing paragraph that
+    # explains what the rule catches. `name` matches the category on
+    # the corresponding Summary::Entry, so the rollup and the detail
+    # views line up. `severity` is the category's headline severity;
+    # individual findings may differ (deep a11y maps axe impact per
+    # finding).
+    Category = Struct.new(:name, :severity, :framing, :findings, :auto_fix, keyword_init: true) do
+      def count
+        findings.length
+      end
+    end
+  end
+end