lumitrace 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d58e330a4db4410a5ab30043d6f222d3a1281e06b1b9bf9b499b663d85e9e502
-  data.tar.gz: 7d12352c93ec9cba4dba03df61bc6dd618632902e7930867262cdb428393876c
+  metadata.gz: cb5fe18ff96f6cea6cac519424f9d7a3ead8e4ce4f9be3ad2db7ddde2804302e
+  data.tar.gz: 17c83251a9b042481e297422f2ddcad5f923a890f52202331e3fc85e28a9e888
 SHA512:
-  metadata.gz: 336673fd02c877740c3970354dfde67b7c149ecd812cb897159c097dda9e90346f0f35f0dd1bbd149a8805d75043518f82d8e687929be1c63d85bd33cb614b4c
-  data.tar.gz: ac97e8d31ef4fbc053b306f1f4d95b0467e7e2ce58e95e443ad81a0aa4258ff4007851ff81aff42a56350b509a741ce4dba5d01697107907a38bb59127cd731f
+  metadata.gz: eb65e28bfad568fb9aaff142a4ee0150e49b8f37cf8ffb99508c706691a710310119b23826942668874a60a6189a91732367389581bd056a9cdc09592a286d0a
+  data.tar.gz: dbbbfb431b4a957f186a93a849949fac88b54ed8408b9d761550c0eeb76055195f589e4ca9dfdd23152854ed156be6d13172337a555441bf0960d05825ef7332

data/docs/spec.md

@@ -267,12 +267,21 @@ 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.
 - 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.
+- 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)`.
@@ -280,10 +289,79 @@ lumitrace [options] exec CMD [args...]
 - 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.
 
+### 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`.
+- `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
 

data/docs/tutorial.ja.md

@@ -130,6 +130,10 @@ HTML について:
 - 引数の値は HTML では `🧷` で表示されます。
 - 記録対象の式がすべて未実行の行は薄い赤で表示され、混在行では未実行の式のみ薄赤になります。
 - 範囲指定時の省略は行番号欄に `...` が入ります。
+- 複数ファイルが含まれる場合は、左側のファイルツリーで表示ファイルを切り替えられます。
+- ファイルツリーには、ファイルごとの行カバレッジが `(実行行数/式のある行数)` で表示されます。
+- 選択中ファイルは URL ハッシュ（`#file=...`）に反映されるため、URL を共有するとそのファイル表示を開けます。
+- 行番号をクリックすると、その行を含む URL ハッシュ（`#file=...&line=...`）に更新され、同じファイル・行を開けます。
 
 ### 範囲指定の例
 

data/docs/tutorial.md

@@ -130,6 +130,10 @@ 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.
+- 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.
 
 ### Range example