lumitrace 0.4.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d58e330a4db4410a5ab30043d6f222d3a1281e06b1b9bf9b499b663d85e9e502
-  data.tar.gz: 7d12352c93ec9cba4dba03df61bc6dd618632902e7930867262cdb428393876c
+  metadata.gz: 4511842d6a3c76fbf50be2da922a089e852adfe571d952efe770e536060d2ab2
+  data.tar.gz: e24617018967e09c04e8d79079e1182ae32b64f8ff69a2046bb802e1daadd6a9
 SHA512:
-  metadata.gz: 336673fd02c877740c3970354dfde67b7c149ecd812cb897159c097dda9e90346f0f35f0dd1bbd149a8805d75043518f82d8e687929be1c63d85bd33cb614b4c
-  data.tar.gz: ac97e8d31ef4fbc053b306f1f4d95b0467e7e2ce58e95e443ad81a0aa4258ff4007851ff81aff42a56350b509a741ce4dba5d01697107907a38bb59127cd731f
+  metadata.gz: aeb9654b4eb02f0b0d60a1f15567d5abd591b27abb1e3b1acf660b19f3e23ddd74487699e667a15d533d793bdc6f4700f2d8f5ee4a6ee0ec9507ae6053f164be
+  data.tar.gz: 98a92961b2dc9cf10e50fe7310cfdd5f4d6c138fc13f41a9485a4cdad0a68007145c7bfb5c5f1cfe4980733f6a287c8ceb7a133b1bd41d6cf19612d9275a61d8

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/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
 
@@ -267,26 +299,111 @@ lumitrace [options] exec CMD [args...]
 ## HTML Rendering
 
 - `GenerateResultedHtml.render_all` renders all files in one page.
+- Generated HTML is a single self-contained file (no external fetch): it embeds source/trace data as JSON and renders DOM with JavaScript.
+- JavaScript is required to render the code/trace view (a `<noscript>` message is shown otherwise).
 - The page header shows the active collect mode:
   - `Mode: last (last value)`
   - `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`).
+- When the HTML is opened with a file+line hash, the renderer selects that file and scrolls to the target line.
+- File tree items show line coverage as `(executed_lines / lines_with_expressions)` for a quick per-file overview.
+- Files with no instrumentable expressions do not show a coverage count.
 - Expressions are marked with an inline icon (`🔎` for executed, `∅` for not hit).
 - 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`)
+
+- The generated HTML embeds a JSON payload in:
+  - `<script id="lumitrace-payload" type="application/json">...</script>`
+- Payload top-level shape:
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "mode": "last|types|history",
+    "mode_text": "Mode: ...",
+    "max_samples": 3
+  },
+  "files": [
+    {
+      "path": "/abs/path/to/file.rb",
+      "display_path": "path/to/file.rb",
+      "source": "file contents...",
+      "ranges": [[1, 10], [20, 30]],
+      "trace": [
+        {
+          "location": [1, 0, 1, 5],
+          "kind": "expr|arg",
+          "name": "x",
+          "sampled_values": [{"type": "Integer", "preview": "1"}],
+          "types": {"Integer": 3},
+          "total": 3
+        }
+      ]
+    }
+  ]
+}
+```
+
+- `version`:
+  - Payload schema version for the embedded HTML renderer. Current version is `1`.
+- `meta.mode`:
+  - Effective collect mode used for display (`last`, `types`, `history`).
+- `meta.mode_text`:
+  - 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`:
+  - Absolute path used internally to associate trace events with source.
+- `files[].display_path`:
+  - Path label shown in the HTML report (typically root-relative).
+  - Multi-file HTML navigation and URL hash (`#file=...`, `#file=...&line=...`) use this value as the file key.
+- `files[].source`:
+  - Full Ruby source text for that file.
+- `files[].ranges`:
+  - Normalized line ranges as inclusive `[start_line, end_line]` pairs, or `null` when unrestricted.
+- `files[].trace[]`:
+  - Trace events for that file only (`file` is intentionally omitted from each event).
+- `files[].trace[].location`:
+  - Location tuple `[start_line, start_col, end_line, end_col]`.
+- `files[].trace[].kind`:
+  - Event kind (`expr` or `arg`).
+- `files[].trace[].name`:
+  - Argument name when `kind=arg`; otherwise `null`.
+- `files[].trace[].sampled_values`:
+  - Normalized sampled values (or synthesized `last_value` entry when collect mode is `last`).
+- `files[].trace[].types`:
+  - Type counts map, normalized as `{ "TypeName": count }`.
+- `files[].trace[].total`:
+  - Total execution count for the location.
 
 ### Copy/Paste Behavior
 
 - Inline icon uses a separate marker span to reduce copy/paste artifacts.
-- Lines are rendered as inline spans with explicit `\n` inserted.
+- Lines are rendered as per-line block spans to keep copy/paste artifacts small while preserving line alignment.
 
 ## Known Limitations
 
 - 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

@@ -130,6 +130,73 @@ HTML について:
 - 引数の値は 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` で機械可読に取得できます。
 
 ### 範囲指定の例
 
@@ -294,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

@@ -130,6 +130,73 @@ HTML notes:
 - Argument values show `🧷` in HTML.
 - 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