lumitrace 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff34ab7d27bf0d9882368d03a66d0409cb093c5d0850f896e4be79d19a06753d
-  data.tar.gz: ec55e6059af4babd1ab074d74b17104a1a6b36e576c55d32a44b4f53a3227855
+  metadata.gz: 4be2a97656c1b025f8ae4c8eacf1f1d00969f0759de4b838fdb0681610689e76
+  data.tar.gz: a2142bb03fec41ed02668ae63c27437dfe885f874bbb758cb1b5649fde2df635
 SHA512:
-  metadata.gz: 26c2710ee8a470ae316541d1d833556a14a19f87d775b88904cd06816c4e192b3dd9c6f9f07811235d4350acb1341c78a8b2e7ef47a7880369871280afe7f0b9
-  data.tar.gz: d30d9161e9ab43473004b0a694fe7269aa3255ce9763f746b3233d6e6eebf218b06d885a4913c7401a74de5a23bc425ed5435c6aa91297422dd17ee32d186642
+  metadata.gz: 42b5a8463939fe9820d9cce36bc56f2b3bb5eb2759096f975f517460d371969353a0fe322181fb7ab153eb94f388888f4118b8c9e5eebcd1b744046c778874e3
+  data.tar.gz: f076ae99fdfd6f0f28d77f29957c504e254609b1812a265b3353c368173007bbd21570c683064b9704bf8e81c49132bef2e03f573987047c27e09229e272082b

data/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS
+
+This file describes how agents should work in this repository.
+
+## Purpose
+- Keep changes focused on Lumitrace and its docs/tests.
+- Prefer minimal, reviewable edits over wide refactors.
+
+## Where To Look First
+- Overview and usage: `README.md`
+- Detailed behavior/spec: `docs/spec.md`
+- Syntax coverage: `docs/supported_syntax.md`
+- Tutorials: `docs/tutorial.md`, `docs/tutorial.ja.md`
+
+## Repository Layout
+- Source code: `lib/`, `exe/`, `bin/`
+- Docs: `docs/`
+- Tests: `test/`
+- Samples: `sample/`
+
+## Coding And Style
+- Follow existing Ruby style and structure in nearby files.
+- Keep changes small and localized when possible.
+- Add comments only when logic is non-obvious.
+
+## Tests
+- Prefer running the smallest relevant test set.
+- When source code changes, run tests by default (at least `rake test`).
+- If you cannot run tests, say so and explain why.
+
+## Safety
+- Do not delete or rewrite large sections without a clear reason.
+- Do not use destructive git commands unless asked.
+
+## Communication
+- Summarize what you changed and why.
+- Call out any assumptions or follow-ups needed.

data/README.md

@@ -8,6 +8,8 @@ Lumitrace instruments Ruby source code at load time, records expression results,
 - [Tutorial](https://ko1.github.io/lumitrace/docs/tutorial.html)
 - [Tutorial in Japanese](https://ko1.github.io/lumitrace/docs/tutorial.ja.html)
 - [Spec](https://ko1.github.io/lumitrace/docs/spec.html)
+- [AI Help](https://ko1.github.io/lumitrace/docs/ai-help.html)
+- [AI Schema](https://ko1.github.io/lumitrace/docs/ai-schema.html)
 - [Supported Syntax](https://ko1.github.io/lumitrace/docs/supported_syntax.html)
 - [GitHub repository](https://github.com/ko1/lumitrace)
 
@@ -41,7 +43,7 @@ lumitrace -h path/to/entry.rb
 Limit the number of recorded values per expression (defaults to 3):
 
 ```bash
-LUMITRACE_VALUES_MAX=5 lumitrace path/to/entry.rb
+LUMITRACE_MAX_SAMPLES=5 lumitrace path/to/entry.rb
 ```
 
 Write JSON output explicitly:
@@ -57,6 +59,14 @@ Restrict to specific line ranges:
 lumitrace --range path/to/entry.rb:10-20,30-35 path/to/entry.rb
 ```
 
+Show AI/human help:
+
+```bash
+lumitrace help
+lumitrace help --format json
+lumitrace schema --format json
+```
+
 ### Library
 
 Enable instrumentation and HTML output at exit:
@@ -83,11 +93,28 @@ require "lumitrace/enable"
 - 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`).
 - Fork/exec: merged by default. Child processes write fragments under `LUMITRACE_RESULTS_DIR`.
 
+JSON event entries always include `types` (type-name => count).
+
+```json
+{
+  "file": "/abs/path/app.rb",
+  "start_line": 10,
+  "start_col": 2,
+  "end_line": 10,
+  "end_col": 9,
+  "kind": "expr",
+  "types": { "Integer": 3, "NilClass": 1 },
+  "total": 4
+}
+```
+
 ## Environment Variables
 
-- `LUMITRACE_VALUES_MAX`: default max values per expression (default 3 if unset).
+- `LUMITRACE_MAX_SAMPLES`: default max samples per expression (default 3 if unset).
+- `LUMITRACE_COLLECT_MODE`: value collection mode (`last`, `types`, `history`; default `last`).
 - `LUMITRACE_ROOT`: root directory used to decide which files are instrumented.
 - `LUMITRACE_TEXT`: control text output. `1` forces text on, `0`/`false` disables. Any other value is treated as the text output path.
 - `LUMITRACE_HTML`: enable HTML output; `1` uses the default path, otherwise treats the value as the HTML output path. `0`/`false` disables.
@@ -105,7 +132,7 @@ require "lumitrace/enable"
 ## Notes And Limitations
 
 - Requires `RubyVM::InstructionSequence.translate` support.
-- Very large projects or hot loops can still generate large HTML; use `LUMITRACE_VALUES_MAX`.
+- Very large projects or hot loops can still generate large HTML; use `LUMITRACE_MAX_SAMPLES`.
 - Instrumentation changes evaluation order for debugging, not for production.
 
 ## Development

data/Rakefile

@@ -13,6 +13,27 @@ task default: :test
 
 require "benchmark"
 
+desc "Sync embedded Lumitrace code in runv/index.html"
+task :runv do
+  ruby "runv/sync_inline.rb"
+end
+
+namespace :docs do
+  desc "Generate AI help/schema docs from manifests"
+  task :ai do
+    require_relative "lib/lumitrace"
+
+    help_path = File.expand_path("docs/ai-help.md", __dir__)
+    schema_path = File.expand_path("docs/ai-schema.md", __dir__)
+
+    File.write(help_path, Lumitrace.render_ai_help_markdown)
+    File.write(schema_path, Lumitrace.render_ai_schema_markdown)
+
+    puts "updated #{help_path}"
+    puts "updated #{schema_path}"
+  end
+end
+
 desc "Run simple runtime comparison for lumitrace vs ruby"
 task :bench do
   sample = File.expand_path("bench/bench_sample.rb", __dir__)

data/bench/bench_sample.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Small-ish workload for lumitrace timing.
+# Run:
+#   time lumitrace bench_sample.rb
+
+WORDS = %w[alpha beta gamma delta epsilon zeta eta theta iota kappa lambda mu nu xi omicron pi rho sigma tau upsilon phi chi psi omega].freeze
+
+class MiniReport
+  def initialize(size)
+    @size = size
+  end
+
+  def run
+    data = build_data
+    counts = count_words(data)
+    stats = summarize(counts)
+    format_output(stats)
+  end
+
+  private
+
+  def build_data
+    out = []
+    @size.times do |i|
+      base = WORDS[i % WORDS.length]
+      out << "#{base}-#{i}"
+      if i % 7 == 0
+        out << base.upcase
+      elsif i % 5 == 0
+        out << base.reverse
+      end
+    end
+    out
+  end
+
+  def count_words(data)
+    counts = Hash.new(0)
+    data.each do |w|
+      key = w.downcase
+      counts[key] += 1
+    end
+    counts
+  end
+
+  def summarize(counts)
+    top = counts.sort_by { |_, v| -v }.first(5)
+    total = counts.values.sum
+    {
+      total: total,
+      unique: counts.length,
+      top: top
+    }
+  end
+
+  def format_output(stats)
+    lines = []
+    lines << "total=#{stats[:total]} unique=#{stats[:unique]}"
+    stats[:top].each_with_index do |(k, v), idx|
+      lines << "#{idx + 1}. #{k}=#{v}"
+    end
+    lines.join("\n")
+  end
+end
+
+n = (ENV["N"] || 1000).to_i
+report = MiniReport.new(n)
+result = report.run
+
+# Keep output minimal but non-empty
+puts result if ENV["PRINT"] == "1"

data/docs/ai-help.md

@@ -0,0 +1,44 @@
+<!-- generated file: do not edit. run `rake docs:ai` -->
+
+# Lumitrace Help
+
+- Version: 0.4.0
+- Help version: 1
+- Primary JSON entrypoint: `lumitrace help --format json`
+- Schema JSON entrypoint: `lumitrace schema --format json`
+
+## Recommended Flow
+- Read `lumitrace help --format json`.
+- Read `lumitrace schema --format json` to understand output structure.
+- Run lumitrace with `--collect-mode` and optional `--max-samples`.
+- Inspect JSON/HTML/text outputs depending on your task.
+
+## Commands
+- `lumitrace [options] script.rb [ruby_opt]`
+  - Run a Ruby script with Lumitrace enabled.
+- `lumitrace [options] exec CMD [args...]`
+  - Run an arbitrary command with Lumitrace env injected.
+- `lumitrace help [--format text|json]`
+  - Show AI/human help.
+- `lumitrace schema [--format text|json]`
+  - Show output schema for each collect mode.
+
+## Collect Modes
+- `last`: Keep only the last observed value and type counts.
+- `types`: Keep only type counts and total hit count.
+- `history`: Keep last N sampled values and type counts.
+
+## 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.)
+- `--range SPEC` (repeatable=true; Restrict instrumentation to file ranges.)
+- `--git-diff[=MODE]` (Restrict instrumentation to diff hunks.)
+
+## Examples
+- `lumitrace --collect-mode history --max-samples 5 -j app.rb`
+- `lumitrace --collect-mode types -h -j app.rb`
+- `lumitrace help --format json`
+- `lumitrace schema --format json`

data/docs/ai-schema.md

@@ -0,0 +1,36 @@
+<!-- generated file: do not edit. run `rake docs:ai` -->
+
+# Lumitrace JSON Schema
+
+- Version: 0.4.0
+- Schema version: 1
+- Top level: array of event
+
+## Common Event Fields
+- `file` (string, required) - Absolute source path.
+- `start_line` (integer, required)
+- `start_col` (integer, required)
+- `end_line` (integer, required)
+- `end_col` (integer, required)
+- `kind` (string, required)
+- `name` (string|null, optional) - Present for kind=arg.
+- `total` (integer, required) - Execution count.
+- `types` (object, required) - Ruby class name => observed count.
+
+## Value Summary Fields
+- `type` (string, required) - Ruby class name.
+- `preview` (string, required) - Value preview string (inspect-based).
+- `length` (integer, optional) - Original preview length when preview was truncated.
+
+## Collect Modes
+- `last`
+  - required fields: file, start_line, start_col, end_line, end_col, kind, total, types, last_value
+  - optional fields: name
+  - `last_value`: value_summary
+- `types`
+  - required fields: file, start_line, start_col, end_line, end_col, kind, total, types
+  - optional fields: name
+- `history`
+  - required fields: file, start_line, start_col, end_line, end_col, kind, total, types, sampled_values
+  - optional fields: name
+  - `sampled_values`: array (items: value_summary)

data/docs/spec.md

@@ -7,6 +7,12 @@
 
 Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSequence.translate` when available), records expression results, and renders text or HTML output that overlays recorded values on your code. It is designed for local “what happened here?” inspection.
 
+## AI-Oriented Docs
+
+- AI help reference: `docs/ai-help.md`
+- AI schema reference: `docs/ai-schema.md`
+- Regenerate both files with: `rake docs:ai`
+
 ## Goals
 
 - Record expression results with minimal friction.
@@ -35,10 +41,10 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
 - `LUMITRACE_ENABLE=1` + `require "lumitrace"` (auto-`enable!`)
 - `LUMITRACE_ENABLE="-t -h -j ..."` + `require "lumitrace"` (CLI-style options parsed and passed to `enable!`)
 
-### `Lumitrace.enable!(max_values: nil, ranges_by_file: nil, root: nil, text: nil, html: nil, json: nil, verbose: nil, at_exit: true)`
+### `Lumitrace.enable!(max_samples: nil, ranges_by_file: nil, root: nil, text: nil, html: nil, json: nil, verbose: nil, at_exit: true)`
 
 - Arguments:
-  - `max_values`: integer, string, or nil.
+  - `max_samples`: integer, string, or nil.
   - `ranges_by_file`: hash or nil. `{ "/path/to/file.rb" => [1..5, 10..12] }`.
   - `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.
@@ -52,7 +58,8 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
   - Fixes the HTML output directory to the `Dir.pwd` at call time.
 - Root scope for instrumentation uses `root` if provided, otherwise `ENV["LUMITRACE_ROOT"]` if set, otherwise `Dir.pwd`.
 - Environment variables (resolved by `Lumitrace.enable!`):
-  - `LUMITRACE_VALUES_MAX`: default max values per expression when `max_values` is nil (default 3 if unset).
+  - `LUMITRACE_MAX_SAMPLES`: default max samples per expression when `max_samples` is nil (default 3 if unset).
+  - `LUMITRACE_COLLECT_MODE`: value collection mode (`last`, `types`, `history`; default `last`).
   - `LUMITRACE_ROOT`: root directory used to decide which files are instrumented.
   - `LUMITRACE_HTML`: enable HTML output; `1` uses the default path, otherwise treats the value as the HTML output path. `0`/`false` disables.
   - `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.
@@ -129,6 +136,7 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
 ### Wrap Targets
 
 - `CallNode` (except those with block bodies)
+- `YieldNode`
 - Variable reads:
   - `LocalVariableReadNode`
   - `ConstantReadNode`
@@ -136,15 +144,18 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
   - `ClassVariableReadNode`
   - `GlobalVariableReadNode`
 - Literal nodes are excluded (e.g. integer, string, true/false, nil, etc.)
+- Method and block arguments are recorded by inserting `Lumitrace::R` at the start of the body.
 
 ## Recording
 
 - Results are stored per expression key:
   - `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).
+- Collection mode is selected by `collect_mode` (`last`, `types`, `history`; default `last`).
+- In `history` mode, keep only the last N values (`max_samples_per_expr`, default 3).
 - Track `total` count for how many times the expression executed.
-- Values are stored via `inspect` for non-primitive types.
-- String values are truncated to 1000 bytes for storage.
+- In `collect_mode=last`, `last_value.preview` is always the `inspect` result string.
+- `last_value.length` is included only when `preview` is truncated.
+- Argument records are stored alongside expression records with `kind: "arg"` and `name` (argument name).
 
 ## Fork/Exec Merge
 
@@ -156,7 +167,42 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
 
 ### Output JSON
 
-`lumitrace_recorded.json` contains an array of entries:
+`lumitrace_recorded.json` contains an array of entries.
+
+`collect_mode=last` (default):
+
+```json
+{
+  "file": "/path/to/file.rb",
+  "start_line": 10,
+  "start_col": 4,
+  "end_line": 10,
+  "end_col": 20,
+  "kind": "expr",
+  "name": null,
+  "last_value": { "type": "String", "preview": "\"ok\"" },
+  "types": { "Integer": 10, "NilClass": 2, "String": 111 },
+  "total": 123
+}
+```
+
+`collect_mode=types`:
+
+```json
+{
+  "file": "/path/to/file.rb",
+  "start_line": 10,
+  "start_col": 4,
+  "end_line": 10,
+  "end_col": 20,
+  "kind": "expr",
+  "name": null,
+  "types": { "Integer": 10, "NilClass": 2, "String": 111 },
+  "total": 123
+}
+```
+
+`collect_mode=history`:
 
 ```json
 {
@@ -165,11 +211,22 @@ Lumitrace instruments Ruby source code at load time (via `RubyVM::InstructionSeq
   "start_col": 4,
   "end_line": 10,
   "end_col": 20,
-  "values": ["..."],
+  "kind": "expr",
+  "name": null,
+  "sampled_values": [
+    { "type": "Integer", "preview": "42" },
+    { "type": "NilClass", "preview": "nil" },
+    { "type": "String", "preview": "\"ok\"" }
+  ],
+  "types": { "Integer": 10, "NilClass": 2, "String": 111 },
   "total": 123
 }
 ```
 
+- `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.
+
 ## CLI
 
 ### `lumitrace`
@@ -184,14 +241,15 @@ lumitrace [options] exec CMD [args...]
 - `-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` sets max values per expression.
+- `--max-samples` sets max samples per expression in `collect_mode=history`.
+- `--collect-mode` sets value collection mode (`last|types|history`).
 - `--range` restricts instrumentation per file (`FILE` or `FILE:1-5,10-12`). Can be repeated.
 - `--git-diff=MODE` restricts instrumentation to diff hunks (`staged|base:REV|range:SPEC`).
 - `--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[=LEVEL]` prints verbose logs to stderr (level 1-3).
-- `LUMITRACE_VALUES_MAX` sets the default max values per expression.
+- `LUMITRACE_MAX_SAMPLES` sets the default max samples per expression.
 - The CLI launches a child process (Ruby or `exec` target) with `RUBYOPT=-rlumitrace` and `LUMITRACE_*` env vars.
 
 ### Text Output (CLI)
@@ -199,19 +257,28 @@ lumitrace [options] exec CMD [args...]
 - Text output starts with a header line: `=== Lumitrace Results (text) ===`.
 - Each file is printed with a header: `### path/to/file.rb`.
 - Each line is prefixed with a line number like ` 12| `.
+- Lines where all instrumentable expressions are unexecuted are prefixed with `!`.
 - Skipped ranges are represented by a line containing `...`.
-- Only the last value is shown per expression; if an expression ran multiple times, the last value is annotated with the ordinal run (e.g., `#=> 2 (3rd run)`).
-- When `--text` is used and `--max` is not provided, `max_values` defaults to `1`.
+- Only the last value is shown per expression as `value (Type)`; if an expression ran multiple times, the last value is annotated with the ordinal run (e.g., `#=> 2 (Integer) (3rd run)`).
+- When `collect_mode=history` and `--text` is used with no `--max-samples`, `max_samples` defaults to `1`.
 - When `ranges_by_file` is provided, only files present in the hash are shown in text output.
+- When writing to stdout (`tty: true`), long comments are truncated to the terminal width (using `COLUMNS` or `IO.console.winsize`). File output is not truncated.
 
 ## HTML Rendering
 
 - `GenerateResultedHtml.render_all` renders all files in one page.
+- 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.
-- Expressions are marked with an inline icon.
+- 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; additional values are summarized as `... (+N more)`.
+- 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.
+- 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.
 
 ### Copy/Paste Behavior
 

data/docs/supported_syntax.md

@@ -21,6 +21,11 @@ positions:
     ```ruby
     foo(bar)
     ```
+- `yield` expressions (`Prism::YieldNode`)
+  - Example:
+    ```ruby
+    yield value
+    ```
 - Local variable reads (`Prism::LocalVariableReadNode`)
   - Example:
     ```ruby

data/docs/tutorial.ja.md

@@ -26,11 +26,13 @@ lumitrace sample/sample.rb
   ```
    12| 
   ```
+- 記録対象の式がすべて未実行の行は `!` が付きます。
 - 範囲が飛ぶ場合は次の行が入ります:
   ```
   ...
   ```
 - 最終値は `#=> ...` で表示され、複数回実行された場合は `(3rd run)` が付きます。
+- TTY に出力する場合、長いコメントは端末幅（`COLUMNS` または `IO.console.winsize`）に合わせて省略されます。
 
 出力例（stdout）:
 
@@ -123,6 +125,12 @@ Lumitrace のテキストは `sample/lumitrace_results_01.txt`、HTML は `sampl
 HTML 出力を見る:
 - [lumitrace_results_01.html](https://ko1.github.io/lumitrace/sample/lumitrace_results_01.html)
 
+HTML について:
+- 実行済みの式は `🔎`、未実行の式は `∅` で表示されます。
+- 引数の値は HTML では `🧷` で表示されます。
+- 記録対象の式がすべて未実行の行は薄い赤で表示され、混在行では未実行の式のみ薄赤になります。
+- 範囲指定時の省略は行番号欄に `...` が入ります。
+
 ### 範囲指定の例
 
 出力が多いときは、対象行を絞って読みやすくします。
@@ -145,6 +153,7 @@ HTML 出力を見る:
 === Lumitrace Results (text) ===
 
 ### sample/sample.rb (lines: 4-18, 28-32)
+...
  4| def score(n)
  5|   base = n + 1                 #=> 3 (3rd run)
  6|   scaled = Sample2.scale(base) #=> 6 (3rd run)
@@ -166,6 +175,7 @@ HTML 出力を見る:
 30| 
 31| puts labels.join(", ") #=> nil
 32| p flags                #=> [false, false, true]
+...
 ```
 
 環境変数で HTML を有効化:
@@ -180,7 +190,7 @@ LUMITRACE_HTML=/tmp/out.html lumitrace path/to/entry.rb
 出力が長すぎたり読みづらいときに、1 行あたりの記録数を制限します。
 
 ```bash
-LUMITRACE_VALUES_MAX=5 lumitrace path/to/entry.rb
+LUMITRACE_MAX_SAMPLES=5 lumitrace path/to/entry.rb
 ```
 
 ### 行範囲を限定する
@@ -220,9 +230,11 @@ lumitrace -g --git-diff-no-untracked path/to/entry.rb
 レンジ計算や動作の理由を追いたいときに有効です。
 
 ```bash
-lumitrace --verbose path/to/entry.rb
+lumitrace --verbose[=LEVEL] path/to/entry.rb
 ```
 
+レベル: `1`（基本ログ）、`2`（変換したファイル名）、`3`（変換後ソース）。
+
 ### JSON も出力する
 
 ツール連携や後処理のために JSON を出します。
@@ -249,6 +261,7 @@ CI アーティファクトなどに残したいときに便利です。
 lumitrace --text=/tmp/lumi.txt path/to/entry.rb
 ```
 
+
 ### テキストと HTML を両方出力
 
 素早い確認と詳細閲覧を一回で得たいときに使います。
@@ -409,5 +422,5 @@ lumitrace --root /path/to/project your_script.rb
 
 日常的に効く小さなコツをまとめます。
 
-- 出力が大きい場合は `LUMITRACE_VALUES_MAX` を下げると軽くなります。
+- 出力が大きい場合は `LUMITRACE_MAX_SAMPLES` を下げると軽くなります。
 - 1 ファイルだけの確認は `enable_git_diff` が便利です。

data/docs/tutorial.md

@@ -26,11 +26,13 @@ Text output format:
   ```
    12| 
   ```
+- Lines where all instrumentable expressions are unexecuted are prefixed with `!`.
 - Skipped ranges are shown as:
   ```
   ...
   ```
 - The last value is shown as `#=> ...` (with `(3rd run)` when run multiple times).
+- When printing to a TTY, long comments are truncated to the terminal width (from `COLUMNS` or `IO.console.winsize`).
 
 Example output (stdout):
 
@@ -123,6 +125,12 @@ If you run without `--html PATH`, the HTML output defaults to `lumitrace_recorde
 View the HTML output:
 - [lumitrace_results_01.html](https://ko1.github.io/lumitrace/sample/lumitrace_results_01.html)
 
+HTML notes:
+- Executed expressions show `🔎`; unexecuted expressions show `∅`.
+- 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.
+
 ### 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.
@@ -145,6 +153,7 @@ View the HTML output:
 === Lumitrace Results (text) ===
 
 ### sample/sample.rb (lines: 4-18, 28-32)
+...
  4| def score(n)
  5|   base = n + 1                 #=> 3 (3rd run)
  6|   scaled = Sample2.scale(base) #=> 6 (3rd run)
@@ -166,6 +175,7 @@ View the HTML output:
 30| 
 31| puts labels.join(", ") #=> nil
 32| p flags                #=> [false, false, true]
+...
 ```
 
 Enable HTML output via env:
@@ -180,7 +190,7 @@ LUMITRACE_HTML=/tmp/out.html lumitrace path/to/entry.rb
 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
+LUMITRACE_MAX_SAMPLES=5 lumitrace path/to/entry.rb
 ```
 
 ### Limit to specific lines
@@ -220,9 +230,11 @@ lumitrace -g --git-diff-no-untracked path/to/entry.rb
 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
+lumitrace --verbose[=LEVEL] path/to/entry.rb
 ```
 
+Levels: `1` (basic), `2` (instrumented file names), `3` (instrumented source).
+
 ### Write JSON too
 
 Use JSON output when you want to post-process results with scripts or other tools.
@@ -249,6 +261,7 @@ Send text output to a file when you want to archive results or attach them to CI
 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.
@@ -408,5 +421,5 @@ lumitrace --root /path/to/project your_script.rb
 
 Small knobs that keep outputs readable and noise low in day-to-day use.
 
-- If your output is large, lower `LUMITRACE_VALUES_MAX`.
+- If your output is large, lower `LUMITRACE_MAX_SAMPLES`.
 - For quick checks on a single file, `enable_git_diff` keeps noise down.