ui_guardrails 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f34f9ff613f4b10edd128972a3ee8b268e82fee79abc499d7554d48bf834eec
-  data.tar.gz: 937199143fb681851d6493dc666ce9a381d4db83b247059e00e9b0dd91b8a901
+  metadata.gz: a78df8763f35470a40ab6c8c8dcc6daf1351d35e733772a33afde5d1b7af1a54
+  data.tar.gz: a1f8aa3366f9a350673c55ff4200716e6c37db2f777592b914ada3236f67682e
 SHA512:
-  metadata.gz: 8e6d87b9e1bac27c0f79f941343855806c0fb3a3c55b0191cfeb1e184a0b4b5cc6b09eb88ce4df2512ac646c1572f528da269dedacc56fd269f8a4b3ac7630eb
-  data.tar.gz: d50217306f64e883988ad9184adde4d02e274fc8262560aeab3b8a0c9eecd573bae847006c0a3383222020ab3d9281ba96d1720ea9019f17c3491bf21fcf08e1
+  metadata.gz: f16927ab59ea1e9e89fe51203d3a0ca0f14331956fdcce4ca1e957642579129ba143651d066d9bb763f85fb4b2f3e5afd93a657a9266550b8435e0159478c659
+  data.tar.gz: 7f4dfebecd72b184a84258ca90f48f978c603eb01739d3217f8cad8b24d0ab7991f2d8a79dc53834e7e67002b0da74219cf68e3aee0ca60c344febb1e3e722e0

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.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/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 ""

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