ui_guardrails 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a78df8763f35470a40ab6c8c8dcc6daf1351d35e733772a33afde5d1b7af1a54
-  data.tar.gz: a1f8aa3366f9a350673c55ff4200716e6c37db2f777592b914ada3236f67682e
+  metadata.gz: da306d3808653d6bd263a867d1ba0aaf159a2c3a515a6e1284276cc69e34cc8c
+  data.tar.gz: c895cef92d7cc7acf0be8ddf97079a51a9753aa434223fc3ce3e5fe28125cc39
 SHA512:
-  metadata.gz: f16927ab59ea1e9e89fe51203d3a0ca0f14331956fdcce4ca1e957642579129ba143651d066d9bb763f85fb4b2f3e5afd93a657a9266550b8435e0159478c659
-  data.tar.gz: 7f4dfebecd72b184a84258ca90f48f978c603eb01739d3217f8cad8b24d0ab7991f2d8a79dc53834e7e67002b0da74219cf68e3aee0ca60c344febb1e3e722e0
+  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.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.
+**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.
 
 ---
 
@@ -219,6 +219,7 @@ The editor is `$GUARDRAILS_EDITOR`, then `$VISUAL`, then `$EDITOR`. VS Code-fami
 |---|---|
 | `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`. |
@@ -242,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_deep.rb

@@ -5,6 +5,7 @@ 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'
@@ -39,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))
@@ -47,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

data/lib/guardrails/audit.rb

@@ -7,6 +7,7 @@ require "yaml"
 require_relative "erb_parser"
 require_relative "report/style"
 require_relative "report/finding"
+require_relative "report/severity"
 
 module Guardrails
   class Audit
@@ -71,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
@@ -82,7 +85,12 @@ 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

data/lib/guardrails/report/html/template.html.erb

@@ -107,7 +107,7 @@
 </header>
 
 <main class="wrap">
-  <p class="meta"><%= pluralize(findings.length, "finding") %> across <%= pluralize(@categories.length, "category", "categories") %> · <span class="mono"><%= h @root %></span> · generated <%= h @generated_at.strftime("%Y-%m-%d %H:%M") %> by ui_guardrails <%= h Guardrails::VERSION %></p>
+  <p class="meta"><%= pluralize(findings.length, "finding") %> across <%= pluralize(@categories.length, "category", "categories") %> · <span class="mono"><%= h @root %></span> · generated <%= h @generated_at.strftime("%Y-%m-%d %H:%M") %> by ui_guardrails <%= h Guardrails::VERSION %><% if muted_note %> · <strong><%= h muted_note %></strong><% end %></p>
 
   <%- if @categories.empty? -%>
   <p class="clean">✓ No findings — the audit is clean.</p>

data/lib/guardrails/report/html.rb

@@ -34,7 +34,10 @@ module Guardrails
 
       SEVERITY_LABEL = { error: "Error", warning: "Warning", suggestion: "Suggestion" }.freeze
 
-      def initialize(categories:, root:, generated_at: Time.now)
+      # `muted` — severities the run was told not to check (SEVERITY=).
+      # Stated on the page so a filtered report can't pass for a full one.
+      def initialize(categories:, root:, generated_at: Time.now, muted: [])
+        @muted = muted
         @categories = categories
         @root = Pathname(root).expand_path
         @generated_at = generated_at
@@ -74,6 +77,12 @@ module Guardrails
         end
       end
 
+      def muted_note
+        return nil if @muted.empty?
+
+        "#{@muted.map { |s| "#{SEVERITY_LABEL[s].downcase}s" }.join(' and ')} not checked"
+      end
+
       def severity_count(severity)
         findings.count { |f| f.severity == severity }
       end

data/lib/guardrails/report/run.rb

@@ -13,6 +13,7 @@ require_relative "../a11y_deep"
 require_relative "../visual_diff"
 require_relative "summary"
 require_relative "finding"
+require_relative "severity"
 require_relative "../configuration"
 
 module Guardrails
@@ -33,11 +34,13 @@ module Guardrails
       TRUTHY = %w[1 true yes].freeze
 
       attr_reader :violations, :stimulus, :similarity, :view_components,
-                  :a11y, :patterns, :classitis, :a11y_deep, :visual_diff
+                  :a11y, :patterns, :classitis, :a11y_deep, :visual_diff, :min_severity
 
       # Builds a Run from the documented env vars (SUGGEST, APPLY,
       # AXE_JSON, VISUAL_DIFF*, SIMILARITY_THRESHOLD, PATTERN_*,
-      # CLASSITIS_*).
+      # CLASSITIS_*, SEVERITY). Raises ArgumentError on a SEVERITY it
+      # doesn't recognize — a typo there would otherwise silently
+      # un-gate a CI check.
       def self.from_env(root:, style: nil, env: ENV)
         # Visual-diff is opt-in (baselines need deliberate setup). Enabled
         # when either VISUAL_DIFF=1 is set in the env (sidecar mode) or
@@ -66,7 +69,8 @@ module Guardrails
         new(root: root, style: style,
             suggest: truthy?(env["SUGGEST"]), apply: truthy?(env["APPLY"]),
             axe_json: env["AXE_JSON"], visual_diff: visual_diff_on,
-            similarity: similarity, patterns: patterns, classitis: classitis)
+            similarity: similarity, patterns: patterns, classitis: classitis,
+            min_severity: Severity.parse(env["SEVERITY"]))
       end
 
       def self.truthy?(value)
@@ -80,7 +84,9 @@ module Guardrails
       # uncolored output (what JSON mode wants — the body is discarded).
       def initialize(root:, style: nil, suggest: false, apply: false,
                      axe_json: nil, visual_diff: false,
-                     similarity: {}, patterns: {}, classitis: {})
+                     similarity: {}, patterns: {}, classitis: {},
+                     min_severity: Severity::DEFAULT)
+        @min_severity = min_severity
         @root = Pathname(root)
         @style = style
         @suggest = suggest
@@ -94,20 +100,35 @@ module Guardrails
       end
 
       def call
-        @violations = detect(Audit.new(**common, suggest: @suggest, apply: @apply, format: :text))
-        @stimulus = detect(StimulusAudit.new(**common))
-        @similarity = detect(PartialSimilarity.new(**common, **@similarity_opts))
-        @view_components = detect(ViewComponentAudit.new(**common))
+        # Detectors whose findings all sit below the severity floor
+        # aren't run at all — SEVERITY=error skips the two slowest
+        # (similarity, patterns) rather than computing results to
+        # discard. Audit and A11yDeep emit mixed severities, so they
+        # always run and filter internally.
+        @violations = detect(Audit.new(**common, suggest: @suggest, apply: @apply, format: :text,
+                                                 min_severity: @min_severity))
+        @stimulus = wanted?(:warning) ? detect(StimulusAudit.new(**common)) : StimulusAudit::Result.new(orphaned: [], dead: [])
+        @similarity = wanted?(:suggestion) ? detect(PartialSimilarity.new(**common, **@similarity_opts)) : []
+        @view_components = if wanted?(:warning) then detect(ViewComponentAudit.new(**common))
+                           else ViewComponentAudit::Result.new(missing_previews: [], orphan_slots: [])
+                           end
         @a11y = detect(A11yAudit.new(**common))
-        @patterns = detect(CrossCodebasePatterns.new(**common, **@pattern_opts))
-        @classitis = detect(ClassItis.new(**common, **@classitis_opts))
-        @a11y_deep_runner = @axe_json ? A11yDeep.new(input: @axe_json, output: @sink, style: @style) : nil
+        @patterns = wanted?(:suggestion) ? detect(CrossCodebasePatterns.new(**common, **@pattern_opts)) : []
+        @classitis = wanted?(:suggestion) ? detect(ClassItis.new(**common, **@classitis_opts)) : []
+        @a11y_deep_runner = if @axe_json
+                              A11yDeep.new(input: @axe_json, output: @sink, style: @style, min_severity: @min_severity)
+                            end
         @a11y_deep = @a11y_deep_runner ? detect(@a11y_deep_runner) : []
         @visual_diff_runner = @visual_diff_on ? VisualDiff.new(**common) : nil
         @visual_diff = @visual_diff_runner ? detect(@visual_diff_runner) : []
         self
       end
 
+      # Severities this run didn't look at (empty by default).
+      def muted_severities
+        Severity.muted(@min_severity)
+      end
+
       # Every finding as detector-agnostic data (see Report::Finding),
       # grouped by category and ordered errors → warnings →
       # suggestions, biggest category first — the same order the
@@ -208,6 +229,10 @@ module Guardrails
         result
       end
 
+      def wanted?(severity)
+        Severity.include?(severity, @min_severity)
+      end
+
       def common
         { root: @root, output: @sink, style: @style }
       end

data/lib/guardrails/report/severity.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "summary"
+
+module Guardrails
+  module Report
+    # The severity floor behind SEVERITY=: "only tell me about findings
+    # at least this serious". `:suggestion` (the default) is everything;
+    # `:warning` mutes suggestions; `:error` mutes warnings too.
+    module Severity
+      ORDER = Summary::SEVERITY_ORDER
+      DEFAULT = :suggestion
+
+      NAMES = {
+        "error" => :error, "errors" => :error,
+        "warning" => :warning, "warnings" => :warning,
+        "suggestion" => :suggestion, "suggestions" => :suggestion, "suggest" => :suggestion, "all" => :suggestion
+      }.freeze
+
+      module_function
+
+      # nil / blank is "not set", not an error — same blank-env
+      # tolerance as the VISUAL_DIFF_* vars.
+      def parse(value)
+        text = value.to_s.strip.downcase
+        return DEFAULT if text.empty?
+
+        NAMES.fetch(text) do
+          raise ArgumentError, "SEVERITY=#{value} isn't a severity. Use error, warning, or suggestion."
+        end
+      end
+
+      def include?(severity, floor)
+        ORDER.index(severity) <= ORDER.index(floor)
+      end
+
+      # The severities a floor hides, most serious first.
+      def muted(floor)
+        ORDER.reject { |severity| include?(severity, floor) }
+      end
+    end
+  end
+end

data/lib/guardrails/tui.rb

@@ -90,7 +90,7 @@ module Guardrails
     end
 
     def open_web_report
-      path = Report::Html.new(categories: @run.categories, root: @root).write
+      path = Report::Html.new(categories: @run.categories, root: @root, muted: @run.muted_severities).write
       opener = Editor.opener(path.to_s)
       opened = opener && system(*opener, out: File::NULL, err: File::NULL)
       @state.notice = "#{opened ? 'Opened' : 'Wrote'} #{path.relative_path_from(Pathname(@root).expand_path)}"

data/lib/guardrails/version.rb

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

data/lib/tasks/guardrails.rake

@@ -9,7 +9,7 @@ namespace :guardrails do
     Guardrails::Init.new(root: root, force: force).run
   end
 
-  desc "Audit views and components for UI drift (SUGGEST=1, APPLY=1, FORMAT=json|html)"
+  desc "Audit views and components for UI drift (SUGGEST=1, APPLY=1, FORMAT=json|html, SEVERITY=error|warning)"
   task :audit do
     require "guardrails/report/run"
     require "guardrails/report/style"
@@ -22,7 +22,11 @@ namespace :guardrails do
     # (see Report::Run). JSON and HTML modes discard the report body,
     # so they run unstyled.
     report_style = format == :text ? Guardrails::Report::Style.new(io: $stdout) : nil
-    run = Guardrails::Report::Run.from_env(root: root, style: report_style).call
+    run = begin
+      Guardrails::Report::Run.from_env(root: root, style: report_style).call
+    rescue ArgumentError => e
+      abort e.message
+    end
 
     if format == :json
       require "json"
@@ -32,7 +36,7 @@ namespace :guardrails do
       # CI artifact. OUTPUT= overrides the default tmp/ location.
       require "guardrails/report/html"
       output = ENV["OUTPUT"].to_s.strip
-      path = Guardrails::Report::Html.new(categories: run.categories, root: root)
+      path = Guardrails::Report::Html.new(categories: run.categories, root: root, muted: run.muted_severities)
                                      .write(output.empty? ? Guardrails::Report::Html::DEFAULT_PATH : output)
       $stdout.puts "Guardrails audit: #{run.findings.length} findings → #{path}"
     else
@@ -45,6 +49,13 @@ namespace :guardrails do
       summary.render
       $stdout.write run.body
       summary.render(recap: true)
+      # A filtered run that prints "no violations found" must not read
+      # as a clean bill of health.
+      unless run.muted_severities.empty?
+        muted = run.muted_severities.map { |s| "#{s}s" }.join(" and ")
+        $stdout.puts ""
+        $stdout.puts report_style.colorize("SEVERITY=#{run.min_severity} — #{muted} were not checked.", :dim)
+      end
     end
 
     exit 1 if run.failing?
@@ -63,7 +74,7 @@ namespace :guardrails do
     runner = -> { Guardrails::Report::Run.from_env(root: root, env: env).call }
     begin
       Guardrails::TUI.new(runner: runner, root: root).start
-    rescue Guardrails::TUI::NotInteractive => e
+    rescue Guardrails::TUI::NotInteractive, ArgumentError => e
       abort e.message
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ui_guardrails
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - John Athayde
@@ -109,6 +109,7 @@ files:
 - lib/guardrails/report/html.rb
 - lib/guardrails/report/html/template.html.erb
 - lib/guardrails/report/run.rb
+- lib/guardrails/report/severity.rb
 - lib/guardrails/report/style.rb
 - lib/guardrails/report/summary.rb
 - lib/guardrails/stimulus_audit.rb