lumitrace 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2ba7add22897e99449be04384c54d69bc475240840e2d229f73b90a5f289c0a0
+  data.tar.gz: 259751a540b06b2f790bef892f14191b1daaa8341ec5a484b8e91affe46120fa
+SHA512:
+  metadata.gz: cf8fc986e2d8ff10480bbbbb8ce57eac21cd9d72ba94a83604ffdba7e4cdccd8b6cb9a8e0e52b6413f5bf098a4d8d4d90e60c8cd70038d52bb0826d83b26c56a
+  data.tar.gz: e3752f0b9f8249345443352898c69a138e4cdb35f5ff3257c5a52b7bd9665b0ac48e6c0aca16575a6577b67838d47d709c453238ce35fc5ba6d8506c1a0420b2

data/README.md

@@ -0,0 +1,92 @@
+# Lumitrace
+
+Lumitrace instruments Ruby source code at load time, records expression results, and renders an HTML view that overlays recorded values on your code. It is designed for quick, local “what happened here?” inspection during test runs or scripts.
+
+## How It Works
+
+Lumitrace hooks `RubyVM::InstructionSequence.translate` (when available) to rewrite files at require-time. It records expression results and renders an HTML view that shows them inline. Only the last N values per expression are kept to avoid huge output.
+
+## Usage
+
+### CLI
+
+Run a script and emit HTML (default output: `lumitrace_recorded.html`):
+
+```bash
+ruby exe/lumitrace path/to/entry.rb
+```
+
+Limit the number of recorded values per expression (defaults to 3):
+
+```bash
+LUMITRACE_VALUES_MAX=5 ruby exe/lumitrace path/to/entry.rb
+```
+
+Write JSON output explicitly:
+
+```bash
+ruby exe/lumitrace path/to/entry.rb --json
+ruby exe/lumitrace path/to/entry.rb --json out/lumitrace_recorded.json
+```
+
+Restrict to specific line ranges:
+
+```bash
+ruby exe/lumitrace path/to/entry.rb --range path/to/entry.rb:10-20,30-35
+```
+
+### Library
+
+Enable instrumentation and HTML output at exit:
+
+```ruby
+require "lumitrace"
+Lumitrace.enable!
+```
+
+Enable only for diff ranges (current file):
+
+```ruby
+require "lumitrace/enable_git_diff"
+```
+
+If you want to enable via a single require:
+
+```ruby
+require "lumitrace/enable"
+```
+
+## Output
+
+- HTML: `lumitrace_recorded.html` by default, override with `LUMITRACE_HTML_OUT`.
+- JSON: written only when `--json` (CLI) or `LUMITRACE_JSON_OUT` (library) is provided. Default filename is `lumitrace_recorded.json`.
+
+## Environment Variables
+
+- `LUMITRACE_VALUES_MAX`: default max values per expression (default 3 if unset).
+- `LUMITRACE_ROOT`: root directory used to decide which files are instrumented.
+- `LUMITRACE_HTML_OUT`: override HTML output path.
+- `LUMITRACE_JSON_OUT`: if set, writes JSON to this path at exit.
+- `LUMITRACE_GIT_DIFF=working|staged|base:REV|range:SPEC`: diff source for `enable_git_diff`.
+- `LUMITRACE_GIT_DIFF_CONTEXT=N`: expand diff hunks by +/-N lines (default 3).
+- `LUMITRACE_GIT_CMD`: git executable override (default `git`).
+
+## Notes And Limitations
+
+- Requires `RubyVM::InstructionSequence.translate` support.
+- Very large projects or hot loops can still generate large HTML; use `LUMITRACE_VALUES_MAX`.
+- Instrumentation changes evaluation order for debugging, not for production.
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the CLI locally:
+
+```bash
+ruby exe/lumitrace path/to/entry.rb
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb", "test/**/test_*.rb"]
+  t.verbose = false
+end
+
+task default: :test

data/exe/lumitrace

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../lib/lumitrace"
+
+html_out = nil
+max_values = nil
+range_specs = []
+json_out = nil
+
+emit_html = true
+
+parser = OptionParser.new do |opts|
+  opts.banner = "usage: lumitrace FILE [options]"
+  opts.on("--html PATH", "Write HTML output to PATH") do |v|
+    emit_html = true
+    html_out = v
+  end
+  opts.on("--json [PATH]", "Write JSON output (default: lumitrace_recorded.json)") do |v|
+    json_out = v || ""
+  end
+  opts.on("--max N", Integer, "Max values per expression") do |v|
+    max_values = v
+  end
+  opts.on("--range SPEC", "Restrict instrumentation per file: FILE:1-5,10-12") do |v|
+    range_specs << v
+  end
+  opts.on("-h", "--help", "Show help") do
+    puts opts
+    exit 0
+  end
+end
+
+args = parser.parse(ARGV)
+path = args.shift or abort(parser.to_s)
+
+env_max = ENV["LUMITRACE_VALUES_MAX"]
+max_values = env_max if max_values.nil? && env_max && !env_max.empty?
+
+ranges_by_file = nil
+if range_specs.any?
+  ranges_by_file = Hash.new { |h, k| h[k] = [] }
+  range_specs.each do |spec|
+    file_part, range_part = spec.split(":", 2)
+    if file_part.nil? || file_part.strip.empty?
+      abort "invalid --range (expected FILE or FILE:1-5,10-12): #{spec}"
+    end
+
+    file = File.expand_path(file_part)
+    if range_part.nil? || range_part.strip.empty?
+      ranges_by_file[file] = []
+      next
+    end
+
+    range_part.split(",").each do |seg|
+      seg = seg.strip
+      if seg =~ /\A(\d+)-(\d+)\z/
+        ranges_by_file[file] << ($1.to_i..$2.to_i)
+      else
+        abort "invalid --range segment (expected N-M): #{seg}"
+      end
+    end
+  end
+end
+
+Lumitrace.enable!(max_values: max_values, ranges_by_file: ranges_by_file)
+load File.expand_path(path)
+events = Lumitrace::RecordInstrument.events
+
+if json_out
+  json_path = json_out.empty? ? "lumitrace_recorded.json" : json_out
+  events_path = File.expand_path(json_path, Dir.pwd)
+  Lumitrace.dump!(events_path)
+  puts "recorded: #{events_path}"
+end
+
+if emit_html
+  html = Lumitrace::GenerateResultedHtml.render_all_from_events(
+    events,
+    root: File.dirname(File.expand_path(path)),
+    ranges_by_file: ranges_by_file
+  )
+  out_path = html_out || File.join(File.dirname(File.expand_path(path)), "lumitrace_recorded.html")
+  File.write(out_path, html)
+  puts "html: #{out_path}"
+end

data/lib/lumitrace/enable.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "../lumitrace"
+
+Lumitrace.enable!

data/lib/lumitrace/enable_git_diff.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../lumitrace"
+
+def lumitrace_parse_git_diff_ranges(diff_text, root)
+  ranges_by_file = Hash.new { |h, k| h[k] = [] }
+  current_file = nil
+
+  diff_text.each_line do |line|
+    if line.start_with?("+++ ")
+      path = line.sub("+++ ", "").strip
+      if path == "/dev/null"
+        current_file = nil
+      else
+        path = path.sub(%r{\A[ab]/}, "")
+        current_file = File.expand_path(path, root)
+      end
+    elsif line.start_with?("@@")
+      next unless current_file
+      if line =~ /\+(\d+)(?:,(\d+))?\s@@/
+        start_line = Regexp.last_match(1).to_i
+        count = Regexp.last_match(2) ? Regexp.last_match(2).to_i : 1
+        next if count == 0
+        end_line = start_line + count - 1
+        context = ENV.fetch("LUMITRACE_GIT_DIFF_CONTEXT", "3").to_i
+        context = 0 if context < 0
+        start_line = [start_line - context, 1].max
+        end_line += context
+        ranges_by_file[current_file] << (start_line..end_line)
+      end
+    end
+  end
+
+  ranges_by_file
+end
+
+def lumitrace_diff_args
+  mode = ENV.fetch("LUMITRACE_GIT_DIFF", "working")
+  case mode
+  when "working"
+    []
+  when "staged"
+    ["--cached"]
+  when /\Abase:(.+)\z/
+    [Regexp.last_match(1)]
+  when /\Arange:(.+)\z/
+    [Regexp.last_match(1)]
+  else
+    abort "invalid LUMITRACE_GIT_DIFF (working|staged|base:REV|range:SPEC): #{mode}"
+  end
+end
+
+def lumitrace_git_root(dir, git_cmd)
+  out, status = Open3.capture2(git_cmd, "-C", dir, "rev-parse", "--show-toplevel")
+  return dir unless status.success?
+  out.strip
+end
+
+def lumitrace_diff_ranges
+  target = File.expand_path($PROGRAM_NAME)
+  base_dir = File.dirname(target)
+  git_cmd = ENV.fetch("LUMITRACE_GIT_CMD", "git")
+  root = lumitrace_git_root(base_dir, git_cmd)
+  args = [git_cmd, "-C", base_dir, "diff", "--unified=0", "--no-color"] + lumitrace_diff_args
+  args += ["--", target] if File.file?(target)
+  stdout, status = Open3.capture2(*args)
+  return nil unless status.success?
+  ranges_by_file = lumitrace_parse_git_diff_ranges(stdout, root)
+  ranges_by_file.empty? ? nil : ranges_by_file
+end
+
+ranges_by_file = lumitrace_diff_ranges
+Lumitrace.enable!(ranges_by_file: ranges_by_file, at_exit: true) if ranges_by_file

data/lib/lumitrace/generate_resulted_html.rb

@@ -0,0 +1,397 @@
+require "json"
+
+module Lumitrace
+module GenerateResultedHtml
+  def self.render(source_path, events_path, ranges: nil)
+    unless File.exist?(events_path)
+      abort "missing #{events_path}"
+    end
+    unless File.exist?(source_path)
+      abort "missing #{source_path}"
+    end
+
+    raw_events = JSON.parse(File.read(events_path))
+    events = normalize_events(raw_events)
+
+    src_lines = File.read(source_path).lines
+    ranges = normalize_ranges(ranges)
+
+    html_lines = src_lines.each_with_index.map do |line, idx|
+      lineno = idx + 1
+      next if ranges && !line_in_ranges?(lineno, ranges)
+      line_text = line.chomp
+      evs = aggregate_events_for_line(events, lineno, line_text.length)
+
+      if evs.empty?
+        "<span class=\"line\" data-line=\"#{lineno}\"><span class=\"ln\">#{lineno}</span> #{esc(line_text)}</span>\n"
+      else
+        rendered = render_line_with_events(line_text, evs)
+        "<span class=\"line hit\" data-line=\"#{lineno}\"><span class=\"ln\">#{lineno}</span> #{rendered}</span>\n"
+      end
+    end.compact
+
+    <<~HTML
+      <!doctype html>
+      <html>
+      <head>
+        <meta charset="utf-8">
+        <title>Recorded Result View</title>
+        <style>
+          body { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; background: #f7f5f0; color: #1f1f1f; padding: 24px; }
+          .code { background: #fffdf7; border: 1px solid #e5dfd0; border-radius: 8px; padding: 16px; line-height: 1.5; }
+          .line { display: inline; padding: 2px 8px; }
+          .line:hover { background: #fff2c6; }
+          .line.hit { background: #f0ffe7; }
+          .ln { display: inline-block; width: 3em; color: #888; user-select: none; }
+          .hint { color: #666; margin-bottom: 8px; }
+          .expr { position: relative; display: inline-block; padding-bottom: 1px; }
+          .expr.hit { }
+          .expr.depth-1 { --hl: #7fbf7f; }
+          .expr.depth-2 { --hl: #6fa8ff; }
+          .expr.depth-3 { --hl: #ffb347; }
+          .expr.depth-4 { --hl: #d78bff; }
+          .expr.depth-5 { --hl: #ff6f91; }
+          .expr.active { background: rgba(127, 191, 127, 0.15); box-shadow: inset 0 -2px var(--hl, #7fbf7f); }
+          .marker { position: relative; display: inline-block; margin-left: 4px; cursor: help; font-size: 10px; line-height: 1; user-select: none; -webkit-user-select: none; -moz-user-select: none; }
+          .marker .tooltip {
+            display: none;
+            position: absolute;
+            left: 0;
+            top: 100%;
+            margin-top: 4px;
+            background: #2b2b2b;
+            color: #fff;
+            padding: 4px 6px;
+            border-radius: 4px;
+            font-size: 12px;
+            white-space: pre;
+            min-width: 16ch;
+            max-width: 90vw;
+            overflow-x: auto;
+            overflow-y: hidden;
+            z-index: 10;
+            pointer-events: auto;
+          }
+          .marker:hover .tooltip,
+          .marker:focus-within .tooltip,
+          .marker .tooltip:hover { display: block; }
+        </style>
+      </head>
+      <body>
+        <div class="hint">Hover highlighted text to see recorded values.</div>
+        <pre class="code"><code>
+      #{html_lines.join("")}
+        </code></pre>
+        <script>
+          (function() {
+            document.querySelectorAll('.marker').forEach(marker => {
+              marker.addEventListener('mouseenter', () => {
+                document.querySelectorAll('.expr').forEach(e => e.classList.remove('active'));
+                marker.closest('.expr')?.classList.add('active');
+              });
+              marker.addEventListener('mouseleave', () => {
+                marker.closest('.expr')?.classList.remove('active');
+              });
+            });
+          })();
+        </script>
+      </body>
+      </html>
+    HTML
+  end
+
+  def self.esc(s)
+    s.to_s
+      .gsub("&", "&amp;")
+      .gsub("<", "&lt;")
+      .gsub(">", "&gt;")
+      .gsub('"', "&quot;")
+  end
+
+  def self.format_value(v)
+    case v
+    when NilClass
+      "nil"
+    else
+      v.to_s
+    end
+  end
+
+  def self.render_line_with_events(line_text, events)
+    opens = Hash.new { |h, k| h[k] = [] }
+    closes = Hash.new { |h, k| h[k] = [] }
+
+    events.each do |e|
+      s = e[:start_col].to_i
+      t = e[:end_col].to_i
+      next if t <= s
+
+      values = e[:values]
+      total = e[:total]
+      value_text = summarize_values(values, total)
+      tooltip_html = esc(value_text)
+      depth_class = "depth-#{e[:depth]}"
+      open_tag = "<span class=\"expr hit #{depth_class}\">"
+      close_tag = "<span class=\"marker\" aria-hidden=\"true\">🔎<span class=\"tooltip\">#{tooltip_html}</span></span></span>"
+
+      len = t - s
+      opens[s] << { len: len, start: s, end: t, tag: open_tag }
+      closes[t] << { len: len, start: s, end: t, tag: close_tag }
+    end
+
+    positions = (opens.keys + closes.keys).uniq.sort
+    out = +""
+    cursor = 0
+
+    positions.each do |pos|
+      out << esc(line_text[cursor...pos]) if pos > cursor
+      if closes.key?(pos)
+        closes[pos].sort_by { |c| [-c[:start], c[:len]] }.each { |c| out << c[:tag] }
+      end
+      if opens.key?(pos)
+        opens[pos].sort_by { |o| -o[:end] }.each { |o| out << o[:tag] }
+      end
+      cursor = pos
+    end
+
+    out << esc(line_text[cursor..]) if cursor < line_text.length
+    out
+  end
+
+  def self.summarize_values(values, total = nil)
+    return "" if values.nil? || values.empty?
+    total ||= values.length
+    last_vals = values.last(3)
+    first_index = total - last_vals.length + 1
+    lines = []
+    extra = total - last_vals.length
+    lines << "... (+#{extra} more)" if extra > 0
+    last_vals.each_with_index do |v, i|
+      idx = first_index + i
+      lines << "##{idx}: #{format_value(v)}"
+    end
+    lines.join("\n")
+  end
+
+  def self.aggregate_events_for_line(events, lineno, line_len)
+    buckets = {}
+    spans = []
+
+    events.each do |e|
+      sline = e[:start_line]
+      eline = e[:end_line]
+      next if lineno < sline || lineno > eline
+
+      if sline == eline
+        s = e[:start_col]
+        t = e[:end_col]
+      else
+        if lineno == sline
+          s = e[:start_col]
+          t = line_len
+        elsif lineno == eline
+          s = 0
+          t = e[:end_col]
+        else
+          s = 0
+          t = line_len
+        end
+      end
+
+      next if t <= s
+      spans << { start_col: s, end_col: t }
+      buckets[e[:key]] = {
+        key: e[:key],
+        start_col: s,
+        end_col: t,
+        values: e[:values],
+        total: e[:total]
+      }
+    end
+
+    buckets.values.each do |b|
+      depth = spans.count { |sp| b[:start_col] >= sp[:start_col] && b[:end_col] <= sp[:end_col] }
+      b[:depth] = [[depth, 1].max, 5].min
+    end
+
+    buckets.values.sort_by { |b| b[:start_col] }
+  end
+
+  def self.normalize_events(events)
+    merged = {}
+    events.each do |e|
+      file = e["file"] || e[:file]
+      start_line = e["start_line"] || e[:start_line]
+      start_col = e["start_col"] || e[:start_col]
+      end_line = e["end_line"] || e[:end_line]
+      end_col = e["end_col"] || e[:end_col]
+      key = [
+        file,
+        start_line.to_i,
+        start_col.to_i,
+        end_line.to_i,
+        end_col.to_i
+      ]
+      entry = (merged[key] ||= {
+        key: key,
+        file: key[0],
+        start_line: key[1],
+        start_col: key[2],
+        end_line: key[3],
+        end_col: key[4],
+        values: [],
+        total: 0
+      })
+
+      vals = e["values"] || e[:values] || [e["value"] || e[:value]].compact
+      entry[:values].concat(vals)
+      entry[:total] += (e["total"] || e[:total] || vals.length)
+    end
+    merged.values
+  end
+
+  def self.normalize_ranges(ranges)
+    return nil unless ranges
+    ranges.map do |r|
+      a = (r.respond_to?(:begin) ? r.begin : r[0]).to_i
+      b = (r.respond_to?(:end) ? r.end : r[1]).to_i
+      a <= b ? [a, b] : [b, a]
+    end
+  end
+
+  def self.normalize_ranges_by_file(input)
+    return nil unless input
+    input.each_with_object({}) do |(file, ranges), h|
+      abs = File.expand_path(file)
+      if ranges.nil? || ranges.empty?
+        h[abs] = []
+      else
+        h[abs] = normalize_ranges(ranges)
+      end
+    end
+  end
+
+  def self.line_in_ranges?(line, ranges)
+    return true if ranges.empty?
+    ranges.any? { |(s, e)| line >= s && line <= e }
+  end
+
+  def self.render_all(events_path, root: Dir.pwd, ranges_by_file: nil)
+    raw_events = JSON.parse(File.read(events_path))
+    events = normalize_events(raw_events)
+    render_all_from_events(events, root: root, ranges_by_file: ranges_by_file)
+  end
+
+  def self.render_all_from_events(events, root: Dir.pwd, ranges_by_file: nil)
+    events = normalize_events(events)
+    by_file = events.group_by { |e| e[:file] }
+    ranges_by_file = normalize_ranges_by_file(ranges_by_file)
+
+    target_paths = if ranges_by_file
+      ranges_by_file.keys
+    else
+      by_file.keys
+    end
+
+    sections = target_paths.sort.map do |path|
+      next unless File.exist?(path)
+      src = File.read(path)
+      ranges = ranges_by_file ? (ranges_by_file[path] || []) : nil
+      html_lines = src.lines.each_with_index.map do |line, idx|
+        lineno = idx + 1
+        next if ranges && !line_in_ranges?(lineno, ranges)
+        line_text = line.chomp
+        evs = aggregate_events_for_line(by_file[path] || [], lineno, line_text.length)
+        if evs.empty?
+          "<span class=\"line\" data-line=\"#{lineno}\"><span class=\"ln\">#{lineno}</span> #{esc(line_text)}</span>\n"
+        else
+          rendered = render_line_with_events(line_text, evs)
+          "<span class=\"line hit\" data-line=\"#{lineno}\"><span class=\"ln\">#{lineno}</span> #{rendered}</span>\n"
+        end
+      end.compact
+
+      rel = path.start_with?(root) ? path.sub(root + File::SEPARATOR, "") : path
+      <<~HTML
+        <h2 class="file">#{esc(rel)}</h2>
+        <pre class="code"><code>
+      #{html_lines.join("")}
+        </code></pre>
+      HTML
+    end.compact.join("\n")
+
+    <<~HTML
+      <!doctype html>
+      <html>
+      <head>
+        <meta charset="utf-8">
+        <title>Recorded Result View</title>
+        <style>
+          body { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; background: #f7f5f0; color: #1f1f1f; padding: 24px; }
+          .code { background: #fffdf7; border: 1px solid #e5dfd0; border-radius: 8px; padding: 16px; line-height: 1.5; }
+          .line { display: inline; padding: 2px 8px; }
+          .line:hover { background: #fff2c6; }
+          .line.hit { background: #f0ffe7; }
+          .ln { display: inline-block; width: 3em; color: #888; user-select: none; }
+          .hint { color: #666; margin-bottom: 8px; }
+          .file { margin: 24px 0 8px; font-size: 16px; color: #333; }
+          .expr { position: relative; display: inline-block; padding-bottom: 1px; }
+          .expr.hit { }
+          .expr.depth-1 { --hl: #7fbf7f; }
+          .expr.depth-2 { --hl: #6fa8ff; }
+          .expr.depth-3 { --hl: #ffb347; }
+          .expr.depth-4 { --hl: #d78bff; }
+          .expr.depth-5 { --hl: #ff6f91; }
+          .expr.active { background: rgba(127, 191, 127, 0.15); box-shadow: inset 0 -2px var(--hl, #7fbf7f); }
+          .marker { position: relative; display: inline-block; margin-left: 4px; cursor: help; font-size: 10px; line-height: 1; user-select: none; -webkit-user-select: none; -moz-user-select: none; }
+          .marker .tooltip {
+            display: none;
+            position: absolute;
+            left: 0;
+            top: 100%;
+            margin-top: 4px;
+            background: #2b2b2b;
+            color: #fff;
+            padding: 4px 6px;
+            border-radius: 4px;
+            font-size: 12px;
+            white-space: pre;
+            min-width: 16ch;
+            max-width: 90vw;
+            overflow-x: auto;
+            overflow-y: hidden;
+            z-index: 10;
+            pointer-events: auto;
+          }
+          .marker:hover .tooltip,
+          .marker:focus-within .tooltip,
+          .marker .tooltip:hover { display: block; }
+        </style>
+      </head>
+      <body>
+        <div class="hint">Hover highlighted text to see recorded values.</div>
+        #{sections}
+        <script>
+          (function() {
+            document.querySelectorAll('.marker').forEach(marker => {
+              marker.addEventListener('mouseenter', () => {
+                document.querySelectorAll('.expr').forEach(e => e.classList.remove('active'));
+                marker.closest('.expr')?.classList.add('active');
+              });
+              marker.addEventListener('mouseleave', () => {
+                marker.closest('.expr')?.classList.remove('active');
+              });
+            });
+          })();
+        </script>
+      </body>
+      </html>
+    HTML
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  source_path = ARGV[0] or abort "usage: ruby generate_resulted_html.rb SOURCE_PATH EVENTS_PATH"
+  events_path = ARGV[1] or abort "usage: ruby generate_resulted_html.rb SOURCE_PATH EVENTS_PATH"
+  puts GenerateResultedHtml.render(source_path, events_path)
+end
+end

data/lib/lumitrace/record_instrument.rb

@@ -0,0 +1,234 @@
+require "json"
+require "prism"
+
+module Lumitrace
+module RecordInstrument
+  SKIP_NODE_CLASSES = [
+    Prism::DefNode,
+    Prism::ClassNode,
+    Prism::ModuleNode,
+    Prism::IfNode,
+    Prism::UnlessNode,
+    Prism::WhileNode,
+    Prism::UntilNode,
+    Prism::ForNode,
+    Prism::CaseNode,
+    Prism::BeginNode,
+    Prism::RescueNode,
+    Prism::EnsureNode,
+    Prism::AliasMethodNode,
+    Prism::UndefNode
+  ].freeze
+
+  LITERAL_NODE_CLASSES = [
+    Prism::IntegerNode,
+    Prism::FloatNode,
+    Prism::RationalNode,
+    Prism::ImaginaryNode,
+    Prism::StringNode,
+    Prism::SymbolNode,
+    Prism::TrueNode,
+    Prism::FalseNode,
+    Prism::NilNode
+  ].freeze
+
+  WRAP_NODE_CLASSES = [
+    Prism::CallNode,
+    Prism::LocalVariableReadNode,
+    Prism::ConstantReadNode,
+    Prism::InstanceVariableReadNode,
+    Prism::ClassVariableReadNode,
+    Prism::GlobalVariableReadNode
+  ].freeze
+
+  def self.instrument_source(src, ranges, file_label: nil, record_method: "Lumitrace::RecordInstrument.expr_record")
+    file_label ||= "(unknown)"
+    ranges = normalize_ranges(ranges)
+
+    parse = Prism.parse(src)
+    if parse.errors.any?
+      raise "parse errors: #{parse.errors.map(&:message).join(", ") }"
+    end
+
+    inserts = collect_inserts(parse.value, src, ranges, file_label, record_method)
+
+    apply_insertions(src, inserts)
+  end
+
+  def self.collect_inserts(root, src, ranges, file_label, record_method)
+    inserts = []
+    stack = [[root, nil]]
+
+    until stack.empty?
+      node, parent = stack.pop
+      next unless node
+
+      if node.respond_to?(:location)
+        line = node.location.start_line
+        if in_ranges?(line, ranges) && wrap_expr?(node, parent)
+          loc = expr_location(node)
+          prefix = "#{record_method}(\"#{file_label}\", #{loc[:start_line]}, #{loc[:start_col]}, #{loc[:end_line]}, #{loc[:end_col]}, ("
+          suffix = "))"
+          span_len = loc[:end_offset] - loc[:start_offset]
+          inserts << { pos: loc[:start_offset], text: prefix, kind: :open, len: span_len }
+          inserts << { pos: loc[:end_offset], text: suffix, kind: :close, len: span_len }
+        end
+      end
+
+      node.child_nodes.each { |child| stack << [child, node] }
+    end
+
+    inserts
+  end
+
+  def self.normalize_ranges(ranges)
+    ranges.map do |r|
+      a = r[0].to_i
+      b = r[1].to_i
+      a <= b ? [a, b] : [b, a]
+    end
+  end
+
+  def self.in_ranges?(line, ranges)
+    return true if ranges.empty?
+    ranges.any? { |(s, e)| line >= s && line <= e }
+  end
+
+  def self.apply_insertions(src, inserts)
+    out = src.dup
+    kind_order = { open: 0, close: 1 }
+    inserts.sort_by do |i|
+      [
+        -i[:pos],
+        kind_order[i[:kind]],
+        i[:kind] == :open ? i[:len] : -i[:len]
+      ]
+    end.each do |i|
+      out.insert(i[:pos], i[:text])
+    end
+    out
+  end
+
+  def self.literal_value_node?(node)
+    LITERAL_NODE_CLASSES.include?(node.class)
+  end
+
+  def self.wrap_expr?(node, parent = nil)
+    return false unless node.respond_to?(:location)
+    return false if literal_value_node?(node)
+    return false if node.is_a?(Prism::CallNode) && has_block_with_body?(node)
+    if node.is_a?(Prism::ConstantReadNode) &&
+       (parent.is_a?(Prism::ClassNode) || parent.is_a?(Prism::ModuleNode))
+      return false
+    end
+    WRAP_NODE_CLASSES.include?(node.class)
+  end
+
+  def self.expr_location(node)
+    loc = node.location
+    return {
+      start_offset: loc.start_offset,
+      end_offset: loc.start_offset + loc.length,
+      start_line: loc.start_line,
+      start_col: loc.start_column,
+      end_line: loc.end_line,
+      end_col: loc.end_column
+    } unless node.is_a?(Prism::CallNode)
+
+    best = loc
+    [node.arguments&.location, node.block&.location, node.closing_loc].compact.each do |l|
+      next unless l
+      best = l if (l.start_offset + l.length) >= (best.start_offset + best.length)
+    end
+
+    {
+      start_offset: loc.start_offset,
+      end_offset: best.start_offset + best.length,
+      start_line: loc.start_line,
+      start_col: loc.start_column,
+      end_line: best.end_line,
+      end_col: best.end_column
+    }
+  end
+
+  def self.has_block_with_body?(call_node)
+    block = call_node.child_nodes.find { |n| n.is_a?(Prism::BlockNode) }
+    block && block.body.is_a?(Prism::StatementsNode)
+  end
+
+  @events_by_key = {}
+  @max_values_per_expr = 3
+
+  def self.max_values_per_expr=(n)
+    @max_values_per_expr = n.to_i if n && n.to_i > 0
+  end
+
+  def self.max_values_per_expr
+    @max_values_per_expr
+  end
+
+  def self.expr_record(file, start_line, start_col, end_line, end_col, value)
+    key = [file, start_line, start_col, end_line, end_col]
+    entry = (@events_by_key[key] ||= {
+      file: file,
+      start_line: start_line,
+      start_col: start_col,
+      end_line: end_line,
+      end_col: end_col,
+      values: [],
+      total: 0
+    })
+
+    entry[:total] += 1
+    entry[:values] << safe_value(value)
+    if entry[:values].length > @max_values_per_expr
+      entry[:values].shift(entry[:values].length - @max_values_per_expr)
+    end
+    value
+  end
+
+  def self.dump_json(path = nil)
+    path ||= File.expand_path("lumitrace_recorded.json", Dir.pwd)
+    File.write(path, JSON.dump(@events_by_key.values))
+    path
+  end
+
+  def self.events
+    @events_by_key.values.map do |e|
+      {
+        file: e[:file],
+        start_line: e[:start_line],
+        start_col: e[:start_col],
+        end_line: e[:end_line],
+        end_col: e[:end_col],
+        values: e[:values].dup,
+        total: e[:total]
+      }
+    end
+  end
+
+  def self.safe_value(v)
+    case v
+    when String
+      v.bytesize > 1000 ? v[0, 1000] + "..." : v
+    when Numeric, TrueClass, FalseClass, NilClass
+      v
+    else
+      v.inspect
+    end
+  end
+end
+end
+
+if $PROGRAM_NAME == __FILE__
+  path = ARGV[0] or abort "usage: ruby record_instrument.rb FILE RANGES_JSON [record_method] [out_path]"
+  ranges = JSON.parse(ARGV[1] || "[]")
+  record_method = ARGV[2] || "Lumitrace::RecordInstrument.expr_record"
+  out = RecordInstrument.instrument_source(File.read(path), ranges, file_label: path, record_method: record_method)
+
+  if ARGV[3]
+    File.write(ARGV[3], out)
+  else
+    puts out
+  end
+end

data/lib/lumitrace/record_require.rb

@@ -0,0 +1,110 @@
+require "json"
+require "prism"
+require_relative "./record_instrument"
+
+module Lumitrace
+module RecordRequire
+  @enabled = false
+  @processed = {}
+  @root = File.expand_path(ENV.fetch("LUMITRACE_ROOT", Dir.pwd))
+  @tool_root = File.expand_path(__dir__)
+  @ranges_by_file = {}
+  @ranges_filtering = false
+
+  def self.enable(max_values: nil, ranges_by_file: nil)
+    return if @enabled
+    RecordInstrument.max_values_per_expr = max_values if max_values
+    if ranges_by_file
+      @ranges_by_file = normalize_ranges_by_file(ranges_by_file)
+      @ranges_filtering = true
+    else
+      @ranges_by_file = {}
+      @ranges_filtering = false
+    end
+    @enabled = true
+  end
+
+  def self.ranges_for(path)
+    return [] unless @ranges_filtering
+    @ranges_by_file[File.expand_path(path)] || []
+  end
+
+  def self.ranges_filtering?
+    @ranges_filtering
+  end
+
+  def self.listed_file?(path)
+    @ranges_by_file.key?(File.expand_path(path))
+  end
+
+  def self.normalize_ranges_by_file(input)
+    return {} unless input
+    input.each_with_object({}) do |(file, ranges), h|
+      next unless file
+      abs = File.expand_path(file)
+      if ranges.nil? || ranges.empty?
+        h[abs] = []
+      else
+        h[abs] = ranges.map { |r| [r.begin, r.end] }
+      end
+    end
+  end
+
+  def self.disable
+    @enabled = false
+  end
+
+  def self.enabled?
+    @enabled
+  end
+
+  def self.in_root?(path)
+    abs = File.expand_path(path)
+    abs.start_with?(@root + File::SEPARATOR)
+  end
+
+  def self.excluded?(path)
+    abs = File.expand_path(path)
+    abs.start_with?(@tool_root + File::SEPARATOR)
+  end
+
+  def self.already_processed?(path)
+    @processed[path]
+  end
+
+  def self.mark_processed(path)
+    @processed[path] = true
+  end
+end
+
+if defined?(RubyVM::InstructionSequence)
+  class RubyVM::InstructionSequence
+    class << self
+      if respond_to?(:translate)
+        alias_method :recordrequire_orig_translate, :translate
+      end
+
+      def translate(iseq)
+        return recordrequire_orig_translate(iseq) if respond_to?(:recordrequire_orig_translate) && !RecordRequire.enabled?
+        path = iseq.path
+        abs = File.expand_path(path)
+        if RecordRequire.in_root?(abs) && !RecordRequire.excluded?(abs) && !RecordRequire.already_processed?(abs) &&
+           (iseq.label == "<main>" || iseq.label == "<top (required)>")
+          if RecordRequire.ranges_filtering? && !RecordRequire.listed_file?(abs)
+            return recordrequire_orig_translate(iseq) if respond_to?(:recordrequire_orig_translate)
+            return nil
+          end
+          RecordRequire.mark_processed(abs)
+          src = File.read(abs)
+          ranges = RecordRequire.ranges_for(abs)
+          modified = RecordInstrument.instrument_source(src, ranges, file_label: abs)
+          return RubyVM::InstructionSequence.compile(modified, abs)
+        end
+        return recordrequire_orig_translate(iseq) if respond_to?(:recordrequire_orig_translate)
+        nil
+      end
+    end
+  end
+end
+
+end

data/lib/lumitrace/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lumitrace
+  VERSION = "0.1.0"
+end

data/lib/lumitrace.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lumitrace/version"
+require_relative "lumitrace/record_instrument"
+require_relative "lumitrace/generate_resulted_html"
+
+module Lumitrace
+  class Error < StandardError; end
+  @atexit_registered = false
+  @atexit_output_root = nil
+  @atexit_ranges_by_file = nil
+
+  def self.enable!(max_values: ENV["LUMITRACE_VALUES_MAX"], ranges_by_file: nil, at_exit: true)
+    require_relative "lumitrace/record_require"
+    RecordRequire.enable(max_values: max_values, ranges_by_file: ranges_by_file)
+    if at_exit
+      @atexit_output_root = Dir.pwd
+      @atexit_ranges_by_file = ranges_by_file
+      unless @atexit_registered
+        at_exit do
+          next unless RecordRequire.enabled?
+          if ENV["LUMITRACE_JSON_OUT"] && !ENV["LUMITRACE_JSON_OUT"].empty?
+            RecordInstrument.dump_json(File.expand_path(ENV["LUMITRACE_JSON_OUT"], @atexit_output_root))
+          end
+          events = RecordInstrument.events
+          html = GenerateResultedHtml.render_all_from_events(
+            events,
+            root: @atexit_output_root,
+            ranges_by_file: @atexit_ranges_by_file
+          )
+          out_path = ENV.fetch("LUMITRACE_HTML_OUT", File.expand_path("lumitrace_recorded.html", @atexit_output_root))
+          File.write(out_path, html)
+        end
+        @atexit_registered = true
+      end
+    end
+  end
+
+  def self.disable!
+    return unless defined?(RecordRequire)
+    RecordRequire.disable
+  end
+end

data/sample_project/.github/workflows/lumitrace-sample.yml

@@ -0,0 +1,38 @@
+name: Lumitrace Sample
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  run-lumitrace:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Run tests with Lumitrace
+        env:
+          LUMITRACE_GIT_DIFF: "range:origin/${{ github.base_ref || HEAD~1 }}...HEAD"
+          LUMITRACE_HTML_OUT: "${{ github.workspace }}/lumitrace_recorded.html"
+        run: RUBYOPT='-r lumitrace/enable_git_diff' bundle exec rake test
+
+      - name: Upload Lumitrace HTML
+        uses: actions/upload-artifact@v4
+        with:
+          name: lumitrace-recorded-html
+          path: lumitrace_recorded.html
+
+      - name: Artifact URL
+        run: |
+          echo "Artifact URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}" >> $GITHUB_STEP_SUMMARY

data/sample_project/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "lumitrace", path: ".."

data/sample_project/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb", "test/**/test_*.rb"]
+  t.verbose = false
+end
+
+task default: :test

data/sample_project/test/test_sample_test.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "../test"
+
+class SampleProjectTest < Minitest::Test
+  def test_compute
+    assert_equal 13, compute(5)
+  end
+end

data/sample_project/test.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+def compute(x)
+  y = x * 2
+  z = y + 3
+  z
+end
+
+puts compute(5)

data/sig/lumitrace.rbs

@@ -0,0 +1,4 @@
+module Lumitrace
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/test/test_lumitrace.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "json"
+require "tmpdir"
+require_relative "../lib/lumitrace"
+
+class LumiTraceTest < Minitest::Test
+  def test_namespaces_loaded
+    assert defined?(Lumitrace::RecordInstrument)
+    assert defined?(Lumitrace::GenerateResultedHtml)
+  end
+
+  def test_instrument_wraps_calls_and_reads
+    src = <<~RUBY
+      def compute(x)
+        v1 = add(x, 2)
+        v2 = mul(v1, 3)
+      end
+    RUBY
+
+    out = Lumitrace::RecordInstrument.instrument_source(src, [], file_label: "sample.rb")
+
+    assert_includes out, "Lumitrace::RecordInstrument.expr_record(\"sample.rb\", 2, 7,"
+    assert_includes out, "Lumitrace::RecordInstrument.expr_record(\"sample.rb\", 2, 11,"
+  end
+
+  def test_render_all_generates_html
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "lumitrace_events.json")
+      sample = File.join(dir, "sample.rb")
+      events = [
+        {
+          "file" => sample,
+          "start_line" => 1,
+          "start_col" => 0,
+          "end_line" => 1,
+          "end_col" => 5,
+          "values" => ["ok"],
+          "total" => 1
+        }
+      ]
+
+      File.write(path, JSON.dump(events))
+      File.write(sample, "puts hi\n")
+
+      html = Lumitrace::GenerateResultedHtml.render_all(path, root: dir)
+      assert_includes html, "Recorded Result View"
+      assert_includes html, "sample.rb"
+    end
+  end
+
+  def test_require_instruments_multiple_files
+    skip "RubyVM::InstructionSequence unavailable" unless defined?(RubyVM::InstructionSequence)
+
+    Dir.mktmpdir do |dir|
+      ENV["LUMITRACE_ROOT"] = dir
+
+      main = File.join(dir, "main.rb")
+      sub = File.join(dir, "sub.rb")
+
+      File.write(sub, <<~RUBY)
+        def sub_value(x)
+          x + 1
+        end
+      RUBY
+
+      File.write(main, <<~RUBY)
+        require_relative "./sub"
+        sub_value(10)
+      RUBY
+
+      Lumitrace.enable!(max_values: 3, at_exit: false)
+      Lumitrace::RecordInstrument.instance_variable_set(:@events_by_key, {})
+
+      load main
+
+      out = File.join(dir, "events.json")
+      Lumitrace::RecordInstrument.dump_json(out)
+      events = JSON.parse(File.read(out))
+      files = events.map { |e| e["file"] }.uniq
+
+      assert_includes files, main
+      assert_includes files, sub
+    end
+  ensure
+    ENV.delete("LUMITRACE_ROOT")
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: lumitrace
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Koichi Sasada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Inline expression tracing for Ruby
+email:
+- ko1@atdot.net
+executables:
+- lumitrace
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- exe/lumitrace
+- lib/lumitrace.rb
+- lib/lumitrace/enable.rb
+- lib/lumitrace/enable_git_diff.rb
+- lib/lumitrace/generate_resulted_html.rb
+- lib/lumitrace/record_instrument.rb
+- lib/lumitrace/record_require.rb
+- lib/lumitrace/version.rb
+- sample_project/.github/workflows/lumitrace-sample.yml
+- sample_project/Gemfile
+- sample_project/Rakefile
+- sample_project/test.rb
+- sample_project/test/test_sample_test.rb
+- sig/lumitrace.rbs
+- test/test_lumitrace.rb
+homepage: https://github.com/ko1/lumitrace
+licenses: []
+metadata:
+  homepage_uri: https://github.com/ko1/lumitrace
+  source_code_uri: https://github.com/ko1/lumitrace
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Inline expression tracing for Ruby
+test_files: []