lumitrace 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4511842d6a3c76fbf50be2da922a089e852adfe571d952efe770e536060d2ab2
-  data.tar.gz: e24617018967e09c04e8d79079e1182ae32b64f8ff69a2046bb802e1daadd6a9
+  metadata.gz: 4de22b014b5ce2ce0e63b230487c6888147ee99459a2ef832ccae42a9b6004c6
+  data.tar.gz: 78cb61f36f9764daa1898eae3897090a92c2d44dd422a31589db983b7a951ec7
 SHA512:
-  metadata.gz: aeb9654b4eb02f0b0d60a1f15567d5abd591b27abb1e3b1acf660b19f3e23ddd74487699e667a15d533d793bdc6f4700f2d8f5ee4a6ee0ec9507ae6053f164be
-  data.tar.gz: 98a92961b2dc9cf10e50fe7310cfdd5f4d6c138fc13f41a9485a4cdad0a68007145c7bfb5c5f1cfe4980733f6a287c8ceb7a133b1bd41d6cf19612d9275a61d8
+  metadata.gz: 1ac281aaf18f6f0382af924d9d2ef850ae27353e10255114e90cce2121bcdaa5572d077c3edb3b8dde465bb8a820804aa039abab4af0420bbcbc8381ffca112d
+  data.tar.gz: 6df68f6e6c1769616c584278fdca6be2c736c8c5a99ddab37b5a86c42b66d056edeb51b041a9e0c53b11db324fa219e72a5c1bfe6c968ee4dfe6869f350f1219

data/docs/ai-help.md

@@ -2,7 +2,9 @@
 
 # Lumitrace Help
 
-- Version: 0.4.1
+AI agents: run `lumitrace help --format json` to get structured help.
+
+- Version: 0.6.1
 - Help version: 1
 - Primary JSON entrypoint: `lumitrace help --format json`
 - Schema JSON entrypoint: `lumitrace schema --format json`
@@ -37,11 +39,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/lib/lumitrace/ai_docs.rb

@@ -20,6 +20,8 @@ module Lumitrace
     lines = []
     lines << "# Lumitrace Help"
     lines << ""
+    lines << "AI agents: run `lumitrace help --format json` to get structured help."
+    lines << ""
     lines << "- Version: #{data[:version]}"
     lines << "- Help version: #{data[:help_version]}"
     lines << "- Primary JSON entrypoint: `#{data[:entrypoint][:primary]}`"
@@ -70,7 +72,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 +91,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/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/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.6.0"
+  VERSION = "0.6.2"
 end

data/lib/lumitrace.rb

@@ -305,6 +305,8 @@ module Lumitrace
       if allow_help
         o.separator ""
         o.on("--help", "Show this help") { opts[:help] = true }
+        o.separator ""
+        o.separator "For AI/structured help: lumitrace help --format json"
       end
     end
 

metadata

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