rspec_telemetry 0.3.0

data/lib/rspec_telemetry/trace/viewer/document.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative "../../ndjson"
+
+module RSpecTelemetry
+  module Trace
+    module Viewer
+      # Incrementally folds an NDJSON trace into examples and their child events.
+      class Document
+        # The single source of truth for which statuses count as failures.
+        FAILED_STATUSES = %w[failed error].freeze
+
+        Action = Data.define(:seq, :verb, :label, :t, :source, :wall_ms, :status, :duration_ms, :exception) do
+          def failed? = FAILED_STATUSES.include?(status)
+        end
+
+        Event = Data.define(:seq, :op, :t, :action, :fields)
+
+        # Hidden from generic labels/details; the original fields remain on each event.
+        INFRA_FIELDS = %w[type seq op action wall_ms t timestamp monotonic_time pid thread_id].freeze
+
+        attr_reader(
+          :entries,
+          :version,
+          :level,
+          :metadata,
+          :wall_time,
+          :failed_action,
+          :end_wall_ms,
+          :example_count,
+          :failure_count,
+          :pending_count
+        )
+
+        def self.from_lines(lines)
+          lines.each_with_object(new) { |line, doc| doc.apply(line) }
+        end
+
+        def initialize
+          @entries = []
+          @actions_by_seq = {}
+          @action_by_example = {}
+          @current_action = nil
+          @seq = -1
+          @t0 = nil
+          @started = false
+          @ended = false
+          @status = nil
+        end
+
+        # Unknown future event types are kept as generic events instead of dropped.
+        def apply(line)
+          parsed = parse(line)
+          return self unless parsed.is_a?(Hash)
+
+          @started = true
+          set_origin(parsed)
+
+          case parsed["type"]
+          when nil
+            self
+          when "example.started"
+            open_action(parsed)
+          when "example.finished"
+            close_action(parsed)
+          when "factory_bot.run_factory"
+            record("factory", parsed)
+          when "suite.finished"
+            finish(parsed)
+          else
+            record(parsed["type"], parsed)
+          end
+
+          self
+        end
+
+        def events = @entries.grep(Event)
+
+        def actions = @entries.grep(Action)
+
+        def action(seq) = @actions_by_seq[seq]
+
+        def events_for(action_seq)
+          @entries.select { |entry| entry.is_a?(Event) && entry.action == action_seq }
+        end
+
+        def pending? = @started && !@ended
+
+        def status
+          return @status if @status
+          return "ok" if @ended
+
+          "pending"
+        end
+
+        private
+
+        def parse(line) = Ndjson.parse(line)
+
+        # Normalize each process-local monotonic clock to t=0 for display.
+        def set_origin(parsed)
+          @t0 ||= parsed["monotonic_time"]
+        end
+
+        def wall_ms_of(parsed)
+          mono = parsed["monotonic_time"]
+          return nil if mono.nil? || @t0.nil?
+
+          ((mono - @t0) * 1000.0).round(3)
+        end
+
+        def next_seq = (@seq += 1)
+
+        def open_action(parsed)
+          wall = wall_ms_of(parsed)
+          mark_wall(wall)
+          action = Action.new(
+            seq: next_seq,
+            verb: "example",
+            label: parsed["full_description"] || parsed["example_id"] || "(example)",
+            t: parsed["t"],
+            source: source_of(parsed),
+            wall_ms: wall,
+            status: nil,
+            duration_ms: nil,
+            exception: nil
+          )
+          @entries << action
+          @actions_by_seq[action.seq] = action
+          @action_by_example[parsed["example_id"]] = action.seq if parsed["example_id"]
+          @current_action = action.seq
+        end
+
+        # Data objects are immutable, so finishing an example replaces its entry.
+        def close_action(parsed)
+          mark_wall(wall_ms_of(parsed))
+          seq = @action_by_example[parsed["example_id"]]
+          old = seq && @actions_by_seq[seq]
+          return if old.nil?
+
+          updated = old.with(
+            status: parsed["status"],
+            duration_ms: parsed["duration_ms"],
+            exception: exception_of(parsed)
+          )
+          @actions_by_seq[seq] = updated
+          @failed_action = seq if updated.failed?
+          index = @entries.index(old)
+          @entries[index] = updated if index
+        end
+
+        def record(op, parsed)
+          wall = wall_ms_of(parsed)
+          mark_wall(wall)
+          owner = @action_by_example[parsed["example_id"]] || @current_action
+          event = Event.new(
+            seq: next_seq,
+            op: op,
+            t: parsed["t"],
+            action: owner,
+            fields: parsed.merge("wall_ms" => wall)
+          )
+          @entries << event
+        end
+
+        def finish(parsed)
+          @ended = true
+          @example_count = parsed["example_count"]
+          @failure_count = parsed["failure_count"]
+          @pending_count = parsed["pending_count"]
+          @status = parsed["failure_count"].to_i.positive? ? "failed" : "ok"
+          mark_wall(wall_ms_of(parsed))
+        end
+
+        def mark_wall(wall)
+          return if wall.nil?
+
+          @end_wall_ms = wall if @end_wall_ms.nil? || wall > @end_wall_ms
+        end
+
+        def source_of(parsed)
+          file = parsed["file_path"]
+          return nil if file.nil?
+
+          line = parsed["line_number"]
+          line ? "#{file}:#{line}" : file
+        end
+
+        def exception_of(parsed)
+          klass = parsed["exception_class"]
+          return nil if klass.nil?
+
+          {"class" => klass, "message" => parsed["exception_message"]}
+        end
+      end
+    end
+  end
+end

data/lib/rspec_telemetry/trace/viewer/follow_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RSpecTelemetry
+  module Trace
+    module Viewer
+      # Owns "follow mode": draining a live source into the Document, keeping the
+      # cursor parked at the tail, and advancing the pending spinner.
+      class FollowController
+        SPINNER = %w[| / - \\].freeze
+
+        def initialize(source:, active:)
+          @source = source
+          @active = active
+          @stick = active
+          @spin = 0
+        end
+
+        def active? = @active
+        def wants_tick? = @active
+        def spinner = SPINNER[@spin % SPINNER.length]
+
+        # Flip follow on/off; resume tail-sticking only when parked at the end.
+        def toggle(at_end:)
+          @active = !@active
+          @stick = @active && at_end
+          @active
+        end
+
+        # Re-evaluate sticking after the cursor moves (e.g. App#go_to).
+        def reset_stick(at_end:)
+          @stick = @active && at_end
+        end
+
+        # Advance the spinner and fold any new source lines into the document.
+        def drain(document)
+          return false unless @active
+
+          @spin += 1
+          lines = @source ? @source.drain : []
+          lines.each { |line| document.apply(line) }
+          !lines.empty?
+        end
+
+        # Keep the cursor parked at the tail while sticking.
+        def stick(list)
+          list.to_end if @stick
+        end
+      end
+    end
+  end
+end

data/lib/rspec_telemetry/trace/viewer/format.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RSpecTelemetry
+  module Trace
+    module Viewer
+      module Format
+        def self.ms(value)
+          return nil if value.nil?
+
+          value >= 1000 ? "#{(value / 1000.0).round(2)}s" : "#{value.round}ms"
+        end
+
+        # Inspect a value deterministically across Ruby versions (Ruby 3.4 changed
+        # Hash#inspect from `{"k"=>v}` to `{"k" => v}`). Recurses into Hashes.
+        def self.value(obj)
+          return "{#{obj.map { |key, val| "#{key.inspect} => #{value(val)}" }.join(", ")}}" if obj.is_a?(Hash)
+
+          obj.inspect
+        end
+      end
+    end
+  end
+end

data/lib/rspec_telemetry/trace/viewer/label.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "document"
+require_relative "format"
+
+module RSpecTelemetry
+  module Trace
+    module Viewer
+      module Label
+        Segment = Data.define(:text, :style)
+
+        def self.segments(entry)
+          return action_segments(entry) if entry.is_a?(Document::Action)
+
+          event_segments(entry)
+        end
+
+        def self.plain(entry) = segments(entry).map(&:text).join
+
+        def self.category(entry)
+          if entry.is_a?(Document::Action)
+            return entry.failed? ? :error : :action
+          end
+
+          case entry.op
+          when "factory"
+            entry.fields["depth"].to_i.positive? ? :dim : :plain
+          else
+            :plain
+          end
+        end
+
+        def self.action_segments(action)
+          tag = action.failed? ? " [#{action.status.upcase}]" : ""
+          style = action.failed? ? :error : :action
+          segments = [seg("EXAMPLE #{action.label}#{tag}", style)]
+          segments << seg("  at: #{action.source}", :dim) if action.source
+          segments
+        end
+
+        def self.event_segments(event)
+          case event.op
+          when "factory"
+            factory_segments(event.fields)
+          else
+            [seg("#{event.op.upcase} #{compact(extra(event.fields))}", :plain)]
+          end
+        end
+
+        def self.factory_segments(fields)
+          depth = fields["depth"].to_i
+          style = depth.positive? ? :dim : :plain
+          [seg("#{"  " * depth}FACTORY #{name(fields)}#{traits(fields["traits"])}  #{timing(fields)}", style)]
+        end
+
+        def self.name(fields) = "#{fields["factory"]}:#{fields["strategy"]}"
+
+        def self.timing(fields)
+          total = Format.ms(fields["duration_ms"])
+          self_ms = fields["self_duration_ms"]
+          return total.to_s unless self_ms && self_ms != fields["duration_ms"]
+
+          "#{total} (self #{Format.ms(self_ms)})"
+        end
+
+        def self.traits(list)
+          list.nil? || list.empty? ? "" : " [#{Array(list).join(",")}]"
+        end
+
+        def self.extra(fields)
+          fields.reject { |key, _| Document::INFRA_FIELDS.include?(key) }
+        end
+
+        def self.seg(text, style) = Segment.new(text: text, style: style)
+
+        def self.compact(value)
+          return "" if value.nil? || value.empty?
+
+          Format.value(value)
+        end
+      end
+    end
+  end
+end

data/lib/rspec_telemetry/trace/viewer/layout.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "tui_tui"
+
+module RSpecTelemetry
+  module Trace
+    module Viewer
+      # Pure geometry shared by rendering and mouse hit-testing.
+      module Layout
+        MIN_TWO_PANE = 60
+        GUTTER = 1
+        MIN_PANE_COLS = 12
+        MIN_SOURCE_ROWS = 3
+        MIN_BODY_ROWS = 4
+
+        Regions = Data.define(
+          :time,
+          :body,
+          :list,
+          :detail,
+          :divider,
+          :source,
+          :source_top,
+          :content,
+          :status
+        )
+
+        # Regions are nil when the terminal is too small or a feature is hidden.
+        def self.compute(size:, want_time_bar:, want_source:, split_ratio:, source_rows:)
+          return single(whole(size)) if size.rows < 2
+
+          body, status = whole(size).split_h(size.rows - 1)
+          time, body = carve_time_bar(body) if want_time_bar
+          content, body, source, source_top = carve_source(body, source_rows) if want_source
+          list, detail, divider = split_panes(body, split_ratio)
+
+          Regions.new(
+            time: time,
+            body: body,
+            list: list,
+            detail: detail,
+            divider: divider,
+            source: source,
+            source_top: source_top,
+            content: content,
+            status: status
+          )
+        end
+
+        def self.source_height(content, source_rows)
+          # Keep both source and main body usable while dragging.
+          lo = MIN_SOURCE_ROWS
+          hi = content.rows - MIN_BODY_ROWS
+          return nil if hi < lo
+
+          source_rows.clamp(lo, hi)
+        end
+
+        def self.single(body)
+          Regions.new(
+            time: nil,
+            body: body,
+            list: body,
+            detail: nil,
+            divider: nil,
+            source: nil,
+            source_top: nil,
+            content: nil,
+            status: nil
+          )
+        end
+
+        def self.carve_time_bar(body)
+          return [nil, body] if body.rows < 2
+
+          body.split_h(1)
+        end
+
+        def self.carve_source(body, source_rows)
+          return [nil, body, nil, nil] if body.rows < MIN_BODY_ROWS + MIN_SOURCE_ROWS + 1
+
+          height = source_height(body, source_rows)
+          return [nil, body, nil, nil] if height.nil?
+
+          top, source = body.split_h(body.rows - height)
+          [body, top, source, source.row]
+        end
+
+        def self.split_panes(body, ratio)
+          return [body, nil, nil] if body.cols < MIN_TWO_PANE
+
+          left, detail = body.split_ratio(ratio, min: MIN_PANE_COLS, gutter: GUTTER)
+          [left, detail, left.col + left.cols]
+        end
+
+        def self.whole(size) = TuiTui::Rect.new(row: 1, col: 1, rows: size.rows, cols: size.cols)
+      end
+    end
+  end
+end

data/lib/rspec_telemetry/trace/viewer/pane_resizer.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "layout"
+
+module RSpecTelemetry
+  module Trace
+    module Viewer
+      # Owns mouse drag state and reports plain clicks back as focus targets.
+      class PaneResizer
+        DEFAULT_SOURCE_ROWS = 10
+
+        attr_reader :split_ratio, :source_rows
+
+        def initialize(split_ratio: 0.5, source_rows: DEFAULT_SOURCE_ROWS)
+          @split_ratio = split_ratio
+          @source_rows = source_rows
+          @dragging = false
+        end
+
+        def handle(event, region)
+          case event.action
+          when :press
+            return press(event, region)
+          when :drag
+            drag(event, region)
+          when :release
+            @dragging = false
+          end
+
+          nil
+        end
+
+        private
+
+        def press(event, region)
+          if on_source_header?(event.row, region)
+            @dragging = :source
+            nil
+          elsif near_divider?(event.col, region)
+            @dragging = :divider
+            nil
+          else
+            focus_target(event.col, region)
+          end
+        end
+
+        def drag(event, region)
+          case @dragging
+          when :divider
+            drag_divider(event.col, region)
+          when :source
+            drag_source(event.row, region)
+          end
+        end
+
+        def near_divider?(col, region)
+          !region.divider.nil? && (col - region.divider).abs <= 1
+        end
+
+        def drag_divider(col, region)
+          body = region.body
+          return unless region.divider
+
+          left_cols = (col - body.col).clamp(
+            Layout::MIN_PANE_COLS,
+            body.cols - Layout::MIN_PANE_COLS - Layout::GUTTER
+          )
+          @split_ratio = left_cols.to_f / body.cols
+        end
+
+        def on_source_header?(row, region)
+          !region.source_top.nil? && row == region.source_top
+        end
+
+        def drag_source(row, region)
+          content = region.content
+          return unless content
+
+          bottom = content.row + content.rows - 1
+          @source_rows = (bottom - row + 1).clamp(
+            Layout::MIN_SOURCE_ROWS,
+            content.rows - Layout::MIN_BODY_ROWS
+          )
+        end
+
+        def focus_target(col, region)
+          return :timeline if in_rect?(region.list, col)
+          return :detail if in_rect?(region.detail, col)
+
+          nil
+        end
+
+        def in_rect?(rect, col)
+          !rect.nil? && col >= rect.col && col < rect.col + rect.cols
+        end
+      end
+    end
+  end
+end

data/lib/rspec_telemetry/trace/viewer/report_pane.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "theme"
+
+module RSpecTelemetry
+  module Trace
+    module Viewer
+      class ReportPane
+        def initialize(rows, list:, focus:)
+          @rows = rows
+          @list = list
+          @focus = focus
+        end
+
+        def draw(canvas, rect)
+          highlight = @focus ? Theme::SELECT : Theme::SELECT_BLUR
+          TuiTui::List.new(@list).draw(canvas, rect, highlight: highlight, scrollbar: Theme.base) do |index, selected|
+            row = @rows[index]
+            style = selected ? highlight : Theme.style(row.style)
+            TuiTui::Line[TuiTui::Span[row.text, style]]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec_telemetry/trace/viewer/report_view.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "document"
+require_relative "format"
+require_relative "../../factory_aggregation"
+
+module RSpecTelemetry
+  module Trace
+    module Viewer
+      module ReportView
+        Row = Data.define(:text, :style, :source, :payload)
+
+        TITLES = {examples: "slowest examples", factories: "factories by self time"}.freeze
+
+        def self.title(view) = TITLES[view]
+
+        def self.rows(document, view)
+          case view
+          when :examples
+            example_rows(document)
+          when :factories
+            factory_rows(document)
+          else
+            []
+          end
+        end
+
+        def self.example_rows(document)
+          document.actions.sort_by { |action| -(action.duration_ms || 0.0) }.map do |action|
+            tag = action.failed? ? " [#{action.status.upcase}]" : ""
+            Row.new(
+              text: "#{dur(action.duration_ms)}  #{action.label}#{tag}",
+              style: action.failed? ? :error : :plain,
+              source: action.source,
+              payload: action
+            )
+          end
+        end
+
+        def self.factory_rows(document)
+          aggregate(document).top.map do |stat|
+            Row.new(
+              text: "#{dur(stat.self_total_ms)}  #{stat.key}  ×#{stat.count}  total #{Format.ms(stat.total_ms)}",
+              style: :plain,
+              source: nil,
+              payload: stat
+            )
+          end
+        end
+
+        def self.detail(payload)
+          return [] unless payload.is_a?(FactoryAggregation::Stat)
+
+          [
+            "FACTORY #{payload.key}",
+            "",
+            "count: #{payload.count}",
+            "self total: #{Format.ms(payload.self_total_ms)}  (children excluded)",
+            "total: #{Format.ms(payload.total_ms)}  (children included)",
+            "avg: #{Format.ms(payload.avg_ms)}",
+            "max: #{Format.ms(payload.max_ms)}"
+          ]
+        end
+
+        def self.aggregate(document)
+          acc = FactoryAggregation::Accumulator.new
+          document.events.each do |event|
+            next unless event.op == "factory"
+
+            fields = event.fields
+            acc.add(
+              factory: fields["factory"],
+              strategy: fields["strategy"],
+              duration_ms: fields["duration_ms"],
+              self_duration_ms: fields["self_duration_ms"]
+            )
+          end
+
+          acc
+        end
+
+        def self.dur(ms) = (Format.ms(ms) || "-").rjust(8)
+      end
+    end
+  end
+end