kumi 0.0.18 → 0.0.20

data/lib/kumi/dev/printer/irv2_formatter.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Dev
+    module Printer
+      class IRV2Formatter
+        def initialize(irv2_data)
+          @irv2 = irv2_data
+        end
+
+        def format
+          output = []
+
+          output += format_header
+          output << ""
+          output += format_declarations
+          output += format_analysis_details
+
+          output.join("\n")
+        end
+
+        private
+
+        def format_header
+          output = []
+          output << "Schema: #{@irv2['$schema']}" if @irv2["$schema"]
+          output << "Version: #{@irv2['version']}" if @irv2["version"]
+          output << "Module: #{@irv2['module']}"
+          output << "Declarations: #{@irv2['declarations'].keys.join(', ')}"
+          output << "Inputs: #{@irv2['analysis']['inputs'].size}"
+          output
+        end
+
+        def format_declarations
+          output = []
+          @irv2["declarations"].each do |name, decl|
+            output += format_declaration(name, decl)
+            output << ""
+          end
+          output
+        end
+
+        def format_declaration(name, decl)
+          output = []
+          output << "## #{name}"
+
+          # Format parameters
+          params = decl["parameters"].map do |param|
+            case param["type"]
+            when "input"
+              "#{param['name']}: #{param['path'].join('.')} (#{param['dtype']})"
+            else
+              "#{param['name']}: #{param['type']}"
+            end
+          end
+          output << "  Parameters: #{params.join(', ')}"
+
+          # Format operations
+          output << "  Operations:"
+          decl["operations"].each_with_index do |op, idx|
+            output << "    #{format_operation(idx, op)}"
+          end
+
+          output << "  Result: %#{decl['result']}"
+          output
+        end
+
+        def format_operation(idx, op)
+          base_op = case op["op"]
+                    when "LoadInput"
+                      "LoadInput(#{op['args'].first.join('.')})"
+                    when "Const"
+                      "Const(#{op['args'].first})"
+                    when "Map"
+                      op_name = op.dig("attrs", "op") || "unknown"
+                      args_str = format_operation_args(op["args"])
+                      "Map(#{op_name}) <- #{args_str}"
+                    when "ConstructTuple"
+                      args_str = format_operation_args(op["args"])
+                      "ConstructTuple(#{args_str})"
+                    else
+                      args_str = format_operation_args(op["args"])
+                      "#{op['op']}(#{args_str})"
+                    end
+
+          # Add attributes if present and not just 'op'
+          attrs = op["attrs"] || {}
+          extra_attrs = attrs.reject { |k, _| ["op", :op].include?(k) }
+          attr_str = extra_attrs.empty? ? "" : " [#{extra_attrs.map { |k, v| "#{k}: #{v}" }.join(', ')}]"
+
+          "%#{idx} = #{base_op}#{attr_str}"
+        end
+
+        def format_operation_args(args)
+          return "" unless args
+
+          args.map do |arg|
+            if arg.respond_to?(:id) && arg.respond_to?(:op)
+              "%#{arg.id}"
+            elsif arg.is_a?(Array)
+              arg.join(".")
+            else
+              arg.to_s
+            end
+          end.join(", ")
+        end
+
+        def format_analysis_details
+          output = []
+          output << ""
+          output << "## Analysis"
+
+          defaults = @irv2["analysis"]["defaults"]
+          if defaults
+            output << "  Defaults:"
+            defaults.each { |k, v| output << "    #{k}: #{v}" }
+          end
+
+          # Add input plans within analysis section
+          output << ""
+          output << "  Input Plans:"
+          @irv2["analysis"]["inputs"].each do |input|
+            path_str = input["path"].join(".")
+            axes_info = input["axes"].empty? ? "(scalar)" : "(axes: #{input['axes'].join(', ')})"
+
+            output << "    #{path_str}: #{input['dtype']} #{axes_info}"
+
+            # Add policy information if different from defaults
+            output << "      key_policy: #{input['key_policy']}" if input["key_policy"] != defaults["key_policy"]
+            output << "      on_missing: #{input['on_missing']}" if input["on_missing"] != defaults["on_missing"]
+
+            # Add access chain details
+            if input["chain"] && !input["chain"].empty?
+              chain_str = input["chain"].map { |link| format_chain_link(link) }.join(" -> ")
+              output << "      chain: #{chain_str}"
+            end
+          end
+
+          output
+        end
+
+        def format_chain_link(link)
+          case link["kind"]
+          when "scalar_leaf"
+            "scalar(#{link['key']})"
+          when "array_element"
+            alias_info = link["alias"] ? ":#{link['alias']}" : ""
+            axis_info = link["axis"] ? "@#{link['axis']}" : ""
+            "element(#{link['key'] || 'item'}#{alias_info}#{axis_info})"
+          when "array_field"
+            axis_info = link["axis"] ? "@#{link['axis']}" : ""
+            "array_field(#{link['key']}#{axis_info})"
+          when "hash_value"
+            "hash[#{link['key']}]"
+          else
+            key_info = link["key"] ? "(#{link['key']})" : ""
+            "#{link['kind']}#{key_info}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/dev/printer/width_aware_json.rb

@@ -0,0 +1,44 @@
+require "json"
+
+module Kumi
+  module Dev
+    module Printer
+      module WidthAwareJson
+        module_function
+
+        def dump(obj, max: 120, indent: 0)
+          # First try a compact one-liner
+          one = JSON.generate(obj)
+          return one if one.size <= max
+
+          case obj
+          when Array
+            items = obj.map { |v| dump(v, max: max, indent: indent + 2) }
+            join_multiline("[", items, "]", indent)
+          when Hash
+            items = obj.map do |k, v|
+              key = JSON.generate(k)
+              val = dump(v, max: max, indent: indent + 2)
+              "#{key}: #{val}"
+            end
+            join_multiline("{", items, "}", indent)
+          else
+            one # scalars just return compact
+          end
+        end
+
+        def join_multiline(open, items, close, indent)
+          pad = " " * (indent + 2)
+          [
+            open,
+            pad + items.join(",\n" + pad),
+            (" " * indent) + close
+          ].join("\n")
+        end
+      end
+
+      # Usage:
+      # puts WidthAwareJSON.dump(ir_hash, max: 140)
+    end
+  end
+end

data/lib/kumi/dev/profile_aggregator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'json'
+require "json"
 
 module Kumi
   module Dev
@@ -167,18 +167,18 @@ module Kumi
         puts "Total events: #{events.length}"
         puts "VM operations: #{total_ops}"
         puts "VM executions: #{vm_execution_count}"
-        
+
         # Schema differentiation
         schema_stats = schema_breakdown
         if schema_stats.any? && schema_stats.keys.first != "Unknown"
-          puts "Schemas analyzed: #{schema_stats.keys.join(", ")}"
+          puts "Schemas analyzed: #{schema_stats.keys.join(', ')}"
           schema_stats.each do |schema, stats|
             puts "  #{schema}: #{stats[:operations]} operations, #{stats[:time]}ms"
           end
         else
           puts "Schema runs: #{runs_analyzed.length} (runs: #{runs_analyzed.join(', ')})"
         end
-        
+
         puts "Total VM time: #{total_vm_time.round(4)}ms"
         puts "Average per VM execution: #{vm_execution_count > 0 ? (total_vm_time / vm_execution_count).round(4) : 0}ms"
         puts
@@ -191,13 +191,13 @@ module Kumi
         end
 
         mem = memory_analysis
-        if mem
-          puts
-          puts "Memory Growth:"
-          puts "  Heap: +#{mem[:growth][:heap_objects]} objects (#{mem[:growth][:heap_growth_pct]}%)"
-          puts "  RSS: +#{mem[:growth][:rss_mb]}MB (#{mem[:growth][:rss_growth_pct]}%)"
-          puts "  GC: #{mem[:growth][:minor_gcs]} minor, #{mem[:growth][:major_gcs]} major"
-        end
+        return unless mem
+
+        puts
+        puts "Memory Growth:"
+        puts "  Heap: +#{mem[:growth][:heap_objects]} objects (#{mem[:growth][:heap_growth_pct]}%)"
+        puts "  RSS: +#{mem[:growth][:rss_mb]}MB (#{mem[:growth][:rss_growth_pct]}%)"
+        puts "  GC: #{mem[:growth][:minor_gcs]} minor, #{mem[:growth][:major_gcs]} major"
       end
 
       def detailed_report(limit: 15)
@@ -206,7 +206,7 @@ module Kumi
         puts "=== TOP #{limit} HOTSPOTS ==="
         hotspots = hotspot_analysis(limit: limit)
         hotspots.each_with_index do |(key, stats), i|
-          puts "#{(i+1).to_s.rjust(2)}. #{key.ljust(40)} #{stats[:total_ms].to_s.rjust(10)}ms (#{stats[:count]} calls, #{stats[:avg_ms]}ms avg)"
+          puts "#{(i + 1).to_s.rjust(2)}. #{key.ljust(40)} #{stats[:total_ms].to_s.rjust(10)}ms (#{stats[:count]} calls, #{stats[:avg_ms]}ms avg)"
         end
 
         # Schema breakdown if available
@@ -218,7 +218,7 @@ module Kumi
             puts "#{schema}:"
             puts "  Operations: #{stats[:operations]}"
             puts "  Total time: #{stats[:time]}ms"
-            puts "  Declarations: #{stats[:declarations].join(", ")}"
+            puts "  Declarations: #{stats[:declarations].join(', ')}"
             puts
           end
         end
@@ -268,34 +268,32 @@ module Kumi
         return unless File.exist?(@jsonl_file)
 
         File.readlines(@jsonl_file).each do |line|
-          begin
-            event = JSON.parse(line.strip)
-            next unless event && event.is_a?(Hash)
-
-            @events << event
-
-            case event["kind"]
-            when "phase"
-              @phases << event
-            when "mem"
-              @memory_snapshots << event
-            when "final_summary"
-              @final_summary = event
-            else
-              # VM operations don't have a "kind" field - they have ts, run, decl, i, tag, wall_ms, cpu_ms, etc.
-              # According to profiler.rb line 118-130, VM operations are identified by having decl + tag but no kind
-              if event["decl"] && event["tag"] && !event["kind"]
-                @operations << event
-              elsif event["kind"] && !["summary", "cache_analysis"].include?(event["kind"])
-                # Handle any future event types that have a kind but aren't known
-                @operations << event
-              end
+          event = JSON.parse(line.strip)
+          next unless event && event.is_a?(Hash)
+
+          @events << event
+
+          case event["kind"]
+          when "phase"
+            @phases << event
+          when "mem"
+            @memory_snapshots << event
+          when "final_summary"
+            @final_summary = event
+          else
+            # VM operations don't have a "kind" field - they have ts, run, decl, i, tag, wall_ms, cpu_ms, etc.
+            # According to profiler.rb line 118-130, VM operations are identified by having decl + tag but no kind
+            if event["decl"] && event["tag"] && !event["kind"]
+              @operations << event
+            elsif event["kind"] && !%w[summary cache_analysis].include?(event["kind"])
+              # Handle any future event types that have a kind but aren't known
+              @operations << event
             end
-          rescue JSON::ParserError
-            # Skip malformed JSON lines
           end
+        rescue JSON::ParserError
+          # Skip malformed JSON lines
         end
       end
     end
   end
-end
+end

data/lib/kumi/dev/profile_runner.rb

@@ -21,7 +21,7 @@ module Kumi
 
         puts "Profiling: #{script_path}"
         puts "Configuration:"
-        puts "  Output: #{ENV['KUMI_PROFILE_FILE']}"
+        puts "  Output: #{ENV.fetch('KUMI_PROFILE_FILE', nil)}"
         puts "  Phases: enabled"
         puts "  Operations: #{ENV['KUMI_PROFILE_OPS'] == '1' ? 'enabled' : 'disabled'}"
         puts "  Sampling: #{ENV['KUMI_PROFILE_SAMPLE'] || '1'}"
@@ -38,7 +38,7 @@ module Kumi
         # Execute the script
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         begin
-          result = Dev::Profiler.phase("script_execution", script: File.basename(script_path)) do
+          Dev::Profiler.phase("script_execution", script: File.basename(script_path)) do
             # Execute in a clean environment to avoid polluting the current process
             load(File.expand_path(script_path))
           end
@@ -67,8 +67,6 @@ module Kumi
         false
       end
 
-      private
-
       def self.setup_profiler_env(opts)
         # Always enable profiling
         ENV["KUMI_PROFILE"] = "1"
@@ -84,14 +82,14 @@ module Kumi
         ENV["KUMI_PROFILE_STREAM"] = opts[:stream] ? "1" : "0"
 
         # Operations profiling
-        if opts[:phases_only]
-          ENV["KUMI_PROFILE_OPS"] = "0"
-        elsif opts[:ops]
-          ENV["KUMI_PROFILE_OPS"] = "1"
-        else
-          # Default: phases only
-          ENV["KUMI_PROFILE_OPS"] = "0"
-        end
+        ENV["KUMI_PROFILE_OPS"] = if opts[:phases_only]
+                                    "0"
+                                  elsif opts[:ops]
+                                    "1"
+                                  else
+                                    # Default: phases only
+                                    "0"
+                                  end
 
         # Sampling
         ENV["KUMI_PROFILE_SAMPLE"] = opts[:sample].to_s if opts[:sample]
@@ -104,7 +102,7 @@ module Kumi
       end
 
       def self.show_analysis(opts)
-        output_file = ENV["KUMI_PROFILE_FILE"]
+        output_file = ENV.fetch("KUMI_PROFILE_FILE", nil)
 
         unless File.exist?(output_file)
           puts "No profile data generated"
@@ -131,31 +129,29 @@ module Kumi
         else
           # Show summary + key insights
           aggregator.summary_report
-          
+
           # Add some key insights for CLI users
           puts
           puts "=== KEY INSIGHTS ==="
-          
+
           # Show top hotspots
           hotspots = aggregator.hotspot_analysis(limit: 3)
           if hotspots.any?
             puts "Top Performance Bottlenecks:"
-            hotspots.each_with_index do |(key, stats), i|
-              puts "  #{i+1}. #{stats[:decl]} (#{stats[:tag]}): #{stats[:total_ms]}ms"
+            hotspots.each_with_index do |(_key, stats), i|
+              puts "  #{i + 1}. #{stats[:decl]} (#{stats[:tag]}): #{stats[:total_ms]}ms"
             end
           end
-          
+
           # Reference analysis summary
           ref_analysis = aggregator.reference_operation_analysis
           if ref_analysis[:operations] > 0
             puts "Reference Operation Impact: #{(ref_analysis[:total_time] / aggregator.vm_execution_time * 100).round(1)}% of VM time"
           end
-          
+
           # Memory impact
           mem = aggregator.memory_analysis
-          if mem
-            puts "Memory Impact: #{mem[:growth][:heap_growth_pct]}% heap growth, #{mem[:growth][:rss_growth_pct]}% RSS growth"
-          end
+          puts "Memory Impact: #{mem[:growth][:heap_growth_pct]}% heap growth, #{mem[:growth][:rss_growth_pct]}% RSS growth" if mem
         end
 
         puts
@@ -196,4 +192,4 @@ module Kumi
       end
     end
   end
-end
+end

data/lib/kumi/dev/runner.rb

@@ -23,19 +23,19 @@ module Kumi
             Kumi::Analyzer.run_analysis_passes(schema, Kumi::Analyzer::DEFAULT_PASSES, state, errors)
           end
           ir = final_state[:ir_module]
-          
+
           result = Result.new(
             state: final_state,
             ir: ir,
             errors: errors
           )
-          
+
           # Report trace file if enabled
           if opts[:trace] && defined?(@trace_file) && @trace_file
             trace_file_path = @trace_file
             result.define_singleton_method(:trace_file) { trace_file_path }
           end
-          
+
           result
         rescue StandardError => e
           # Convert exception to error if not already captured
@@ -48,38 +48,28 @@ module Kumi
         end
       end
 
-      private
-
       def self.setup_env_vars(opts)
         if opts[:trace]
           ENV["KUMI_DEBUG_STATE"] = "1"
           trace_file = ENV["KUMI_DEBUG_FILE"] || "tmp/state_trace.jsonl"
           ENV["KUMI_DEBUG_FILE"] = trace_file
-          
+
           # Store for later reporting
           @trace_file = trace_file
         end
 
-        if opts[:snap]
-          ENV["KUMI_CHECKPOINT_PHASES"] = opts[:snap]
-        end
+        ENV["KUMI_CHECKPOINT_PHASES"] = opts[:snap] if opts[:snap]
 
-        if opts[:snap_dir]
-          ENV["KUMI_CHECKPOINT_DIR"] = opts[:snap_dir]
-        end
+        ENV["KUMI_CHECKPOINT_DIR"] = opts[:snap_dir] if opts[:snap_dir]
 
-        if opts[:resume_from]
-          ENV["KUMI_CHECKPOINT_RESUME_FROM"] = opts[:resume_from]
-        end
+        ENV["KUMI_CHECKPOINT_RESUME_FROM"] = opts[:resume_from] if opts[:resume_from]
 
-        if opts[:resume_at]
-          ENV["KUMI_CHECKPOINT_RESUME_AT"] = opts[:resume_at]
-        end
+        ENV["KUMI_CHECKPOINT_RESUME_AT"] = opts[:resume_at] if opts[:resume_at]
 
-        if opts[:stop_after]
-          ENV["KUMI_CHECKPOINT_STOP_AFTER"] = opts[:stop_after]
-        end
+        return unless opts[:stop_after]
+
+        ENV["KUMI_CHECKPOINT_STOP_AFTER"] = opts[:stop_after]
       end
     end
   end
-end
+end

data/lib/kumi/dev/support/kumi_runner.mjs

@@ -0,0 +1,39 @@
+// run_kumi_direct.mjs
+import fs from "fs";
+import path from "path";
+
+async function main() {
+  try {
+    const modulePath = path.resolve(process.argv[2]);
+    const inputPath  = path.resolve(process.argv[3]);
+    const declsToRun = (process.argv[4] || "")
+      .split(",")
+      .map(s => s.trim())
+      .filter(Boolean);
+
+    if (!modulePath || !inputPath || declsToRun.length === 0) {
+      console.error("Usage: node run_kumi_direct.mjs <module.mjs> <input.json> <decl1,decl2,...>");
+      process.exit(2);
+    }
+
+    const mod = await import(modulePath);
+    const input = JSON.parse(fs.readFileSync(inputPath, "utf-8"));
+
+    const results = {};
+    for (const decl of declsToRun) {
+      const fnName = `_${decl}`;
+      const fn = mod[fnName];
+      if (typeof fn !== "function") {
+        throw new Error(`Missing export ${fnName}`);
+      }
+      results[decl] = fn(input);
+    }
+
+    console.log(JSON.stringify(results));
+  } catch (err) {
+    console.error(`JS Runner Error: ${err?.message}\n${err?.stack}`);
+    process.exit(1);
+  }
+}
+
+main();

data/lib/kumi/dev.rb

@@ -4,11 +4,11 @@ module Kumi
   module Dev
     # Alias to the execution engine profiler for cross-layer access
     Profiler = Kumi::Core::IR::ExecutionEngine::Profiler
-    
+
     # Load profile runner for CLI
     autoload :ProfileRunner, "kumi/dev/profile_runner"
-    
+
     # Load profile aggregator for data analysis
     autoload :ProfileAggregator, "kumi/dev/profile_aggregator"
   end
-end
+end

data/lib/kumi/frontends/ruby.rb

@@ -4,25 +4,25 @@ module Kumi
   module Frontends
     module Ruby
       module_function
-      
+
       def load(path:, inputs: {})
         mod = Module.new
         mod.extend(Kumi::Schema)
         mod.module_eval(File.read(path), path)
-        
+
         # Extract just the syntax tree AST (same as Text frontend)
         schema_ast = if mod.const_defined?(:GoldenSchema)
-          golden = mod.const_get(:GoldenSchema)
-          golden.build if golden.respond_to?(:build)
-          golden.__syntax_tree__
-        elsif mod.__syntax_tree__
-          mod.__syntax_tree__
-        else
-          raise "No schema AST found. Make sure the .rb file calls 'schema do...end'"
-        end
-        
+                       golden = mod.const_get(:GoldenSchema)
+                       golden.build if golden.respond_to?(:build)
+                       golden.__syntax_tree__
+                     elsif mod.__syntax_tree__
+                       mod.__syntax_tree__
+                     else
+                       raise "No schema AST found. Make sure the .rb file calls 'schema do...end'"
+                     end
+
         [schema_ast, inputs]
       end
     end
   end
-end
+end

data/lib/kumi/frontends/text.rb

@@ -4,43 +4,48 @@ module Kumi
   module Frontends
     module Text
       module_function
-      
-      def load(path:, inputs: {})
-        src = File.read(path)
-        
+
+      # Load from a file path or a raw string.
+      # Usage:
+      #   Text.load(path: "schema.kumi", inputs: {...})
+      #   Text.load(src: "...raw text...", inputs: {...})
+      def load(path: nil, src: nil, inputs: {})
+        raise ArgumentError, "provide either :path or :src" if (path.nil? && src.nil?) || (path && src)
+
+        src ||= File.read(path)
+        file_label = path || "(string)"
+
         begin
           require "kumi-parser"
           ast = Kumi::Parser::TextParser.parse(src)
-          Core::Analyzer::Debug.info(:parse, kind: :text, file: path, ok: true) if Core::Analyzer::Debug.enabled?
+          Core::Analyzer::Debug.info(:parse, kind: :text, file: file_label, ok: true) if Core::Analyzer::Debug.enabled?
           [ast, inputs]
         rescue LoadError
           raise "kumi-parser gem not available. Install: gem install kumi-parser"
         rescue StandardError => e
           loc = (e.respond_to?(:location) && e.location) || {}
           line, col = loc.values_at(:line, :column)
-          snippet = self.code_frame(src, line, col)
-          raise StandardError, "#{path}:#{line || '?'}:#{col || '?'}: #{e.message}\n#{snippet}"
+          snippet = code_frame(src, line, col)
+          raise StandardError, "#{file_label}:#{line || '?'}:#{col || '?'}: #{e.message}\n#{snippet}"
         end
       end
-      
-      private
-      
+
       def self.code_frame(src, line, col, context: 2)
         return "" unless line
-        
-        lines = src.lines
-        from = [line - 1 - context, 0].max
-        to = [line - 1 + context, lines.length - 1].min
-        out = []
-        
+
+        lines  = src.lines
+        from   = [line - 1 - context, 0].max
+        to     = [line - 1 + context, lines.length - 1].min
+        out    = []
+
         (from..to).each do |i|
-          prefix = (i + 1 == line) ? "➤" : " "
-          out << "#{prefix} %4d | %s" % [i + 1, lines[i].rstrip]
-          out << "       | %s^" % (" " * (col - 1)) if i + 1 == line && col
+          prefix = i + 1 == line ? "➤" : " "
+          out << format("#{prefix} %4d | %s", i + 1, lines[i].rstrip)
+          out << format("       | %s^", " " * (col - 1)) if i + 1 == line && col
         end
-        
+
         out.join("\n")
       end
     end
   end
-end
+end