ui_guardrails 1.2.0 → 1.3.0

data/lib/tasks/guardrails.rake

@@ -9,214 +9,63 @@ 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)"
+  desc "Audit views and components for UI drift (SUGGEST=1, APPLY=1, FORMAT=json|html)"
   task :audit do
-    require "guardrails/audit"
-    require "guardrails/stimulus_audit"
-    require "guardrails/partial_similarity"
-    require "guardrails/view_component_audit"
-    require "guardrails/a11y_audit"
-    require "guardrails/cross_codebase_patterns"
-    require "guardrails/class_itis"
-    require "guardrails/a11y_deep"
-    require "guardrails/visual_diff"
-    require "stringio"
+    require "guardrails/report/run"
+    require "guardrails/report/style"
     root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
-    axe_json_path = ENV["AXE_JSON"]
 
-    # Visual-diff is opt-in (baselines need deliberate setup). Enabled
-    # when either VISUAL_DIFF=1 is set in the env (sidecar mode) or
-    # Guardrails.configuration.visual_diff.enabled was flipped on by a
-    # Rails initializer (embedded mode). Env overrides Configuration.
-    visual_diff_env = %w[1 true yes].include?(ENV["VISUAL_DIFF"]&.downcase)
-    visual_diff_on = visual_diff_env || Guardrails.configuration.visual_diff.enabled
-    # Strip + reject blank env values — an empty VISUAL_DIFF_DIR would
-    # otherwise be applied as snap_diff_dir = "" and glob from the repo
-    # root (potentially scanning the whole tree).
-    if (dir = ENV["VISUAL_DIFF_DIR"]) && !dir.strip.empty?
-      Guardrails.configure { |c| c.visual_diff.snap_diff_dir = dir.strip }
-    end
-    if (thr = ENV["VISUAL_DIFF_THRESHOLD"]) && !thr.strip.empty?
-      Guardrails.configure { |c| c.visual_diff.threshold = thr.strip }
-    end
-    suggest = %w[1 true yes].include?(ENV["SUGGEST"]&.downcase)
-    apply = %w[1 true yes].include?(ENV["APPLY"]&.downcase)
-    format = ENV["FORMAT"]&.downcase == "json" ? :json : :text
-    similarity_opts = { root: root }
-    similarity_opts[:threshold] = ENV["SIMILARITY_THRESHOLD"].to_f if ENV["SIMILARITY_THRESHOLD"]
-    pattern_opts = { root: root }
-    pattern_opts[:min_size] = ENV["PATTERN_MIN_SIZE"].to_i if ENV["PATTERN_MIN_SIZE"]
-    pattern_opts[:min_occurrences] = ENV["PATTERN_MIN_OCCURRENCES"].to_i if ENV["PATTERN_MIN_OCCURRENCES"]
-    classitis_opts = { root: root }
-    classitis_opts[:min_classes] = ENV["CLASSITIS_MIN_CLASSES"].to_i if ENV["CLASSITIS_MIN_CLASSES"]
-    classitis_opts[:min_occurrences] = ENV["CLASSITIS_MIN_OCCURRENCES"].to_i if ENV["CLASSITIS_MIN_OCCURRENCES"]
+    format = { "json" => :json, "html" => :html }.fetch(ENV["FORMAT"].to_s.downcase, :text)
 
-    if format == :json
-      # Run sub-audits silently so the only thing printed to stdout is one
-      # JSON document. Audit's own JSON output goes through @output, so we
-      # capture it instead of re-emitting.
-      sink = StringIO.new
-      violations = Guardrails::Audit.new(
-        root: root, output: sink, suggest: suggest, apply: apply, format: :text
-      ).run
-      stimulus = Guardrails::StimulusAudit.new(root: root, output: sink).run
-      similarity_opts[:output] = sink
-      similarity = Guardrails::PartialSimilarity.new(**similarity_opts).run
-      vc = Guardrails::ViewComponentAudit.new(root: root, output: sink).run
-      a11y = Guardrails::A11yAudit.new(root: root, output: sink).run
-      pattern_opts[:output] = sink
-      patterns = Guardrails::CrossCodebasePatterns.new(**pattern_opts).run
-      classitis_opts[:output] = sink
-      classitis = Guardrails::ClassItis.new(**classitis_opts).run
-      a11y_deep_runner = axe_json_path ? Guardrails::A11yDeep.new(input: axe_json_path, output: sink) : nil
-      a11y_deep = a11y_deep_runner&.run || []
-      visual_diff_runner = visual_diff_on ? Guardrails::VisualDiff.new(root: root, output: sink) : nil
-      visual_diff = visual_diff_runner&.run || []
+    # One Style bound to the real terminal, threaded through every
+    # detector so the whole report tracks the same TTY/NO_COLOR signal
+    # (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
 
+    if format == :json
       require "json"
-      payload = {
-        summary: {
-          violations: violations.length,
-          stimulus_orphaned: stimulus.orphaned.length,
-          stimulus_dead: stimulus.dead.length,
-          similar_partials: similarity.length,
-          missing_previews: vc.missing_previews.length,
-          orphan_slots: vc.orphan_slots.length,
-          a11y: a11y.length,
-          a11y_deep: a11y_deep.length,
-          patterns: patterns.length,
-          classitis: classitis.length,
-          visual_diff: visual_diff.length
-        },
-        violations: violations.map(&:to_h),
-        stimulus: { orphaned: stimulus.orphaned, dead: stimulus.dead },
-        similar_partials: similarity.map(&:to_h),
-        view_components: {
-          missing_previews: vc.missing_previews,
-          orphan_slots: vc.orphan_slots.map(&:to_h)
-        },
-        a11y: a11y.map(&:to_h),
-        a11y_deep: a11y_deep.map(&:to_h),
-        patterns: patterns.map { |p|
-          { fingerprint: p.fingerprint, shape: p.shape, size: p.size, count: p.count, occurrences: p.occurrences.map(&:to_h) }
-        },
-        classitis: classitis.map { |c|
-          { tag: c.tag, classes: c.classes, count: c.count, occurrences: c.occurrences.map(&:to_h) }
-        },
-        visual_diff: visual_diff.map(&:to_h)
-      }
-      $stdout.puts JSON.pretty_generate(payload)
+      $stdout.puts JSON.pretty_generate(run.to_h)
+    elsif format == :html
+      # One self-contained file — for a browser, a PR attachment, or a
+      # 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)
+                                     .write(output.empty? ? Guardrails::Report::Html::DEFAULT_PATH : output)
+      $stdout.puts "Guardrails audit: #{run.findings.length} findings → #{path}"
     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, output: sink, suggest: suggest, apply: apply, format: :text,
-        style: report_style
-      ).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, 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, output: sink, style: report_style) : nil
-      a11y_deep = a11y_deep_runner&.run || []
-      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 = Guardrails::Report::Summary.new(entries: run.summary_entries, output: $stdout, style: report_style)
       summary.render
-      $stdout.write sink.string
+      $stdout.write run.body
       summary.render(recap: true)
     end
 
-    # Deep a11y findings only fail the audit when their impact crosses
-    # the configured threshold (default: any impact fails, same as
-    # static a11y). When AXE_JSON is not set, a11y_deep is [] and the
-    # check is a no-op. Same logic for visual_diff: opt-in via
-    # VISUAL_DIFF=1 / Configuration; threshold gates failure.
-    a11y_deep_failing = a11y_deep_runner&.any_failing?(a11y_deep) || false
-    visual_diff_failing = visual_diff_runner&.any_failing?(visual_diff) || false
-    exit 1 if violations.any? || stimulus.violations? || similarity.any? || vc.violations? || a11y.any? || a11y_deep_failing || visual_diff_failing
+    exit 1 if run.failing?
+  end
+
+  desc "Browse audit findings interactively (same env options as guardrails:audit)"
+  task :tui do
+    require "guardrails/report/run"
+    require "guardrails/tui"
+    root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
+
+    # APPLY / SUGGEST are deliberately not honored here: browsing
+    # shouldn't rewrite views or drop markdown files, least of all
+    # again on every `r` re-run.
+    env = ENV.to_h.reject { |key, _| %w[APPLY SUGGEST].include?(key) }
+    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
+      abort e.message
+    end
   end
 
   desc "Parse axe-core JSON output and report deep a11y findings (AXE_JSON=path/to/axe.json)"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ui_guardrails
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - John Athayde
@@ -105,12 +105,21 @@ files:
 - lib/guardrails/lookbook/views/lookbook_panels/_guardrails.html.erb
 - lib/guardrails/partial_similarity.rb
 - lib/guardrails/railtie.rb
+- lib/guardrails/report/finding.rb
+- lib/guardrails/report/html.rb
+- lib/guardrails/report/html/template.html.erb
+- lib/guardrails/report/run.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
 - lib/guardrails/tokens/tailwind_config_parser.rb
+- lib/guardrails/tui.rb
+- lib/guardrails/tui/editor.rb
+- lib/guardrails/tui/keys.rb
+- lib/guardrails/tui/screen.rb
+- lib/guardrails/tui/state.rb
 - lib/guardrails/version.rb
 - lib/guardrails/view_component_audit.rb
 - lib/guardrails/visual_diff.rb