kumi 0.0.18 → 0.0.19

data/lib/kumi/schema.rb

@@ -1,69 +1,109 @@
 # frozen_string_literal: true
 
-require "ostruct"
+require "mutex_m"
+require "digest"
+require "fileutils"
 
 module Kumi
+  # This module is the main entry point for users of the Kumi DSL.
+  # When a user module `extend`s this, it gains the `schema` block method
+  # and the `from` class method to execute the compiled logic.
   module Schema
-    attr_reader :__syntax_tree__, :__analyzer_result__, :__executable__
+    # The `__syntax_tree__` is available on the class for introspection.
+    attr_reader :__kumi_syntax_tree__, :__kumi_compiled_module__
 
-    def from(context)
-      # VERY IMPORTANT: This method is overriden on specs in order to use dual mode.
-
-      raise("No schema defined") unless @__executable__
+    def build_syntax_tree(&)
+      @__kumi_syntax_tree__ = Kumi::Core::RubyParser::Dsl.build_syntax_tree(&)
+    end
 
-      # Validate input types and domain constraints
-      input_meta = @__analyzer_result__.state[:input_metadata] || {}
-      violations = Core::Input::Validator.validate_context(context, input_meta)
+    def schema(&block)
+      @__kumi_syntax_tree__ = Kumi::Core::RubyParser::Dsl.build_syntax_tree(&block)
+      # Store the location where the schema was defined. This is essential for caching
+      # and providing good error messages.
+      @kumi_source_location = block.source_location.first
 
-      raise Errors::InputValidationError, violations unless violations.empty?
+      ensure_compiled!
+    end
 
-      # TODO: Lazily start a Runner
-      @__executable__.read(context, mode: :ruby)
+    def schema_metadata
+      ensure_compiled!
+      SchemaMetadata.new(@__kumi_analyzer_result__.state, @__kumi_syntax_tree__)
     end
 
-    def explain(context, *keys)
-      raise("No schema defined") unless @__executable__
+    def runner
+      ensure_compiled!
 
-      # Validate input types and domain constraints
-      input_meta = @__analyzer_result__.state[:input_metadata] || {}
-      violations = Core::Input::Validator.validate_context(context, input_meta)
+      __kumi_compiled_module__.from({})
+    end
 
-      raise Errors::InputValidationError, violations unless violations.empty?
+    def from(input_data)
+      ensure_compiled!
+      __kumi_compiled_module__.from(input_data)
+    end
 
-      keys.each do |key|
-        puts Core::Explain.call(self, key, inputs: context)
-      end
+    def write_source(file_path, platform: :ruby)
+      raise "No schema defined" unless @__kumi_syntax_tree__
+      raise ArgumentError, "platform must be :ruby or :javascript" unless %i[ruby javascript].include?(platform)
 
-      nil
-    end
+      result = Kumi::Analyzer.analyze!(@__kumi_syntax_tree__)
 
-    def build_syntax_tree(&)
-      @__syntax_tree__ = Core::RubyParser::Dsl.build_syntax_tree(&).freeze
-    end
+      code = case platform
+             when :ruby
+               result.state[:ruby_codegen_files]&.fetch("codegen.rb", nil)
+             when :javascript
+               result.state[:javascript_codegen_files]&.fetch("codegen.mjs", nil)
+             end
 
-    def schema(&)
-      # from_location = caller_locations(1, 1).first
-      # raise "Called from #{from_location.path}:#{from_location.lineno}"
-      @__syntax_tree__ = Dev::Profiler.phase("frontend.parse") do
-        Core::RubyParser::Dsl.build_syntax_tree(&).freeze
-      end
+      raise "Compiler did not produce #{platform}_codegen_files" unless code
 
-      puts Support::SExpressionPrinter.print(@__syntax_tree__, indent: 2) if ENV["KUMI_DEBUG"] || ENV["KUMI_PRINT_SYNTAX_TREE"]
+      FileUtils.mkdir_p(File.dirname(file_path))
+      File.write(file_path, code)
+      file_path
+    end
 
-      @__analyzer_result__ = Dev::Profiler.phase("analyzer") do
-        Analyzer.analyze!(@__syntax_tree__).freeze
-      end
-      @__executable__ = Dev::Profiler.phase("compiler") do
-        Compiler.compile(@__syntax_tree__, analyzer: @__analyzer_result__, schema_name: name).freeze
+    private
+
+    def ensure_compiled!
+      @kumi_compile_lock ||= Mutex.new
+      @kumi_compile_lock.synchronize do
+        # We check `force_recompile` here to allow for debugging the compiler.
+        return if @kumi_compiled && !Kumi.configuration.force_recompile
+
+        @__kumi_analyzer_result__ = Kumi::Analyzer.analyze!(@__kumi_syntax_tree__)
+
+        schema_digest = @__kumi_syntax_tree__.digest
+        cache_path = File.join(Kumi.configuration.cache_path, "#{schema_digest}.rb")
+
+        # This is the core JIT vs. AOT logic.
+        case Kumi.configuration.compilation_mode
+        when :jit
+          compile_and_write_cache(cache_path, schema_digest) unless File.exist?(cache_path)
+        when :aot
+          unless File.exist?(cache_path) && !Kumi.configuration.force_recompile
+            raise "Schema #{name} is not precompiled for digest #{schema_digest}. Please run the `kumi:compile` build task."
+          end
+        else
+          raise "Invalid Kumi compilation mode: #{Kumi.configuration.compilation_mode}"
+        end
+
+        # Load the dynamically generated but statically cached file.
+        require cache_path
+
+        # The loaded file defined a module inside Kumi::Compiled. We now include it
+        # to mix in the compiled methods (_total_payroll, etc.) and the instance
+        # method `__kumi_compiled_module__`.
+        @__kumi_compiled_module__ = Kumi::Compiled.const_get(schema_digest)
+        @kumi_compiled = true
       end
-
-      nil
     end
 
-    def schema_metadata
-      raise("No schema defined") unless @__analyzer_result__
+    def compile_and_write_cache(cache_path, digest)
+      # 1. Extract the generated code from the final state object.
+      compiler_output = @__kumi_analyzer_result__.state[:ruby_codegen_files]["codegen.rb"]
+      raise "Compiler did not produce ruby_codegen_files" unless compiler_output
 
-      @schema_metadata ||= SchemaMetadata.new(@__analyzer_result__.state, @__syntax_tree__)
+      FileUtils.mkdir_p(File.dirname(cache_path))
+      File.write(cache_path, compiler_output)
     end
   end
 end

data/lib/kumi/support/diff.rb

@@ -4,7 +4,7 @@ module Kumi
   module Support
     module Diff
       module_function
-      
+
       def unified(a_str, b_str)
         a = a_str.lines
         b = b_str.lines
@@ -12,6 +12,7 @@ module Kumi
         max = [a.size, b.size].max
         (0...max).each do |i|
           next if a[i] == b[i]
+
           out << format("%4d- %s", i + 1, a[i] || "")
           out << format("%4d+ %s", i + 1, b[i] || "")
         end
@@ -19,4 +20,4 @@ module Kumi
       end
     end
   end
-end
+end

data/lib/kumi/support/ir_render.rb

@@ -42,7 +42,7 @@ module Kumi
 
         if defined?(Kumi::Support::IRDump)
           # Convert AnalysisState to hash if needed
-          state_hash = analysis_state.to_h
+          analysis_state.to_h
         else
           # Fallback: simple text representation
           lines = []

data/lib/kumi/support/lir_printer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Support
+    class LIRPrinter
+      LIR = Kumi::Core::LIR
+
+      # Public: print all declarations
+      # ops_by_decl: { "name" => { operations: [Instruction...] } }
+      def self.print(ops_by_decl, show_stamps: true, show_locations: false)
+        out = +"(LIR\n"
+        ops_by_decl.each do |name, h|
+          out << "  (Declaration #{name}\n"
+          out << indent(print_instructions(h[:operations], show_stamps:, show_locations:), 4)
+          out << "  )\n"
+        end
+        out << ")\n"
+      end
+
+      # Public: print a single instruction list
+      def self.print_instructions(instructions, show_stamps: true, show_locations: false)
+        new(show_stamps:, show_locations:).print_instructions(instructions)
+      end
+
+      def initialize(show_stamps:, show_locations:)
+        @show_stamps = show_stamps
+        @show_locations = show_locations
+      end
+
+      def print_instructions(instructions)
+        out = +""
+        indent = 0
+        instructions.each do |ins|
+          case ins.opcode
+          when :LoopStart
+            out << ("  " * indent)
+            out << loop_start_line(ins) << nl(ins)
+            indent += 1
+          when :LoopEnd
+            indent -= 1
+            out << ("  " * indent)
+            out << "end_loop" << nl(ins)
+          else
+            out << ("  " * indent)
+            out << instr_line(ins) << nl(ins)
+          end
+        end
+        out
+      end
+
+      private
+
+      def instr_line(ins)
+        res = ins.result_register ? "#{fmt_reg(ins.result_register)} = " : ""
+        attrs = fmt_attrs(ins.attributes)
+        imms  = fmt_imms(ins.immediates)
+        case ins.opcode
+        when :Constant
+          lit = ins.immediates&.first
+          "#{res}const #{fmt_lit(lit)}#{stamp(ins)}"
+        when :LoadInput
+          key = ins.immediates&.first&.value
+          "#{res}load_input #{fmt_key(key)}#{stamp(ins)}"
+        when :LoadDeclaration
+          name = ins.immediates&.first&.value
+          axes = ins.attributes[:axes] || []
+          axes_str = axes.empty? ? "" : " axes=[#{axes.join(', ')}]"
+          "#{res}load_decl #{name}#{axes_str}#{stamp(ins)}"
+        when :LoadField
+          key = ins.immediates&.first&.value
+          "#{res}load_field #{only(ins.inputs)}[#{fmt_key(key)}]#{stamp(ins)}"
+        when :KernelCall
+          fn = ins.attributes[:fn]
+          "#{res}call #{fn}(#{list(ins.inputs)})#{stamp(ins)}"
+        when :Select
+          c, t, f = ins.inputs
+          "#{res}select #{fmt_reg(c)}, #{fmt_reg(t)}, #{fmt_reg(f)}#{stamp(ins)}"
+        when :DeclareAccumulator
+          "#{res}decl_acc#{stamp(ins)}"
+        when :Accumulate
+          acc = fmt_reg(ins.result_register)
+          fn   = ins.attributes[:fn]
+          v    = only(ins.inputs)
+          "#{res}acc_add #{fn}(#{acc}, #{fmt_reg(v)})#{stamp(ins)}"
+        when :LoadAccumulator
+          acc = ins.inputs.first or raise "No accumulator bound"
+          "#{res}acc_load #{fmt_reg(acc)}#{stamp(ins)}"
+        when :MakeTuple
+          "#{res}make_tuple(#{list(ins.inputs)})#{stamp(ins)}"
+        when :MakeObject
+          keys = (ins.immediates || []).map { |l| l.value }
+          pairs = keys.zip(ins.inputs || []).map { |k, r| "#{k}: #{fmt_reg(r)}" }.join(", ")
+          "#{res}make_object{#{pairs}}#{stamp(ins)}"
+        when :TupleGet
+          idx = ins.immediates&.first&.value
+          "#{res}tuple_get #{fmt_reg(only(ins.inputs))}[#{idx}]#{stamp(ins)}"
+        when :Yield
+          "yield #{fmt_reg(only(ins.inputs))}"
+        else
+          # Fallback
+          "#{res}#{ins.opcode.downcase} #{list(ins.inputs)}#{imms}#{attrs}#{stamp(ins)}"
+        end
+      end
+
+      def loop_start_line(ins)
+        axis = ins.attributes[:axis]
+        as_e = ins.attributes[:as_element]
+        as_i = ins.attributes[:as_index]
+        id   = ins.attributes[:id]
+        coll = fmt_reg(only(ins.inputs))
+        "loop #{axis} id=#{id} in #{coll} as el=#{fmt_reg(as_e)}, idx=#{fmt_reg(as_i)}"
+      end
+
+      # ---- small helpers ----
+
+      def stamp(ins)
+        return "" unless @show_stamps && ins.stamp
+
+        " :: #{ins.stamp.dtype}"
+      end
+
+      def nl(ins)
+        return "\n" unless @show_locations && ins.location
+
+        loc = ins.location
+        "  ; #{loc.file}:#{loc.line}:#{loc.column}\n"
+      end
+
+      def fmt_reg(r) = r.is_a?(Symbol) ? "%#{r}" : r.inspect
+      def fmt_key(k) = k.inspect
+      def fmt_lit(l) = l ? l.value.inspect : "nil"
+      def list(arr)  = Array(arr).map { fmt_reg(_1) }.join(", ")
+      def only(arr)  = Array(arr).first
+      def fmt_attrs(h) = h && !h.empty? ? " #{h.map { |k, v| "#{k}=#{v.inspect}" }.join(' ')}" : ""
+      def fmt_imms(imm) = imm && !imm.empty? ? " [#{imm.map { |l| fmt_lit(l) }.join(', ')}]" : ""
+
+      def self.indent(str, n)
+        pad = " " * n
+        str.lines.map { |ln| pad + ln }.join
+      end
+    end
+  end
+end

data/lib/kumi/support/nast_printer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Support
+    class NASTPrinter
+      def self.print(nir_module)
+        new.print(nir_module)
+      end
+
+      def initialize(indent: 0)
+        @indent = indent
+      end
+
+      def print(nir_module)
+        return "nil" unless nir_module
+
+        lines = []
+        lines << "(NAST"
+
+        nir_module.decls.each do |name, decl|
+          lines << indent("(#{decl.kind.upcase} #{name}")
+          lines << indent(print_node(decl.body), 2)
+          lines << indent(")")
+        end
+
+        lines << ")"
+        lines.join("\n")
+      end
+
+      private
+
+      def print_node(node, depth = 1)
+        case node
+        when Kumi::Core::NAST::Const
+          "(Const #{node.value.inspect})"
+
+        when Kumi::Core::NAST::InputRef
+          "(InputRef #{node.path.inspect})"
+
+        when Kumi::Core::NAST::Ref
+          "(Ref #{node.name})"
+
+        when Kumi::Core::NAST::Call
+          if node.args.empty?
+            "(Call #{node.fn.inspect})"
+          else
+            lines = ["(Call #{node.fn.inspect}"]
+            node.args.each do |arg|
+              lines << indent(print_node(arg, depth + 1), depth + 1)
+            end
+            lines << indent(")", depth)
+            lines.join("\n")
+          end
+
+        when Kumi::Core::NAST::Tuple
+          if node.args.empty?
+            "(Tuple)"
+          else
+            lines = ["(Tuple"]
+            node.args.each do |elem|
+              lines << indent(print_node(elem, depth + 1), depth + 1)
+            end
+            lines << indent(")", depth)
+            lines.join("\n")
+          end
+
+        when Kumi::Core::NAST::Hash
+          if node.pairs.empty?
+            "(Hash)"
+          else
+            lines = ["(Hash"]
+            node.pairs.each do |pair|
+              lines << indent(print_node(pair, depth + 1), depth + 1)
+            end
+            lines << indent(")", depth)
+            lines.join("\n")
+          end
+        when Kumi::Core::NAST::Pair
+          lines = ["(Pair #{node.key} "]
+          lines << indent(print_node(node.value, depth + 1), depth + 1)
+          lines << indent(")", depth)
+          lines.join("\n")
+        else
+          node.inspect
+        end
+      end
+
+      def indent(text, level = 1)
+        ("  " * level) + text
+      end
+    end
+  end
+end

data/lib/kumi/support/s_expression_printer.rb

@@ -66,11 +66,12 @@ module Kumi
         fields << "domain: #{node.domain.inspect}" if node.respond_to?(:domain) && node.domain
         fields << "access_mode: #{node.access_mode.inspect}" if node.respond_to?(:access_mode) && node.access_mode
 
+        index = node.index ? " :#{node.index}" : ""
         if node.respond_to?(:children) && !node.children.empty?
           children_str = child_printer.visit(node.children)
-          "(InputDeclaration #{fields.join(' ')}\n#{child_indent}#{children_str}\n#{indent_str})"
+          "(InputDeclaration #{fields.join(' ')}#{index}\n#{child_indent}#{children_str}\n#{indent_str})"
         else
-          "(InputDeclaration #{fields.join(' ')})"
+          "(InputDeclaration #{fields.join(' ')}#{index})"
         end
       end
 
@@ -119,8 +120,8 @@ module Kumi
       def visit_hash_expression(node)
         return "(HashExpression)" if node.pairs.empty?
 
-        pairs = node.pairs.map do |pair|
-          "(#{visit(pair.key)} #{visit(pair.value)})"
+        pairs = node.pairs.map do |key, value|
+          "(#{visit(key)} #{visit(value)})"
         end.join("\n#{indent_str(2)}")
 
         "(HashExpression\n#{indent_str(2)}#{pairs}\n#{indent_str})"

data/lib/kumi/support/snast_printer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Support
+    class SNASTPrinter
+      NAST = Kumi::Core::NAST
+
+      def self.print(snast_module, verbosity: :default)
+        new(verbosity: verbosity).print(snast_module)
+      end
+
+      def initialize(verbosity: :default)
+        @verbosity = verbosity
+      end
+
+      def print(snast_module)
+        return "nil" unless snast_module
+
+        output = ["(SNAST"]
+        snast_module.decls.each do |_, decl|
+          output << format_node(decl, 1)
+        end
+        output << ")"
+        output.join("\n")
+      end
+
+      private
+
+      def format_node(node, indent_level)
+        case @verbosity
+        when :full
+          indent = "  " * indent_level
+          "#{indent}#{node.pretty_inspect.gsub("\n", "\n#{indent}")}"
+        else
+          format_concise(node, indent_level)
+        end
+      end
+
+      def format_concise(node, indent_level)
+        indent = "  " * indent_level
+        stamp_str = format_stamp(node.meta[:stamp])
+
+        case node
+        when NAST::Declaration
+          kind = node.meta.dig(:stamp, :dtype) == :boolean ? "TRAIT" : "VALUE"
+          header = "(#{kind} #{node.name}"
+          body = format_concise(node.body, indent_level + 1)
+          "#{indent}#{header}\n#{body}\n#{indent}) #{stamp_str}"
+
+        when NAST::Call
+          header = "(Call :#{node.fn}"
+          args = node.args.map { |arg| format_concise(arg, indent_level + 1) }.join("\n")
+          "#{indent}#{header}\n#{args}\n#{indent}) #{stamp_str}"
+
+        when NAST::Select
+          header = "(Select"
+          cond = format_concise(node.cond, indent_level + 1)
+          tbranch = format_concise(node.on_true,  indent_level + 1)
+          fbranch = format_concise(node.on_false, indent_level + 1)
+          "#{indent}#{header}\n#{cond}\n#{tbranch}\n#{fbranch}\n#{indent}) #{stamp_str}"
+
+        when NAST::Reduce
+          over = "[#{Array(node.over).map(&:to_s).join(', ')}]"
+          header = "(Reduce :#{node.fn} over #{over}"
+          arg = format_concise(node.arg, indent_level + 1)
+          "#{indent}#{header}\n#{arg}\n#{indent}) #{stamp_str}"
+
+        when NAST::Const
+          "#{indent}(Const #{node.value.inspect}) #{stamp_str}"
+
+        when NAST::InputRef
+          key_chain_str = " key_chain=[#{node.key_chain.join(', ')}]"
+          "#{indent}(InputRef #{node.path_fqn}#{key_chain_str}) #{stamp_str}"
+
+        when NAST::Ref
+          "#{indent}(Ref #{node.name}) #{stamp_str}"
+
+        when NAST::IndexRef
+          "#{indent}(IndexRef #{node.name} input=#{node.input_fqn}) #{stamp_str}"
+
+        when NAST::Fold
+          header = "(Fold :#{node.fn}"
+          arg = format_concise(node.arg, indent_level + 1)
+          "#{indent}#{header}\n#{arg}\n#{indent}) #{stamp_str}"
+
+        when NAST::Tuple
+          header = "(Tuple"
+          args = node.args.map { |arg| format_concise(arg, indent_level + 1) }.join("\n")
+          "#{indent}#{header}\n#{args}\n#{indent}) #{stamp_str}"
+        when NAST::Hash
+          header = "(Hash"
+          pairs = node.pairs.map { |arg| format_concise(arg, indent_level + 1) }.join("\n")
+          "#{indent}#{header}\n#{pairs}\n#{indent}) #{stamp_str}"
+
+        when NAST::Pair
+          value = format_concise(node.value, indent_level + 1)
+          "#{indent}(Pair #{node.key}\n#{value}\n#{indent}) #{stamp_str}"
+        else
+          "#{indent}(UnknownNode: #{node.class})"
+        end
+      end
+
+      def format_stamp(stamp)
+        return "" unless stamp
+
+        axes = Array(stamp[:axes]).map(&:to_s).join(", ")
+        ":: [#{axes}] -> #{stamp[:dtype]}"
+      end
+    end
+  end
+end

data/lib/kumi/syntax/call_expression.rb

@@ -2,7 +2,7 @@
 
 module Kumi
   module Syntax
-    CallExpression = Struct.new(:fn_name, :args) do
+    CallExpression = Struct.new(:fn_name, :args, :opts) do
       include Node
 
       def children = args

data/lib/kumi/syntax/input_declaration.rb

@@ -3,11 +3,11 @@
 module Kumi
   module Syntax
     # For field metadata declarations inside input blocks
-    InputDeclaration = Struct.new(:name, :domain, :type, :children, :access_mode) do
+    InputDeclaration = Struct.new(:name, :domain, :type, :children, :index) do
       include Node
 
       def children = self[:children] || []
-      def access_mode = self[:access_mode]
+      def index = self[:index]
     end
   end
 end

data/lib/kumi/syntax/node.rb

@@ -7,10 +7,12 @@ module Kumi
     # Base module included by all AST nodes to provide a standard
     # interface for accessing source location information..
     module Node
-      attr_accessor :loc
+      attr_accessor :loc, :hints
 
-      def initialize(*args, loc: nil, **kwargs)
+      def initialize(*args, hints: {}, loc: nil, **kwargs)
         @loc = loc
+        @hints = hints
+
         super(*args, **kwargs)
         freeze
       end
@@ -30,16 +32,6 @@ module Kumi
           )
       end
       alias eql? ==
-
-      def hash
-        values = if respond_to?(:members)
-                   members.map { |m| self[m] }
-                 else
-                   instance_variables.reject { |iv| iv == :@loc }
-                                     .map { |iv| instance_variable_get(iv) }
-                 end
-        [self.class, *values].hash
-      end
     end
   end
 end

data/lib/kumi/syntax/root.rb

@@ -8,6 +8,16 @@ module Kumi
       include Node
 
       def children = [inputs, values, traits]
+
+      def digest
+        # The digest must be stable and depend on anything that could change the
+        # compiled output. This includes the AST, the Kumi version (compiler changes),
+        # and the Ruby version (runtime behavior changes).
+        digest_input = "#{Kumi::VERSION}-#{RUBY_VERSION}-#{self}"
+
+        # Ruby constants cannot start with a number, so we add a prefix.
+        "KUMI_#{Digest::SHA256.hexdigest(digest_input)}"
+      end
     end
   end
 end

data/lib/kumi/syntax/trait_declaration.rb

@@ -6,6 +6,7 @@ module Kumi
       include Node
 
       def children = [expression]
+      def kind = :trait
     end
   end
 end

data/lib/kumi/syntax/value_declaration.rb

@@ -6,6 +6,7 @@ module Kumi
       include Node
 
       def children = [expression]
+      def kind = :value
     end
   end
 end

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.18"
+  VERSION = "0.0.19"
 end