rigortype 0.1.17 → 0.1.19

data/lib/rigor/cli/trace_command.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+require "prism"
+
+require_relative "../configuration"
+require_relative "../environment"
+require_relative "../scope"
+require_relative "../inference/flow_tracer"
+require_relative "../inference/scope_indexer"
+require_relative "command"
+require_relative "trace_renderer"
+
+module Rigor
+  class CLI
+    # Executes the `rigor trace` command: re-runs the inference engine
+    # over one file under {Rigor::Inference::FlowTracer} and replays the
+    # recorded event stream — scope binds, union formation, method
+    # dispatch, and (with `--verbose`) every expression enter/result —
+    # as a step-through terminal animation. A teaching probe: it shows
+    # HOW Rigor arrives at a type, where `rigor type-of` shows only the
+    # answer.
+    #
+    # The tracer is observational; this command never changes what
+    # `rigor check` would infer for the same file.
+    class TraceCommand < Command
+      USAGE = "Usage: rigor trace [options] FILE"
+
+      # Default frame kinds: the three teachable moments. :enter/:result
+      # add one frame per literal and drown the signal; `--verbose`
+      # opts into them.
+      DEFAULT_KINDS = %i[bind union dispatch].freeze
+      VERBOSE_KINDS = (%i[enter result] + DEFAULT_KINDS).freeze
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        file = @argv.first
+        if file.nil? || @argv.size != 1
+          @err.puts(USAGE)
+          return CLI::EXIT_USAGE
+        end
+        return 1 unless file_exists?(file)
+
+        execute(file: file, options: options)
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", delay: nil, verbose: false, line: nil, config: nil }
+        parser = OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--format=FORMAT", "Output format: text (animation) or json (raw event stream)") do |value|
+            options[:format] = value
+          end
+          opts.on("--delay=SECONDS", Float,
+                  "Autoplay with SECONDS between frames (default: step on key press)") do |value|
+            options[:delay] = value
+          end
+          opts.on("--line=N", Integer, "Only replay events whose source range starts on line N") do |value|
+            options[:line] = value
+          end
+          opts.on("--verbose", "Include every expression enter/result frame") { options[:verbose] = true }
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+        end
+        parser.parse!(@argv)
+        options
+      end
+
+      def execute(file:, options:)
+        configuration = Configuration.load(options.fetch(:config))
+        source = File.read(file, encoding: Encoding::UTF_8)
+        parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
+        return 1 if parse_errors?(parse_result, file)
+
+        events = record_events(parse_result.value, file, configuration)
+        frames = filter(events, options)
+
+        if options.fetch(:format) == "json"
+          @out.puts(JSON.pretty_generate(frames.map { |event| event_to_h(event) }))
+          return 0
+        end
+
+        if frames.empty?
+          @out.puts("trace: no events to replay (try --verbose)")
+          return 0
+        end
+
+        interactive = @out.respond_to?(:tty?) && @out.tty?
+        TraceRenderer.new(out: @out, source: source, file: file)
+                     .play(frames, delay: options.fetch(:delay), interactive: interactive)
+        0
+      end
+
+      # Mirrors the single-file path `rigor type-of` takes: a
+      # project-aware environment, an empty seed scope, one
+      # statement-level evaluation of the whole program — but recorded
+      # under the FlowTracer.
+      def record_events(root, file, configuration)
+        environment = Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths
+        )
+        scope = Scope.empty(environment: environment, source_path: file)
+        Inference::FlowTracer.record { scope.evaluate(root) }
+      end
+
+      def filter(events, options)
+        kinds = options.fetch(:verbose) ? VERBOSE_KINDS : DEFAULT_KINDS
+        frames = events.select { |event| kinds.include?(event.kind) }
+        line = options.fetch(:line)
+        frames = frames.select { |event| event.location && event.location[:start_line] == line } if line
+        frames
+      end
+
+      def event_to_h(event)
+        {
+          kind: event.kind,
+          depth: event.depth,
+          location: event.location,
+          stack: event.stack,
+          data: event.data
+        }
+      end
+
+      def file_exists?(file)
+        return true if File.file?(file)
+
+        @err.puts("trace: file not found: #{file}")
+        false
+      end
+
+      def parse_errors?(result, file)
+        return false if result.errors.empty?
+
+        result.errors.each { |error| @err.puts("#{file}:#{error.location.start_line}: #{error.message}") }
+        true
+      end
+    end
+  end
+end

data/lib/rigor/cli/trace_renderer.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require_relative "prism_colorizer"
+
+module Rigor
+  class CLI
+    # Replays a `Rigor::Inference::FlowTracer` event stream as a terminal
+    # animation for `rigor trace`. Each frame draws a box-drawn screen:
+    # the source panel (syntax-coloured, current node range underlined)
+    # side-by-side with the scope panel (locals accumulated from :bind
+    # events), and an event panel describing the current step and the
+    # expression stack.
+    #
+    # The frame is fitted to the measured terminal: the source panel
+    # scrolls vertically (a window centred on the line under evaluation)
+    # instead of overflowing the screen height, over-long rows are
+    # clipped with an ellipsis instead of wrapping, and the event panel
+    # keeps a minimum height of {EVENT_PANE_MIN} rows so the narration
+    # never collapses to a sliver.
+    #
+    # Pure ANSI + `io/console` (both stdlib) per ADR-0's zero-runtime-
+    # dependency policy. When the output is not a TTY the frames are
+    # printed sequentially without cursor control against a default
+    # 80×24 layout, which keeps the renderer deterministic under test.
+    class TraceRenderer
+      RESET = "\e[0m"
+      DIM = "\e[90m"
+      BOLD = "\e[1m"
+      HIGHLIGHT = "\e[7m" # reverse video for the frame's source range
+
+      EVENT_PANE_MIN = 2     # minimum event-panel rows
+      SCOPE_WIDTH_MIN = 19   # minimum scope-column width
+      BODY_HEIGHT_MIN = 3    # never shrink the source window below this
+      DEFAULT_SIZE = [24, 80].freeze
+
+      # @param out [IO]
+      # @param source [String] the traced file's source.
+      # @param file [String] display path.
+      def initialize(out:, source:, file:)
+        @out = out
+        @source = source
+        @file = file
+        @lines = source.lines.map(&:chomp)
+      end
+
+      # @param events [Array<Rigor::Inference::FlowTracer::Event>] the
+      #   pre-filtered frame list (the command owns kind filtering).
+      # @param delay [Float, nil] seconds between frames (autoplay);
+      #   nil = step on key press when interactive.
+      # @param interactive [Boolean] whether to clear/redraw and wait.
+      def play(events, delay: nil, interactive: false)
+        @rows, @cols = interactive ? terminal_size : DEFAULT_SIZE
+        @interactive = interactive
+        locals_per_frame = accumulate_locals(events)
+        events.each_with_index do |event, index|
+          @out.print("\e[H\e[2J") if interactive
+          render_frame(event, index: index, total: events.size, locals: locals_per_frame[index])
+          @out.puts unless interactive
+          next if index == events.size - 1
+
+          if delay
+            sleep(delay)
+          elsif interactive
+            break unless next_frame?
+          end
+        end
+      end
+
+      private
+
+      # `IO.console` reflects the controlling terminal even when stdout
+      # is, say, a StringIO under test — which is why the measured size
+      # is only used for interactive replays.
+      def terminal_size
+        require "io/console"
+        size = IO.console&.winsize
+        return size if size && size[0].positive? && size[1].positive?
+
+        DEFAULT_SIZE
+      rescue LoadError, SystemCallError
+        DEFAULT_SIZE
+      end
+
+      # Replays :bind events into a per-frame snapshot of the locals
+      # panel, so frame N shows exactly the bindings visible after the
+      # first N events.
+      def accumulate_locals(events)
+        locals = {}
+        events.map do |event|
+          locals[event.data[:name]] = event.data[:type] if event.kind == :bind
+          locals.dup
+        end
+      end
+
+      def render_frame(event, index:, total:, locals:)
+        inner = @cols - 3 # three vertical borders
+        lines = event_pane_lines(event, inner - 1)
+        body_height = body_height_for(lines.size)
+
+        source_rows = source_panel_rows(event)
+        left_width, right_width = column_widths(source_rows, inner)
+        source_rows = clip_rows(scroll_window(source_rows, body_height), left_width)
+        scope_rows = fit_rows(scope_panel_rows(locals), body_height, right_width)
+
+        @out.puts(top_border(left_width, right_width))
+        body_rows(source_rows, scope_rows, left_width, right_width)
+        @out.puts(divider(left_width, right_width, label: " step #{index + 1}/#{total} · #{event.kind} "))
+        lines.each { |line| @out.puts(boxed_line(line, left_width + right_width + 1)) }
+        @out.puts(bottom_border(left_width + right_width + 1))
+      end
+
+      # Screen budget: borders (3 rows) + event pane + the key-hint row
+      # when stepping interactively; whatever remains belongs to the
+      # source/scope body, floored at {BODY_HEIGHT_MIN}.
+      def body_height_for(event_rows)
+        chrome = 3 + event_rows + (@interactive ? 1 : 0)
+        [@rows - chrome, BODY_HEIGHT_MIN].max
+      end
+
+      # The event pane keeps at least {EVENT_PANE_MIN} rows (padding with
+      # blanks) so the bottom of the frame is visually stable across
+      # event kinds; over-long lines are clipped to the frame width.
+      def event_pane_lines(event, max_width)
+        lines = [describe_event(event), stack_line(event)].compact
+        lines << "" while lines.size < EVENT_PANE_MIN
+        lines.map { |line| clip(line, max_width) }
+      end
+
+      # Source rows win the width contest; the scope column keeps its
+      # minimum and absorbs whatever the source does not need.
+      def column_widths(source_rows, inner)
+        left_need = (source_rows.map { |raw, _| raw.length }.max || 0) + 1
+        left_width = left_need.clamp(24, [inner - SCOPE_WIDTH_MIN, 24].max)
+        [left_width, [inner - left_width, SCOPE_WIDTH_MIN].max]
+      end
+
+      # Vertical scroll: when the panel is taller than the window, keep
+      # a slice centred on the row under evaluation (the `▶` row, which
+      # the marker row directly follows).
+      def scroll_window(rows, height)
+        return rows if rows.size <= height
+
+        focus = rows.index { |raw, _| raw.start_with?("▶") } || 0
+        start = (focus - (height / 2)).clamp(0, rows.size - height)
+        rows[start, height]
+      end
+
+      def clip_rows(rows, width)
+        rows.map do |raw, painted|
+          next [raw, painted] if raw.length <= width
+
+          # Re-paint from the clipped raw text — clipping the painted
+          # string directly would cut ANSI escapes in half.
+          clipped = clip(raw, width)
+          [clipped, repaint_clipped(clipped)]
+        end
+      end
+
+      # A clipped row loses its highlight/marker alignment guarantees, so
+      # it is repainted with plain syntax colouring (gutter dimmed).
+      def repaint_clipped(clipped)
+        gutter = clipped[0, 6]
+        rest = clipped[6..] || ""
+        DIM + gutter + RESET + PrismColorizer.colorize(rest).chomp
+      end
+
+      def fit_rows(rows, height, width)
+        rows = rows[0, height - 1] + ["  … (+#{rows.size - height + 1} more)"] if rows.size > height
+        rows.map { |row| clip(row, width) }
+      end
+
+      def clip(text, width)
+        return text if text.length <= width
+
+        "#{text[0, [width - 1, 0].max]}…"
+      end
+
+      # Each row is `[raw_text, painted_text]` so width math runs on the
+      # escape-free string. The row under the event's source range gets a
+      # `▔▔▔` marker row injected after it.
+      def source_panel_rows(event)
+        rows = []
+        location = event.location
+        @lines.each_with_index do |line, i|
+          number = i + 1
+          current = location && number == location[:start_line]
+          gutter = "#{current ? '▶' : ' '}#{number.to_s.rjust(3)}  "
+          raw = gutter + line
+          painted = (current ? BOLD + gutter + RESET : DIM + gutter + RESET) + paint_line(line, location, number)
+          rows << [raw, painted]
+          rows << marker_row(gutter.length, line, location) if current
+        end
+        rows
+      end
+
+      def marker_row(gutter_width, line, location)
+        before, slice, = split_at_range(line, location)
+        indent = " " * (gutter_width + before.length)
+        width = [slice.length, 1].max
+        [indent + ("▔" * width), indent + BOLD + ("▔" * width) + RESET]
+      end
+
+      # Highlights the in-range slice with reverse video; everything else
+      # gets Prism syntax colouring. The highlight is applied on the raw
+      # slice (not the colorized string) so byte offsets stay honest.
+      def paint_line(line, location, number)
+        return PrismColorizer.colorize(line) unless location && number == location[:start_line]
+
+        before, slice, after = split_at_range(line, location)
+        return PrismColorizer.colorize(line) if slice.empty?
+
+        PrismColorizer.colorize(before).chomp +
+          HIGHLIGHT + slice + RESET +
+          PrismColorizer.colorize(after).chomp
+      end
+
+      # Prism columns are BYTE columns — split the line with byteslice
+      # so a multibyte character earlier on the line cannot shift (or
+      # overrun) the highlight range. Returns `[before, slice, after]`.
+      def split_at_range(line, location)
+        from = [location[:start_column], line.bytesize].min
+        to = location[:end_line] == location[:start_line] ? [location[:end_column], line.bytesize].min : line.bytesize
+        to = from if to < from
+        [line.byteslice(0, from), line.byteslice(from, to - from), line.byteslice(to, line.bytesize - to) || ""]
+      end
+
+      def scope_panel_rows(locals)
+        return [" (no locals yet)"] if locals.empty?
+
+        width = locals.keys.map(&:length).max
+        locals.map { |name, type| format(" %-#{width}s : %s", name, type) }
+      end
+
+      def describe_event(event)
+        data = event.data
+        case event.kind
+        when :bind then "bind     #{data[:name]} ← #{data[:type]}"
+        when :union then "union    #{data[:members].join(' | ')}  →  #{data[:type]}"
+        when :dispatch then describe_dispatch(data)
+        when :enter then "eval     #{data[:node]}"
+        when :result then "result   #{data[:node]}  →  #{data[:type]}"
+        else "#{event.kind}  #{data.inspect}"
+        end
+      end
+
+      def describe_dispatch(data)
+        call = "#{data[:receiver]} ##{data[:method]}(#{data[:args].join(', ')})"
+        return "dispatch #{call}  →  #{data[:type]}" if data[:resolved]
+
+        "dispatch #{call}  →  no rule matched (fail-soft → Dynamic[top])"
+      end
+
+      def stack_line(event)
+        return nil if event.stack.empty?
+
+        "stack    #{event.stack.join(' › ')}"
+      end
+
+      # -- box drawing ---------------------------------------------------
+
+      def top_border(left, right)
+        "┌#{pad_label("─ #{@file} ", left)}┬#{pad_label('─ scope ', right)}┐"
+      end
+
+      # Pads `label` with `─` to exactly `width` cells (truncating an
+      # over-long label so the frame never breaks).
+      def pad_label(label, width)
+        label = "#{label[0, width - 2]} " if label.length > width
+        label + ("─" * [width - label.length, 0].max)
+      end
+
+      def body_rows(source_rows, scope_rows, left, right)
+        [source_rows.size, scope_rows.size].max.times do |i|
+          raw, painted = source_rows[i] || ["", ""]
+          scope = scope_rows[i] || ""
+          @out.puts("│#{painted}#{' ' * [left - raw.length, 0].max}│#{scope}#{' ' * [right - scope.length, 0].max}│")
+        end
+      end
+
+      def divider(left, right, label:)
+        "├#{pad_label(label, left)}┴#{'─' * right}┤"
+      end
+
+      def boxed_line(text, width)
+        "│ #{text}#{' ' * [width - text.length - 1, 0].max}│"
+      end
+
+      def bottom_border(width)
+        "└#{'─' * width}┘"
+      end
+
+      # Single-keystroke stepping via stdlib io/console; falls back to
+      # line-buffered Enter when raw mode is unavailable (e.g. pipes that
+      # still claim to be TTYs). Returns false when the user quits.
+      def next_frame?
+        @out.print("#{DIM}  [any key: next · q: quit]#{RESET}")
+        key = read_key
+        @out.print("\r\e[K")
+        key != "q"
+      end
+
+      def read_key
+        require "io/console"
+        $stdin.getch
+      rescue LoadError, Errno::ENOTTY, Errno::ENODEV
+        $stdin.gets&.strip
+      end
+    end
+  end
+end

data/lib/rigor/cli/triage_command.rb

@@ -21,7 +21,7 @@ module Rigor
     # command, not a gate (`rigor check` remains the gate).
     class TriageCommand < Command
       USAGE = "Usage: rigor triage [options] [paths]"
-      DEFAULT_SECTIONS = %i[distribution hotspots hints].freeze
+      DEFAULT_SECTIONS = %i[distribution selectors hotspots hints].freeze
 
       # @return [Integer] CLI exit status (always 0).
       def run
@@ -46,8 +46,11 @@ module Rigor
           opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
           opts.on("--top=N", Integer, "Hotspot-file count (default 10)") { |v| options[:top] = v }
           opts.on("--hints-only", "Print only the heuristic-hints section") { options[:sections] = %i[hints] }
-          opts.on("--no-hints", "Print distribution + hotspots only") do
-            options[:sections] = %i[distribution hotspots]
+          opts.on("--no-hints", "Print distribution + selectors + hotspots only") do
+            options[:sections] = %i[distribution selectors hotspots]
+          end
+          opts.on("--selectors-only", "Print only the class/method selectors section") do
+            options[:sections] = %i[selectors]
           end
         end.parse!(@argv)
         validate!(options)

data/lib/rigor/cli/triage_renderer.rb

@@ -10,10 +10,11 @@ module Rigor
     # triage` text report or as `--format json`.
     class TriageRenderer
       BAR_WIDTH = 24
+      SELECTOR_ROWS = 15 # text-output cap; `--format json` carries the full list
 
       def initialize(report, sections:)
         @report = report
-        @sections = sections # subset of %i[distribution hotspots hints]
+        @sections = sections # subset of %i[distribution selectors hotspots hints]
       end
 
       def json
@@ -23,6 +24,7 @@ module Rigor
       def text
         blocks = []
         blocks << distribution_block if @sections.include?(:distribution)
+        blocks << selectors_block    if @sections.include?(:selectors)
         blocks << hotspots_block     if @sections.include?(:hotspots)
         blocks << hints_block        if @sections.include?(:hints)
         "#{blocks.join("\n\n")}\n"
@@ -42,6 +44,18 @@ module Rigor
         lines.join("\n")
       end
 
+      def selectors_block
+        return "Selectors — by class / method\n  (none)" if @report.selectors.empty?
+
+        lines = ["Selectors — by class / method (top #{SELECTOR_ROWS}; full list in --format json)"]
+        @report.selectors.first(SELECTOR_ROWS).each do |sel|
+          label = sel.receiver ? "#{sel.receiver}##{sel.method_name}" : sel.method_name
+          lines << format("  %<label>-44s %<count>5d  %<files>3d file(s)",
+                          label: label, count: sel.count, files: sel.files)
+        end
+        lines.join("\n")
+      end
+
       def hotspots_block
         return "Hotspot files\n  (none)" if @report.hotspots.empty?