ui_guardrails 1.2.0 → 1.3.0

data/lib/guardrails/stimulus_audit.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require_relative "report/style"
+require_relative "report/finding"
 
 module Guardrails
   class StimulusAudit
@@ -56,16 +57,92 @@ module Guardrails
       result
     end
 
+    # Detector-agnostic view of `result` (see Report::Finding). Unlike
+    # the text report, findings carry locations: every view line that
+    # references an orphaned controller, and the JS file behind a dead
+    # one — the names alone don't tell you where to go.
+    def categories(result)
+      [
+        Report::Category.new(
+          name: "stimulus orphaned", severity: :warning, framing: ORPHANED_FRAMING.join(" "),
+          findings: result.orphaned.map { |name|
+            Report::Finding.new(
+              category: "stimulus orphaned", severity: :warning,
+              title: "stimulus orphaned: #{name}", suggestion: orphaned_suggestion(name),
+              locations: reference_locations(name)
+            )
+          }
+        ),
+        Report::Category.new(
+          name: "stimulus dead", severity: :warning, framing: DEAD_FRAMING.join(" "),
+          findings: result.dead.map { |name|
+            Report::Finding.new(
+              category: "stimulus dead", severity: :warning,
+              title: "stimulus dead: #{name}", suggestion: dead_suggestion(name),
+              locations: controller_locations(name)
+            )
+          }
+        )
+      ].reject { |c| c.findings.empty? }
+    end
+
     private
 
-    def collect_defined_controllers
-      paths = CONTROLLER_BASES.flat_map do |base|
+    ORPHANED_FRAMING = [
+      "data-controller=\"…\" references a Stimulus controller, but no matching",
+      "*_controller.{js,ts} file exists. Either create the controller or",
+      "remove the reference."
+    ].freeze
+
+    DEAD_FRAMING = [
+      "*_controller.{js,ts} file exists, but no view references it via",
+      "data-controller=\"…\". Either wire the controller into a template",
+      "or delete the file."
+    ].freeze
+
+    def orphaned_suggestion(name)
+      "create app/javascript/controllers/#{name}_controller.js or remove the data-controller=\"#{name}\" reference"
+    end
+
+    def dead_suggestion(name)
+      "reference it via data-controller=\"#{name}\" in a view, or delete the JS file"
+    end
+
+    def controller_paths
+      CONTROLLER_BASES.flat_map do |base|
         absolute = @root.join(base)
         next [] unless absolute.exist?
 
         Dir.glob(absolute.join(CONTROLLER_GLOB))
       end
-      paths.map { |path| controller_name_from_path(path) }.compact.uniq
+    end
+
+    def controller_locations(name)
+      controller_paths.select { |path| controller_name_from_path(path) == name }.sort.map do |path|
+        Report::Location.new(file: Pathname(path).relative_path_from(@root).to_s)
+      end
+    end
+
+    # Line-level lookup, only run for the (usually few) orphaned names
+    # — the main pass reads whole files and keeps names only. A
+    # reference the patterns only match across lines (a multi-line
+    # `data: { controller: ... }` hash) falls back to a file-level
+    # location rather than dropping out.
+    def reference_locations(name)
+      VIEW_PATTERNS.flat_map { |pattern| Dir.glob(@root.join(pattern)) }.sort.flat_map do |path|
+        content = File.read(path, encoding: Encoding::UTF_8)
+        next [] unless extract_names(content).include?(name)
+
+        relative = Pathname(path).relative_path_from(@root).to_s
+        lines = content.each_line.with_index(1).filter_map do |line, number|
+          Report::Location.new(file: relative, line: number) if extract_names(line).include?(name)
+        end
+        lines.empty? ? [Report::Location.new(file: relative)] : lines
+      end
+    end
+
+    def collect_defined_controllers
+      controller_paths.map { |path| controller_name_from_path(path) }.compact.uniq
     end
 
     # Derive a Stimulus controller identifier from a file path. We anchor
@@ -95,7 +172,10 @@ module Guardrails
     end
 
     def extract_referenced(file)
-      content = File.read(file, encoding: Encoding::UTF_8)
+      extract_names(File.read(file, encoding: Encoding::UTF_8))
+    end
+
+    def extract_names(content)
       [DATA_CONTROLLER_PATTERN, RUBY_DATA_CONTROLLER_PATTERN].flat_map do |pattern|
         content.scan(pattern).flat_map { |captures| captures[0].strip.split(/\s+/) }
       end
@@ -111,13 +191,11 @@ module Guardrails
           :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."
+        ORPHANED_FRAMING.each { |line| @output.puts "  #{line}" }
         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")}"
+          @output.puts "    #{@style.suggestion(orphaned_suggestion(name))}"
         end
       end
 
@@ -128,13 +206,11 @@ module Guardrails
           :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."
+        DEAD_FRAMING.each { |line| @output.puts "  #{line}" }
         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")}"
+          @output.puts "    #{@style.suggestion(dead_suggestion(name))}"
         end
       end
     end

data/lib/guardrails/tui/editor.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "rbconfig"
+
+module Guardrails
+  class TUI
+    # Builds the command that opens a Report::Location in the user's
+    # editor, at the right line when the editor has a way to say so.
+    #
+    # Editor choice: $GUARDRAILS_EDITOR, then $VISUAL, then $EDITOR;
+    # with none set, the OS opener (`open` / `xdg-open`), which loses
+    # the line number but still gets you to the file.
+    #
+    # Always returns an argv array (never a shell string) — paths come
+    # from the audited project's filenames, and they go nowhere near a
+    # shell.
+    module Editor
+      # file:line:col as one argument, behind a --goto flag.
+      GOTO_FLAG = %w[code code-insiders codium cursor windsurf].freeze
+      # file:line:col as one bare argument.
+      COLON_SUFFIX = %w[zed subl sublime_text hx].freeze
+      # +line before the file.
+      PLUS_LINE = %w[vi vim nvim nano emacs emacsclient micro kak].freeze
+      # --line N before the file.
+      LINE_FLAG = %w[rubymine idea mine].freeze
+
+      # `code --wait` is the usual $EDITOR value for git's benefit. Here
+      # it would freeze the TUI until the editor tab closes.
+      WAIT_FLAGS = %w[--wait -w -W].freeze
+      TERMINAL_EDITORS = (PLUS_LINE + %w[hx]).freeze
+
+      module_function
+
+      def command(location, root:, env: ENV, host_os: RbConfig::CONFIG["host_os"])
+        path = File.join(root.to_s, location.file)
+        editor = [env["GUARDRAILS_EDITOR"], env["VISUAL"], env["EDITOR"]].find { |v| v && !v.strip.empty? }
+        return opener(path, host_os) unless editor
+
+        parts = Shellwords.split(editor)
+        name = File.basename(parts.first)
+        parts -= WAIT_FLAGS unless TERMINAL_EDITORS.include?(name)
+        parts + target_args(name, path, location)
+      end
+
+      # Terminal editors need the TUI to get out of the way (leave the
+      # alternate screen, restore cooked mode) while they run.
+      def terminal?(command)
+        TERMINAL_EDITORS.include?(File.basename(command.first))
+      end
+
+      def opener(path, host_os = RbConfig::CONFIG["host_os"])
+        case host_os
+        when /darwin/ then ["open", path]
+        when /linux|bsd/ then ["xdg-open", path]
+        end
+      end
+
+      def target_args(name, path, location)
+        position = [path, location.line, location.line && location.column].compact.join(":")
+        if GOTO_FLAG.include?(name) then ["--goto", position]
+        elsif COLON_SUFFIX.include?(name) then [position]
+        elsif name == "mate" then location.line ? ["-l", location.line.to_s, path] : [path]
+        elsif PLUS_LINE.include?(name) then location.line ? ["+#{location.line}", path] : [path]
+        elsif LINE_FLAG.include?(name) then location.line ? ["--line", location.line.to_s, path] : [path]
+        else [path]
+        end
+      end
+    end
+  end
+end

data/lib/guardrails/tui/keys.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Guardrails
+  class TUI
+    # Turns raw terminal bytes into key events: symbols for named keys
+    # (:up, :enter, :escape, …), one-character strings for printable
+    # input.
+    #
+    # Reads with read_nonblock into its own buffer rather than
+    # getc/getch. Arrow keys arrive as a multi-byte escape sequence,
+    # and telling a lone Esc from the start of one needs a "is more
+    # coming?" check — which IO.select can't answer correctly if Ruby's
+    # buffered reader has already swallowed the rest of the sequence.
+    class Keys
+      ESCAPE_SEQUENCES = {
+        "[A" => :up, "[B" => :down, "[C" => :right, "[D" => :left,
+        "OA" => :up, "OB" => :down, "OC" => :right, "OD" => :left,
+        "[H" => :home, "[F" => :end, "OH" => :home, "OF" => :end,
+        "[1~" => :home, "[4~" => :end, "[7~" => :home, "[8~" => :end,
+        "[5~" => :page_up, "[6~" => :page_down, "[Z" => :tab
+      }.freeze
+
+      CONTROL = {
+        "\r" => :enter, "\n" => :enter, "\t" => :tab,
+        "\x7F" => :backspace, "\b" => :backspace, "\x03" => :ctrl_c
+      }.freeze
+
+      # How long a lone Esc waits for the rest of a sequence before
+      # it's taken at face value. Long enough for a slow SSH hop,
+      # short enough that Esc-to-go-back doesn't feel laggy.
+      ESCAPE_TIMEOUT = 0.05
+
+      def initialize(input)
+        @input = input
+        @buffer = +""
+      end
+
+      # Next key event; nil if `timeout` seconds pass with no input
+      # (the main loop uses the nil to notice terminal resizes); :eof
+      # once the input has hung up.
+      def next(timeout: nil)
+        fill(timeout) if @buffer.empty?
+        return :eof if @eof && @buffer.empty?
+        return nil if @buffer.empty?
+
+        fill(ESCAPE_TIMEOUT) if @buffer == "\e"
+        parse
+      end
+
+      private
+
+      def parse
+        return parse_escape if @buffer.start_with?("\e")
+
+        char = @buffer.slice!(0)
+        CONTROL.fetch(char) { char.match?(/[[:print:]]/) ? char : :unknown }
+      end
+
+      def parse_escape
+        rest = @buffer[1..]
+        sequence = ESCAPE_SEQUENCES.keys.find { |s| rest.start_with?(s) }
+        if sequence
+          @buffer.slice!(0, 1 + sequence.length)
+          ESCAPE_SEQUENCES[sequence]
+        elsif rest.empty?
+          @buffer.clear
+          :escape
+        else
+          # Unrecognized sequence (function key, mouse report, paste
+          # bracket): drop all of it rather than leaking its tail into
+          # the filter box as literal characters.
+          @buffer.clear
+          :unknown
+        end
+      end
+
+      def fill(timeout)
+        return unless ready?(timeout)
+
+        chunk = @input.read_nonblock(256, exception: false)
+        return if chunk == :wait_readable
+
+        # A selectable input that reads nil has hung up (terminal
+        # closed). Surface it so the main loop exits instead of spinning.
+        return @eof = true if chunk.nil?
+
+        @buffer << chunk.dup.force_encoding(Encoding::UTF_8).scrub("")
+      end
+
+      # StringIO (specs) has no file descriptor to select on; it's
+      # "ready" whenever it has bytes left.
+      def ready?(timeout)
+        return !@input.eof? unless @input.respond_to?(:fileno) && @input.fileno
+
+        !IO.select([@input], nil, nil, timeout).nil?
+      rescue NotImplementedError
+        !@input.eof?
+      end
+    end
+  end
+end

data/lib/guardrails/tui/screen.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+require_relative "../report/style"
+
+module Guardrails
+  class TUI
+    # Renders a State into exactly `height` terminal lines. Pure: takes
+    # state and dimensions, returns strings, touches no terminal — the
+    # main loop owns writing them out. (It does write `scroll` and
+    # `page_size` back onto the state, since both depend on how tall
+    # the list region turned out to be.)
+    #
+    # Layout, top to bottom:
+    #
+    #   title bar        totals by severity, grouping / filter
+    #   breadcrumb       where you are in the drill-down
+    #   ─────
+    #   [info block]     detail screens only: title, suggestion, framing
+    #   list             the rows State built for this frame
+    #   ─────
+    #   [preview]        findings + detail: source around the location
+    #   ─────
+    #   hints            keys for this screen, or the filter prompt
+    class Screen
+      ATTRIBUTES = { bold: 1, dim: 2, reverse: 7 }.freeze
+      COLORS = { red: 31, green: 32, yellow: 33, cyan: 36 }.freeze
+      SEVERITY = Report::Style::SEVERITY_FORMAT
+
+      MAX_SOURCE_BYTES = 2 * 1024 * 1024
+
+      HELP = [
+        ["↑ ↓  j k", "move"],
+        ["PgUp PgDn  space", "move a page"],
+        ["g  G", "jump to top / bottom"],
+        ["⏎  →  l", "open the highlighted row"],
+        ["esc  ←  h", "go back (at the top level: clear the filter)"],
+        ["tab", "switch grouping: by category ↔ by file"],
+        ["/", "filter by category, title, suggestion, or file"],
+        ["o", "open the highlighted location in your editor"],
+        ["w", "write the HTML report and open it in a browser"],
+        ["r", "re-run the audit"],
+        ["q", "quit"]
+      ].freeze
+
+      def initialize(state:, root:, width:, height:, color: true, sources: {})
+        @state = state
+        @root = root.to_s
+        @width = [width, 20].max
+        @height = [height, 8].max
+        @color = color
+        @sources = sources
+      end
+
+      def lines
+        body_height = @height - 5
+        body = @state.help? ? help_lines : body_lines(body_height)
+        body = body.first(body_height)
+        body += [""] * (body_height - body.length)
+
+        [title_bar, breadcrumb, rule, *body, rule(position_label), footer]
+      end
+
+      private
+
+      # ---- chrome -----------------------------------------------------
+
+      def title_bar
+        totals = @state.totals
+        left = [[" Guardrails", %i[bold]], ["  —  #{pluralize(totals.values.sum, 'finding')}   ", []]]
+        totals.each do |severity, count|
+          next if count.zero?
+
+          format = SEVERITY.fetch(severity)
+          left << ["#{format[:glyph]} #{count}  ", [:bold, format[:color]]]
+        end
+        right = @state.filter.empty? ? "by #{@state.grouping}" : "by #{@state.grouping} · filter: #{@state.filter}"
+        justify(left, [[right, %i[dim]]])
+      end
+
+      def breadcrumb
+        crumbs = @state.breadcrumb
+        segments = [[" ", []]]
+        crumbs.each_with_index do |crumb, i|
+          segments << [" ▸ ", %i[dim]] unless i.zero?
+          segments << [crumb, i == crumbs.length - 1 ? %i[bold] : %i[dim]]
+        end
+        compose(segments)
+      end
+
+      def rule(label = nil)
+        return paint("─" * @width, :dim) if label.nil? || label.empty?
+
+        tail = " #{label} ──"
+        paint("#{'─' * [@width - tail.length, 0].max}#{tail}", :dim)
+      end
+
+      def position_label
+        return nil if @state.help? || @state.frame.cursor.nil?
+
+        selectable = @state.rows.each_index.select { |i| @state.rows[i].selectable? }
+        "#{selectable.index(@state.frame.cursor).to_i + 1}/#{selectable.length}"
+      end
+
+      def footer
+        if @state.filtering?
+          compose([[" / ", %i[bold cyan]], [@state.filter, %i[bold]], ["█", %i[dim]],
+                   ["   ⏎ keep   esc clear", %i[dim]]])
+        elsif @state.notice
+          compose([[" #{@state.notice}", %i[yellow]]])
+        else
+          compose([[" #{hints}", %i[dim]]])
+        end
+      end
+
+      def hints
+        case @state.frame.kind
+        when :rollup, :files
+          other = @state.grouping == :category ? "by file" : "by category"
+          "↑↓ move  ⏎ open  tab #{other}  / filter  w web report  r re-run  ? help  q quit"
+        when :findings
+          "↑↓ move  ⏎ details  o editor  esc back  / filter  w web report  ? help  q quit"
+        when :detail
+          "↑↓ location  ⏎ open in editor  esc back  w web report  ? help  q quit"
+        end
+      end
+
+      # ---- body -------------------------------------------------------
+
+      def body_lines(height)
+        return empty_lines if @state.rows.empty? && @state.frame.kind != :detail
+
+        case @state.frame.kind
+        when :findings then list_with_preview(height, [])
+        when :detail then list_with_preview(height, info_block(height / 2))
+        else list_lines(height)
+        end
+      end
+
+      # Splits the body between the list and a source preview. The
+      # preview is worth having only when there's room for context
+      # around the line, so short terminals get the list alone.
+      def list_with_preview(height, info)
+        remaining = height - info.length
+        preview_height = remaining >= 12 ? [remaining / 2, 14].min : 0
+        list_height = remaining - preview_height - (preview_height.zero? ? 0 : 1)
+
+        out = info + list_lines(list_height)
+        out += [rule, *preview_lines(preview_height)] unless preview_height.zero?
+        out
+      end
+
+      def list_lines(height)
+        return [] if height <= 0
+
+        @state.page_size = [height - 1, 1].max
+        rows = @state.rows
+        scroll = scroll_for(rows, height)
+        visible = rows[scroll, height] || []
+        out = visible.each_with_index.map { |row, i| row_line(row, selected: scroll + i == @state.frame.cursor) }
+        out + [""] * (height - out.length)
+      end
+
+      def scroll_for(rows, height)
+        frame = @state.frame
+        cursor = frame.cursor || 0
+        scroll = frame.scroll || 0
+        scroll = cursor if cursor < scroll
+        scroll = cursor - height + 1 if cursor >= scroll + height
+        # Keep a leading header on screen when the cursor sits on the
+        # first item beneath it.
+        scroll = 0 if cursor < height && rows[0...cursor].none?(&:selectable?)
+        frame.scroll = scroll.clamp(0, [rows.length - height, 0].max)
+      end
+
+      def row_line(row, selected:)
+        return header_line(row) unless row.selectable?
+
+        format = row.severity && SEVERITY.fetch(row.severity)
+        marker = selected ? " › " : "   "
+        glyph = format ? "#{format[:glyph]} " : ""
+        right = [row.meta, row.flag && "[#{row.flag}]"].compact.reject(&:empty?).join("  ")
+
+        if selected
+          paint(plain_justified("#{marker}#{glyph}#{sanitize(row.label)}", right), :reverse, :bold)
+        else
+          justify(
+            [[marker, []], [glyph, [:bold, format && format[:color]]], [sanitize(row.label), []]],
+            [[right, %i[dim]]]
+          )
+        end
+      end
+
+      def header_line(row)
+        format = SEVERITY.fetch(row.severity)
+        compose([[" #{format[:glyph]} #{format[:label]}", [:bold, format[:color]]], [" — #{row.label}", %i[dim]]])
+      end
+
+      def empty_lines
+        message = if @state.filter.empty?
+                    ["✓ No findings — the audit is clean.", %i[green bold]]
+                  else
+                    ["No findings match “#{@state.filter}”. Esc clears the filter.", %i[dim]]
+                  end
+        ["", compose([["   ", []], message])]
+      end
+
+      def help_lines
+        ["", compose([["   Keys", %i[bold]]]), ""] +
+          HELP.map { |keys, what| compose([["   #{keys.ljust(20)}", %i[cyan]], [what, []]]) } +
+          ["", compose([["   Editor: $GUARDRAILS_EDITOR, then $VISUAL, then $EDITOR.  Any key closes this.", %i[dim]]])]
+      end
+
+      # ---- detail info block --------------------------------------------
+
+      def info_block(max_height)
+        finding = @state.selected_finding
+        format = SEVERITY.fetch(finding.severity)
+        out = wrap(sanitize(finding.title), @width - 14).first(3).each_with_index.map do |text, i|
+          tag = i.zero? ? "[#{format[:label].downcase}]".ljust(10) : " " * 10
+          compose([["  ", []], [tag, [:bold, format[:color]]], [" #{text}", %i[bold]]])
+        end
+        wrap(finding.suggestion.to_s, @width - 6).first(3).each_with_index do |text, i|
+          out << compose([[i.zero? ? "  → " : "    ", %i[cyan]], [sanitize(text), []]])
+        end
+        finding.details.each do |label, value|
+          wrap("#{label}: #{sanitize(value.to_s)}", @width - 4).first(3).each { |text| out << compose([["  #{text}", []]]) }
+        end
+        framing = @state.category_for(finding)&.framing
+        if framing
+          out << ""
+          wrap(framing, @width - 4).first(4).each { |text| out << compose([["  #{text}", %i[dim]]]) }
+        end
+        out << ""
+        out << compose([[locations_heading(finding), %i[bold]]])
+        out.last([max_height, 3].max)
+      end
+
+      def locations_heading(finding)
+        count = finding.locations.length
+        count.zero? ? "  No file locations for this finding." : "  #{pluralize(count, 'location')}"
+      end
+
+      # ---- source preview ---------------------------------------------
+
+      def preview_lines(height)
+        finding = @state.selected_finding
+        location = @state.selected_location
+        return [""] * height unless finding
+
+        out = []
+        if @state.frame.kind == :findings && finding.suggestion
+          wrap(finding.suggestion, @width - 6).first(2).each_with_index do |text, i|
+            out << compose([[i.zero? ? "  → " : "    ", %i[cyan]], [sanitize(text), []]])
+          end
+        end
+        out << compose([["  #{location || 'no file location'}", %i[dim]]])
+        out += source_lines(location, height - out.length) if location
+        out.first(height) + [""] * [height - out.length, 0].max
+      end
+
+      def source_lines(location, height)
+        return [] if height <= 0
+
+        source = read_source(location.file)
+        return [compose([["  (#{source})", %i[dim]]])] if source.is_a?(String)
+
+        target = location.line
+        first = target ? (target - (height / 2)).clamp(1, [source.length - height + 1, 1].max) : 1
+        gutter = (first + height).to_s.length
+        source[first - 1, height].to_a.each_with_index.map do |text, i|
+          number = first + i
+          hit = number == target
+          compose([
+            [hit ? "  ▸ " : "    ", %i[bold yellow]],
+            ["#{number.to_s.rjust(gutter)} │ ", hit ? %i[bold] : %i[dim]],
+            [sanitize(text), hit ? %i[bold] : []]
+          ])
+        end
+      end
+
+      # Array of lines, or a String explaining why there aren't any.
+      def read_source(file)
+        @sources[file] ||= begin
+          path = File.join(@root, file)
+          if !File.file?(path) then "file not found"
+          elsif File.size(path) > MAX_SOURCE_BYTES then "file too large to preview"
+          else
+            raw = File.binread(path)
+            raw.include?("\0") ? "binary file" : raw.force_encoding(Encoding::UTF_8).scrub("?").lines(chomp: true)
+          end
+        end
+      end
+
+      # ---- text plumbing ------------------------------------------------
+
+      # File contents and snippets end up on screen verbatim, so strip
+      # anything a terminal would act on rather than display — a view
+      # containing a literal escape sequence mustn't be able to move
+      # the cursor or recolor the UI.
+      def sanitize(text)
+        text.to_s.gsub("\t", "  ").gsub(/[[:cntrl:]]/, "")
+      end
+
+      def paint(text, *styles)
+        codes = styles.flatten.compact.filter_map { |s| ATTRIBUTES[s] || (@color ? COLORS[s] : nil) }
+        codes.empty? ? text : "\e[#{codes.join(';')}m#{text}\e[0m"
+      end
+
+      # Segments are [text, styles] pairs. Truncation happens on the
+      # plain text *before* painting, so an ANSI sequence is never cut
+      # in half and never counts toward the width.
+      def compose(segments, width = @width)
+        remaining = width
+        segments.filter_map do |text, styles|
+          next if remaining <= 0 || text.nil? || text.empty?
+
+          text = "#{text[0, [remaining - 1, 0].max]}…" if text.length > remaining
+          remaining -= text.length
+          paint(text, *styles)
+        end.join
+      end
+
+      # Left segments, then right segments flush against the right
+      # edge. The right side wins when space is tight (it's the count /
+      # location — the part you scan down), capped at 3/5 of the width.
+      def justify(left, right)
+        right_text = right.sum { |text, _| text.to_s.length }
+        right_width = [right_text, @width * 3 / 5].min
+        left_width = @width - right_width - 2
+        left_text = left.sum { |text, _| text.to_s.length }
+        gap = [@width - [left_text, left_width].min - right_width - 1, 1].max
+
+        "#{compose(left, left_width)}#{' ' * gap}#{compose(right, right_width)}"
+      end
+
+      def plain_justified(left, right)
+        right = truncate(right, @width * 3 / 5)
+        left = truncate(left, @width - right.length - 2)
+        "#{left}#{' ' * [@width - left.length - right.length - 1, 1].max}#{right} "
+      end
+
+      def truncate(text, limit)
+        text.length <= limit ? text : "#{text[0, [limit - 1, 0].max]}…"
+      end
+
+      def wrap(text, width)
+        width = [width, 10].max
+        text.to_s.split(/\s+/).each_with_object([+""]) do |word, lines|
+          if lines.last.empty? then lines.last << word
+          elsif lines.last.length + 1 + word.length <= width then lines.last << " " << word
+          else lines << +word
+          end
+        end.reject(&:empty?)
+      end
+
+      def pluralize(count, singular)
+        "#{count} #{count == 1 ? singular : "#{singular}s"}"
+      end
+    end
+  end
+end