lumitrace 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ffc13efecd8f5143486eff6929c93bf73aaa3934bf24fa57e906a2f90498e2c
-  data.tar.gz: df8ce2960f59409dc832d21f9d1df7a2b33cc431fde00c76633f1149a5da3ab3
+  metadata.gz: ff34ab7d27bf0d9882368d03a66d0409cb093c5d0850f896e4be79d19a06753d
+  data.tar.gz: ec55e6059af4babd1ab074d74b17104a1a6b36e576c55d32a44b4f53a3227855
 SHA512:
-  metadata.gz: 2030ec337dc9a941f1c9878b1faa74e15e605a715e1d2049675115573c7c1357d821ded3a200b348521a9593faf6f719ff93766f5ffe1c623d9a9c6dcaa663b1
-  data.tar.gz: 68564fe5bde3b1d00edd5390211c922b72f3565069446affed3dfdf042fc86491949f8170e175df8cdd99c55b1c05f030adab69fe140ce05cfd003f3f3a51719
+  metadata.gz: 26c2710ee8a470ae316541d1d833556a14a19f87d775b88904cd06816c4e192b3dd9c6f9f07811235d4350acb1341c78a8b2e7ef47a7880369871280afe7f0b9
+  data.tar.gz: d30d9161e9ab43473004b0a694fe7269aa3255ce9763f746b3233d6e6eebf218b06d885a4913c7401a74de5a23bc425ed5435c6aa91297422dd17ee32d186642

data/README.md

@@ -93,7 +93,7 @@ require "lumitrace/enable"
 - `LUMITRACE_HTML`: enable HTML output; `1` uses the default path, otherwise treats the value as the HTML output path. `0`/`false` disables.
 - `LUMITRACE_JSON`: enable JSON output; `1` uses the default path, otherwise treats the value as the JSON output path. `0`/`false` disables.
 - `LUMITRACE_ENABLE`: when `1`/`true`, `require "lumitrace"` will call `Lumitrace.enable!`. When set to a non-boolean string, it is parsed as CLI-style arguments and passed to `enable!`.
-- `LUMITRACE_VERBOSE`: when `1`/`true`, prints verbose logs to stderr.
+- `LUMITRACE_VERBOSE`: verbosity level (1-3). `1`/`true` enables basic logs, `2` adds instrumented file names, `3` adds instrumented source output.
 - `LUMITRACE_RANGE`: semicolon-separated range specs (e.g. `a.rb:1-3,5-6;b.rb`).
 - `LUMITRACE_RESULTS_DIR`: internal use. Shared results directory for fork/exec merge (default: `Dir.tmpdir/lumitrace_results/<user>_<parent_pid>`).
 - `LUMITRACE_RESULTS_PARENT_PID`: internal use. Parent PID for fork/exec merge (auto-set).

data/Rakefile

@@ -10,3 +10,28 @@ Rake::TestTask.new do |t|
 end
 
 task default: :test
+
+require "benchmark"
+
+desc "Run simple runtime comparison for lumitrace vs ruby"
+task :bench do
+  sample = File.expand_path("bench/bench_sample.rb", __dir__)
+  unless File.exist?(sample)
+    abort "missing bench/bench_sample.rb"
+  end
+
+  env = {}
+  env["N"] = ENV["N"] if ENV["N"]
+
+  def run_cmd(label, env, cmd)
+    t = Benchmark.realtime do
+      ok = system(env, *cmd, out: File::NULL, err: File::NULL)
+      raise "failed: #{cmd.join(' ')}" unless ok
+    end
+    puts format("%-12s %8.3fs", label, t)
+  end
+
+  puts "N=#{env['N'] || 1000}"
+  run_cmd("ruby", env, ["ruby", sample])
+  run_cmd("lumitrace", env, ["./exe/lumitrace", sample])
+end

data/docs/spec.md

@@ -43,7 +43,7 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
   - `text`: boolean or string or nil. When nil, determined from environment variables. When string, uses it as the text output path.
   - `html`: boolean or string or nil. When nil, determined from environment variables.
   - `json`: boolean or string or nil. When nil, determined from environment variables.
-  - `verbose`: boolean or nil. When nil, determined from `LUMITRACE_VERBOSE`.
+  - `verbose`: integer (level) or nil. When nil, determined from `LUMITRACE_VERBOSE`.
   - `at_exit`: boolean. When true, registers output at exit.
 - Returns: `nil`.
 - Side effects:
@@ -58,7 +58,7 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
   - `LUMITRACE_TEXT`: control text output. `1` forces text on, `0`/`false` disables. If unset, text is enabled only when both HTML and JSON are disabled. Any other value is treated as the text output path.
   - `LUMITRACE_JSON`: enable JSON output; `1` uses the default path, otherwise treats the value as the JSON output path. `0`/`false` disables.
   - `LUMITRACE_GIT_DIFF_UNTRACKED`: include untracked files in git diff ranges (`1` default). Set to `0` to exclude.
-  - `LUMITRACE_VERBOSE`: when `1`/`true`, prints verbose logs to stderr.
+  - `LUMITRACE_VERBOSE`: verbosity level (1-3). `1`/`true` enables basic logs, `2` adds instrumented file names, `3` adds instrumented source output.
   - `LUMITRACE_ENABLE`: when `1`/`true`, `require "lumitrace"` will call `Lumitrace.enable!`. When set to a non-boolean string, it is parsed as CLI-style arguments and passed to `enable!`.
   - `LUMITRACE_RANGE`: semicolon-separated range specs, e.g. `a.rb:1-3,5-6;b.rb`.
   - `LUMITRACE_RESULTS_DIR`: internal use. Shared results directory for fork/exec merge (default: `Dir.tmpdir/lumitrace_results/<user>_<parent_pid>`).
@@ -115,7 +115,7 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
 
 - AST is parsed with Prism.
 - For each node, if it matches “wrapable” expression classes, injects:
-  - `RecordInstrument.expr_record(file, start_line, start_col, end_line, end_col, (expr))`
+  - `Lumitrace::R(id, (expr))` where `id` maps to location metadata.
 - Insertions are done by offset to preserve original formatting.
 
 ### Range Filtering
@@ -140,7 +140,7 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
 ## Recording
 
 - Results are stored per expression key:
-  - `(file, start_line, start_col, end_line, end_col)`
+  - `id` (an integer assigned at instrumentation time) with a separate `id -> location` table.
 - Keep only the last N values (`max_values_per_expr`, default 3).
 - Track `total` count for how many times the expression executed.
 - Values are stored via `inspect` for non-primitive types.
@@ -190,7 +190,7 @@ lumitrace [options] exec CMD [args...]
 - `--git-diff-context` expands hunks by +/-N lines.
 - `--git-cmd` overrides the git executable.
 - `--git-diff-no-untracked` excludes untracked files (untracked files are included by default).
-- `--verbose` prints verbose logs to stderr.
+- `--verbose[=LEVEL]` prints verbose logs to stderr (level 1-3).
 - `LUMITRACE_VALUES_MAX` sets the default max values per expression.
 - The CLI launches a child process (Ruby or `exec` target) with `RUBYOPT=-rlumitrace` and `LUMITRACE_*` env vars.
 

data/docs/supported_syntax.md

@@ -4,7 +4,7 @@
 # Supported Syntax
 
 Lumitrace instruments Ruby source by wrapping selected expression nodes with
-`Lumitrace::RecordInstrument.expr_record(...)`. It does **not** rewrite the
+`Lumitrace::R(id, (expr))`. It does **not** rewrite the
 entire AST, so coverage is best described as "expressions that are safe to wrap
 in parentheses and call-position contexts."
 

data/docs/tutorial.ja.md

@@ -7,6 +7,8 @@
 
 ## 1. クイックスタート（CLI）
 
+まずは最小のコマンドで動かして、出力形式の雰囲気を掴みます。
+
 同梱の sample を最小のコマンドで実行します（テキストは stdout に出ます）:
 
 ```bash
@@ -16,9 +18,18 @@ lumitrace sample/sample.rb
 プログラム本体の stdout はそのまま出力され、続けて Lumitrace のテキストが表示されます。
 
 テキスト出力の形式:
-- 各ファイルの見出しは `### path/to/file.rb`。
-- 行頭に行番号が付きます（例: ` 12| `）。
-- 範囲が飛ぶ場合は `...` の行が入ります。
+- 各ファイルの見出しは次のように表示されます:
+  ```
+  ### path/to/file.rb
+  ```
+- 行頭に行番号が付きます（例）:
+  ```
+   12| 
+  ```
+- 範囲が飛ぶ場合は次の行が入ります:
+  ```
+  ...
+  ```
 - 最終値は `#=> ...` で表示され、複数回実行された場合は `(3rd run)` が付きます。
 
 出力例（stdout）:
@@ -95,6 +106,8 @@ n0=2, n1=5, n2=11
 
 ### ファイルに保存
 
+結果をあとで見返したり共有したいときは、テキストと HTML をディスクに書き出すのが便利です。
+
 同梱の sample を実行して、テキストと HTML を保存します:
 
 ```bash
@@ -112,6 +125,8 @@ HTML 出力を見る:
 
 ### 範囲指定の例
 
+出力が多いときは、対象行を絞って読みやすくします。
+
 範囲を指定して、別の出力として保存します:
 
 ```bash
@@ -162,18 +177,30 @@ LUMITRACE_HTML=/tmp/out.html lumitrace path/to/entry.rb
 
 ### 記録する値の数を減らす
 
+出力が長すぎたり読みづらいときに、1 行あたりの記録数を制限します。
+
 ```bash
 LUMITRACE_VALUES_MAX=5 lumitrace path/to/entry.rb
 ```
 
 ### 行範囲を限定する
 
+特定の行だけを明示的に追いたいときの指定です。
+
 ```bash
 lumitrace --range path/to/entry.rb:10-20,30-35 path/to/entry.rb
 ```
 
+別コマンドをラップするときは、環境変数で range を渡せます（`;` 区切り）:
+
+```bash
+LUMITRACE_RANGE="a.rb:1-3,5-6;b.rb" ruby your_script.rb
+```
+
 ### 差分だけ計測（CLI）
 
+変更行だけを自動で追うと、レビュー時のノイズが減ります。
+
 ```bash
 lumitrace -g path/to/entry.rb
 lumitrace --git-diff=staged path/to/entry.rb
@@ -190,12 +217,16 @@ lumitrace -g --git-diff-no-untracked path/to/entry.rb
 
 ### 詳細ログ
 
+レンジ計算や動作の理由を追いたいときに有効です。
+
 ```bash
 lumitrace --verbose path/to/entry.rb
 ```
 
 ### JSON も出力する
 
+ツール連携や後処理のために JSON を出します。
+
 ```bash
 lumitrace -j path/to/entry.rb
 ```
@@ -204,24 +235,32 @@ lumitrace -j path/to/entry.rb
 
 ### stdout にテキスト出力
 
+端末でさっと確認したいとき向けです。
+
 ```bash
 lumitrace -t path/to/entry.rb
 ```
 
 ### テキストをファイルに出力
 
+CI アーティファクトなどに残したいときに便利です。
+
 ```bash
 lumitrace --text=/tmp/lumi.txt path/to/entry.rb
 ```
 
 ### テキストと HTML を両方出力
 
+素早い確認と詳細閲覧を一回で得たいときに使います。
+
 ```bash
 lumitrace -t -h path/to/entry.rb
 ```
 
 ### exec で実行
 
+テストなど別コマンドをラップして計測します。
+
 ```bash
 lumitrace --html=sample/lumitrace_rake.html exec rake
 ```
@@ -229,18 +268,23 @@ lumitrace --html=sample/lumitrace_rake.html exec rake
 HTML 出力:
 - [lumitrace_rake.html](https://ko1.github.io/lumitrace/sample/lumitrace_rake.html)
 
-### Fork/exec のマージ
+### GitHub Actions
 
-fork/exec の結果はデフォルトでマージされます。親プロセスが最終出力を行い、子プロセスは `LUMITRACE_RESULTS_DIR` に断片 JSON を保存します。
+CI で差分ログを出し、Pages で HTML を共有したいときの導線です。
 
-環境変数で range を渡す場合（`;` 区切り）:
+GitHub Actions への追加手順（`LUMITRACE_GIT_DIFF` や Pages へのアップロード設定を含む）は `sample/sample_project/README.md` を参照してください。公開済み Pages はこちらです:
+[https://ko1.github.io/lumitrace_sample_project/](https://ko1.github.io/lumitrace_sample_project/)
 
-```bash
-LUMITRACE_RANGE="a.rb:1-3,5-6;b.rb" ruby your_script.rb
-```
+### Fork/exec のマージ
+
+プロセスが増える構成のとき、結果がどう合流するかを押さえます。
+
+fork/exec の結果はデフォルトでマージされます。親プロセスが最終出力を行い、子プロセスは `LUMITRACE_RESULTS_DIR` に断片 JSON を保存します。
 
 ## 2. ライブラリとして使う
 
+CLI を使わずアプリに組み込みたい場合はここから始めます。
+
 終了時にテキストを出力する設定:
 
 ```ruby
@@ -303,10 +347,12 @@ ENV["LUMITRACE_ENABLE"] = "-t --html=/tmp/lumi.html -j"
 require "lumitrace"
 ```
 
-exec 先でも読み込まれるように、Lumitrace は `RUBYOPT=-rlumitrace` を設定します。
+exec 先でも読み込まれるように、Lumitrace は `RUBYOPT=-rlumitrace` を設定します。これにより fork/exec の結果をマージできます。
 
 ### 出力先を変更する
 
+用途に合わせて HTML/JSON/テキストの保存先を変えられます。
+
 ```bash
 LUMITRACE_HTML=/tmp/lumi.html ruby your_script.rb
 ```
@@ -320,6 +366,8 @@ Lumitrace.enable!(json: "/tmp/lumi.json")
 
 ## 3. 差分だけ計測（git diff）
 
+ライブラリ側で `git diff` に連動させ、変更行だけを追う方法です。
+
 現在のプログラムファイルに対する `git diff` の範囲だけを有効化します。
 
 ```ruby
@@ -334,12 +382,16 @@ LUMITRACE_GIT_DIFF=staged ruby your_script.rb
 
 ### 差分前後の行数を広げる
 
+前後の文脈も含めたいときに範囲を広げます。
+
 ```bash
 LUMITRACE_GIT_DIFF_CONTEXT=5 ruby your_script.rb
 ```
 
 ## 4. ルート範囲
 
+計測対象のディレクトリ範囲を明確にしたいときに使います。
+
 デフォルトは現在のディレクトリ配下のみ計測します。
 別のルートを指定したい場合:
 
@@ -355,5 +407,7 @@ lumitrace --root /path/to/project your_script.rb
 
 ## 5. Tips
 
+日常的に効く小さなコツをまとめます。
+
 - 出力が大きい場合は `LUMITRACE_VALUES_MAX` を下げると軽くなります。
 - 1 ファイルだけの確認は `enable_git_diff` が便利です。

data/docs/tutorial.md

@@ -7,6 +7,8 @@ This is a short, practical guide to using Lumitrace.
 
 ## 1. Quick Start (CLI)
 
+Start here to see what Lumitrace does in one command and what the default text output looks like.
+
 Run the bundled sample with the simplest command (text output goes to stdout by default):
 
 ```bash
@@ -16,9 +18,18 @@ lumitrace sample/sample.rb
 The program’s own stdout is still printed, and Lumitrace text output follows it.
 
 Text output format:
-- Each file header is `### path/to/file.rb`.
-- Each line is prefixed with a line number like ` 12| `.
-- Skipped ranges are shown as a line containing `...`.
+- Each file header is shown like:
+  ```
+  ### path/to/file.rb
+  ```
+- Each line is prefixed with a line number like:
+  ```
+   12| 
+  ```
+- Skipped ranges are shown as:
+  ```
+  ...
+  ```
 - The last value is shown as `#=> ...` (with `(3rd run)` when run multiple times).
 
 Example output (stdout):
@@ -95,6 +106,8 @@ n0=2, n1=5, n2=11
 
 ### Save outputs to files
 
+Use this when you want to keep results for review or share them; it writes text and HTML outputs to disk.
+
 Run the bundled sample and write both text and HTML outputs:
 
 ```bash
@@ -112,6 +125,8 @@ View the HTML output:
 
 ### Range example
 
+When a full run is too noisy, narrow the scope to specific line ranges so you can focus on the slice you care about.
+
 Run with ranges and save separate outputs:
 
 ```bash
@@ -162,18 +177,30 @@ LUMITRACE_HTML=/tmp/out.html lumitrace path/to/entry.rb
 
 ### Limit recorded values
 
+If the output is too long or slow to scan, cap how many values per line are recorded.
+
 ```bash
 LUMITRACE_VALUES_MAX=5 lumitrace path/to/entry.rb
 ```
 
 ### Limit to specific lines
 
+Use `--range` when you want precise control over which lines are traced.
+
 ```bash
 lumitrace --range path/to/entry.rb:10-20,30-35 path/to/entry.rb
 ```
 
+You can also pass ranges via env (semicolon-separated) when wrapping another command:
+
+```bash
+LUMITRACE_RANGE="a.rb:1-3,5-6;b.rb" ruby your_script.rb
+```
+
 ### Diff-based ranges
 
+Let Git choose the interesting lines by tracing only changes from `git diff`; this keeps review noise low.
+
 ```bash
 lumitrace -g path/to/entry.rb
 lumitrace --git-diff=staged path/to/entry.rb
@@ -190,12 +217,16 @@ lumitrace -g --git-diff-no-untracked path/to/entry.rb
 
 ### Verbose logs
 
+Turn this on when you need to understand how ranges were computed or why a line was (not) recorded.
+
 ```bash
 lumitrace --verbose path/to/entry.rb
 ```
 
 ### Write JSON too
 
+Use JSON output when you want to post-process results with scripts or other tools.
+
 ```bash
 lumitrace -j path/to/entry.rb
 ```
@@ -204,24 +235,32 @@ This creates `lumitrace_recorded.json`. HTML is written only when `--html` is al
 
 ### Text output to stdout
 
+Choose this for quick, interactive feedback in your terminal.
+
 ```bash
 lumitrace -t path/to/entry.rb
 ```
 
 ### Text output to a file
 
+Send text output to a file when you want to archive results or attach them to CI artifacts.
+
 ```bash
 lumitrace --text=/tmp/lumi.txt path/to/entry.rb
 ```
 
 ### Text plus HTML
 
+Get both the fast terminal view and the richer HTML report in one run.
+
 ```bash
 lumitrace -t -h path/to/entry.rb
 ```
 
 ### Running with exec
 
+Wrap another command (like tests) so Lumitrace instruments what that command runs.
+
 ```bash
 lumitrace --html=sample/lumitrace_rake.html exec rake
 ```
@@ -229,18 +268,22 @@ lumitrace --html=sample/lumitrace_rake.html exec rake
 HTML output:
 - [lumitrace_rake.html](https://ko1.github.io/lumitrace/sample/lumitrace_rake.html)
 
-### Fork/exec merge
+### GitHub Actions
 
-Fork/exec results are merged by default. The parent process writes final output; child processes only write fragments under `LUMITRACE_RESULTS_DIR`.
+Use CI to publish diff-scoped results automatically and share the HTML report via GitHub Pages.
 
-You can pass ranges via env (semicolon-separated):
+For a practical CI setup (including `LUMITRACE_GIT_DIFF` and Pages upload), see `sample/sample_project/README.md`. The published Pages example is here: [https://ko1.github.io/lumitrace_sample_project/](https://ko1.github.io/lumitrace_sample_project/).
 
-```bash
-LUMITRACE_RANGE="a.rb:1-3,5-6;b.rb" ruby your_script.rb
-```
+### Fork/exec merge
+
+If your app forks or execs, this explains how Lumitrace merges results across processes.
+
+Fork/exec results are merged by default. The parent process writes final output; child processes only write fragments under `LUMITRACE_RESULTS_DIR`.
 
 ## 2. Library Mode
 
+Use this when you want to enable Lumitrace inside an app or script without relying on the CLI wrapper.
+
 Enable instrumentation and text output at exit:
 
 ```ruby
@@ -307,6 +350,8 @@ Lumitrace also sets `RUBYOPT=-rlumitrace` to ensure exec'd Ruby processes load i
 
 ### Change output paths
 
+Customize where HTML/JSON/text outputs go when using library mode.
+
 ```bash
 LUMITRACE_HTML=/tmp/lumi.html ruby your_script.rb
 ```
@@ -320,6 +365,8 @@ Lumitrace.enable!(json: "/tmp/lumi.json")
 
 ## 3. Diff-Based Instrumentation
 
+Focus on just the changed lines in your codebase by wiring Lumitrace to `git diff` in library mode.
+
 Enable only lines touched by `git diff` for the current program file:
 
 ```ruby
@@ -334,12 +381,16 @@ LUMITRACE_GIT_DIFF=staged ruby your_script.rb
 
 ### Expand the diff context
 
+Widen the diff window to include surrounding lines for better context.
+
 ```bash
 LUMITRACE_GIT_DIFF_CONTEXT=5 ruby your_script.rb
 ```
 
 ## 4. Root Scope
 
+Limit (or expand) which files are eligible for instrumentation by defining a root directory.
+
 By default, Lumitrace only instruments files under the current directory.
 Override the root with:
 
@@ -355,5 +406,7 @@ lumitrace --root /path/to/project your_script.rb
 
 ## 5. Tips
 
+Small knobs that keep outputs readable and noise low in day-to-day use.
+
 - If your output is large, lower `LUMITRACE_VALUES_MAX`.
 - For quick checks on a single file, `enable_git_diff` keeps noise down.

data/exe/lumitrace

@@ -32,7 +32,7 @@ env["LUMITRACE_HTML"] = opts[:html] == true ? "1" : opts[:html] == false ? "0" :
 env["LUMITRACE_JSON"] = opts[:json] == true ? "1" : opts[:json] == false ? "0" : opts[:json].to_s if !opts[:json].nil?
 env["LUMITRACE_VALUES_MAX"] = opts[:max_values].to_s if opts[:max_values]
 env["LUMITRACE_ROOT"] = opts[:root] if opts[:root]
-env["LUMITRACE_VERBOSE"] = opts[:verbose] ? "1" : "0" if !opts[:verbose].nil?
+env["LUMITRACE_VERBOSE"] = opts[:verbose].to_s if !opts[:verbose].nil?
 if opts[:range_specs].any?
   env["LUMITRACE_RANGE"] = opts[:range_specs].join(";")
 end

data/lib/lumitrace/env.rb

@@ -8,6 +8,14 @@ module Lumitrace
     value
   end
 
+  def self.parse_env_int(value)
+    return nil if value.nil?
+    flag = parse_env_flag(value)
+    return 1 if flag == true
+    return 0 if flag == false
+    flag.to_i
+  end
+
   def self.resolve_env_options
     html_env = parse_env_flag(ENV["LUMITRACE_HTML"])
     json_env = parse_env_flag(ENV["LUMITRACE_JSON"])
@@ -32,7 +40,7 @@ module Lumitrace
       text = (text_env != false)
     end
 
-    verbose = parse_env_flag(ENV["LUMITRACE_VERBOSE"]) == true
+    verbose = parse_env_int(ENV["LUMITRACE_VERBOSE"])
     range_specs = if range_env.nil? || range_env.strip.empty?
       []
     else