ui_guardrails 1.2.0 → 1.3.0

data/lib/guardrails/tui/state.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require_relative "../report/finding"
+require_relative "../report/summary"
+
+module Guardrails
+  class TUI
+    # Everything the TUI knows that isn't pixels: which screen you're
+    # on, where the cursor is, the active filter and grouping. Keys go
+    # in through `handle`, which returns an action for the main loop
+    # when the key asks for something State can't do itself (open an
+    # editor, write the web report, re-run the audit, quit).
+    #
+    # No terminal I/O in here — that's what makes the navigation
+    # logic testable without a PTY.
+    class State
+      # One line in a list. `:header` rows group items and are skipped
+      # by the cursor; `:item` rows are selectable and carry a payload
+      # (category name, file path, Finding, or Location).
+      Row = Struct.new(:kind, :label, :meta, :severity, :payload, :flag, keyword_init: true) do
+        def selectable?
+          kind == :item
+        end
+      end
+
+      # A screen in the drill-down stack.
+      #   :rollup   — categories grouped by severity      (root, by category)
+      #   :files    — files ranked by finding count       (root, by file)
+      #   :findings — findings within one category / file
+      #   :detail   — one finding; rows are its locations
+      Frame = Struct.new(:kind, :title, :scope, :cursor, :scroll, keyword_init: true)
+
+      GROUPINGS = %i[category file].freeze
+      NO_FILE = "(no file)"
+
+      attr_reader :grouping, :filter, :mode
+      attr_accessor :notice, :page_size
+
+      def initialize(categories:)
+        @grouping = :category
+        @filter = +""
+        @mode = :normal
+        @help = false
+        @page_size = 10
+        replace(categories: categories)
+      end
+
+      # Swap in fresh audit results (initial load and re-run). Grouping
+      # and filter survive; the drill-down stack doesn't, since the
+      # finding you were looking at may no longer exist.
+      def replace(categories:)
+        @categories = categories
+        @rows_cache = {}.compare_by_identity
+        reset_frames
+      end
+
+      def frame
+        @frames.last
+      end
+
+      def depth
+        @frames.length
+      end
+
+      def help?
+        @help
+      end
+
+      def filtering?
+        @mode == :filter
+      end
+
+      def breadcrumb
+        @frames.map(&:title)
+      end
+
+      def rows
+        @rows_cache[frame] ||= build_rows(frame)
+      end
+
+      def selected_row
+        frame.cursor && rows[frame.cursor]
+      end
+
+      # The finding the preview pane should describe: the highlighted
+      # row on a findings list, or the finding a detail screen is for.
+      def selected_finding
+        case frame.kind
+        when :findings then selected_row&.payload
+        when :detail then frame.scope
+        end
+      end
+
+      def selected_location
+        case frame.kind
+        when :files then file_location(selected_row&.payload)
+        when :findings then selected_location_in_list
+        when :detail then selected_row&.payload
+        end
+      end
+
+      def category_for(finding)
+        @categories.find { |c| c.name == finding.category }
+      end
+
+      def visible_findings
+        all = @categories.flat_map(&:findings)
+        return all if @filter.empty?
+
+        needle = @filter.downcase
+        all.select { |f| haystack(f).include?(needle) }
+      end
+
+      def totals
+        counts = visible_findings.group_by(&:severity).transform_values(&:length)
+        Report::Summary::SEVERITY_ORDER.to_h { |s| [s, counts.fetch(s, 0)] }
+      end
+
+      def handle(key)
+        @notice = nil
+        if @help
+          @help = false
+          return nil
+        end
+        return handle_filter_key(key) if filtering?
+
+        handle_normal_key(key)
+      end
+
+      private
+
+      def handle_normal_key(key)
+        case key
+        when :up, "k" then move(-1)
+        when :down, "j" then move(1)
+        when :page_up then move(-@page_size)
+        when :page_down, " " then move(@page_size)
+        when :home, "g" then jump(:first)
+        when :end, "G" then jump(:last)
+        when :enter, :right, "l" then return drill_in
+        when :escape, :left, "h", :backspace then back
+        when :tab then toggle_grouping
+        when "/" then @mode = :filter
+        when "o" then return edit_action
+        when "w" then return [:web]
+        when "r" then return [:rerun]
+        when "?" then @help = true
+        when "q", :ctrl_c then return [:quit]
+        end
+        nil
+      end
+
+      def handle_filter_key(key)
+        case key
+        when :enter then @mode = :normal
+        when :escape then apply_filter(+"", done: true)
+        when :ctrl_c then return [:quit]
+        when :backspace
+          @filter.empty? ? @mode = :normal : apply_filter(@filter[0...-1])
+        when String then apply_filter(@filter + key)
+        end
+        nil
+      end
+
+      # Filtering changes what every screen contains, so the stack
+      # collapses to the root rather than leaving you inside a category
+      # that may have just filtered down to nothing.
+      def apply_filter(text, done: false)
+        @filter = text
+        @mode = :normal if done
+        @rows_cache = {}.compare_by_identity
+        reset_frames
+      end
+
+      def toggle_grouping
+        @grouping = GROUPINGS[(GROUPINGS.index(@grouping) + 1) % GROUPINGS.length]
+        reset_frames
+      end
+
+      def reset_frames
+        root = if @grouping == :category
+                 Frame.new(kind: :rollup, title: "All findings")
+               else
+                 Frame.new(kind: :files, title: "All files")
+               end
+        @frames = [root]
+        place_cursor(root)
+      end
+
+      def drill_in
+        row = selected_row
+        return nil unless row
+
+        case frame.kind
+        when :rollup then push(Frame.new(kind: :findings, title: row.payload, scope: [:category, row.payload]))
+        when :files then push(Frame.new(kind: :findings, title: row.payload, scope: [:file, row.payload]))
+        when :findings then push(Frame.new(kind: :detail, title: short(row.payload.title), scope: row.payload))
+        when :detail then return edit_action
+        end
+        nil
+      end
+
+      def back
+        if @frames.length > 1
+          @rows_cache.delete(@frames.pop)
+        elsif !@filter.empty?
+          apply_filter(+"")
+        end
+      end
+
+      def push(new_frame)
+        @frames << new_frame
+        place_cursor(new_frame)
+      end
+
+      def edit_action
+        location = selected_location
+        if location
+          [:edit, location]
+        else
+          @notice = frame.kind == :rollup ? "Open a category first — o works on a file or finding." : "Nothing to open — no file location here."
+          nil
+        end
+      end
+
+      def file_location(file)
+        Report::Location.new(file: file) if file && file != NO_FILE
+      end
+
+      # On a file-scoped list, open the occurrence in *that* file, not
+      # whichever location the finding happens to list first.
+      def selected_location_in_list
+        finding = selected_row&.payload
+        return nil unless finding
+
+        kind, value = frame.scope
+        (kind == :file && finding.locations.find { |l| l.file == value }) || finding.location
+      end
+
+      def place_cursor(target)
+        list = @rows_cache[target] ||= build_rows(target)
+        target.cursor = list.index(&:selectable?)
+        target.scroll = 0
+      end
+
+      def move(delta)
+        return unless frame.cursor
+
+        selectable = rows.each_index.select { |i| rows[i].selectable? }
+        position = selectable.index(frame.cursor) || 0
+        frame.cursor = selectable[(position + delta).clamp(0, selectable.length - 1)]
+      end
+
+      def jump(edge)
+        selectable = rows.each_index.select { |i| rows[i].selectable? }
+        frame.cursor = selectable.public_send(edge) unless selectable.empty?
+      end
+
+      def build_rows(target)
+        case target.kind
+        when :rollup then rollup_rows
+        when :files then file_rows
+        when :findings then finding_rows(target.scope)
+        when :detail then location_rows(target.scope)
+        end
+      end
+
+      def rollup_rows
+        by_category = visible_findings.group_by(&:category)
+        visible = @categories.select { |c| by_category.key?(c.name) }
+
+        Report::Summary::SEVERITY_ORDER.flat_map do |severity|
+          group = visible.select { |c| c.severity == severity }
+          next [] if group.empty?
+
+          total = group.sum { |c| by_category[c.name].length }
+          header = Row.new(kind: :header, severity: severity,
+                           label: "#{pluralize(group.length, 'category', 'categories')}, #{pluralize(total, 'finding')}")
+          items = group.sort_by { |c| -by_category[c.name].length }.map do |c|
+            Row.new(kind: :item, label: c.name, severity: severity, payload: c.name,
+                    meta: pluralize(by_category[c.name].length, "finding"),
+                    flag: c.auto_fix ? "auto-fix" : nil)
+          end
+          [header, *items]
+        end
+      end
+
+      # A finding spanning several files counts once in each of them —
+      # from a file's point of view, it has that problem.
+      def file_rows
+        by_file = Hash.new { |h, k| h[k] = [] }
+        visible_findings.each do |finding|
+          files = finding.files
+          (files.empty? ? [NO_FILE] : files).each { |file| by_file[file] << finding }
+        end
+
+        by_file.sort_by { |file, list| [-list.length, file] }.map do |file, list|
+          Row.new(kind: :item, label: file, payload: file, severity: worst_severity(list),
+                  meta: pluralize(list.length, "finding"))
+        end
+      end
+
+      def finding_rows(scope)
+        kind, value = scope
+        list = visible_findings.select do |f|
+          if kind == :category then f.category == value
+          elsif value == NO_FILE then f.files.empty?
+          else f.files.include?(value)
+          end
+        end
+
+        list.map do |finding|
+          Row.new(kind: :item, label: finding.title, severity: finding.severity, payload: finding,
+                  meta: kind == :file ? file_scoped_meta(finding, value) : location_meta(finding),
+                  # Within a category the rollup row already said so.
+                  flag: kind == :file && finding.auto_fix ? "auto-fix" : nil)
+        end
+      end
+
+      def location_rows(finding)
+        finding.locations.map do |location|
+          Row.new(kind: :item, label: location.to_s, payload: location, severity: finding.severity)
+        end
+      end
+
+      def location_meta(finding)
+        case finding.locations.length
+        when 0 then ""
+        when 1 then finding.location.to_s
+        else "#{finding.locations.length} locations"
+        end
+      end
+
+      def file_scoped_meta(finding, file)
+        lines = finding.locations.select { |l| l.file == file }.map(&:line).compact
+        lines.empty? ? finding.category : "#{finding.category} · line #{lines.first(3).join(', ')}#{lines.length > 3 ? '…' : ''}"
+      end
+
+      def worst_severity(findings)
+        Report::Summary::SEVERITY_ORDER.find { |s| findings.any? { |f| f.severity == s } }
+      end
+
+      def haystack(finding)
+        [finding.category, finding.title, finding.suggestion, *finding.files].compact.join("\n").downcase
+      end
+
+      def pluralize(count, singular, plural = "#{singular}s")
+        "#{count} #{count == 1 ? singular : plural}"
+      end
+
+      def short(text, limit = 40)
+        text.length <= limit ? text : "#{text[0, limit - 1]}…"
+      end
+    end
+  end
+end

data/lib/guardrails/tui.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "io/console"
+require_relative "../guardrails"
+require_relative "report/style"
+require_relative "report/html"
+require_relative "tui/state"
+require_relative "tui/screen"
+require_relative "tui/keys"
+require_relative "tui/editor"
+
+module Guardrails
+  # Interactive browser for an audit run: a severity roll-up you can
+  # drill into (category → finding → location), regroup by file,
+  # filter, and jump from into your editor or the HTML report.
+  #
+  # This class owns the terminal and nothing else — raw mode, the
+  # alternate screen, the read-key/redraw loop, and the side effects
+  # a key can ask for. Navigation lives in TUI::State, drawing in
+  # TUI::Screen, key decoding in TUI::Keys; each is testable without
+  # a terminal, which this file is not.
+  #
+  # Built on io/console alone. A list with drill-down doesn't need a
+  # widget toolkit, and the gem's dependency list stays at two.
+  class TUI
+    class NotInteractive < Guardrails::Error; end
+
+    ENTER_SCREEN = "\e[?1049h\e[?25l"  # alternate screen, hide cursor
+    LEAVE_SCREEN = "\e[?25h\e[?1049l"
+    RESIZE_POLL = 0.25
+
+    # `runner` is a callable returning a finished Report::Run. It's a
+    # callable rather than a Run so `r` can re-run the audit with the
+    # same options the task was started with.
+    def initialize(runner:, root:, input: $stdin, output: $stdout, env: ENV)
+      @runner = runner
+      @root = root
+      @input = input
+      @output = output
+      @env = env
+      @sources = {}
+    end
+
+    def start
+      unless @input.respond_to?(:tty?) && @input.tty? && @output.tty?
+        raise NotInteractive, "guardrails:tui needs an interactive terminal. " \
+                              "Use guardrails:audit (or FORMAT=json / FORMAT=html) when piping or in CI."
+      end
+
+      @output.puts "Running Guardrails audit…"
+      @run = @runner.call
+      @state = State.new(categories: @run.categories)
+      @keys = Keys.new(@input)
+      with_terminal { event_loop }
+    end
+
+    private
+
+    def event_loop
+      draw
+      loop do
+        key = @keys.next(timeout: RESIZE_POLL)
+        if key.nil?
+          draw if resized?
+          next
+        end
+        break if key == :eof || perform(@state.handle(key)) == :quit
+
+        draw
+      end
+    end
+
+    def perform(action)
+      kind, payload = action
+      case kind
+      when :quit then :quit
+      when :edit then open_editor(payload)
+      when :web then open_web_report
+      when :rerun then rerun
+      end
+    end
+
+    def open_editor(location)
+      command = Editor.command(location, root: @root, env: @env)
+      return @state.notice = "No editor found — set $EDITOR (or $GUARDRAILS_EDITOR)." unless command
+
+      ok = Editor.terminal?(command) ? suspended { system(*command) } : system(*command, out: File::NULL, err: File::NULL)
+      @state.notice = ok ? "Opened #{location}" : "Couldn't run #{command.first} — check $EDITOR."
+      @sources.clear # the file may have just been edited
+    end
+
+    def open_web_report
+      path = Report::Html.new(categories: @run.categories, root: @root).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)}"
+    rescue SystemCallError => e
+      @state.notice = "Couldn't write the report: #{e.message}"
+    end
+
+    def rerun
+      @state.notice = "Running audit…"
+      draw
+      @run = @runner.call
+      @sources.clear
+      @state.replace(categories: @run.categories)
+      @state.notice = "Audit re-run."
+    end
+
+    # ---- terminal ---------------------------------------------------
+
+    def draw
+      rows, columns = size
+      @drawn_size = [rows, columns]
+      lines = Screen.new(state: @state, root: @root, width: columns, height: rows,
+                         color: Report::Style.new(io: @output).color?, sources: @sources).lines
+      # \e[K after each line clears leftovers from a longer previous
+      # frame; \r\n because raw mode doesn't translate newlines.
+      @output.write("\e[H#{lines.map { |line| "#{line}\e[K" }.join("\r\n")}\e[J")
+      @output.flush
+    end
+
+    def size
+      rows, columns = @output.winsize
+      rows.to_i.positive? && columns.to_i.positive? ? [rows, columns] : [24, 80]
+    rescue SystemCallError, NotImplementedError
+      [24, 80]
+    end
+
+    def resized?
+      size != @drawn_size
+    end
+
+    def with_terminal
+      @input.raw do
+        @output.write(ENTER_SCREEN)
+        yield
+      ensure
+        @output.write(LEAVE_SCREEN)
+        @output.flush
+      end
+    end
+
+    # Hand the terminal to a child process (a terminal editor), then
+    # take it back.
+    def suspended
+      @output.write(LEAVE_SCREEN)
+      @output.flush
+      @input.cooked { yield }
+    ensure
+      @output.write(ENTER_SCREEN)
+    end
+  end
+end

data/lib/guardrails/version.rb

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

data/lib/guardrails/view_component_audit.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   class ViewComponentAudit
@@ -68,8 +69,60 @@ module Guardrails
       orphans
     end
 
+    # Detector-agnostic view of `result` (see Report::Finding). Missing
+    # previews point at the component class file so there's somewhere
+    # to jump to.
+    def categories(result)
+      [
+        Report::Category.new(
+          name: "missing previews", severity: :warning,
+          framing: missing_previews_framing(result.missing_previews.length).join(" "),
+          findings: result.missing_previews.map { |name|
+            Report::Finding.new(
+              category: "missing previews", severity: :warning,
+              title: "missing preview: #{name}_component", suggestion: missing_preview_suggestion(name),
+              locations: [Report::Location.new(file: "#{COMPONENT_DIR}/#{name}_component.rb")]
+            )
+          }
+        ),
+        Report::Category.new(
+          name: "orphan slots", severity: :warning, framing: ORPHAN_SLOTS_FRAMING.join(" "),
+          findings: result.orphan_slots.map { |o|
+            Report::Finding.new(
+              category: "orphan slots", severity: :warning,
+              title: "orphan slot: #{o.component}_component##{o.slot} (#{o.slot_kind})",
+              suggestion: orphan_slot_suggestion(o),
+              locations: [Report::Location.new(file: o.file, line: o.line)]
+            )
+          }
+        )
+      ].reject { |c| c.findings.empty? }
+    end
+
     private
 
+    ORPHAN_SLOTS_FRAMING = [
+      "renders_one / renders_many declared in the component class but never",
+      "referenced in the template. Either reference the slot or remove the",
+      "declaration."
+    ].freeze
+
+    def missing_previews_framing(count)
+      noun = count == 1 ? "component" : "components"
+      [
+        "Component classes without a corresponding Lookbook preview file.",
+        "Add #{noun} previews so the component is discoverable + visually testable."
+      ]
+    end
+
+    def missing_preview_suggestion(name)
+      "create test/components/previews/#{name}_component_preview.rb (or lookbook/previews/...)"
+    end
+
+    def orphan_slot_suggestion(slot)
+      "reference :#{slot.slot} in the template, or remove the #{slot.slot_kind} declaration"
+    end
+
     def component_files
       base = @root.join(COMPONENT_DIR)
       return [] unless base.exist?
@@ -141,12 +194,11 @@ module Guardrails
           :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."
+        missing_previews_framing(result.missing_previews.length).each { |line| @output.puts "  #{line}" }
         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/...)")}"
+          @output.puts "    #{@style.suggestion(missing_preview_suggestion(name))}"
         end
       end
 
@@ -157,14 +209,12 @@ module Guardrails
           :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."
+        ORPHAN_SLOTS_FRAMING.each { |line| @output.puts "  #{line}" }
         result.orphan_slots.each do |o|
           @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.suggestion(orphan_slot_suggestion(o))}"
           @output.puts "    #{@style.location("#{o.file}:#{o.line}")}"
         end
       end

data/lib/guardrails/visual_diff.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require_relative "configuration"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   # Consumes screenshot-diff tool output and folds findings into the
@@ -68,8 +69,40 @@ module Guardrails
       adapter.collect
     end
 
+    # Detector-agnostic view of `findings` (see Report::Finding). The
+    # diff image is the thing to open, so it leads the locations.
+    def categories(findings)
+      return [] if findings.empty?
+
+      [Report::Category.new(
+        name: "visual diff", severity: :error, framing: FRAMING.join(" "),
+        findings: findings.map { |f|
+          Report::Finding.new(
+            category: "visual diff", severity: :error,
+            title: "#{ratio_label(f)} #{f.scenario}#{f.viewport ? " (#{f.viewport})" : ""}",
+            suggestion: SUGGESTION,
+            locations: [f.diff_path, f.baseline_path].compact.map { |path| Report::Location.new(file: path) },
+            details: [["baseline", f.baseline_path], ["diff", f.diff_path], ["url", f.url], ["selector", f.selector]]
+                     .reject { |_, v| v.nil? }
+          )
+        }
+      )]
+    end
+
     private
 
+    FRAMING = [
+      "Screenshot-diff tool flagged these scenarios. Review each diff image",
+      "and either accept the new baseline (commit the updated screenshot) or",
+      "fix the regression that caused the visual change."
+    ].freeze
+
+    SUGGESTION = "compare baseline ↔ diff; accept the new baseline or fix the regression"
+
+    def ratio_label(finding)
+      finding.mismatch_ratio.nil? ? "[diff present]" : "[#{(finding.mismatch_ratio * 100).round(2)}% mismatch]"
+    end
+
     def adapter
       case @adapter_name
       when :snap_diff
@@ -104,17 +137,14 @@ module Guardrails
         :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."
+      FRAMING.each { |line| @output.puts "  #{line}" }
 
       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 "  #{@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.severity(:error, "#{ratio_label(f)} #{f.scenario}#{suffix}")}"
+        @output.puts "    #{@style.suggestion(SUGGESTION)}"
         @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