lumitrace 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb5fe18ff96f6cea6cac519424f9d7a3ead8e4ce4f9be3ad2db7ddde2804302e
-  data.tar.gz: 17c83251a9b042481e297422f2ddcad5f923a890f52202331e3fc85e28a9e888
+  metadata.gz: bbe02bbc074d7d4ef9a4279ea426500296ea6aca0b560c146140f5e143ea4f8f
+  data.tar.gz: 6d0101d97cf784392d3f62a90edfc29a244b6a6582da9b15800447d8b3ad9175
 SHA512:
-  metadata.gz: eb65e28bfad568fb9aaff142a4ee0150e49b8f37cf8ffb99508c706691a710310119b23826942668874a60a6189a91732367389581bd056a9cdc09592a286d0a
-  data.tar.gz: dbbbfb431b4a957f186a93a849949fac88b54ed8408b9d761550c0eeb76055195f589e4ca9dfdd23152854ed156be6d13172337a555441bf0960d05825ef7332
+  metadata.gz: bb1c57562f18e6827bcf0f425e45ab098182553ba9f44f311f4302f8c919e133903a2dbe97695c37914ad01415709deb68445d6109ccaa1f87a3979bb5dd307a
+  data.tar.gz: 8f863f58547b5e5ab455b07857919383e2784d18dc3c32486b3ff94e84d799deae180938d4c6ef3cb94bac0a8bd8689c5caf0b9e6b11f1dc52ed8f6bcb81c936

data/README.md

@@ -67,7 +67,8 @@ lumitrace help --format json
 lumitrace schema --format json
 ```
 
-AI-oriented usage guide (Japanese):
+AI-oriented usage guide:
+- `docs/tutorial.md` section "Using with AI agents"
 - `docs/tutorial.ja.md` section "AI と使う"
 
 ### Library

data/docs/ai-help.md

@@ -2,7 +2,7 @@
 
 # Lumitrace Help
 
-- Version: 0.4.1
+- Version: 0.6.1
 - Help version: 1
 - Primary JSON entrypoint: `lumitrace help --format json`
 - Schema JSON entrypoint: `lumitrace schema --format json`
@@ -37,11 +37,16 @@
 ## Key Options
 - `--collect-mode` (default="last"; values=last,types,history)
 - `--max-samples` (default=3; Used by history mode.)
-- `--json[=PATH]` (Emit JSON output.)
-- `--html[=PATH]` (Emit HTML output.)
-- `--text[=PATH]` (Emit text output.)
+- `-j, --json[=PATH]` (Emit JSON output.)
+- `-h, --html[=PATH]` (Emit HTML output.)
+- `-t, --text[=PATH]` (Emit text output.)
+- `-g, --git-diff[=MODE]` (Restrict instrumentation to diff hunks.)
 - `--range SPEC` (repeatable=true; Restrict instrumentation to file ranges.)
-- `--git-diff[=MODE]` (Restrict instrumentation to diff hunks.)
+- `--git-diff-context N` (Expand diff hunks by +/-N lines.)
+- `--git-cmd PATH` (Git executable for diff.)
+- `--git-diff-no-untracked` (Exclude untracked files from diff.)
+- `--root PATH` (Root directory for instrumentation.)
+- `--verbose[=LEVEL]` (Verbose logs to stderr (level 1-3).)
 
 ## Examples
 - `lumitrace --collect-mode history --max-samples 5 -j app.rb`

data/docs/ai-schema.md

@@ -2,9 +2,12 @@
 
 # Lumitrace JSON Schema
 
-- Version: 0.4.1
+- Version: 0.6.1
 - Schema version: 1
-- Top level: array of event
+- Top level: object
+  - `version` (integer) - Schema version number.
+  - `events` (array of event) - Traced expression events.
+  - `coverage` (array of coverage_entry) - Per-file coverage summary.
 
 ## Common Event Fields
 - `file` (string, required) - Absolute source path.
@@ -14,9 +17,15 @@
 - `end_col` (integer, required)
 - `kind` (string, required)
 - `name` (string|null, optional) - Present for kind=arg.
-- `total` (integer, required) - Execution count.
+- `total` (integer, required) - Execution count. 0 means the expression was never executed (uncovered).
 - `types` (object, required) - Ruby class name => observed count.
 
+## Coverage Entry Fields
+- `file` (string, required) - Absolute source path.
+- `total_lines` (integer, required) - Number of traced expression lines.
+- `covered_lines` (integer, required) - Lines with total > 0.
+- `coverage_percent` (float, required) - Covered / total * 100, rounded to 1 decimal.
+
 ## Value Summary Fields
 - `type` (string, required) - Ruby class name.
 - `preview` (string, required) - Value preview string (inspect-based).

data/docs/spec.md

@@ -167,7 +167,21 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
 
 ### Output JSON
 
-`lumitrace_recorded.json` contains an array of entries.
+`lumitrace_recorded.json` is a JSON object with the following top-level structure:
+
+```json
+{
+  "version": 1,
+  "events": [ ... ],
+  "coverage": [ ... ]
+}
+```
+
+- `version`: Schema version (currently `1`).
+- `events`: Array of trace event entries (see below).
+- `coverage`: Array of per-file coverage summaries (see below).
+
+#### Event entries
 
 `collect_mode=last` (default):
 
@@ -226,6 +240,24 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
 - `last_value`: summary of the last observed value: `{ type, preview }` (+ `length` only when truncated).
 - `types`: observed Ruby class counts (class name => count).
 - `sampled_values`: retained sample (last N values) of summary objects (`{ type, preview }` + optional `length`) in `history` mode.
+- `total`: total execution count. When `0`, the expression was instrumented but never executed (uncovered).
+
+#### Coverage summary
+
+Each entry in the `coverage` array summarizes line-level coverage for one file:
+
+```json
+{
+  "file": "/path/to/file.rb",
+  "total_lines": 18,
+  "covered_lines": 12,
+  "coverage_percent": 66.7
+}
+```
+
+- `total_lines`: number of lines that contain at least one instrumented expression.
+- `covered_lines`: number of those lines where at least one expression has `total > 0`.
+- `coverage_percent`: `covered_lines / total_lines * 100`, rounded to one decimal place.
 
 ## CLI
 
@@ -274,8 +306,10 @@ lumitrace [options] exec CMD [args...]
   - `Mode: types (type counts)`
   - `Mode: history (last N sample[s])`
   - In `history`, `N` uses configured `max_samples` when available; otherwise it is inferred from the loaded events.
+- When available, the page header also shows the executed command as `Command: ...`.
 - Each file is shown in its own section.
 - When multiple files are present, the HTML UI shows a left file tree and a single-file viewer on the right.
+- Directory nodes in the file tree are expanded by default.
 - Selecting a file in the tree switches the visible file without reloading the page.
 - The selected file is reflected in the URL hash as `#file=...` (using the rendered file path label) so links can open a specific file view.
 - Clicking a line number updates the URL hash to include the selected line (for example `#file=lib/foo.rb&line=42`).
@@ -286,8 +320,10 @@ lumitrace [options] exec CMD [args...]
 - Hovering the icon shows recorded values.
 - Only the last 3 values are shown in the tooltip as `value (Type)`; additional values are summarized as `... (+N more)`.
 - Tooltip is scrollable horizontally for long values.
+- Tooltip is shown above the marker icon (to avoid covering the mouse cursor).
 - When ranges are used, skipped sections are shown as `...` in the line-number column.
 - Lines where all instrumentable expressions are unexecuted are highlighted in a light red. If a line mixes executed and unexecuted expressions, only the unexecuted expressions are highlighted.
+- The page footer includes an attribution link to the Lumitrace site and the Lumitrace version used to generate the report.
 
 ### HTML Payload Schema (`v1`)
 
@@ -332,6 +368,8 @@ lumitrace [options] exec CMD [args...]
   - Human-readable label shown in the HTML header.
 - `meta.max_samples`:
   - Effective/inferred max samples for `history`; may be `null`.
+- `meta.command`:
+  - Optional command line shown in the HTML header (for CLI-generated reports).
 - `files[]`:
   - One entry per rendered source file.
 - `files[].path`:
@@ -367,4 +405,5 @@ lumitrace [options] exec CMD [args...]
 
 - Requires `RubyVM::InstructionSequence.translate` support in the Ruby build.
 - Instrumentation is for debugging; semantics may change for unusual edge cases.
+- Expressions inside `defined?(...)` are intentionally not instrumented to preserve `defined?` semantics.
 - Tool does not attempt to preserve file encoding comments.

data/docs/supported_syntax.md

@@ -112,6 +112,13 @@ These are intentionally skipped to keep output valid Ruby:
     ```
   - The implicit `token` read is **not** instrumented.
 
+- Expressions inside `defined?(...)`:
+  - Example:
+    ```ruby
+    defined?(foo + bar)
+    ```
+  - The operand expression (`foo + bar`) is **not** instrumented, to preserve `defined?` semantics.
+
 ## Rationale
 
 All skips above correspond to syntactic positions where wrapping the token with

data/docs/tutorial.ja.md

@@ -131,9 +131,72 @@ HTML について:
 - 記録対象の式がすべて未実行の行は薄い赤で表示され、混在行では未実行の式のみ薄赤になります。
 - 範囲指定時の省略は行番号欄に `...` が入ります。
 - 複数ファイルが含まれる場合は、左側のファイルツリーで表示ファイルを切り替えられます。
+- ファイルツリーのディレクトリはデフォルトで展開されています。
 - ファイルツリーには、ファイルごとの行カバレッジが `(実行行数/式のある行数)` で表示されます。
 - 選択中ファイルは URL ハッシュ（`#file=...`）に反映されるため、URL を共有するとそのファイル表示を開けます。
 - 行番号をクリックすると、その行を含む URL ハッシュ（`#file=...&line=...`）に更新され、同じファイル・行を開けます。
+- 移動時に URL ハッシュは自動更新されるため、専用の permalink ボタンはありません。
+- CLI から生成した HTML では、ヘッダに `Command: ...` が表示されます。
+- フッターには、HTML を生成した Lumitrace のバージョンが表示されます。
+
+### AI と使う
+
+テストが落ちたとき、Lumitrace で実行時の値を取得し、その結果を AI に渡すと効率的にデバッグできます。
+
+**典型的なシナリオ:**
+
+1. テストが失敗する
+2. Lumitrace でテスト実行時の値を記録する
+3. 結果を AI に渡して原因を分析してもらう
+
+```bash
+# テストを lumitrace 付きで実行し、JSON を取得
+lumitrace --collect-mode last -j exec rake test
+
+# 結果の JSON を AI に渡す
+```
+
+**CLAUDE.md / AGENTS.md に貼れるスニペット例:**
+
+プロジェクトの `CLAUDE.md` や `AGENTS.md` に以下を追加すると、AI エージェントが Lumitrace を活用しやすくなります:
+
+````markdown
+## デバッグ（Lumitrace）
+lumitrace は Ruby の各式の実行時の値を記録するツール。
+テスト失敗時は `lumitrace help` を読んでから使うこと。
+基本: `lumitrace -t exec rake test`
+````
+
+**段階的アプローチ（トークン節約）:**
+
+AI に読ませる前提なら、次の順番にすると効率が良いです。
+
+1. まず型分布だけ取る（安く全体像を見る）
+
+```bash
+lumitrace --collect-mode types -j path/to/entry.rb
+```
+
+2. 次に最終値を見る（値の当たりを付ける）
+
+```bash
+lumitrace --collect-mode last -j path/to/entry.rb
+```
+
+3. 変化が必要な箇所だけ履歴を見る
+
+```bash
+lumitrace --collect-mode history --max-samples 5 -j path/to/entry.rb
+```
+
+4. 対象を絞る（トークン節約）
+
+```bash
+lumitrace --collect-mode last -j --range path/to/entry.rb:120-180 path/to/entry.rb
+lumitrace --collect-mode last -j -g path/to/entry.rb
+```
+
+補助情報は `lumitrace help --format json` と `lumitrace schema --format json` で機械可読に取得できます。
 
 ### 範囲指定の例
 
@@ -298,37 +361,6 @@ GitHub Actions への追加手順（`LUMITRACE_GIT_DIFF` や Pages へのアッ
 
 fork/exec の結果はデフォルトでマージされます。親プロセスが最終出力を行い、子プロセスは `LUMITRACE_RESULTS_DIR` に断片 JSON を保存します。
 
-### AI と使う
-
-AI に読ませる前提なら、次の順番にすると効率が良いです。
-
-1. まず型分布だけ取る（安く全体像を見る）
-
-```bash
-lumitrace --collect-mode types -j path/to/entry.rb
-```
-
-2. 次に最終値を見る（値の当たりを付ける）
-
-```bash
-lumitrace --collect-mode last -j path/to/entry.rb
-```
-
-3. 変化が必要な箇所だけ履歴を見る
-
-```bash
-lumitrace --collect-mode history --max-samples 5 -j path/to/entry.rb
-```
-
-4. 対象を絞る（トークン節約）
-
-```bash
-lumitrace --collect-mode last -j --range path/to/entry.rb:120-180 path/to/entry.rb
-lumitrace --collect-mode last -j -g path/to/entry.rb
-```
-
-補助情報は `lumitrace help --format json` と `lumitrace schema --format json` で機械可読に取得できます。
-
 ## 2. ライブラリとして使う
 
 CLI を使わずアプリに組み込みたい場合はここから始めます。

data/docs/tutorial.md

@@ -131,9 +131,72 @@ HTML notes:
 - Lines where all instrumentable expressions are unexecuted are shaded light red; mixed lines only shade the unexecuted expressions.
 - When ranges are used, skipped sections are shown as `...` in the line-number column.
 - When multiple files are included, use the left file tree to switch files.
+- Directory nodes in the file tree are expanded by default.
 - The file tree shows per-file line coverage as `(executed/expression-lines)`.
 - The selected file is stored in the URL hash (`#file=...`), so copying the URL shares a direct link to that file view.
 - Click a line number to update the URL with that line (`#file=...&line=...`) and open the same file+line later.
+- The URL hash is updated automatically while navigating (there is no separate permalink button).
+- The header also shows `Command: ...` for CLI-generated reports.
+- The footer shows the Lumitrace version that generated the report.
+
+### Using with AI agents
+
+When a test fails, you can use Lumitrace to capture runtime values and pass the results to an AI for efficient debugging.
+
+**Typical scenario:**
+
+1. A test fails
+2. Run the test with Lumitrace to record runtime values
+3. Pass the results to an AI to analyze the root cause
+
+```bash
+# Run tests with lumitrace and get JSON output
+lumitrace --collect-mode last -j exec rake test
+
+# Pass the resulting JSON to your AI
+```
+
+**Snippet for CLAUDE.md / AGENTS.md:**
+
+Add the following to your project's `CLAUDE.md` or `AGENTS.md` so AI agents can leverage Lumitrace:
+
+````markdown
+## Debugging (Lumitrace)
+lumitrace is a tool that records runtime values of each Ruby expression.
+When a test fails, read `lumitrace help` first, then use it.
+Basic: `lumitrace -t exec rake test`
+````
+
+**Gradual approach (save tokens):**
+
+When feeding results to an AI, this order is efficient:
+
+1. Start with type distributions (cheap overview)
+
+```bash
+lumitrace --collect-mode types -j path/to/entry.rb
+```
+
+2. Then check last values (get a feel for the data)
+
+```bash
+lumitrace --collect-mode last -j path/to/entry.rb
+```
+
+3. Look at history only where changes are needed
+
+```bash
+lumitrace --collect-mode history --max-samples 5 -j path/to/entry.rb
+```
+
+4. Narrow the scope (save tokens)
+
+```bash
+lumitrace --collect-mode last -j --range path/to/entry.rb:120-180 path/to/entry.rb
+lumitrace --collect-mode last -j -g path/to/entry.rb
+```
+
+Machine-readable help is available via `lumitrace help --format json` and `lumitrace schema --format json`.
 
 ### Range example
 

data/lib/lumitrace/ai_docs.rb

@@ -70,7 +70,17 @@ module Lumitrace
     lines << ""
     lines << "- Version: #{data[:version]}"
     lines << "- Schema version: #{data[:schema_version]}"
-    lines << "- Top level: #{data[:json_top_level][:type]} of #{data[:json_top_level][:items]}"
+    top = data[:json_top_level]
+    if top[:type] == "object" && top[:fields]
+      lines << "- Top level: #{top[:type]}"
+      top[:fields].each do |name, spec|
+        type_text = spec[:items] ? "#{spec[:type]} of #{spec[:items]}" : spec[:type].to_s
+        desc = spec[:description] ? " - #{spec[:description]}" : ""
+        lines << "  - `#{name}` (#{type_text})#{desc}"
+      end
+    else
+      lines << "- Top level: #{top[:type]} of #{top[:items]}"
+    end
     lines << ""
     lines << "## Common Event Fields"
     data[:event_common_fields].each do |name, spec|
@@ -79,6 +89,16 @@ module Lumitrace
       desc = spec[:description] ? " - #{spec[:description]}" : ""
       lines << "- `#{name}` (#{type_text}, #{req})#{desc}"
     end
+    if data[:coverage_entry_fields]
+      lines << ""
+      lines << "## Coverage Entry Fields"
+      data[:coverage_entry_fields].each do |name, spec|
+        req = spec[:required] ? "required" : "optional"
+        type_text = Array(spec[:type]).join("|")
+        desc = spec[:description] ? " - #{spec[:description]}" : ""
+        lines << "- `#{name}` (#{type_text}, #{req})#{desc}"
+      end
+    end
     lines << ""
     lines << "## Value Summary Fields"
     data[:value_summary_fields].each do |name, spec|

data/lib/lumitrace/generate_resulted_html.rb

@@ -25,7 +25,8 @@ module GenerateResultedHtml
       abort "missing #{source_path}"
     end
 
-    raw_events = JSON.parse(File.read(events_path))
+    raw = JSON.parse(File.read(events_path))
+    raw_events = raw.is_a?(Hash) && raw.key?("events") ? raw["events"] : raw
     src = File.read(source_path)
     mode_info = resolve_mode_info(raw_events, collect_mode: collect_mode, max_samples: max_samples)
     normalized_ranges = normalize_ranges(ranges)
@@ -654,7 +655,8 @@ module GenerateResultedHtml
   end
 
   def self.render_all(events_path, root: Dir.pwd, ranges_by_file: nil, collect_mode: nil, max_samples: nil, logger: nil, command_text: nil)
-    raw_events = JSON.parse(File.read(events_path))
+    raw = JSON.parse(File.read(events_path))
+    raw_events = raw.is_a?(Hash) && raw.key?("events") ? raw["events"] : raw
     render_all_from_events(
       raw_events,
       root: root,

data/lib/lumitrace/help_manifest.rb

@@ -56,11 +56,16 @@ module Lumitrace
       key_options: [
         { name: "--collect-mode", values: COLLECT_MODES, default: "last" },
         { name: "--max-samples", type: "Integer", default: 3, note: "Used by history mode." },
-        { name: "--json[=PATH]", type: "bool|string", note: "Emit JSON output." },
-        { name: "--html[=PATH]", type: "bool|string", note: "Emit HTML output." },
-        { name: "--text[=PATH]", type: "bool|string", note: "Emit text output." },
+        { name: "-j, --json[=PATH]", type: "bool|string", note: "Emit JSON output." },
+        { name: "-h, --html[=PATH]", type: "bool|string", note: "Emit HTML output." },
+        { name: "-t, --text[=PATH]", type: "bool|string", note: "Emit text output." },
+        { name: "-g, --git-diff[=MODE]", type: "string", note: "Restrict instrumentation to diff hunks." },
         { name: "--range SPEC", type: "string", repeatable: true, note: "Restrict instrumentation to file ranges." },
-        { name: "--git-diff[=MODE]", type: "string", note: "Restrict instrumentation to diff hunks." }
+        { name: "--git-diff-context N", type: "Integer", note: "Expand diff hunks by +/-N lines." },
+        { name: "--git-cmd PATH", type: "string", note: "Git executable for diff." },
+        { name: "--git-diff-no-untracked", type: "bool", note: "Exclude untracked files from diff." },
+        { name: "--root PATH", type: "string", note: "Root directory for instrumentation." },
+        { name: "--verbose[=LEVEL]", type: "Integer", note: "Verbose logs to stderr (level 1-3)." }
       ],
       outputs: [
         { kind: "json", default_path: "lumitrace_recorded.json" },

data/lib/lumitrace/record_instrument.rb

@@ -495,10 +495,42 @@ module RecordInstrument
 
   def self.dump_events_json(events, path = nil)
     path ||= File.expand_path("lumitrace_recorded.json", Dir.pwd)
-    File.write(path, JSON.dump(events), perm: 0o600)
+    payload = {
+      version: 1,
+      events: events,
+      coverage: compute_coverage(events)
+    }
+    File.write(path, JSON.dump(payload), perm: 0o600)
     path
   end
 
+  def self.compute_coverage(events)
+    by_file = {}
+    events.each do |e|
+      file = e[:file] || e["file"]
+      next unless file
+      total = e[:total] || e["total"] || 0
+      start_line = e[:start_line] || e["start_line"]
+      next unless start_line
+
+      entry = (by_file[file] ||= { lines: {}, covered_lines: {} })
+      entry[:lines][start_line] = true
+      entry[:covered_lines][start_line] = true if total > 0
+    end
+
+    by_file.map do |file, entry|
+      total_lines = entry[:lines].size
+      covered_lines = entry[:covered_lines].size
+      pct = total_lines > 0 ? (covered_lines * 100.0 / total_lines).round(1) : 0.0
+      {
+        file: file,
+        total_lines: total_lines,
+        covered_lines: covered_lines,
+        coverage_percent: pct
+      }
+    end.sort_by { |e| e[:file] }
+  end
+
   def self.load_events_json(path)
     JSON.parse(File.read(path))
   end
@@ -686,25 +718,36 @@ module RecordInstrument
     events_from_ids
   end
 
+  KERNEL_INSPECT = ::Kernel.instance_method(:inspect)
+
+  def self.safe_inspect(v)
+    v.inspect
+  rescue ::NoMethodError
+    KERNEL_INSPECT.bind_call(v)
+  end
+
   def self.safe_value(v)
     case v
     when Numeric, TrueClass, FalseClass, NilClass
       v
     else
-      s = v.inspect
+      s = safe_inspect(v)
       s.bytesize > 1000 ? s[0, 1000] + "..." : s
     end
   end
 
+  KERNEL_CLASS = ::Kernel.instance_method(:class)
+
   def self.value_type_name(v)
-    name = v.class.name
-    name && !name.empty? ? name : v.class.to_s
+    klass = KERNEL_CLASS.bind_call(v)
+    name = klass.name
+    name && !name.empty? ? name : klass.to_s
   end
 
   def self.summarize_value(v, type: nil)
     type ||= value_type_name(v)
     preview_limit = 120
-    inspected = v.inspect
+    inspected = safe_inspect(v)
     if inspected.length > preview_limit
       {
         type: type,

data/lib/lumitrace/schema_manifest.rb

@@ -9,8 +9,18 @@ module Lumitrace
       tool: "lumitrace",
       version: VERSION,
       json_top_level: {
-        type: "array",
-        items: "event"
+        type: "object",
+        fields: {
+          version: { type: "integer", description: "Schema version number." },
+          events: { type: "array", items: "event", description: "Traced expression events." },
+          coverage: { type: "array", items: "coverage_entry", description: "Per-file coverage summary." }
+        }
+      },
+      coverage_entry_fields: {
+        file: { type: "string", required: true, description: "Absolute source path." },
+        total_lines: { type: "integer", required: true, description: "Number of traced expression lines." },
+        covered_lines: { type: "integer", required: true, description: "Lines with total > 0." },
+        coverage_percent: { type: "float", required: true, description: "Covered / total * 100, rounded to 1 decimal." }
       },
       event_common_fields: {
         file: { type: "string", required: true, description: "Absolute source path." },
@@ -20,7 +30,7 @@ module Lumitrace
         end_col: { type: "integer", required: true },
         kind: { type: "string", required: true, enum: %w[expr arg] },
         name: { type: ["string", "null"], required: false, description: "Present for kind=arg." },
-        total: { type: "integer", required: true, description: "Execution count." },
+        total: { type: "integer", required: true, description: "Execution count. 0 means the expression was never executed (uncovered)." },
         types: {
           type: "object",
           required: true,

data/lib/lumitrace/version.rb

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

data/lib/lumitrace.rb

@@ -13,6 +13,8 @@ require_relative "lumitrace/ai_docs"
 
 module Lumitrace
   class Error < StandardError; end
+  KERNEL_CLASS = ::Kernel.instance_method(:class)
+
   @atexit_registered = false
   @atexit_output_root = nil
   @atexit_ranges_by_file = nil
@@ -62,7 +64,7 @@ module Lumitrace
           def R(id, value)
             events_by_id = RecordInstrument.events_by_id
             entry = events_by_id[id]
-            klass = value.class
+            klass = KERNEL_CLASS.bind_call(value)
             type = klass.name
             type = klass.to_s if type.nil? || type.empty?
             if entry
@@ -81,7 +83,7 @@ module Lumitrace
           def R(id, value)
             events_by_id = RecordInstrument.events_by_id
             entry = events_by_id[id]
-            klass = value.class
+            klass = KERNEL_CLASS.bind_call(value)
             type = klass.name
             type = klass.to_s if type.nil? || type.empty?
             if entry
@@ -99,7 +101,7 @@ module Lumitrace
           def R(id, value)
             events_by_id = RecordInstrument.events_by_id
             entry = events_by_id[id]
-            klass = value.class
+            klass = KERNEL_CLASS.bind_call(value)
             type = klass.name
             type = klass.to_s if type.nil? || type.empty?
             if entry

data/runv/index.html

@@ -4,9 +4,9 @@
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>LumiTrace Playground</title>
-  <meta name="description" content="Run Ruby in the browser and see traced values inline with lumitrace 0.5.0.">
+  <meta name="description" content="Run Ruby in the browser and see traced values inline with lumitrace 0.6.0.">
   <meta property="og:title" content="LumiTrace Playground">
-  <meta property="og:description" content="Run Ruby in the browser and see traced values inline with lumitrace 0.5.0.">
+  <meta property="og:description" content="Run Ruby in the browser and see traced values inline with lumitrace 0.6.0.">
   <meta property="og:type" content="website">
   <meta property="og:url" content="https://github.com/ko1/lumitrace/tree/master/runv">
   <meta property="og:see_also" content="https://github.com/ko1/lumitrace/tree/master/runv">
@@ -290,7 +290,7 @@
   <header>
     <div>
       <h1>LumiTrace Playground</h1>
-      <p class="sub">Run Ruby in the browser and see traced values inline with lumitrace 0.5.0.</p>
+      <p class="sub">Run Ruby in the browser and see traced values inline with lumitrace 0.6.0.</p>
     </div>
   </header>
 
@@ -936,10 +936,42 @@ module RecordInstrument
 
   def self.dump_events_json(events, path = nil)
     path ||= File.expand_path("lumitrace_recorded.json", Dir.pwd)
-    File.write(path, JSON.dump(events), perm: 0o600)
+    payload = {
+      version: 1,
+      events: events,
+      coverage: compute_coverage(events)
+    }
+    File.write(path, JSON.dump(payload), perm: 0o600)
     path
   end
 
+  def self.compute_coverage(events)
+    by_file = {}
+    events.each do |e|
+      file = e[:file] || e["file"]
+      next unless file
+      total = e[:total] || e["total"] || 0
+      start_line = e[:start_line] || e["start_line"]
+      next unless start_line
+
+      entry = (by_file[file] ||= { lines: {}, covered_lines: {} })
+      entry[:lines][start_line] = true
+      entry[:covered_lines][start_line] = true if total > 0
+    end
+
+    by_file.map do |file, entry|
+      total_lines = entry[:lines].size
+      covered_lines = entry[:covered_lines].size
+      pct = total_lines > 0 ? (covered_lines * 100.0 / total_lines).round(1) : 0.0
+      {
+        file: file,
+        total_lines: total_lines,
+        covered_lines: covered_lines,
+        coverage_percent: pct
+      }
+    end.sort_by { |e| e[:file] }
+  end
+
   def self.load_events_json(path)
     JSON.parse(File.read(path))
   end
@@ -1127,25 +1159,36 @@ module RecordInstrument
     events_from_ids
   end
 
+  KERNEL_INSPECT = ::Kernel.instance_method(:inspect)
+
+  def self.safe_inspect(v)
+    v.inspect
+  rescue ::NoMethodError
+    KERNEL_INSPECT.bind_call(v)
+  end
+
   def self.safe_value(v)
     case v
     when Numeric, TrueClass, FalseClass, NilClass
       v
     else
-      s = v.inspect
+      s = safe_inspect(v)
       s.bytesize > 1000 ? s[0, 1000] + "..." : s
     end
   end
 
+  KERNEL_CLASS = ::Kernel.instance_method(:class)
+
   def self.value_type_name(v)
-    name = v.class.name
-    name && !name.empty? ? name : v.class.to_s
+    klass = KERNEL_CLASS.bind_call(v)
+    name = klass.name
+    name && !name.empty? ? name : klass.to_s
   end
 
   def self.summarize_value(v, type: nil)
     type ||= value_type_name(v)
     preview_limit = 120
-    inspected = v.inspect
+    inspected = safe_inspect(v)
     if inspected.length > preview_limit
       {
         type: type,
@@ -1371,7 +1414,8 @@ module GenerateResultedHtml
       abort "missing #{source_path}"
     end
 
-    raw_events = JSON.parse(File.read(events_path))
+    raw = JSON.parse(File.read(events_path))
+    raw_events = raw.is_a?(Hash) && raw.key?("events") ? raw["events"] : raw
     src = File.read(source_path)
     mode_info = resolve_mode_info(raw_events, collect_mode: collect_mode, max_samples: max_samples)
     normalized_ranges = normalize_ranges(ranges)
@@ -2773,7 +2817,8 @@ end
   end
 
   def self.render_all(events_path, root: Dir.pwd, ranges_by_file: nil, collect_mode: nil, max_samples: nil, logger: nil, command_text: nil)
-    raw_events = JSON.parse(File.read(events_path))
+    raw = JSON.parse(File.read(events_path))
+    raw_events = raw.is_a?(Hash) && raw.key?("events") ? raw["events"] : raw
     render_all_from_events(
       raw_events,
       root: root,

data/test/test_lumitrace.rb

@@ -499,6 +499,164 @@ class LumiTraceTest < Minitest::Test
     assert_equal "ruby script.rb arg1", payload[:meta][:command]
   end
 
+  def test_value_type_name_with_basic_object
+    klass = Class.new(BasicObject)
+    obj = klass.new
+    type = Lumitrace::RecordInstrument.value_type_name(obj)
+    refute_nil type
+    refute_empty type
+  end
+
+  def test_summarize_value_with_basic_object
+    klass = Class.new(BasicObject)
+    obj = klass.new
+    summary = Lumitrace::RecordInstrument.summarize_value(obj)
+    assert summary.is_a?(Hash)
+    assert summary.key?(:type)
+    assert summary.key?(:preview)
+    refute_nil summary[:type]
+    refute_empty summary[:type]
+  end
+
+  def test_R_with_basic_object_last_mode
+    with_record_instrument_state do
+      mod = Lumitrace::RecordInstrument
+      mod.instance_variable_set(:@events_by_id, [])
+      mod.instance_variable_set(:@loc_by_id, [])
+      mod.instance_variable_set(:@next_id, 0)
+      Lumitrace.install_collect_mode("last")
+
+      id = mod.register_location(
+        "a.rb",
+        { start_line: 1, start_col: 0, end_line: 1, end_col: 1 },
+        kind: :expr
+      )
+
+      klass = Class.new(BasicObject)
+      obj = klass.new
+      result = Lumitrace::R(id, obj)
+      assert_same obj, result
+
+      events = mod.events_from_ids
+      assert_equal 1, events.first[:total]
+      refute_empty events.first[:types]
+    end
+  end
+
+  def test_R_with_basic_object_history_mode
+    with_record_instrument_state do
+      mod = Lumitrace::RecordInstrument
+      mod.instance_variable_set(:@events_by_id, [])
+      mod.instance_variable_set(:@loc_by_id, [])
+      mod.instance_variable_set(:@next_id, 0)
+      Lumitrace.install_collect_mode("history")
+      mod.max_samples_per_expr = 3
+
+      id = mod.register_location(
+        "a.rb",
+        { start_line: 1, start_col: 0, end_line: 1, end_col: 1 },
+        kind: :expr
+      )
+
+      klass = Class.new(BasicObject)
+      Lumitrace::R(id, klass.new)
+      Lumitrace::R(id, 42)
+
+      events = mod.events_from_ids
+      assert_equal 2, events.first[:total]
+      assert_equal 2, events.first[:sampled_values].length
+    end
+  end
+
+  def test_R_with_basic_object_types_mode
+    with_record_instrument_state do
+      mod = Lumitrace::RecordInstrument
+      mod.instance_variable_set(:@events_by_id, [])
+      mod.instance_variable_set(:@loc_by_id, [])
+      mod.instance_variable_set(:@next_id, 0)
+      Lumitrace.install_collect_mode("types")
+
+      id = mod.register_location(
+        "a.rb",
+        { start_line: 1, start_col: 0, end_line: 1, end_col: 1 },
+        kind: :expr
+      )
+
+      klass = Class.new(BasicObject)
+      Lumitrace::R(id, klass.new)
+
+      events = mod.events_from_ids
+      assert_equal 1, events.first[:total]
+      refute_empty events.first[:types]
+    end
+  end
+
+  def test_compute_coverage
+    events = [
+      { file: "a.rb", start_line: 1, start_col: 0, end_line: 1, end_col: 5, total: 3 },
+      { file: "a.rb", start_line: 2, start_col: 0, end_line: 2, end_col: 5, total: 0 },
+      { file: "a.rb", start_line: 3, start_col: 0, end_line: 3, end_col: 5, total: 1 },
+      { file: "b.rb", start_line: 1, start_col: 0, end_line: 1, end_col: 5, total: 0 }
+    ]
+    coverage = Lumitrace::RecordInstrument.compute_coverage(events)
+    assert_equal 2, coverage.length
+
+    a = coverage.find { |c| c[:file] == "a.rb" }
+    assert_equal 3, a[:total_lines]
+    assert_equal 2, a[:covered_lines]
+    assert_equal 66.7, a[:coverage_percent]
+
+    b = coverage.find { |c| c[:file] == "b.rb" }
+    assert_equal 1, b[:total_lines]
+    assert_equal 0, b[:covered_lines]
+    assert_equal 0.0, b[:coverage_percent]
+  end
+
+  def test_dump_events_json_wrapped_format
+    Dir.mktmpdir do |dir|
+      events = [
+        { file: "a.rb", start_line: 1, start_col: 0, end_line: 1, end_col: 5, total: 1 }
+      ]
+      path = File.join(dir, "out.json")
+      Lumitrace::RecordInstrument.dump_events_json(events, path)
+      data = JSON.parse(File.read(path))
+
+      assert_equal 1, data["version"]
+      assert data.key?("events")
+      assert data.key?("coverage")
+      assert_equal 1, data["events"].length
+      assert_equal 1, data["coverage"].length
+      assert_equal 100.0, data["coverage"][0]["coverage_percent"]
+    end
+  end
+
+  def test_render_all_reads_wrapped_json
+    Dir.mktmpdir do |dir|
+      sample = File.join(dir, "sample.rb")
+      File.write(sample, "puts hi\n")
+      events_path = File.join(dir, "events.json")
+      payload = {
+        "version" => 1,
+        "events" => [
+          {
+            "file" => sample,
+            "start_line" => 1,
+            "start_col" => 0,
+            "end_line" => 1,
+            "end_col" => 5,
+            "sampled_values" => ["ok"],
+            "total" => 1
+          }
+        ],
+        "coverage" => []
+      }
+      File.write(events_path, JSON.dump(payload))
+
+      html = Lumitrace::GenerateResultedHtml.render_all(events_path, root: dir)
+      assert_includes html, "sample.rb"
+    end
+  end
+
   def test_env_range_parsing
     with_env("LUMITRACE_RANGE" => "a.rb:1-3,5-6;b.rb", "LUMITRACE_COLLECT_MODE" => "types") do
       env = Lumitrace.resolve_env_options

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lumitrace
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Koichi Sasada