lumitrace 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4de22b014b5ce2ce0e63b230487c6888147ee99459a2ef832ccae42a9b6004c6
-  data.tar.gz: 78cb61f36f9764daa1898eae3897090a92c2d44dd422a31589db983b7a951ec7
+  metadata.gz: 95fd4185e9243312420705cc551f30f16ce4399e19c79165683bf97dbf6da70b
+  data.tar.gz: '0998518cd551365fd8c146855fa8a767316665ba1f2a4bdd6db3e83680cc17a9'
 SHA512:
-  metadata.gz: 1ac281aaf18f6f0382af924d9d2ef850ae27353e10255114e90cce2121bcdaa5572d077c3edb3b8dde465bb8a820804aa039abab4af0420bbcbc8381ffca112d
-  data.tar.gz: 6df68f6e6c1769616c584278fdca6be2c736c8c5a99ddab37b5a86c42b66d056edeb51b041a9e0c53b11db324fa219e72a5c1bfe6c968ee4dfe6869f350f1219
+  metadata.gz: 7e2adb4bd754617497dc8d8b7925d44356aa010a7ddf0942bc2f3631d83fc7aba6468fcd008e01742aaf83b26ebe2b1809f244eefd4b728b0321e9fe11b71221
+  data.tar.gz: 82ba698e166b72ff0d47d0f630a76348641189bfccc4393ecea714fb974b24fb0921666784c34a9627ad143aae0443a1e0823eaa1c51f30e82a2af99cf8419d3

data/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+[HTML view example](./docs/lumitrace_html_example.png)
+
 ## Useful links
 
 - [runv/](https://ko1.github.io/lumitrace/runv/): Lumitrace demonstration Ruby playground with inlined tracing
@@ -50,7 +52,7 @@ Write JSON output explicitly:
 
 ```bash
 lumitrace -j path/to/entry.rb
-lumitrace --json=out/lumitrace_recorded.json path/to/entry.rb
+lumitrace --json out/lumitrace_recorded.json path/to/entry.rb
 ```
 
 Restrict to specific line ranges:
@@ -94,10 +96,10 @@ require "lumitrace/enable"
 
 ## Output
 
-- Text: printed by default; use `--text=PATH` to write to a file.
-- HTML: `lumitrace_recorded.html` by default, or `--html=PATH`.
+- Text: printed by default; use `--text PATH` to write to a file.
+- HTML: `lumitrace_recorded.html` by default, or `--html PATH`.
 - JSON: written only when `--json` (CLI) or `LUMITRACE_JSON` (library/CLI) is provided. Default filename is `lumitrace_recorded.json`.
-- JSON collection mode: `--collect-mode=last|types|history` (default `last`).
+- JSON collection mode: `--collect-mode last|types|history` (default `last`).
 - Fork/exec: merged by default. Child processes write fragments under `LUMITRACE_RESULTS_DIR`.
 
 JSON event entries always include `types` (type-name => count).
@@ -151,4 +153,4 @@ Run the CLI locally:
 
 ```bash
 lumitrace path/to/entry.rb
-```
+```

data/docs/ai-help.md

@@ -4,7 +4,7 @@
 
 AI agents: run `lumitrace help --format json` to get structured help.
 
-- Version: 0.6.1
+- Version: 0.7.0
 - Help version: 1
 - Primary JSON entrypoint: `lumitrace help --format json`
 - Schema JSON entrypoint: `lumitrace schema --format json`
@@ -20,6 +20,7 @@ AI agents: run `lumitrace help --format json` to get structured help.
 - Then switch to `--collect-mode last` for final value inspection on suspicious lines.
 - Use `--collect-mode history --max-samples N` only when value transitions matter.
 - Combine `--range` or `--git-diff` to keep outputs small and focused.
+- -j, -h, -t are flags that enable output with default paths. Use --json PATH, --html PATH, --text PATH to specify output paths.
 
 ## Commands
 - `lumitrace [options] script.rb [ruby_opt]`
@@ -39,9 +40,9 @@ AI agents: run `lumitrace help --format json` to get structured help.
 ## Key Options
 - `--collect-mode` (default="last"; values=last,types,history)
 - `--max-samples` (default=3; Used by history mode.)
-- `-j, --json[=PATH]` (Emit JSON output.)
-- `-h, --html[=PATH]` (Emit HTML output.)
-- `-t, --text[=PATH]` (Emit text output.)
+- `-j` / `--json PATH` (Emit JSON output. -j uses default path; --json PATH writes to PATH.)
+- `-h` / `--html PATH` (Emit HTML output. -h uses default path; --html PATH writes to PATH.)
+- `-t` / `--text PATH` (Emit text output. -t uses default path; --text PATH writes to PATH.)
 - `-g, --git-diff[=MODE]` (Restrict instrumentation to diff hunks.)
 - `--range SPEC` (repeatable=true; Restrict instrumentation to file ranges.)
 - `--git-diff-context N` (Expand diff hunks by +/-N lines.)
@@ -54,5 +55,7 @@ AI agents: run `lumitrace help --format json` to get structured help.
 - `lumitrace --collect-mode history --max-samples 5 -j app.rb`
 - `lumitrace --collect-mode types -h -j app.rb`
 - `lumitrace --collect-mode last -j exec bin/rails test`
+- `lumitrace --json output.json exec bin/rails test`
+- `lumitrace -j --html report.html app.rb`
 - `lumitrace help --format json`
 - `lumitrace schema --format json`

data/docs/ai-schema.md

@@ -2,7 +2,7 @@
 
 # Lumitrace JSON Schema
 
-- Version: 0.6.1
+- Version: 0.7.0
 - Schema version: 1
 - Top level: object
   - `version` (integer) - Schema version number.

data/docs/spec.md

@@ -269,9 +269,9 @@ lumitrace [options] exec CMD [args...]
 ```
 
 - Text is rendered by default (from in-memory events; no JSON file is required).
-- `-t` enables text output to stdout. `--text=PATH` writes to a file.
-- `-h` enables HTML output (default path). `--html=PATH` writes to a file.
-- `-j` enables JSON output (default path). `--json=PATH` writes to a file.
+- `-t` enables text output to stdout. `--text PATH` writes to a file.
+- `-h` enables HTML output (default path). `--html PATH` writes to a file.
+- `-j` enables JSON output (default path). `--json PATH` writes to a file.
 - `-g` enables git diff with `working` mode. `--git-diff=MODE` selects `staged|base:REV|range:SPEC`.
 - `--max-samples` sets max samples per expression in `collect_mode=history`.
 - `--collect-mode` sets value collection mode (`last|types|history`).

data/docs/tutorial.ja.md

@@ -325,7 +325,7 @@ lumitrace -t path/to/entry.rb
 CI アーティファクトなどに残したいときに便利です。
 
 ```bash
-lumitrace --text=/tmp/lumi.txt path/to/entry.rb
+lumitrace --text /tmp/lumi.txt path/to/entry.rb
 ```
 
 
@@ -342,7 +342,7 @@ lumitrace -t -h path/to/entry.rb
 テストなど別コマンドをラップして計測します。
 
 ```bash
-lumitrace --html=sample/lumitrace_rake.html exec rake
+lumitrace --html sample/lumitrace_rake.html exec rake
 ```
 
 HTML 出力:
@@ -423,7 +423,7 @@ require "lumitrace"
 `LUMITRACE_ENABLE` に CLI 互換のオプションを渡すこともできます:
 
 ```ruby
-ENV["LUMITRACE_ENABLE"] = "-t --html=/tmp/lumi.html -j"
+ENV["LUMITRACE_ENABLE"] = "-t --html /tmp/lumi.html -j"
 require "lumitrace"
 ```
 

data/docs/tutorial.md

@@ -325,7 +325,7 @@ lumitrace -t path/to/entry.rb
 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
+lumitrace --text /tmp/lumi.txt path/to/entry.rb
 ```
 
 
@@ -342,7 +342,7 @@ lumitrace -t -h path/to/entry.rb
 Wrap another command (like tests) so Lumitrace instruments what that command runs.
 
 ```bash
-lumitrace --html=sample/lumitrace_rake.html exec rake
+lumitrace --html sample/lumitrace_rake.html exec rake
 ```
 
 HTML output:
@@ -422,7 +422,7 @@ require "lumitrace"
 You can also pass CLI-style options via `LUMITRACE_ENABLE`:
 
 ```ruby
-ENV["LUMITRACE_ENABLE"] = "-t --html=/tmp/lumi.html -j"
+ENV["LUMITRACE_ENABLE"] = "-t --html /tmp/lumi.html -j"
 require "lumitrace"
 ```
 

data/exe/lumitrace

@@ -58,6 +58,17 @@ if args.empty?
   exit 1
 end
 
+# Auto-correct: `lumitrace [options] ruby ...` -> exec mode
+#     If the first remaining arg is not `exec` and not a `.rb` file,
+#     check whether it looks like an external command.
+if args[0] != "exec" && !args[0].end_with?(".rb")
+  cmd = args[0]
+  if system("command -v #{cmd} > /dev/null 2>&1")
+    warn "lumitrace: auto-inserting 'exec' before '#{cmd}' (use 'lumitrace exec #{cmd} ...' to be explicit)"
+    args.unshift("exec")
+  end
+end
+
 if opts[:git_diff_mode] == "exec" && args.first != "exec"
   args.unshift("exec")
   opts[:git_diff_mode] = "working"

data/lib/lumitrace/generate_resulted_html.rb

@@ -60,7 +60,9 @@ module GenerateResultedHtml
     meta = {
       mode: mode_info[:mode],
       mode_text: mode_info[:text],
-      max_samples: mode_info[:max_samples]
+      max_samples: mode_info[:max_samples],
+      ruby_version: RUBY_DESCRIPTION,
+      lumitrace_version: defined?(Lumitrace::VERSION) ? Lumitrace::VERSION : nil
     }
     meta[:command] = command_text if command_text && !command_text.to_s.empty?
     {
@@ -202,6 +204,25 @@ module GenerateResultedHtml
       .marker:focus-within .tooltip,
       .marker .tooltip:hover { display: block; }
       .noscript { color: #666; }
+      .tree-overview-btn { font-weight: bold; margin-bottom: 8px; }
+      .overview-section { background: #fffdf7; border: 1px solid #e5dfd0; border-radius: 8px; padding: 20px; }
+      .overview-heading { font-size: 14px; color: #333; margin: 20px 0 8px; border-bottom: 1px solid #e5dfd0; padding-bottom: 4px; }
+      .overview-heading:first-child { margin-top: 0; }
+      .overview-dl { display: grid; grid-template-columns: auto 1fr; gap: 4px 16px; margin: 0; font-size: 13px; }
+      .overview-dl dt { color: #666; font-weight: bold; }
+      .overview-dl dd { margin: 0; word-break: break-all; }
+      .overview-table { border-collapse: collapse; width: 100%; font-size: 13px; margin: 4px 0; }
+      .overview-table th, .overview-table td { padding: 4px 10px; text-align: left; border-bottom: 1px solid #e5dfd0; }
+      .overview-table th { color: #555; font-weight: bold; font-size: 12px; }
+      .overview-table th.sortable { cursor: pointer; user-select: none; }
+      .overview-table th.sortable:hover { color: #2f6f8e; }
+      .overview-table th[data-sort="asc"]::after { content: " \\25B2"; font-size: 10px; }
+      .overview-table th[data-sort="desc"]::after { content: " \\25BC"; font-size: 10px; }
+      .overview-table td { color: #1f1f1f; }
+      .overview-summary-table { max-width: 400px; }
+      .overview-multitype-table td { font-size: 12px; }
+      .overview-file-link { color: #2f6f8e; text-decoration: none; }
+      .overview-file-link:hover { text-decoration: underline; }
       @media (max-width: 900px) {
         body { padding: 16px; }
         .report-layout { grid-template-columns: 1fr; }

data/lib/lumitrace/generate_resulted_html_renderer.js

@@ -638,6 +638,279 @@
     }
   }
 
+  function computeExpressionCoverage(trace) {
+    const seen = new Set();
+    let total = 0;
+    let executed = 0;
+    for (const event of trace || []) {
+      if (!event || event.kind === "arg") continue;
+      const loc = event.location;
+      if (!Array.isArray(loc) || loc.length < 4) continue;
+      const key = `${loc[SL]}:${loc[SC]}:${loc[EL]}:${loc[EC]}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      total += 1;
+      if (Number(event.total) > 0) executed += 1;
+    }
+    return { total, executed };
+  }
+
+  function computeOverviewData(payload) {
+    const files = payload.files || [];
+    const meta = payload.meta || {};
+
+    let totalExprs = 0, executedExprs = 0;
+    let totalLines = 0, executedLines = 0;
+    const multiTypeExprs = [];
+    const perFile = [];
+
+    for (let i = 0; i < files.length; i++) {
+      const file = files[i];
+      const trace = Array.isArray(file.trace) ? file.trace : [];
+      const display = fileDisplayPath(file, i);
+
+      const exprCov = computeExpressionCoverage(trace);
+      const lineCov = expressionLineCoverageForTrace(trace);
+
+      totalExprs += exprCov.total;
+      executedExprs += exprCov.executed;
+      totalLines += lineCov.expected;
+      executedLines += lineCov.executed;
+
+      const seen = new Set();
+      for (const event of trace) {
+        if (!event) continue;
+        const loc = event.location;
+        if (!Array.isArray(loc) || loc.length < 4) continue;
+        const key = `${loc[SL]}:${loc[SC]}:${loc[EL]}:${loc[EC]}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const types = normalizeTypeCounts(event.types);
+        const typeKeys = Object.keys(types);
+        if (typeKeys.length > 1) {
+          multiTypeExprs.push({
+            file: display,
+            fileKey: fileUrlKey(file, i),
+            line: Number(loc[SL]),
+            types: types
+          });
+        }
+      }
+
+      perFile.push({
+        display,
+        key: fileUrlKey(file, i),
+        exprTotal: exprCov.total,
+        exprExecuted: exprCov.executed,
+        lineTotal: lineCov.expected,
+        lineExecuted: lineCov.executed
+      });
+    }
+
+    return {
+      command: meta.command || null,
+      mode: meta.mode_text || null,
+      rubyVersion: meta.ruby_version || null,
+      lumitraceVersion: meta.lumitrace_version || null,
+      totalExprs, executedExprs,
+      totalLines, executedLines,
+      perFile,
+      multiTypeExprs
+    };
+  }
+
+  function pct(n, d) {
+    if (d === 0) return "—";
+    return (n / d * 100).toFixed(1) + "%";
+  }
+
+  function renderOverviewSection(data, onSelectFile) {
+    const section = document.createElement("section");
+    section.className = "overview-section";
+
+    // Context
+    const ctxH = document.createElement("h2");
+    ctxH.className = "overview-heading";
+    ctxH.textContent = "Execution Context";
+    section.appendChild(ctxH);
+
+    const ctxDl = document.createElement("dl");
+    ctxDl.className = "overview-dl";
+    const ctxItems = [];
+    if (data.command) ctxItems.push(["Command", data.command]);
+    if (data.mode) ctxItems.push(["Collect Mode", data.mode]);
+    if (data.rubyVersion) ctxItems.push(["Ruby", data.rubyVersion]);
+    if (data.lumitraceVersion) ctxItems.push(["Lumitrace", data.lumitraceVersion]);
+    for (const [label, value] of ctxItems) {
+      const dt = document.createElement("dt");
+      dt.textContent = label;
+      ctxDl.appendChild(dt);
+      const dd = document.createElement("dd");
+      dd.textContent = value;
+      ctxDl.appendChild(dd);
+    }
+    section.appendChild(ctxDl);
+
+    // Coverage summary
+    const covH = document.createElement("h2");
+    covH.className = "overview-heading";
+    covH.textContent = "Coverage Summary";
+    section.appendChild(covH);
+
+    const covTable = document.createElement("table");
+    covTable.className = "overview-table overview-summary-table";
+    covTable.innerHTML = `<thead><tr><th></th><th>Executed</th><th>Total</th><th>Coverage</th></tr></thead>` +
+      `<tbody>` +
+      `<tr><td>Expressions</td><td>${data.executedExprs}</td><td>${data.totalExprs}</td><td>${pct(data.executedExprs, data.totalExprs)}</td></tr>` +
+      `<tr><td>Lines</td><td>${data.executedLines}</td><td>${data.totalLines}</td><td>${pct(data.executedLines, data.totalLines)}</td></tr>` +
+      `</tbody>`;
+    section.appendChild(covTable);
+
+    // Per-file coverage table
+    if (data.perFile.length > 0) {
+      const fileH = document.createElement("h2");
+      fileH.className = "overview-heading";
+      fileH.textContent = `File Coverage (${data.perFile.length} files)`;
+      section.appendChild(fileH);
+
+      const fileTable = document.createElement("table");
+      fileTable.className = "overview-table overview-file-table";
+      const thead = document.createElement("thead");
+      const headerRow = document.createElement("tr");
+
+      const columns = [
+        { key: "display", label: "File", type: "string" },
+        { key: "exprPct", label: "Expr %", type: "number" },
+        { key: "exprExecuted", label: "Expr Exec", type: "number" },
+        { key: "exprTotal", label: "Expr Total", type: "number" },
+        { key: "linePct", label: "Line %", type: "number" },
+        { key: "lineExecuted", label: "Line Exec", type: "number" },
+        { key: "lineTotal", label: "Line Total", type: "number" }
+      ];
+
+      let sortCol = "exprPct";
+      let sortAsc = true;
+
+      const rows = data.perFile.map((f) => ({
+        ...f,
+        exprPct: f.exprTotal > 0 ? f.exprExecuted / f.exprTotal * 100 : -1,
+        linePct: f.lineTotal > 0 ? f.lineExecuted / f.lineTotal * 100 : -1
+      }));
+
+      function sortRows() {
+        const col = columns.find((c) => c.key === sortCol);
+        if (!col) return;
+        rows.sort((a, b) => {
+          let av = a[sortCol], bv = b[sortCol];
+          if (col.type === "string") {
+            av = String(av || "");
+            bv = String(bv || "");
+            return sortAsc ? av.localeCompare(bv) : bv.localeCompare(av);
+          }
+          return sortAsc ? av - bv : bv - av;
+        });
+      }
+
+      function renderFileTableBody() {
+        sortRows();
+        const oldTbody = fileTable.querySelector("tbody");
+        if (oldTbody) oldTbody.remove();
+        const tbody = document.createElement("tbody");
+        for (const row of rows) {
+          const tr = document.createElement("tr");
+          const tdFile = document.createElement("td");
+          const link = document.createElement("a");
+          link.href = "#";
+          link.className = "overview-file-link";
+          link.textContent = row.display;
+          link.addEventListener("click", (e) => { e.preventDefault(); onSelectFile(row.key); });
+          tdFile.appendChild(link);
+          tr.appendChild(tdFile);
+          tr.appendChild(cellTd(row.exprPct >= 0 ? row.exprPct.toFixed(1) + "%" : "—"));
+          tr.appendChild(cellTd(row.exprExecuted));
+          tr.appendChild(cellTd(row.exprTotal));
+          tr.appendChild(cellTd(row.linePct >= 0 ? row.linePct.toFixed(1) + "%" : "—"));
+          tr.appendChild(cellTd(row.lineExecuted));
+          tr.appendChild(cellTd(row.lineTotal));
+          tbody.appendChild(tr);
+        }
+        fileTable.appendChild(tbody);
+
+        // update header sort indicators
+        headerRow.querySelectorAll("th").forEach((th) => {
+          const col = th.dataset.col;
+          if (col === sortCol) {
+            th.dataset.sort = sortAsc ? "asc" : "desc";
+          } else {
+            delete th.dataset.sort;
+          }
+        });
+      }
+
+      function cellTd(val) {
+        const td = document.createElement("td");
+        td.textContent = String(val);
+        return td;
+      }
+
+      for (const col of columns) {
+        const th = document.createElement("th");
+        th.textContent = col.label;
+        th.dataset.col = col.key;
+        th.className = "sortable";
+        th.addEventListener("click", () => {
+          if (sortCol === col.key) {
+            sortAsc = !sortAsc;
+          } else {
+            sortCol = col.key;
+            sortAsc = col.type === "string";
+          }
+          renderFileTableBody();
+        });
+        headerRow.appendChild(th);
+      }
+      thead.appendChild(headerRow);
+      fileTable.appendChild(thead);
+      renderFileTableBody();
+      section.appendChild(fileTable);
+    }
+
+    // Multi-type expressions
+    if (data.multiTypeExprs.length > 0) {
+      const mtH = document.createElement("h2");
+      mtH.className = "overview-heading";
+      mtH.textContent = `Multi-type Expressions (${data.multiTypeExprs.length})`;
+      section.appendChild(mtH);
+
+      const mtTable = document.createElement("table");
+      mtTable.className = "overview-table overview-multitype-table";
+      mtTable.innerHTML = `<thead><tr><th>File</th><th>Line</th><th>Types</th></tr></thead>`;
+      const tbody = document.createElement("tbody");
+      for (const entry of data.multiTypeExprs) {
+        const tr = document.createElement("tr");
+        const tdFile = document.createElement("td");
+        const link = document.createElement("a");
+        link.href = "#";
+        link.className = "overview-file-link";
+        link.textContent = entry.file;
+        link.addEventListener("click", (e) => { e.preventDefault(); onSelectFile(entry.fileKey, entry.line); });
+        tdFile.appendChild(link);
+        tr.appendChild(tdFile);
+        const tdLine = document.createElement("td");
+        tdLine.textContent = String(entry.line);
+        tr.appendChild(tdLine);
+        const tdTypes = document.createElement("td");
+        tdTypes.textContent = Object.entries(entry.types).sort(([, a], [, b]) => b - a).map(([t, c]) => `${t}(${c})`).join(", ");
+        tr.appendChild(tdTypes);
+        tbody.appendChild(tr);
+      }
+      mtTable.appendChild(tbody);
+      section.appendChild(mtTable);
+    }
+
+    return section;
+  }
+
   function render(payload) {
     app.textContent = "";
 
@@ -702,20 +975,45 @@
     viewer.className = "report-viewer";
     main.appendChild(viewer);
 
+    const OVERVIEW_KEY = "__overview__";
+    const overviewData = computeOverviewData(payload);
+
     const fileKeyToEntry = new Map();
     files.forEach((file, idx) => fileKeyToEntry.set(fileUrlKey(file, idx), { file, idx }));
 
-    let selectedKey = preferredInitialFileKey(files);
-    let selectedLine = preferredInitialLineNumber();
+    let selectedKey = files.length > 1 ? OVERVIEW_KEY : preferredInitialFileKey(files);
+    let selectedLine = files.length > 1 ? null : preferredInitialLineNumber();
 
     function renderTree() {
       treeMount.textContent = "";
+
+      // Overview button
+      if (files.length > 1) {
+        const overviewBtn = document.createElement("button");
+        overviewBtn.type = "button";
+        overviewBtn.className = "tree-file-btn tree-overview-btn";
+        if (selectedKey === OVERVIEW_KEY) {
+          overviewBtn.classList.add("active");
+          overviewBtn.setAttribute("aria-current", "page");
+        }
+        overviewBtn.textContent = "Overview";
+        overviewBtn.addEventListener("click", () => selectOverview(true));
+        treeMount.appendChild(overviewBtn);
+      }
+
       const treeRoot = buildFileTree(files);
       treeMount.appendChild(renderFileTreeNode(treeRoot, selectedKey, (key) => selectFile(key, true, null), 0));
     }
 
-    function renderSelectedFile() {
+    function renderSelectedView() {
       viewer.textContent = "";
+
+      if (selectedKey === OVERVIEW_KEY) {
+        currentPath.textContent = "Overview";
+        viewer.appendChild(renderOverviewSection(overviewData, (key, line) => selectFile(key, true, line || null)));
+        return;
+      }
+
       const entry = fileKeyToEntry.get(selectedKey);
       if (!entry) return;
 
@@ -733,10 +1031,18 @@
     function selectLine(lineno, updateHash) {
       const n = Number(lineno);
       selectedLine = Number.isFinite(n) && n > 0 ? n : null;
-      renderSelectedFile();
+      renderSelectedView();
       if (updateHash) setLocationHashSelection(selectedKey, selectedLine);
     }
 
+    function selectOverview(updateHash) {
+      selectedKey = OVERVIEW_KEY;
+      selectedLine = null;
+      renderTree();
+      renderSelectedView();
+      if (updateHash) setLocationHashSelection("overview", null);
+    }
+
     function selectFile(key, updateHash, nextLine) {
       if (!fileKeyToEntry.has(key)) return;
       if (arguments.length >= 3) {
@@ -746,23 +1052,31 @@
       }
       selectedKey = key;
       renderTree();
-      renderSelectedFile();
+      renderSelectedView();
       if (updateHash) setLocationHashSelection(key, selectedLine);
     }
 
     window.addEventListener("hashchange", () => {
       const state = parseHashStateFromLocation();
+      if (state.fileKey === "overview") {
+        if (selectedKey !== OVERVIEW_KEY) selectOverview(false);
+        return;
+      }
       if (state.fileKey && state.fileKey !== selectedKey && fileKeyToEntry.has(state.fileKey)) {
         selectFile(state.fileKey, false, state.line);
         return;
       }
       if (state.fileKey === selectedKey || (!state.fileKey && selectedKey)) {
         selectedLine = state.line;
-        renderSelectedFile();
+        renderSelectedView();
       }
     });
 
-    selectFile(selectedKey, true);
+    if (selectedKey === OVERVIEW_KEY) {
+      selectOverview(true);
+    } else {
+      selectFile(selectedKey, true);
+    }
   }
 
   try {

data/lib/lumitrace/help_manifest.rb

@@ -23,7 +23,8 @@ module Lumitrace
         "First run with `--collect-mode types` to get a compact shape of runtime behavior.",
         "Then switch to `--collect-mode last` for final value inspection on suspicious lines.",
         "Use `--collect-mode history --max-samples N` only when value transitions matter.",
-        "Combine `--range` or `--git-diff` to keep outputs small and focused."
+        "Combine `--range` or `--git-diff` to keep outputs small and focused.",
+        "-j, -h, -t are flags that enable output with default paths. Use --json PATH, --html PATH, --text PATH to specify output paths."
       ],
       commands: [
         {
@@ -56,9 +57,9 @@ 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: "-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: "-j / --json PATH", type: "bool|string", note: "Emit JSON output. -j uses default path; --json PATH writes to PATH." },
+        { name: "-h / --html PATH", type: "bool|string", note: "Emit HTML output. -h uses default path; --html PATH writes to PATH." },
+        { name: "-t / --text PATH", type: "bool|string", note: "Emit text output. -t uses default path; --text PATH writes to PATH." },
         { 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-context N", type: "Integer", note: "Expand diff hunks by +/-N lines." },
@@ -76,6 +77,8 @@ module Lumitrace
         "lumitrace --collect-mode history --max-samples 5 -j app.rb",
         "lumitrace --collect-mode types -h -j app.rb",
         "lumitrace --collect-mode last -j exec bin/rails test",
+        "lumitrace --json output.json exec bin/rails test",
+        "lumitrace -j --html report.html app.rb",
         "lumitrace help --format json",
         "lumitrace schema --format json"
       ]

data/lib/lumitrace/record_require.rb

@@ -94,7 +94,7 @@ if defined?(RubyVM::InstructionSequence)
         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) &&
+        if RecordRequire.in_root?(abs) && File.file?(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)

data/lib/lumitrace/version.rb

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

data/lib/lumitrace.rb

@@ -290,9 +290,12 @@ module Lumitrace
       o.banner = banner if banner
       o.separator ""
       o.separator "Options:"
-      o.on("-t", "--text[=PATH]", "Text output (stdout or PATH)") { |v| opts[:text] = v.nil? || v.empty? ? true : v }
-      o.on("-h", "--html[=PATH]", "HTML output (default file or PATH)") { |v| opts[:html] = v.nil? || v.empty? ? true : v }
-      o.on("-j", "--json[=PATH]", "JSON output (default file or PATH)") { |v| opts[:json] = v.nil? || v.empty? ? true : v }
+      o.on("-t", "Enable text output (stdout or default path)") { opts[:text] = true }
+      o.on("--text PATH", "Text output to PATH") { |v| opts[:text] = v }
+      o.on("-h", "Enable HTML output (default path)") { opts[:html] = true }
+      o.on("--html PATH", "HTML output to PATH") { |v| opts[:html] = v }
+      o.on("-j", "Enable JSON output (default path)") { opts[:json] = true }
+      o.on("--json PATH", "JSON output to PATH") { |v| opts[:json] = v }
       o.on("-g", "--git-diff[=MODE]", "Diff ranges (working, staged, base:REV, range:SPEC)") { |v| opts[:git_diff_mode] = v.nil? || v.empty? ? "working" : v }
       o.on("--max-samples N", Integer, "Max samples per expression") { |v| opts[:max_samples] = v }
       o.on("--collect-mode MODE", "Collect mode: last, types, history") { |v| opts[:collect_mode] = v }

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

@@ -27,7 +27,7 @@ jobs:
       - name: Run tests with Lumitrace
         env:
           LUMITRACE_GIT_DIFF: range:origin/${{ github.base_ref }}...HEAD
-        run: bundle exec lumitrace -v -t --html=lumitrace_recorded.html exec rake test
+        run: bundle exec lumitrace -v -t --html lumitrace_recorded.html exec rake test
 
       - name: Prepare Pages content
         run: |

data/sample/sample_project/README.md

@@ -42,7 +42,7 @@ steps:
   - name: Run tests with Lumitrace
     env:
       LUMITRACE_GIT_DIFF: range:origin/${{ github.base_ref }}...HEAD
-    run: bundle exec lumitrace -v -t --html=lumitrace_recorded.html exec rake test
+    run: bundle exec lumitrace -v -t --html lumitrace_recorded.html exec rake test
 
   - name: Prepare Pages content
     run: |

data/test/test_lumitrace.rb

@@ -128,7 +128,7 @@ class LumiTraceTest < Minitest::Test
   end
 
   def test_parse_cli_options_basic
-    argv = ["-t", "--html=/tmp/out.html", "-j", "--max-samples", "7", "--collect-mode", "history", "--root", "/tmp/root",
+    argv = ["-t", "--html", "/tmp/out.html", "-j", "--max-samples", "7", "--collect-mode", "history", "--root", "/tmp/root",
             "--range", "a.rb:1-3,5-6", "--verbose", "file.rb"]
     opts, args, _parser = Lumitrace.parse_cli_options(argv, allow_help: true)
 
@@ -144,7 +144,7 @@ class LumiTraceTest < Minitest::Test
   end
 
   def test_parse_enable_args_cli_string
-    opts = Lumitrace.parse_enable_args("--text=/tmp/out.txt -h --json=/tmp/out.json --max-samples 5 --collect-mode types --root /tmp/root")
+    opts = Lumitrace.parse_enable_args("--text /tmp/out.txt -h --json /tmp/out.json --max-samples 5 --collect-mode types --root /tmp/root")
 
     assert_equal "/tmp/out.txt", opts[:text]
     assert_equal true, opts[:html]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lumitrace
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Koichi Sasada
@@ -23,6 +23,7 @@ files:
 - bench/bench_sample.rb
 - docs/ai-help.md
 - docs/ai-schema.md
+- docs/lumitrace_html_example.png
 - docs/spec.md
 - docs/supported_syntax.md
 - docs/tutorial.ja.md