rspec_telemetry 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a39ae80facd19b25cfcbb59d34bde9ad51d47cb815d1ea5bfec9b3a344cead99
+  data.tar.gz: 031a509323010facb690d5cedbc53eb3e318087cbb69439832426b24673efa98
+SHA512:
+  metadata.gz: 8158f6494ea9a691a3c52c236320cfffd6b32986258ab578a87dc708940c800a5f7fde9342187240fb254158d24bed74edf7d39963856c39488ce468f78f898a
+  data.tar.gz: 6d962956bde3f0a320aec11562d584380da45c9c6372a589c1e12cfc5d6361965327624cdfbd6eea08cc6333e7688530095cb91964cce9c8204e2ff2dd3ed611

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [0.3.0] - 2026-06-25
+
+### Added
+- `rspec-telemetry-compare` to compare FactoryBot usage between two runs.
+
+### Changed
+- Requires Ruby >= 3.2.
+- The interactive viewer now works out of the box; no need to add `tui_tui`
+  yourself.
+
+## [0.2.0] - 2026-06-17
+
+### Changed
+- Collection (the RSpec formatter that writes NDJSON) now runs on Ruby >= 3.1.
+- `tui_tui` is no longer a runtime dependency; it is only needed for the
+  interactive viewer (Ruby >= 3.2, `gem "tui_tui"`). The viewer degrades with a
+  clear message when it is missing.
+
+### Added
+- Viewer renders Unicode box-drawing chrome (frames, dividers, scrollbar) when
+  the terminal supports it, falling back to ASCII otherwise.
+
+### Fixed
+- FactoryBot timing is captured again on Rails 6.x / ActiveSupport 6 (a
+  Rails 7-only `require` had silently disabled the subscription).
+
+## [0.1.0] - 2026-06-17
+
+First public release.
+
+[Unreleased]: https://github.com/takahashim/rspec_telemetry/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/takahashim/rspec_telemetry/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/takahashim/rspec_telemetry/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Masayoshi Takahashi (@takahashim)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,193 @@
+# rspec_telemetry
+
+`rspec_telemetry` collects telemetry data during RSpec runs and writes it as NDJSON.
+It helps you analyze your test suite.
+
+- Duration for each example
+- FactoryBot factory time, including nesting depth and self time
+- Rankings of slow factories and slow examples
+- Links between examples and factory events using `example_id`
+
+## Requirements
+
+- Ruby >= 3.2.
+- RSpec.
+- `tui_tui` powers the interactive viewer (`rspec-telemetry-viewer`).
+- activesupport (optional): only needed for FactoryBot tracking, which relies on
+  `ActiveSupport::Notifications`. FactoryBot pulls it in, so projects using
+  FactoryBot already have it; otherwise factory tracking is skipped automatically.
+
+## Install
+
+```ruby
+# Gemfile
+group :test do
+  gem "rspec_telemetry"
+end
+```
+
+## Usage
+
+```ruby
+# spec/spec_helper.rb, etc.
+require "rspec_telemetry"
+```
+
+It can be used together with normal human-readable output such as `progress`.
+
+After requiring the gem, the following features are enabled:
+
+- NDJSON output to `tmp/rspec_telemetry.ndjson`
+- Recording of example start/finish events
+- Recording of FactoryBot factory events
+- Recording of suite finish events
+
+If you want to specify the formatter explicitly in `.rspec`:
+
+```text
+--format progress
+--format RSpecTelemetry::Formatter
+```
+
+> To disable automatic formatter registration, set the environment variable
+> `RSPEC_TELEMETRY_NO_AUTOLOAD=1`.
+
+## Configuration
+
+```ruby
+RSpecTelemetry.configure do |config|
+  config.enabled = true
+  config.output_path = "tmp/rspec_telemetry.ndjson"
+  config.capture_examples = true
+  config.capture_factory_bot = true
+  config.print_summary = false        # true: print a summary to stderr at the end
+  config.flush_each = false           # true: flush after each event, useful for tail -f
+  config.slow_factory_threshold_ms = nil
+  config.slow_example_threshold_ms = 1000.0
+end
+```
+
+## Finding what is slow: `rspec-telemetry`
+
+After running your tests, you can analyze the generated NDJSON file and see where time was spent.
+
+```bash
+$ bundle exec rspec
+$ bundle exec rspec-telemetry          # automatically reads tmp/rspec_telemetry*.ndjson
+```
+
+```text
+Overview
+--------
+  examples:              3 (0 failed, 0 pending)
+  suite wall time:       91.6ms
+  example time (sum):    89.8ms
+  factory self time:     63.8ms (71.1% of example time)   <- 70% of test time was spent in factories
+
+Slowest files (sum of example time)
+Slowest examples
+Slowest factories (by self time, excludes nested children)
+  1. user:create   count 9   self 56.1ms   total 56.1ms   avg 6.2ms   max 6.7ms
+```
+
+Options:
+
+```bash
+rspec-telemetry --top 30                          # number of items shown in each section
+rspec-telemetry --example "./spec/x_spec.rb[1:2]" # drill down into one example, including nested factories
+rspec-telemetry tmp/rspec_telemetry.1.ndjson ...  # explicitly specify files, useful for parallel test runs
+```
+
+Example drill-down output:
+
+```text
+Example: ./spec/x_spec.rb[2:1]
+  status: passed   duration: 52.4ms
+  FactoryBot calls (indented by nesting depth):
+     user:create  self 6.7ms / total 6.7ms
+    order:create  self 2.6ms / total 9.3ms      <- order total includes child user time
+  factory self total: 27.2ms across 6 calls
+```
+
+## Comparing factory usage between two runs
+
+Use `rspec-telemetry-compare` to compare FactoryBot call counts and cumulative
+factory time between two telemetry files.
+
+```bash
+$ bundle exec rspec-telemetry-compare \
+    tmp/rspec_telemetry.before.ndjson \
+    tmp/rspec_telemetry.after.ndjson
+```
+
+By default, only root factory events (`depth == 0`) are counted, and their
+inclusive `duration_ms` is compared.
+
+With `--all-depths`, every factory event is counted and `self_duration_ms` is
+compared. Self time excludes nested child factories, so it avoids double
+counting while showing the actual number and cost of associated factories.
+
+```bash
+rspec-telemetry-compare --sort count BEFORE AFTER
+rspec-telemetry-compare --sort factory BEFORE AFTER
+rspec-telemetry-compare --all-depths BEFORE AFTER
+```
+
+## TUI viewer: `rspec-telemetry-viewer`
+
+You can view the same NDJSON file in an interactive terminal UI.
+
+The viewer uses the built-in TUI implementation and only depends on `io-console`.
+
+In a terminal, it shows a timeline, details, and a status bar.
+When output is piped or redirected, it prints a text report instead.
+
+```bash
+$ bundle exec rspec-telemetry-viewer tmp/rspec_telemetry.ndjson           # TUI when running in a terminal
+$ bundle exec rspec-telemetry-viewer --follow tmp/rspec_telemetry.ndjson  # follow a running test
+$ bundle exec rspec-telemetry-viewer --plain  tmp/rspec_telemetry.ndjson  # force text report
+```
+
+Use `1`, `2`, and `3` to switch between the three screens:
+
+- `1` Timeline: shows examples in execution order, with factory calls grouped under each example
+- `2` Slowest examples: ranks examples by duration
+- `3` Factories by self time: groups factories by `factory:strategy` and ranks them by self time
+
+## Example output: NDJSON
+
+```text
+$ bundle exec rspec
+```
+
+```json
+{"type":"example.started","example_id":"./spec/models/user_spec.rb[1:1]", ...}
+{"type":"factory_bot.run_factory","example_id":"./spec/models/user_spec.rb[1:1]","factory":"user","strategy":"create","traits":["admin"],"overrides":["email"],"duration_ms":42.381,"self_duration_ms":30.12,"depth":0,"parent_factory":null}
+{"type":"example.finished","example_id":"./spec/models/user_spec.rb[1:1]","status":"passed","duration_ms":71.552}
+```
+
+## Design notes
+
+#### Override values are not recorded
+
+For FactoryBot overrides, `rspec_telemetry` records only the attribute names.
+It does not record the actual values, because they may contain personal information, secrets, or other sensitive data.
+
+#### Nested factories and double counting
+
+FactoryBot associations can create other factories internally.
+This is why `rspec_telemetry` also records `self_duration_ms`.
+
+Use self time when you want to find which factory is really slow.
+
+#### Parallel test runs
+
+When `TEST_ENV_NUMBER` is set, `rspec_telemetry` adds the worker number to the output file name.
+This prevents multiple parallel workers from writing to the same NDJSON file.
+
+#### Does not affect test results
+
+Telemetry should not change the result of your test suite.
+
+If writing telemetry data fails, `rspec_telemetry` ignores the error and prints only a warning.
+It does not change whether examples pass or fail.

data/examples/sample.ndjson

@@ -0,0 +1,15 @@
+{"type":"example.started","timestamp":"2026-06-14T15:16:27.832904Z","monotonic_time":1124322.211166,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:1]","file_path":"./sample_spec.rb","line_number":14,"full_description":"User creates an admin"}
+{"type":"factory_bot.run_factory","timestamp":"2026-06-14T15:16:27.838621Z","monotonic_time":1124322.216707,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:1]","factory":"user","strategy":"create","traits":["admin"],"overrides":["email"],"duration_ms":5.055,"self_duration_ms":5.055,"depth":0,"parent_factory":null,"factory_class":"User"}
+{"type":"example.finished","timestamp":"2026-06-14T15:16:27.838679Z","monotonic_time":1124322.216764,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:1]","file_path":"./sample_spec.rb","line_number":14,"full_description":"User creates an admin","status":"passed","duration_ms":5.439,"exception_class":null,"exception_message":null}
+{"type":"example.started","timestamp":"2026-06-14T15:16:27.838770Z","monotonic_time":1124322.216854,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:2]","file_path":"./sample_spec.rb","line_number":15,"full_description":"User creates many"}
+{"type":"factory_bot.run_factory","timestamp":"2026-06-14T15:16:27.844238Z","monotonic_time":1124322.222331,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:2]","factory":"user","strategy":"create","traits":[],"overrides":[],"duration_ms":5.09,"self_duration_ms":5.09,"depth":0,"parent_factory":null,"factory_class":"User"}
+{"type":"factory_bot.run_factory","timestamp":"2026-06-14T15:16:27.849341Z","monotonic_time":1124322.227432,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:2]","factory":"user","strategy":"create","traits":[],"overrides":[],"duration_ms":5.056,"self_duration_ms":5.056,"depth":0,"parent_factory":null,"factory_class":"User"}
+{"type":"factory_bot.run_factory","timestamp":"2026-06-14T15:16:27.854444Z","monotonic_time":1124322.23253,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:2]","factory":"user","strategy":"create","traits":[],"overrides":[],"duration_ms":5.042,"self_duration_ms":5.042,"depth":0,"parent_factory":null,"factory_class":"User"}
+{"type":"factory_bot.run_factory","timestamp":"2026-06-14T15:16:27.859693Z","monotonic_time":1124322.237785,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:2]","factory":"user","strategy":"create","traits":[],"overrides":[],"duration_ms":5.217,"self_duration_ms":5.217,"depth":0,"parent_factory":null,"factory_class":"User"}
+{"type":"factory_bot.run_factory","timestamp":"2026-06-14T15:16:27.864781Z","monotonic_time":1124322.242866,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:2]","factory":"user","strategy":"create","traits":[],"overrides":[],"duration_ms":5.034,"self_duration_ms":5.034,"depth":0,"parent_factory":null,"factory_class":"User"}
+{"type":"example.finished","timestamp":"2026-06-14T15:16:27.877409Z","monotonic_time":1124322.255493,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:2]","file_path":"./sample_spec.rb","line_number":15,"full_description":"User creates many","status":"passed","duration_ms":38.623,"exception_class":null,"exception_message":null}
+{"type":"example.started","timestamp":"2026-06-14T15:16:27.877475Z","monotonic_time":1124322.255559,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:3]","file_path":"./sample_spec.rb","line_number":16,"full_description":"User fails"}
+{"type":"factory_bot.run_factory","timestamp":"2026-06-14T15:16:27.882846Z","monotonic_time":1124322.260935,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:3]","factory":"user","strategy":"create","traits":[],"overrides":[],"duration_ms":5.054,"self_duration_ms":5.054,"depth":1,"parent_factory":"order","factory_class":"User"}
+{"type":"factory_bot.run_factory","timestamp":"2026-06-14T15:16:27.885425Z","monotonic_time":1124322.263514,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:3]","factory":"order","strategy":"create","traits":[],"overrides":[],"duration_ms":7.688,"self_duration_ms":2.634,"depth":0,"parent_factory":null,"factory_class":"Order"}
+{"type":"example.finished","timestamp":"2026-06-14T15:16:27.891811Z","monotonic_time":1124322.269896,"pid":81586,"thread_id":62402625,"example_id":"./sample_spec.rb[1:3]","file_path":"./sample_spec.rb","line_number":16,"full_description":"User fails","status":"failed","duration_ms":14.302,"exception_class":"RSpec::Expectations::ExpectationNotMetError","exception_message":"\nexpected: 2\n     got: 1\n\n(compared using ==)\n"}
+{"type":"suite.finished","timestamp":"2026-06-14T15:16:27.892101Z","monotonic_time":1124322.270186,"pid":81586,"thread_id":62402625,"example_id":null,"duration_ms":60.663,"example_count":3,"failure_count":1,"pending_count":0}

data/exe/rspec-telemetry

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rspec_telemetry/version"
+require "rspec_telemetry/cli"
+
+exit RSpecTelemetry::CLI.new(ARGV).run

data/exe/rspec-telemetry-compare

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rspec_telemetry/compare_cli"
+
+exit RSpecTelemetry::CompareCLI.new(ARGV).run

data/exe/rspec-telemetry-viewer

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rspec_telemetry/trace/viewer"
+
+# Read an rspec_telemetry NDJSON file and either open the interactive TUI (when
+# stdout is a terminal) or print the decorated text report (when piped/redirected).
+#   --plain          force the text report even on a terminal
+#   --follow / -f    tail a running file, folding new lines in live (TTY only)
+#   --source-root D  resolve spec source paths under D (default: cwd)
+#   --color MODE     auto (default) | none | 16 | 256 | truecolor
+#   --mouse / --no-mouse  force mouse reporting on/off (default: on;
+#                  RSPEC_TELEMETRY_MOUSE=0 also disables it)
+def take_option(argv, *flags)
+  flags.each do |flag|
+    index = argv.index(flag)
+    next unless index
+
+    argv.delete_at(index)
+    return argv.delete_at(index)
+  end
+  nil
+end
+
+plain = ARGV.delete("--plain")
+follow = ARGV.delete("--follow") || ARGV.delete("-f")
+mouse = if ARGV.delete("--no-mouse")
+          false
+        elsif ARGV.delete("--mouse")
+          true
+        else
+          # On by default; RSPEC_TELEMETRY_MOUSE=0/off/false disables it.
+          !%w[0 off false].include?(ENV["RSPEC_TELEMETRY_MOUSE"])
+        end
+source_root = take_option(ARGV, "--source-root", "-r") || Dir.pwd
+color = take_option(ARGV, "--color") || "auto"
+depth = TuiTui::ColorDepth.from(color)
+path = ARGV[0]
+if path.nil?
+  abort "usage: rspec-telemetry-viewer [--plain] [--follow] [--source-root DIR] " \
+        "[--color auto|none|16|256|truecolor] FILE.ndjson"
+end
+abort "no such file: #{path}" unless File.file?(path)
+
+if !plain && $stdout.tty?
+  base_dir = File.dirname(path) # resolve spec source ancestors relative to the file
+  if follow
+    # Start empty and let the tailer read the existing content first, so the
+    # initial frame is populated and subsequent appends stream in.
+    document = RSpecTelemetry::Trace::Viewer::Document.new
+    source = RSpecTelemetry::Trace::Viewer::TailSource.new(path)
+    source.drain.each { |line| document.apply(line) }
+    app = RSpecTelemetry::Trace::Viewer::App.new(document, source: source, follow: true,
+      base_dir: base_dir, source_root: source_root, depth: depth)
+  else
+    document = RSpecTelemetry::Trace::Viewer::Document.from_lines(File.foreach(path))
+    app = RSpecTelemetry::Trace::Viewer::App.new(document, base_dir: base_dir,
+      source_root: source_root, depth: depth)
+  end
+  TuiTui::Runtime.new(app).run(depth: depth, mouse: mouse)
+else
+  document = RSpecTelemetry::Trace::Viewer::Document.from_lines(File.foreach(path))
+  enabled = $stdout.tty? && depth != :none
+  report = RSpecTelemetry::Trace::Viewer::TextReport.new(document, depth: depth, enabled: enabled)
+  puts report.render
+  puts report.summary
+end

data/lib/rspec_telemetry/analyzer.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "ndjson"
+require_relative "factory_aggregation"
+
+module RSpecTelemetry
+  class Analyzer
+    Example = Struct.new(
+      :example_id,
+      :file_path,
+      :line_number,
+      :full_description,
+      :status,
+      :duration_ms,
+      :fb_self_total_ms,
+      :fb_count,
+      keyword_init: true
+    )
+
+    FileStat = Struct.new(:file_path, :example_count, :duration_ms, keyword_init: true)
+
+    attr_reader(
+      :examples,
+      :files,
+      :example_count,
+      :failure_count,
+      :pending_count,
+      :suite_duration_ms
+    )
+
+    def initialize
+      @examples = {}
+      @factory_acc = FactoryAggregation::Accumulator.new
+      @files = {}
+      # Factory events arrive before example.finished, so merge them after loading.
+      @example_fb = Hash.new { |h, k| h[k] = [0.0, 0] }
+      @example_count = 0
+      @failure_count = 0
+      @pending_count = 0
+      @suite_duration_ms = 0.0
+    end
+
+    def self.load(paths)
+      new.tap do |analyzer|
+        Array(paths).each do |path|
+          File.foreach(path) do |line|
+            event = Ndjson.parse(line)
+            analyzer.add(event) if event
+          end
+        end
+      end
+    end
+
+    def add(event)
+      case event["type"]
+      when "example.finished"
+        add_example(event)
+      when "factory_bot.run_factory"
+        add_factory(event)
+      when "suite.finished"
+        add_suite(event)
+      end
+    end
+
+    def total_example_ms
+      @examples.values.sum { |e| e.duration_ms.to_f }
+    end
+
+    def factories
+      @factory_acc.stats
+    end
+
+    def total_factory_self_ms
+      @factory_acc.stats.sum(&:self_total_ms)
+    end
+
+    def factory_time_ratio
+      total = total_example_ms
+      total.zero? ? 0.0 : total_factory_self_ms / total
+    end
+
+    def slow_examples(limit = 20)
+      merged_examples.sort_by { |e| -e.duration_ms.to_f }.first(limit)
+    end
+
+    def merged_examples
+      # Mutate the report structs at the read boundary; raw aggregates stay separate.
+      @examples.values.map do |ex|
+        self_total, count = @example_fb[ex.example_id]
+        ex.fb_self_total_ms = self_total
+        ex.fb_count = count
+        ex
+      end
+    end
+
+    def top_factories(limit = 20)
+      @factory_acc.top(limit)
+    end
+
+    def slow_files(limit = 20)
+      @files.values.sort_by { |f| -f.duration_ms.to_f }.first(limit)
+    end
+
+    def self.events_for_example(paths, example_id)
+      events = []
+      Array(paths).each do |path|
+        File.foreach(path) do |line|
+          event = Ndjson.parse(line)
+          next unless event && event["example_id"] == example_id
+
+          events << event
+        end
+      end
+
+      events
+    end
+
+    private
+
+    def add_example(event)
+      id = event["example_id"] || event["full_description"]
+      ex = (@examples[id] ||= Example.new(
+        example_id: id,
+        file_path: event["file_path"],
+        line_number: event["line_number"],
+        full_description: event["full_description"],
+        status: event["status"],
+        duration_ms: 0.0,
+        fb_self_total_ms: 0.0,
+        fb_count: 0
+      ))
+      ex.duration_ms = event["duration_ms"]
+      ex.status = event["status"]
+      ex.file_path ||= event["file_path"]
+      ex.line_number ||= event["line_number"]
+      ex.full_description ||= event["full_description"]
+
+      file = event["file_path"]
+      return unless file
+
+      fs = (@files[file] ||= FileStat.new(file_path: file, example_count: 0, duration_ms: 0.0))
+      fs.example_count += 1
+      fs.duration_ms += event["duration_ms"].to_f
+    end
+
+    def add_factory(event)
+      self_ms = (event["self_duration_ms"] || event["duration_ms"]).to_f
+      @factory_acc.add(
+        factory: event["factory"],
+        strategy: event["strategy"],
+        duration_ms: event["duration_ms"],
+        self_duration_ms: self_ms
+      )
+
+      id = event["example_id"]
+      return unless id
+
+      acc = @example_fb[id]
+      acc[0] += self_ms
+      acc[1] += 1
+    end
+
+    def add_suite(event)
+      @example_count += event["example_count"].to_i
+      @failure_count += event["failure_count"].to_i
+      @pending_count += event["pending_count"].to_i
+      @suite_duration_ms += event["duration_ms"].to_f
+    end
+  end
+end

data/lib/rspec_telemetry/cli.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "analyzer"
+require_relative "console_report"
+
+module RSpecTelemetry
+  class CLI
+    DEFAULT_GLOB = "tmp/rspec_telemetry*.ndjson"
+
+    def initialize(argv, out: $stdout, err: $stderr)
+      @argv = argv
+      @out = out
+      @err = err
+      @options = {top: 15, example: nil}
+    end
+
+    def run
+      paths = parse!
+      if paths.empty?
+        @err.puts("No telemetry files found (looked for #{DEFAULT_GLOB}).")
+        @err.puts("Run `bundle exec rspec` first, or pass file paths explicitly.")
+        return 1
+      end
+
+      @options[:example] ? drill_down(paths, @options[:example]) : report(paths)
+      0
+    rescue Errno::ENOENT => e
+      @err.puts("File not found: #{e.message}")
+      1
+    end
+
+    private
+
+    def parse!
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: rspec-telemetry [options] [files...]"
+        o.on("-n", "--top N", Integer, "Show top N rows per section (default: 15)") { |v| @options[:top] = v }
+        o.on("-e", "--example ID", "Drill down into a single example by id") { |v| @options[:example] = v }
+        o.on("-h", "--help", "Show this help") do
+          @out.puts(o)
+          exit(0)
+        end
+
+        o.on("-v", "--version", "Show version") do
+          @out.puts(RSpecTelemetry::VERSION)
+          exit(0)
+        end
+      end
+
+      files = parser.parse(@argv)
+      files.empty? ? Dir.glob(DEFAULT_GLOB).sort : files
+    end
+
+    def report(paths)
+      analyzer = Analyzer.load(paths)
+      @out.puts(ConsoleReport.new(analyzer, files_count: paths.size, top: @options[:top]).render)
+    end
+
+    def drill_down(paths, example_id)
+      events = Analyzer.events_for_example(paths, example_id)
+      if events.empty?
+        @err.puts("No events found for example: #{example_id}")
+        return
+      end
+
+      @out.puts(ConsoleReport.drill_down(events, example_id))
+    end
+  end
+end