ui_guardrails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 200bad03eb94e193c93e5965c52743f8bc9c4d232003149d482cf8b4bc72d77c
-  data.tar.gz: cd365fa2244f58b1c294f317119be08e03da868f050cc1aae268d6ff524237a0
+  metadata.gz: 792f503cf353ceaa71b9e45e39a4c3f9ae9255b40f4ecf361a207048074857e8
+  data.tar.gz: ff563d0927467149ddc42011500457c7c637db11fc9770566db64e3a0a4427e2
 SHA512:
-  metadata.gz: 1c23e135b24dcbf76c3d98983ee339a22800fdf4a40fbc4b13dcbebaecfbf8b7160a5aa4472f01440fb20bac8bf6585ada295207189aae11f8809f894ef70003
-  data.tar.gz: 56572b2788586158520982bf9d3d0f18e4920136aab255dec5ef88b08d7c7ef0347ba653e71564f0b439c2c94db53c7eee30a241f9a5c516fc72722900769074
+  metadata.gz: 3eb224a5d378469571b727813ac68adcacd95576c63bade906a29e4119f9c0b28e972dbbbcf3710acbb6d7647684b14250a28b61c0a52ca65fd2c96e4f435d3a
+  data.tar.gz: 62c132501303b6cc6bcd5ffa8bf566955fc82cf6c4ed30ea3d1ad678ff4270841a57b636daf635035a38681a2e8797ab1e0018ceb62685a144aa840dc3aed238

data/lib/guardrails/a11y_audit.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require "set"
 require_relative "erb_parser"
+require_relative "report/style"
 
 module Guardrails
   # Static a11y checks that don't require a browser — element-level rules
@@ -23,9 +24,17 @@ module Guardrails
 
     NON_INTERACTIVE_INPUT_TYPES = %w[hidden submit button reset image].freeze
 
-    def initialize(root:, output: $stdout)
+    SUGGESTION_FOR_RULE = {
+      "image_alt" => "add an alt attribute (or alt=\"\" if decorative)",
+      "button_name" => "add text, aria-label, or aria-labelledby",
+      "link_name" => "add link text, aria-label, or aria-labelledby",
+      "input_label" => "add aria-label, aria-labelledby, or a matching <label for=...>"
+    }.freeze
+
+    def initialize(root:, output: $stdout, style: nil)
       @root = Pathname(root)
       @output = output
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -237,12 +246,19 @@ module Guardrails
     def print_report(findings)
       return if findings.empty?
 
-      @output.puts ""
       noun = findings.length == 1 ? "issue" : "issues"
-      @output.puts "Guardrails a11y: #{findings.length} static #{noun} found"
+      @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."
+
       findings.each do |f|
-        @output.puts "  [#{f.rule}] #{f.file}:#{f.line}:#{f.column}"
-        @output.puts "    #{f.snippet}"
+        @output.puts ""
+        @output.puts "  #{@style.severity(:error, "#{f.rule}: #{f.snippet.to_s[0, 60]}")}"
+        suggestion = SUGGESTION_FOR_RULE[f.rule.to_s]
+        @output.puts "    #{@style.suggestion(suggestion)}" if suggestion
+        @output.puts "    #{@style.location("#{f.file}:#{f.line}:#{f.column}")}"
       end
     end
   end

data/lib/guardrails/a11y_deep.rb

@@ -3,6 +3,7 @@
 require "json"
 require "pathname"
 require "set"
+require_relative "report/style"
 
 module Guardrails
   # Consumes axe-core JSON output and folds the findings into Guardrails'
@@ -37,10 +38,11 @@ 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)
+    def initialize(input:, output: $stdout, failing_impacts: DEFAULT_FAILING_IMPACTS, style: nil)
       @input = input
       @output = output
       @failing_impacts = Set.new(failing_impacts.map(&:to_s))
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -101,19 +103,38 @@ module Guardrails
       return if findings.empty?
 
       grouped = findings.group_by(&:url)
+      noun = findings.length == 1 ? "finding" : "findings"
+
       @output.puts ""
-      @output.puts "Guardrails a11y (deep): #{findings.length} finding#{'s' if findings.length != 1} from axe-core"
+      @output.puts @style.section_heading(
+        :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."
 
       grouped.each do |url, page_findings|
         @output.puts ""
-        @output.puts "  #{url || '(no url)'}"
+        @output.puts "  #{@style.location(url || '(no url)')}"
         page_findings.each do |f|
-          impact_label = f.impact ? "[#{f.impact}]" : "[unknown]"
-          selector = f.selector ? " (#{f.selector})" : ""
-          @output.puts "    #{impact_label} #{f.rule} — #{f.description}#{selector}"
-          @output.puts "      #{f.help_url}" if f.help_url
+          severity = impact_to_severity(f.impact)
+          impact_label = f.impact ? f.impact.to_s : "unknown"
+          selector_part = f.selector ? " (#{f.selector})" : ""
+          @output.puts "    #{@style.severity(severity, "[#{impact_label}] #{f.rule}: #{f.description}#{selector_part}")}"
+          @output.puts "      #{@style.suggestion("see #{f.help_url}")}" if f.help_url
         end
       end
     end
+
+    # Map axe-core's impact levels onto the report's three severities
+    # so they color-code consistently with static a11y findings.
+    def impact_to_severity(impact)
+      case impact.to_s
+      when "critical", "serious" then :error
+      when "moderate" then :warning
+      when "minor" then :suggestion
+      else :warning
+      end
+    end
   end
 end

data/lib/guardrails/audit.rb

@@ -5,6 +5,7 @@ require "set"
 require "stringio"
 require "yaml"
 require_relative "erb_parser"
+require_relative "report/style"
 
 module Guardrails
   class Audit
@@ -69,13 +70,14 @@ module Guardrails
       flood-color lighting-color stop-color
     ].freeze
 
-    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false)
+    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false, style: nil)
       @root = Pathname(root)
       @output = output
       @suggest = suggest
       @format = format
       @apply = apply
       @config = load_audit_config
+      @style = style
     end
 
     def run
@@ -445,18 +447,170 @@ module Guardrails
 
     def print_text(violations)
       if violations.empty?
-        @output.puts "Guardrails audit: no violations found."
+        @output.puts ""
+        @output.puts "#{style.colorize("✓", :green)} Guardrails audit: no violations found."
         return
       end
 
-      noun = violations.length == 1 ? "violation" : "violations"
-      @output.puts "Guardrails audit: #{violations.length} #{noun} found"
+      # Group by type so each rule gets its own section with framing
+      # intro + tagged findings + inline suggestion arrows. The order
+      # mirrors what users care about: hex literals + inline styles +
+      # arbitrary Tailwind (real violations) before helper_recommended
+      # (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.each do |type|
+        list = by_type[type] || []
+        next if list.empty?
+
+        print_violation_type(type, list)
+      end
+    end
+
+    SEVERITY_FOR_TYPE = {
+      inline_style: :warning,
+      raw_color: :error,
+      tailwind_arbitrary: :error,
+      helper_recommended: :warning,
+      image_alt: :error,
+      button_name: :error,
+      link_name: :error,
+      input_label: :error
+    }.freeze
+
+    FRAMING_FOR_TYPE = {
+      inline_style: "Inline style attributes bypass your design tokens. Extract these to a CSS class or component stylesheet that references defined tokens.",
+      raw_color: "Hex/rgb literals in color attributes bypass your design tokens. Run APPLY=1 to auto-fix where a token matches; SUGGEST=1 writes a markdown checklist.",
+      tailwind_arbitrary: "Arbitrary Tailwind values (bg-[#fa3] etc.) bypass your theme. Add the value to theme.colors / theme.fontSize and use the named utility, or APPLY=1 to auto-fix where a token matches.",
+      helper_recommended: "Literal <button>/<a> wrapping ERB output hides intent from static analysis and a11y tooling. Switch to tag.button / link_to / button_to so attributes flow through one place.",
+      image_alt: "Images need accessible alt text. Use alt=\"\" for purely decorative images.",
+      button_name: "Buttons need an accessible name — text content, aria-label, or aria-labelledby.",
+      link_name: "Links need an accessible name — text content, aria-label, or aria-labelledby.",
+      input_label: "Interactive inputs need a programmatic label — aria-label, aria-labelledby, or a matching <label for=...>."
+    }.freeze
+
+    AUTO_FIXABLE_TYPES = %i[raw_color tailwind_arbitrary].freeze
+
+    def print_violation_type(type, violations)
+      severity = SEVERITY_FOR_TYPE.fetch(type, :warning)
+      auto_fix_marker = AUTO_FIXABLE_TYPES.include?(type) ? ", auto-fix available" : ""
+
+      @output.puts ""
+      @output.puts style.section_heading(
+        severity,
+        "#{type} (#{violations.length} #{violations.length == 1 ? "finding" : "findings"}#{auto_fix_marker})"
+      )
+      framing = FRAMING_FOR_TYPE[type]
+      wrap_framing(framing).each { |line| @output.puts "  #{line}" } if framing
+
       violations.each do |v|
-        @output.puts "  [#{v.type}] #{v.file}:#{v.line}:#{v.column}"
-        @output.puts "    #{v.snippet}"
+        @output.puts ""
+        header = "#{type}: #{format_value(v)}"
+        @output.puts "  #{style.severity(severity, header)}"
+        suggestion = suggestion_for_violation(v)
+        @output.puts "    #{style.suggestion(suggestion)}" if suggestion
+        @output.puts "    #{style.location("#{v.file}:#{v.line}:#{v.column}")}"
+        @output.puts "    #{v.snippet}" if v.snippet
+      end
+    end
+
+    def format_value(violation)
+      case violation.type
+      when :raw_color, :tailwind_arbitrary
+        violation.value
+      when :inline_style
+        violation.value || "<inline style>"
+      else
+        violation.snippet.to_s[0, 60]
+      end
+    end
+
+    # Hard-wrap the framing-intro paragraph at ~72 chars so it doesn't
+    # run off the side of an 80-col terminal. Cheap word-wrap; nothing
+    # fancy needed for a 1-2 sentence paragraph.
+    def wrap_framing(text, width: 72)
+      lines = []
+      current = +""
+      text.split(/\s+/).each do |word|
+        if current.empty?
+          current << word
+        elsif current.length + 1 + word.length <= width
+          current << " " << word
+        else
+          lines << current
+          current = +word
+        end
+      end
+      lines << current unless current.empty?
+      lines
+    end
+
+    # Per-violation inline suggestion. For token-aware types
+    # (raw_color, tailwind_arbitrary), reuse load_tokens + TokenMatcher
+    # to surface exact matches inline. Anything more elaborate
+    # (near-match, replacement string, etc.) belongs in SUGGEST=1's
+    # markdown checklist.
+    def suggestion_for_violation(violation)
+      case violation.type
+      when :raw_color
+        matched_token_suggestion(violation, [:css_var])
+      when :tailwind_arbitrary
+        matched_token_suggestion(violation, [:tailwind]) ||
+          matched_token_suggestion(violation, [:css_var])
+      when :inline_style
+        "extract to a CSS class or component stylesheet"
+      when :helper_recommended
+        helper_recommended_suggestion(violation)
+      when :image_alt
+        "add an alt attribute (or alt=\"\" if decorative)"
+      when :button_name
+        "add text, aria-label, or aria-labelledby"
+      when :link_name
+        "add link text, aria-label, or aria-labelledby"
+      when :input_label
+        "add aria-label, aria-labelledby, or a matching <label for=...>"
+      end
+    end
+
+    def matched_token_suggestion(violation, allowed_syntaxes)
+      require_relative "token_matcher"
+      tokens = load_tokens.select { |t| allowed_syntaxes.include?(t.syntax) }
+      return nil if tokens.empty?
+
+      match = TokenMatcher.new(tokens).match(violation.value)
+      return nil unless match && match.kind == :exact
+
+      token = match.token
+      "replace with #{token_reference(token)} (exact match from #{token.file})"
+    end
+
+    def token_reference(token)
+      case token.syntax
+      when :css_var then "var(--#{token.name})"
+      when :scss_var then "$#{token.name}"
+      when :tailwind then token.name.to_s
+      else token.name.to_s
+      end
+    end
+
+    def helper_recommended_suggestion(violation)
+      tag = violation.snippet.to_s[/<(\w+)/, 1]
+      case tag
+      when "button" then "use tag.button(label, ...) or button_to(label, path)"
+      when "a" then "use link_to(label, path, ...)"
+      else "use the Rails helper for this element"
       end
     end
 
+    def style
+      @style ||= Report::Style.new(io: @output)
+    end
+
     def print_json(violations)
       require "json"
       payload = {

data/lib/guardrails/class_itis.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require_relative "erb_parser"
+require_relative "report/style"
 
 module Guardrails
   # Finds repeating "class soup" — the same long class list applied to
@@ -52,12 +53,14 @@ module Guardrails
     def initialize(root:, output: $stdout,
                    min_classes: DEFAULT_MIN_CLASSES,
                    min_occurrences: DEFAULT_MIN_OCCURRENCES,
-                   max_occurrences_shown: DEFAULT_MAX_OCCURRENCES_SHOWN)
+                   max_occurrences_shown: DEFAULT_MAX_OCCURRENCES_SHOWN,
+                   style: nil)
       @root = Pathname(root)
       @output = output
       @min_classes = min_classes
       @min_occurrences = min_occurrences
       @max_occurrences_shown = max_occurrences_shown
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -165,25 +168,49 @@ module Guardrails
 
       total_occurrences = clusters.sum(&:count)
       noun = clusters.length == 1 ? "cluster" : "clusters"
+
       @output.puts ""
-      @output.puts "Guardrails class-itis: #{clusters.length} repeating class #{noun} " \
-                   "(#{total_occurrences} occurrences; >= #{@min_classes} classes, >= #{@min_occurrences} occurrences)"
+      @output.puts @style.section_heading(
+        :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."
 
       clusters.each do |cluster|
         @output.puts ""
-        @output.puts "  <#{cluster.tag}> with #{cluster.class_count} classes, " \
-                     "#{cluster.count} occurrences:"
+        header = "<#{cluster.tag}> with #{cluster.class_count} classes, #{cluster.count} occurrences"
+        @output.puts "  #{@style.severity(:suggestion, header)}"
+        @output.puts "    #{@style.suggestion(suggestion_for(cluster))}"
         @output.puts "    class=#{format_classes(cluster.classes)}"
         cluster.occurrences.first(@max_occurrences_shown).each do |occ|
-          @output.puts "    #{occ.file}:#{occ.line}"
+          @output.puts "    #{@style.location("#{occ.file}:#{occ.line}")}"
         end
         if cluster.occurrences.length > @max_occurrences_shown
           remaining = cluster.occurrences.length - @max_occurrences_shown
-          @output.puts "    … and #{remaining} more"
+          @output.puts "    #{@style.location("… and #{remaining} more")}"
         end
       end
     end
 
+    # Suggestion shape varies by cluster size + count. Big class lists
+    # repeated many places want a component; smaller lists repeated
+    # often might just be a shared CSS rule.
+    def suggestion_for(cluster)
+      if cluster.class_count >= 8
+        "extract a #{component_name(cluster)} component — too many classes to keep inlined"
+      elsif cluster.count >= 6
+        "repeated this often, an @apply rule or shared class would dry it up"
+      else
+        "consider a shared component or @apply rule for this class list"
+      end
+    end
+
+    def component_name(cluster)
+      "#{cluster.tag.capitalize}Component"
+    end
+
     # Cap the displayed class string so a 30-utility soup doesn't blow
     # out the terminal. Fingerprint matching is on the full sorted list,
     # so display truncation is purely cosmetic.

data/lib/guardrails/cross_codebase_patterns.rb

@@ -4,6 +4,7 @@ require "pathname"
 require "digest"
 require "set"
 require_relative "erb_parser"
+require_relative "report/style"
 
 module Guardrails
   # Finds recurring structural patterns across the codebase — element
@@ -50,12 +51,14 @@ module Guardrails
     def initialize(root:, output: $stdout,
                    min_size: DEFAULT_MIN_SIZE,
                    min_occurrences: DEFAULT_MIN_OCCURRENCES,
-                   max_occurrences_shown: DEFAULT_MAX_OCCURRENCES_SHOWN)
+                   max_occurrences_shown: DEFAULT_MAX_OCCURRENCES_SHOWN,
+                   style: nil)
       @root = Pathname(root)
       @output = output
       @min_size = min_size
       @min_occurrences = min_occurrences
       @max_occurrences_shown = max_occurrences_shown
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -212,24 +215,52 @@ module Guardrails
       return if patterns.empty?
 
       total_occurrences = patterns.sum(&:count)
-      noun = patterns.length == 1 ? "shape" : "shapes"
+      noun = patterns.length == 1 ? "candidate" : "candidates"
+
       @output.puts ""
-      @output.puts "Guardrails patterns: #{patterns.length} recurring #{noun} " \
-                   "(#{total_occurrences} occurrences; >= #{@min_size} elements, >= #{@min_occurrences} occurrences)"
+      @output.puts @style.section_heading(
+        :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."
 
       patterns.each do |pattern|
         @output.puts ""
-        @output.puts "  Pattern (#{pattern.size} elements, #{pattern.count} occurrences): #{truncate_shape(pattern.shape)}"
+        header = "shape: #{truncate_shape(pattern.shape)} (#{pattern.size} elements, #{pattern.count} occurrences)"
+        @output.puts "  #{@style.severity(:suggestion, header)}"
+        @output.puts "    #{@style.suggestion(suggestion_for(pattern))}"
         pattern.occurrences.first(@max_occurrences_shown).each do |occ|
-          @output.puts "    #{occ.file}:#{occ.line}"
+          @output.puts "    #{@style.location("#{occ.file}:#{occ.line}")}"
         end
         if pattern.occurrences.length > @max_occurrences_shown
           remaining = pattern.occurrences.length - @max_occurrences_shown
-          @output.puts "    … and #{remaining} more"
+          @output.puts "    #{@style.location("… and #{remaining} more")}"
         end
       end
     end
 
+    # The suggestion line varies with shape signal: small repeats want
+    # a generic partial; large/very-repeating shapes nudge toward a
+    # named component. Specific enough to be actionable without
+    # pretending we know the user's design system.
+    def suggestion_for(pattern)
+      if pattern.count >= 6
+        "repeats often enough that a named component is likely the right shape"
+      elsif pattern.size >= 10
+        "consider extracting into a ViewComponent (large enough to earn one)"
+      else
+        "consider extracting into a shared partial (e.g. _#{partial_hint(pattern)}.html.erb)"
+      end
+    end
+
+    # Quick name hint based on the root tag of the shape. Pure UX,
+    # not a contract — users will pick their own name.
+    def partial_hint(pattern)
+      pattern.shape[/\A(\w+)/, 1] || "shared"
+    end
+
     # Cap shape display length so deep nested patterns don't blow out
     # the terminal. The fingerprint is what we match on; the shape is
     # just for human inspection.

data/lib/guardrails/partial_similarity.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require "set"
 require_relative "erb_parser"
+require_relative "report/style"
 
 module Guardrails
   class PartialSimilarity
@@ -20,11 +21,13 @@ module Guardrails
       "app/components/**/*_component.html.erb"
     ].freeze
 
-    def initialize(root:, output: $stdout, threshold: DEFAULT_THRESHOLD, ngram_size: DEFAULT_NGRAM_SIZE)
+    def initialize(root:, output: $stdout, threshold: DEFAULT_THRESHOLD,
+                   ngram_size: DEFAULT_NGRAM_SIZE, style: nil)
       @root = Pathname(root)
       @output = output
       @threshold = threshold
       @ngram_size = ngram_size
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -202,30 +205,55 @@ module Guardrails
 
       groups = group_findings(findings)
       total_files = groups.sum { |g| g[:files].size }
+      group_noun = groups.length == 1 ? "group" : "groups"
 
       @output.puts ""
-      group_noun = groups.length == 1 ? "group" : "groups"
-      @output.puts "Guardrails templates: #{groups.length} similar #{group_noun} (#{findings.length} pairs across #{total_files} files; >= #{@threshold} structural similarity)"
+      @output.puts @style.section_heading(
+        :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."
 
       groups.each do |group|
+        @output.puts ""
         if group[:files].length == 2
-          # Use the original Finding so we keep the tag-count suffix
-          # (e.g. "(12 / 14 tags)") that single-pair output has always
-          # included. The sorted file list is still authoritative for
-          # display order.
+          # Pair — keep the tag-count suffix; it's a useful signal of
+          # how big the templates are.
           pair = group[:sample_pair]
           file_a, file_b = group[:files]
-          @output.puts "  #{format('%.2f', group[:score_max])}  #{file_a} ↔ #{file_b}  (#{pair.tag_count_a} / #{pair.tag_count_b} tags)"
+          header = "#{format('%.2f', group[:score_max])} similar: #{file_a} ↔ #{file_b}"
+          @output.puts "  #{@style.severity(:suggestion, header)}"
+          @output.puts "    #{@style.suggestion(suggestion_for_pair(group))}"
+          @output.puts "    #{@style.location("#{pair.tag_count_a} / #{pair.tag_count_b} tags")}"
         else
           score_label = if group[:score_min] == group[:score_max]
                          format("%.2f", group[:score_max])
                        else
                          "#{format('%.2f', group[:score_min])}–#{format('%.2f', group[:score_max])}"
                        end
-          @output.puts "  Group of #{group[:files].length} templates (#{score_label}, #{group[:pair_count]} pairs):"
-          group[:files].each { |f| @output.puts "    #{f}" }
+          header = "group of #{group[:files].length} similar templates (#{score_label}, #{group[:pair_count]} pairs)"
+          @output.puts "  #{@style.severity(:suggestion, header)}"
+          @output.puts "    #{@style.suggestion(suggestion_for_group(group))}"
+          group[:files].each { |f| @output.puts "    #{@style.location(f)}" }
         end
       end
     end
+
+    def suggestion_for_pair(group)
+      score = group[:score_max]
+      if score >= 0.95
+        "near-identical — pick one and delete the other, or merge with locals"
+      elsif score >= 0.85
+        "very similar — parameterize one with locals and render it from the other"
+      else
+        "shared structure — consider a partial that both can render"
+      end
+    end
+
+    def suggestion_for_group(group)
+      "#{group[:files].length} templates sharing structure — strong candidate for one shared partial"
+    end
   end
 end

data/lib/guardrails/report/style.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Guardrails
+  module Report
+    # ANSI styling for the text audit report. Three rules:
+    #
+    #   1. Colors only when the output is a real terminal (TTY check).
+    #      Piping to a file or `tee` produces plain text.
+    #   2. `NO_COLOR=1` always wins. (https://no-color.org/ convention.)
+    #   3. Tests pass a non-TTY StringIO and get plain output by default
+    #      — no need to scrub ANSI sequences out of every expectation.
+    #
+    # Callers don't decide whether to colorize; they just call
+    # `Style.severity(:error, "raw_color")` and the style instance
+    # quietly emits ANSI or plain text based on those rules.
+    class Style
+      # Foreground codes, kept small. Bold + dim are modifiers, not
+      # colors — combined where we want emphasis without screaming.
+      ANSI = {
+        reset: "\e[0m",
+        bold: "\e[1m",
+        dim: "\e[2m",
+        red: "\e[31m",
+        yellow: "\e[33m",
+        green: "\e[32m",
+        cyan: "\e[36m",
+        blue: "\e[34m",
+        magenta: "\e[35m"
+      }.freeze
+
+      # Severity → (glyph, color) tuple. Glyphs are ASCII so they
+      # render in any terminal; we don't use emoji or box-drawing
+      # for the per-line tags. The summary box uses light box-drawing
+      # characters separately, with an ASCII fallback for terminals
+      # that mangle them (rare in 2026 but possible over SSH/PTY).
+      SEVERITY_FORMAT = {
+        error: { glyph: "x", color: :red, label: "ERROR" },
+        warning: { glyph: "!", color: :yellow, label: "WARNING" },
+        suggestion: { glyph: "i", color: :cyan, label: "SUGGEST" }
+      }.freeze
+
+      def initialize(io: $stdout, force: nil, no_color: nil)
+        @io = io
+        @force = force
+        @no_color = no_color
+      end
+
+      # True when we should emit ANSI sequences. Tests pass force:
+      # true/false to bypass auto-detection.
+      def color?
+        return @force unless @force.nil?
+        return false if no_color_env?
+
+        @io.respond_to?(:tty?) && @io.tty?
+      end
+
+      # Wrap text in an ANSI color code if `color?`, else return
+      # unchanged. `style` can be a single key or array (e.g.
+      # `[:bold, :red]`) — codes concatenate.
+      def colorize(text, style)
+        return text unless color?
+
+        codes = Array(style).map { |k| ANSI.fetch(k) }.join
+        "#{codes}#{text}#{ANSI[:reset]}"
+      end
+
+      # Tag a finding line with its severity. Output shape:
+      #
+      #   [error]   raw_color
+      #   [warning] helper_recommended
+      #   [suggest] pattern
+      #
+      # Padding aligns the brackets so columns line up across the
+      # report. Colorized form bolds the bracket+label.
+      def severity(level, category)
+        format = SEVERITY_FORMAT.fetch(level)
+        tag = "[#{format[:label].downcase}]".ljust(10)
+        "#{colorize(tag, [:bold, format[:color]])} #{category}"
+      end
+
+      # Section heading — bolded category label with a colored
+      # severity glyph in front. Used for the per-detector section
+      # intro: `x ERROR — raw_color (82 findings)`.
+      def section_heading(level, title)
+        format = SEVERITY_FORMAT.fetch(level)
+        glyph = colorize(format[:glyph], [:bold, format[:color]])
+        "#{glyph} #{colorize(format[:label], [:bold, format[:color]])} #{colorize("—", :dim)} #{colorize(title, :bold)}"
+      end
+
+      # File:line:col, in dim so it recedes when the content next to
+      # it is what matters. Returns plain text when colors are off.
+      def location(path)
+        colorize(path, :dim)
+      end
+
+      # Inline suggestion arrow. Always rendered the same way so the
+      # eye learns it: `→ <action>`. Cyan so it stands out from the
+      # finding line without competing with the severity color.
+      def suggestion(text)
+        "#{colorize("→", :cyan)} #{text}"
+      end
+
+      # Box-drawing characters for the top-of-report summary header.
+      # Falls back to ASCII (`+ - |`) when colors are off, since
+      # both behaviors track the same TTY/NO_COLOR signal.
+      def box_chars
+        if color?
+          { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│", t: "├", b: "┤" }
+        else
+          { tl: "+", tr: "+", bl: "+", br: "+", h: "-", v: "|", t: "+", b: "+" }
+        end
+      end
+
+      private
+
+      def no_color_env?
+        return @no_color unless @no_color.nil?
+
+        # Per https://no-color.org/: ANY value (even empty) disables color.
+        ENV.key?("NO_COLOR")
+      end
+    end
+  end
+end

data/lib/guardrails/report/summary.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "style"
+
+module Guardrails
+  module Report
+    # Top-of-report triage view. Builds a grouped severity rollup from
+    # the audit's per-detector counts, so the reader sees the shape of
+    # the findings before scrolling through the per-section detail.
+    #
+    # Each detector contributes one Entry. The rake task assembles the
+    # full list after running its sub-audits and hands it to Summary.
+    # Detector logic isn't aware of the report; Summary doesn't know
+    # about specific detectors. That decoupling matters when we add
+    # new detectors — they only need to register an Entry.
+    class Summary
+      # Severity order in the report: errors first (urgent), warnings
+      # next (probably-fix), suggestions last (consider).
+      SEVERITY_ORDER = %i[error warning suggestion].freeze
+
+      Entry = Struct.new(:category, :count, :severity, :unit, :action, :auto_fix,
+                         keyword_init: true) do
+        # `unit` is the noun shown after the count: "findings",
+        # "candidates", "groups", "clusters" — each detector picks
+        # what reads naturally. Defaults to "findings".
+        def unit
+          self[:unit] || "findings"
+        end
+      end
+
+      def initialize(entries:, output:, style: nil)
+        @entries = entries.reject { |e| e.count.zero? }
+        @output = output
+        @style = style || Style.new(io: output)
+      end
+
+      def render(recap: false)
+        return if @entries.empty?
+
+        @output.puts ""
+        @output.puts header_line(recap: recap)
+        @output.puts ""
+
+        SEVERITY_ORDER.each do |severity|
+          group = @entries.select { |e| e.severity == severity }
+          next if group.empty?
+
+          render_severity_group(severity, group)
+        end
+
+        @output.puts divider
+      end
+
+      private
+
+      def header_line(recap: false)
+        kind = recap ? "recap" : "audit"
+        title = "Guardrails #{kind}  —  #{total_findings} #{total_findings == 1 ? "finding" : "findings"}"
+        bar = "═" * 3
+        bar_plain = "=" * 3
+        # The divider character tracks the color setting so an
+        # ANSI-stripped pipe stays ASCII-only.
+        bar_used = @style.color? ? bar : bar_plain
+        rest = (@style.color? ? "═" : "=") * [70 - title.length - bar_used.length - 4, 4].max
+
+        "#{@style.colorize(bar_used + ' ', :bold)}" \
+          "#{@style.colorize(title, :bold)} " \
+          "#{@style.colorize(rest, :dim)}"
+      end
+
+      def render_severity_group(severity, entries)
+        total = entries.sum(&:count)
+        @output.puts "  #{@style.section_heading(severity, "#{entries.length} #{entries.length == 1 ? "category" : "categories"}, #{total} #{total == 1 ? "finding" : "findings"}")}"
+
+        entries.sort_by { |e| -e.count }.each do |entry|
+          render_entry(entry)
+        end
+        @output.puts ""
+      end
+
+      def render_entry(entry)
+        name = entry.category.ljust(32)
+        unit = entry.unit
+        unit = unit.sub(/s\z/, "") if entry.count == 1 && unit.end_with?("s")
+        count_str = "#{entry.count.to_s.rjust(4)} #{unit}".ljust(22)
+        flags = []
+        flags << @style.colorize("[auto-fix available]", :green) if entry.auto_fix
+        flags << @style.colorize(entry.action, :dim) if entry.action && !entry.auto_fix
+
+        line = "    #{name}#{count_str}#{flags.join(' ')}".rstrip
+        @output.puts line
+      end
+
+      def divider
+        char = @style.color? ? "═" : "="
+        @style.colorize(char * 75, :dim)
+      end
+
+      def total_findings
+        @entries.sum(&:count)
+      end
+    end
+  end
+end

data/lib/guardrails/stimulus_audit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
+require_relative "report/style"
 
 module Guardrails
   class StimulusAudit
@@ -36,9 +37,10 @@ module Guardrails
     RUBY_DATA_CONTROLLER_PATTERN =
       /data:?\s*(?:=>)?\s*\{[^}]*?controller:?\s*(?:=>)?\s*["']([^"']+)["']/m
 
-    def initialize(root:, output: $stdout)
+    def initialize(root:, output: $stdout, style: nil)
       @root = Pathname(root)
       @output = output
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -102,16 +104,38 @@ module Guardrails
     def print_report(result)
       return unless result.violations?
 
-      @output.puts ""
       unless result.orphaned.empty?
         noun = result.orphaned.length == 1 ? "controller" : "controllers"
-        @output.puts "Guardrails stimulus: #{result.orphaned.length} orphaned #{noun} (referenced in HTML, no JS file)"
-        result.orphaned.each { |name| @output.puts "  - #{name}" }
+        @output.puts ""
+        @output.puts @style.section_heading(
+          :warning,
+          "stimulus orphaned (#{result.orphaned.length} #{noun})"
+        )
+        @output.puts "  data-controller=\"…\" references a Stimulus controller, but no matching"
+        @output.puts "  *_controller.{js,ts} file exists. Either create the controller or"
+        @output.puts "  remove the reference."
+        result.orphaned.each do |name|
+          @output.puts ""
+          @output.puts "  #{@style.severity(:warning, "stimulus orphaned: #{name}")}"
+          @output.puts "    #{@style.suggestion("create app/javascript/controllers/#{name}_controller.js or remove the data-controller=\"#{name}\" reference")}"
+        end
       end
+
       unless result.dead.empty?
         noun = result.dead.length == 1 ? "controller" : "controllers"
-        @output.puts "Guardrails stimulus: #{result.dead.length} dead #{noun} (JS file, never referenced)"
-        result.dead.each { |name| @output.puts "  - #{name}" }
+        @output.puts ""
+        @output.puts @style.section_heading(
+          :warning,
+          "stimulus dead (#{result.dead.length} #{noun})"
+        )
+        @output.puts "  *_controller.{js,ts} file exists, but no view references it via"
+        @output.puts "  data-controller=\"…\". Either wire the controller into a template"
+        @output.puts "  or delete the file."
+        result.dead.each do |name|
+          @output.puts ""
+          @output.puts "  #{@style.severity(:warning, "stimulus dead: #{name}")}"
+          @output.puts "    #{@style.suggestion("reference it via data-controller=\"#{name}\" in a view, or delete the JS file")}"
+        end
       end
     end
   end

data/lib/guardrails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Guardrails
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/guardrails/view_component_audit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
+require_relative "report/style"
 
 module Guardrails
   class ViewComponentAudit
@@ -22,9 +23,10 @@ module Guardrails
 
     SLOT_PATTERN = /^\s*(renders_one|renders_many)\s+:([a-z_][\w]*)/
 
-    def initialize(root:, output: $stdout)
+    def initialize(root:, output: $stdout, style: nil)
       @root = Pathname(root)
       @output = output
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -132,17 +134,38 @@ module Guardrails
     def print_report(result)
       return unless result.violations?
 
-      @output.puts ""
       unless result.missing_previews.empty?
         noun = result.missing_previews.length == 1 ? "component" : "components"
-        @output.puts "Guardrails view_components: #{result.missing_previews.length} #{noun} without a preview"
-        result.missing_previews.each { |name| @output.puts "  - #{name}_component.rb (no #{name}_component_preview.rb)" }
+        @output.puts ""
+        @output.puts @style.section_heading(
+          :warning,
+          "view_components missing previews (#{result.missing_previews.length} #{noun})"
+        )
+        @output.puts "  Component classes without a corresponding Lookbook preview file."
+        @output.puts "  Add #{noun} previews so the component is discoverable + visually testable."
+        result.missing_previews.each do |name|
+          @output.puts ""
+          @output.puts "  #{@style.severity(:warning, "missing preview: #{name}_component")}"
+          @output.puts "    #{@style.suggestion("create test/components/previews/#{name}_component_preview.rb (or lookbook/previews/...)")}"
+        end
       end
+
       unless result.orphan_slots.empty?
-        noun = result.orphan_slots.length == 1 ? "slot declared" : "slots declared"
-        @output.puts "Guardrails view_components: #{result.orphan_slots.length} #{noun} but never referenced in template"
+        noun = result.orphan_slots.length == 1 ? "slot" : "slots"
+        @output.puts ""
+        @output.puts @style.section_heading(
+          :warning,
+          "view_components orphan slots (#{result.orphan_slots.length} #{noun})"
+        )
+        @output.puts "  renders_one / renders_many declared in the component class but never"
+        @output.puts "  referenced in the template. Either reference the slot or remove the"
+        @output.puts "  declaration."
         result.orphan_slots.each do |o|
-          @output.puts "  - #{o.component}_component: :#{o.slot} (#{o.slot_kind} at #{o.file}:#{o.line})"
+          @output.puts ""
+          header = "orphan slot: #{o.component}_component##{o.slot} (#{o.slot_kind})"
+          @output.puts "  #{@style.severity(:warning, header)}"
+          @output.puts "    #{@style.suggestion("reference :#{o.slot} in the template, or remove the #{o.slot_kind} declaration")}"
+          @output.puts "    #{@style.location("#{o.file}:#{o.line}")}"
         end
       end
     end

data/lib/guardrails/visual_diff.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require_relative "configuration"
+require_relative "report/style"
 
 module Guardrails
   # Consumes screenshot-diff tool output and folds findings into the
@@ -36,7 +37,7 @@ module Guardrails
     end
 
     def initialize(root:, output: $stdout,
-                   adapter: nil, threshold: nil)
+                   adapter: nil, threshold: nil, style: nil)
       @root = Pathname(root)
       @output = output
       cfg = Guardrails.configuration.visual_diff
@@ -46,6 +47,7 @@ module Guardrails
       # adapter = "snap_diff"; c.visual_diff.threshold = "0.1" }`.
       @adapter_name = coerce_adapter(adapter) || cfg.adapter
       @threshold = threshold.nil? ? cfg.threshold : Float(threshold)
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -96,19 +98,27 @@ module Guardrails
     def print_report(findings)
       return if findings.empty?
 
+      noun = findings.length == 1 ? "finding" : "findings"
       @output.puts ""
-      @output.puts "Guardrails visual diff: #{findings.length} finding#{'s' if findings.length != 1} " \
-                   "(adapter: #{@adapter_name}, threshold: #{@threshold})"
+      @output.puts @style.section_heading(
+        :error,
+        "visual diff (#{findings.length} #{noun}, adapter: #{@adapter_name}, threshold: #{@threshold})"
+      )
+      @output.puts "  Screenshot-diff tool flagged these scenarios. Review each diff image"
+      @output.puts "  and either accept the new baseline (commit the updated screenshot) or"
+      @output.puts "  fix the regression that caused the visual change."
 
       findings.each do |f|
         ratio_label = f.mismatch_ratio.nil? ? "[diff present]" : "[#{(f.mismatch_ratio * 100).round(2)}% mismatch]"
         suffix = f.viewport ? " (#{f.viewport})" : ""
+
         @output.puts ""
-        @output.puts "  #{ratio_label} #{f.scenario}#{suffix}"
-        @output.puts "    baseline: #{f.baseline_path}" if f.baseline_path
-        @output.puts "    diff:     #{f.diff_path}" if f.diff_path
-        @output.puts "    url:      #{f.url}" if f.url
-        @output.puts "    selector: #{f.selector}" if f.selector
+        @output.puts "  #{@style.severity(:error, "#{ratio_label} #{f.scenario}#{suffix}")}"
+        @output.puts "    #{@style.suggestion("compare baseline ↔ diff; accept the new baseline or fix the regression")}"
+        @output.puts "    #{@style.location("baseline: #{f.baseline_path}")}" if f.baseline_path
+        @output.puts "    #{@style.location("diff:     #{f.diff_path}")}" if f.diff_path
+        @output.puts "    #{@style.location("url:      #{f.url}")}" if f.url
+        @output.puts "    #{@style.location("selector: #{f.selector}")}" if f.selector
       end
     end
   end

data/lib/tasks/guardrails.rake

@@ -107,19 +107,106 @@ namespace :guardrails do
       }
       $stdout.puts JSON.pretty_generate(payload)
     else
+      # Run each sub-audit against an in-memory sink first so we can
+      # render the top-of-report summary before the per-category
+      # details (the summary needs every detector's count). Then
+      # write the sink + per-category sections out together.
+      #
+      # Important: detectors write into `sink` (StringIO) but make
+      # ANSI-color decisions against `$stdout`. If we let each
+      # detector instantiate its own Style bound to the sink, every
+      # color() call would be false (StringIO isn't a TTY) and the
+      # body of the report would print plain even on a real terminal,
+      # while the top/bottom summary printed straight to $stdout
+      # would still be colored. Pre-build one Style here and thread
+      # it through every detector so the whole report tracks the
+      # real terminal's TTY/NO_COLOR signal consistently.
+      require "guardrails/report/summary"
+      require "guardrails/report/style"
+      sink = StringIO.new
+      report_style = Guardrails::Report::Style.new(io: $stdout)
       violations = Guardrails::Audit.new(
-        root: root, suggest: suggest, apply: apply, format: :text
+        root: root, output: sink, suggest: suggest, apply: apply, format: :text,
+        style: report_style
       ).run
-      stimulus = Guardrails::StimulusAudit.new(root: root).run
+      stimulus = Guardrails::StimulusAudit.new(root: root, output: sink, style: report_style).run
+      similarity_opts[:output] = sink
+      similarity_opts[:style] = report_style
       similarity = Guardrails::PartialSimilarity.new(**similarity_opts).run
-      vc = Guardrails::ViewComponentAudit.new(root: root).run
-      a11y = Guardrails::A11yAudit.new(root: root).run
+      vc = Guardrails::ViewComponentAudit.new(root: root, output: sink, style: report_style).run
+      a11y = Guardrails::A11yAudit.new(root: root, output: sink, style: report_style).run
+      pattern_opts[:output] = sink
+      pattern_opts[:style] = report_style
       patterns = Guardrails::CrossCodebasePatterns.new(**pattern_opts).run
+      classitis_opts[:output] = sink
+      classitis_opts[:style] = report_style
       classitis = Guardrails::ClassItis.new(**classitis_opts).run
-      a11y_deep_runner = axe_json_path ? Guardrails::A11yDeep.new(input: axe_json_path) : nil
+      a11y_deep_runner = axe_json_path ? Guardrails::A11yDeep.new(input: axe_json_path, output: sink, style: report_style) : nil
       a11y_deep = a11y_deep_runner&.run || []
-      visual_diff_runner = visual_diff_on ? Guardrails::VisualDiff.new(root: root) : nil
+      visual_diff_runner = visual_diff_on ? Guardrails::VisualDiff.new(root: root, output: sink, style: report_style) : nil
       visual_diff = visual_diff_runner&.run || []
+
+      summary_entries = [
+        Guardrails::Report::Summary::Entry.new(
+          category: "raw_color", count: violations.count { |v| v.type == :raw_color },
+          severity: :error, auto_fix: true
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "tailwind_arbitrary", count: violations.count { |v| v.type == :tailwind_arbitrary },
+          severity: :error, auto_fix: true
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "inline_style", count: violations.count { |v| v.type == :inline_style },
+          severity: :warning
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "helper_recommended", count: violations.count { |v| v.type == :helper_recommended },
+          severity: :warning
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "a11y (static)", count: a11y.length, severity: :error
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "a11y (deep)", count: a11y_deep.length, severity: :error
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "stimulus orphaned", count: stimulus.orphaned.length, severity: :warning
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "stimulus dead", count: stimulus.dead.length, severity: :warning
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "missing previews", count: vc.missing_previews.length, severity: :warning
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "orphan slots", count: vc.orphan_slots.length, severity: :warning
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "visual diff", count: visual_diff.length, severity: :error
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "similar partials", count: similarity.length, severity: :suggestion,
+          unit: "pairs", action: "consider deduplicating"
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "cross-codebase patterns", count: patterns.length, severity: :suggestion,
+          unit: "candidates", action: "consider extracting partials"
+        ),
+        Guardrails::Report::Summary::Entry.new(
+          category: "class-itis", count: classitis.length, severity: :suggestion,
+          unit: "clusters", action: "consider extracting component / @apply"
+        )
+      ]
+
+      # Render the summary twice — once at the top so the reader
+      # knows what to expect, once at the bottom as a recap so they
+      # don't have to scroll back up after the per-detector dump.
+      # On a long output (Patchvault has 981 findings) the bottom
+      # recap is the load-bearing one.
+      summary = Guardrails::Report::Summary.new(entries: summary_entries, output: $stdout, style: report_style)
+      summary.render
+      $stdout.write sink.string
+      summary.render(recap: true)
     end
 
     # Deep a11y findings only fail the audit when their impact crosses

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ui_guardrails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - John Athayde
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -105,6 +105,8 @@ files:
 - lib/guardrails/lookbook/views/lookbook_panels/_guardrails.html.erb
 - lib/guardrails/partial_similarity.rb
 - lib/guardrails/railtie.rb
+- lib/guardrails/report/style.rb
+- lib/guardrails/report/summary.rb
 - lib/guardrails/stimulus_audit.rb
 - lib/guardrails/token_matcher.rb
 - lib/guardrails/tokens.rb