kumi 0.0.0 → 0.0.3

data/lib/kumi/explain.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Explain
+    class ExplanationGenerator
+      def initialize(syntax_tree, analyzer_result, inputs)
+        @analyzer_result = analyzer_result
+        @inputs = EvaluationWrapper.new(inputs)
+        @definitions = analyzer_result.definitions
+        @compiled_schema = Compiler.compile(syntax_tree, analyzer: analyzer_result)
+
+        # TODO: REFACTOR QUICK!
+        # Set up compiler once for expression evaluation
+        @compiler = Compiler.new(syntax_tree, analyzer_result)
+        @compiler.send(:build_index)
+
+        # Populate bindings from the compiled schema
+        @compiled_schema.bindings.each do |name, (type, fn)|
+          @compiler.instance_variable_get(:@bindings)[name] = [type, fn]
+        end
+      end
+
+      def explain(target_name)
+        declaration = @definitions[target_name]
+        raise ArgumentError, "Unknown declaration: #{target_name}" unless declaration
+
+        expression = declaration.expression
+        result_value = @compiled_schema.evaluate_binding(target_name, @inputs)
+
+        prefix = "#{target_name} = "
+        expression_str = format_expression(expression, indent_context: prefix.length)
+
+        "#{prefix}#{expression_str} => #{format_value(result_value)}"
+      end
+
+      private
+
+      def format_expression(expr, indent_context: 0, nested: false)
+        case expr
+        when Syntax::TerminalExpressions::FieldRef
+          "input.#{expr.name}"
+        when Syntax::TerminalExpressions::Binding
+          expr.name.to_s
+        when Syntax::TerminalExpressions::Literal
+          format_value(expr.value)
+        when Syntax::Expressions::CallExpression
+          format_call_expression(expr, indent_context: indent_context, nested: nested)
+        when Syntax::Expressions::ListExpression
+          "[#{expr.elements.map { |e| format_expression(e, indent_context: indent_context, nested: nested) }.join(', ')}]"
+        when Syntax::Expressions::CascadeExpression
+          format_cascade_expression(expr, indent_context: indent_context)
+        else
+          expr.class.name.split("::").last
+        end
+      end
+
+      def format_call_expression(expr, indent_context: 0, nested: false)
+        if pretty_printable?(expr.fn_name)
+          format_pretty_function(expr, expr.fn_name, indent_context, nested)
+        else
+          format_generic_function(expr, indent_context)
+        end
+      end
+
+      def format_pretty_function(expr, fn_name, _indent_context, nested = false)
+        if needs_evaluation?(expr.args) && !nested
+          # For top-level expressions, show the flattened symbolic form and evaluation
+          if is_chain_of_same_operator?(expr, fn_name)
+            # For chains like a + b + c, flatten to show all operands
+            all_operands = flatten_operator_chain(expr, fn_name)
+            symbolic_operands = all_operands.map { |op| format_expression(op, indent_context: 0, nested: true) }
+            symbolic_format = symbolic_operands.join(" #{get_operator_symbol(fn_name)} ")
+
+            evaluated_operands = all_operands.map do |op|
+              if op.is_a?(Syntax::TerminalExpressions::Literal)
+                format_expression(op, indent_context: 0, nested: true)
+              else
+                arg_value = format_value(evaluate_expression(op))
+                if op.is_a?(Syntax::TerminalExpressions::Binding) && all_operands.length > 1
+                  "(#{format_expression(op, indent_context: 0, nested: true)} = #{arg_value})"
+                else
+                  arg_value
+                end
+              end
+            end
+            evaluated_format = evaluated_operands.join(" #{get_operator_symbol(fn_name)} ")
+
+            "#{symbolic_format} = #{evaluated_format}"
+          else
+            # Regular pretty formatting for non-chain expressions
+            symbolic_args = expr.args.map { |arg| format_expression(arg, indent_context: 0, nested: true) }
+            symbolic_format = get_display_format(fn_name, symbolic_args)
+
+            evaluated_args = expr.args.map do |arg|
+              if arg.is_a?(Syntax::TerminalExpressions::Literal)
+                format_expression(arg, indent_context: 0, nested: true)
+              else
+                arg_value = format_value(evaluate_expression(arg))
+                if arg.is_a?(Syntax::TerminalExpressions::Binding) &&
+                   expr.args.count { |a| !a.is_a?(Syntax::TerminalExpressions::Literal) } > 1
+                  "(#{format_expression(arg, indent_context: 0, nested: true)} = #{arg_value})"
+                else
+                  arg_value
+                end
+              end
+            end
+            evaluated_format = get_display_format(fn_name, evaluated_args)
+
+            "#{symbolic_format} = #{evaluated_format}"
+          end
+        else
+          # For nested expressions, just show the symbolic form without evaluation details
+          args = expr.args.map { |arg| format_expression(arg, indent_context: 0, nested: true) }
+          get_display_format(fn_name, args)
+        end
+      end
+
+      def is_chain_of_same_operator?(expr, fn_name)
+        return false unless %i[add subtract multiply divide].include?(fn_name)
+
+        # Check if any argument is the same operator
+        expr.args.any? do |arg|
+          arg.is_a?(Syntax::Expressions::CallExpression) && arg.fn_name == fn_name
+        end
+      end
+
+      def flatten_operator_chain(expr, operator)
+        operands = []
+
+        expr.args.each do |arg|
+          if arg.is_a?(Syntax::Expressions::CallExpression) && arg.fn_name == operator
+            # Recursively flatten nested operations of the same type
+            operands.concat(flatten_operator_chain(arg, operator))
+          else
+            operands << arg
+          end
+        end
+
+        operands
+      end
+
+      def get_operator_symbol(fn_name)
+        case fn_name
+        when :add then "+"
+        when :subtract then "-"
+        when :multiply then "×"
+        when :divide then "÷"
+        else fn_name.to_s
+        end
+      end
+
+      def pretty_printable?(fn_name)
+        %i[add subtract multiply divide == != > < >= <= and or not].include?(fn_name)
+      end
+
+      def get_display_format(fn_name, args)
+        case fn_name
+        when :add then args.join(" + ")
+        when :subtract then args.join(" - ")
+        when :multiply then args.join(" × ")
+        when :divide then args.join(" ÷ ")
+        when :== then "#{args[0]} == #{args[1]}"
+        when :!= then "#{args[0]} != #{args[1]}"
+        when :> then "#{args[0]} > #{args[1]}"
+        when :< then "#{args[0]} < #{args[1]}"
+        when :>= then "#{args[0]} >= #{args[1]}"
+        when :<= then "#{args[0]} <= #{args[1]}"
+        when :and then args.join(" && ")
+        when :or then args.join(" || ")
+        when :not then "!#{args[0]}"
+        else "#{fn_name}(#{args.join(', ')})"
+        end
+      end
+
+      def format_generic_function(expr, indent_context)
+        args = expr.args.map do |arg|
+          arg_desc = format_expression(arg, indent_context: indent_context)
+
+          # For literals and literal lists, just show the value, no need for "100 = 100"
+          if arg.is_a?(Syntax::TerminalExpressions::Literal) ||
+             (arg.is_a?(Syntax::Expressions::ListExpression) && arg.elements.all?(Syntax::TerminalExpressions::Literal))
+            arg_desc
+          else
+            arg_value = evaluate_expression(arg)
+            "#{arg_desc} = #{format_value(arg_value)}"
+          end
+        end
+
+        if args.length > 1
+          # Align with opening parenthesis, accounting for the full context
+          function_indent = indent_context + expr.fn_name.to_s.length + 1
+          indent = " " * function_indent
+          "#{expr.fn_name}(#{args.join(",\n#{indent}")})"
+        else
+          "#{expr.fn_name}(#{args.join(', ')})"
+        end
+      end
+
+      def needs_evaluation?(args)
+        args.any? do |arg|
+          !arg.is_a?(Syntax::TerminalExpressions::Literal) &&
+            !(arg.is_a?(Syntax::Expressions::ListExpression) && arg.elements.all?(Syntax::TerminalExpressions::Literal))
+        end
+      end
+
+      def format_cascade_expression(expr, indent_context: 0)
+        lines = []
+        expr.cases.each do |case_expr|
+          condition_result = evaluate_expression(case_expr.condition)
+          condition_desc = format_expression(case_expr.condition, indent_context: indent_context)
+          result_desc = format_expression(case_expr.result, indent_context: indent_context)
+
+          status = condition_result ? "✓" : "✗"
+          lines << "  #{status} on #{condition_desc}, #{result_desc}"
+
+          break if condition_result
+        end
+
+        "\n#{lines.join("\n")}"
+      end
+
+      def format_value(value)
+        case value
+        when Float, Integer
+          format_number(value)
+        when String
+          "\"#{value}\""
+        when Array
+          if value.length <= 4
+            "[#{value.map { |v| format_value(v) }.join(', ')}]"
+          else
+            "[#{value.take(4).map { |v| format_value(v) }.join(', ')}, …]"
+          end
+        else
+          value.to_s
+        end
+      end
+
+      def format_number(num)
+        return num.to_s unless num.is_a?(Numeric)
+
+        if num.is_a?(Integer) || (num.is_a?(Float) && num == num.to_i)
+          int_val = num.to_i
+          if int_val.abs >= 1000
+            int_val.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1 ').reverse
+          else
+            int_val.to_s
+          end
+        else
+          num.to_s
+        end
+      end
+
+      def evaluate_expression(expr)
+        case expr
+        when Syntax::TerminalExpressions::Binding
+          @compiled_schema.evaluate_binding(expr.name, @inputs)
+        when Syntax::TerminalExpressions::FieldRef
+          @inputs[expr.name]
+        when Syntax::TerminalExpressions::Literal
+          expr.value
+        else
+          # For complex expressions, compile and evaluate using existing compiler
+          compiled_fn = @compiler.send(:compile_expr, expr)
+          compiled_fn.call(@inputs)
+        end
+      end
+    end
+
+    module_function
+
+    def call(schema_class, target_name, inputs:)
+      syntax_tree = schema_class.instance_variable_get(:@__syntax_tree__)
+      analyzer_result = schema_class.instance_variable_get(:@__analyzer_result__)
+
+      raise ArgumentError, "Schema not found or not compiled" unless syntax_tree && analyzer_result
+
+      generator = ExplanationGenerator.new(syntax_tree, analyzer_result, inputs)
+      generator.explain(target_name)
+    end
+  end
+end

data/lib/kumi/export/deserializer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Export
+    class Deserializer
+      include NodeBuilders
+
+      def initialize(validate: true)
+        @validate = validate
+      end
+
+      def deserialize(json_string)
+        data = parse_json(json_string)
+        validate_format(data) if @validate
+
+        build_node(data[:ast])
+      end
+
+      private
+
+      def parse_json(json_string)
+        JSON.parse(json_string, symbolize_names: true)
+      rescue JSON::ParserError => e
+        raise Kumi::Export::Errors::DeserializationError, "Invalid JSON: #{e.message}"
+      end
+
+      def validate_format(data)
+        unless data[:kumi_version] && data[:ast]
+          raise Kumi::Export::Errors::DeserializationError,
+                "Missing required fields: kumi_version, ast"
+        end
+
+        return if data[:ast][:type] == "root"
+
+        raise Kumi::Export::Errors::DeserializationError, "Root node must have type 'root'"
+      end
+    end
+  end
+end

data/lib/kumi/export/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Export
+    module Errors
+      class ExportError < StandardError; end
+      class SerializationError < ExportError; end
+      class DeserializationError < ExportError; end
+      class VersionMismatchError < ExportError; end
+    end
+  end
+end

data/lib/kumi/export/node_builders.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Export
+    module NodeBuilders
+      def build_root(data, node_class)
+        inputs = data[:inputs].map { |input_data| build_node(input_data) }
+        attributes = data[:attributes].map { |attr_data| build_node(attr_data) }
+        traits = data[:traits].map { |trait_data| build_node(trait_data) }
+
+        node_class.new(inputs, attributes, traits)
+      end
+
+      def build_field_declaration(data, node_class)
+        name = restore_name_type(data[:name], data[:name_type])
+        type = deserialize_type(data[:field_type])
+        domain = deserialize_domain(data[:domain])
+
+        # Match the Struct signature of FieldDecl: (name, domain, type)
+        node_class.new(name, domain, type)
+      end
+
+      def build_attribute_declaration(data, node_class)
+        name = restore_name_type(data[:name], data[:name_type])
+        expression = build_node(data[:expression])
+
+        node_class.new(name, expression)
+      end
+
+      def build_trait_declaration(data, node_class)
+        name = restore_name_type(data[:name], data[:name_type])
+        expression = build_node(data[:expression])
+
+        node_class.new(name, expression)
+      end
+
+      def build_call_expression(data, node_class)
+        function_name = restore_name_type(data[:function_name], data[:function_name_type])
+        arguments = data[:arguments].map { |arg_data| build_node(arg_data) }
+
+        node_class.new(function_name, arguments)
+      end
+
+      def build_literal(data, node_class)
+        value = data[:value]
+
+        # Restore proper Ruby type if needed
+        value = coerce_to_type(value, data[:ruby_type]) if data[:ruby_type] && value.is_a?(String)
+
+        node_class.new(value)
+      end
+
+      def build_field_reference(data, node_class)
+        field_name = restore_name_type(data[:field_name], data[:name_type])
+        node_class.new(field_name)
+      end
+
+      def build_binding_reference(data, node_class)
+        binding_name = restore_name_type(data[:binding_name], data[:name_type])
+        node_class.new(binding_name)
+      end
+
+      def build_list_expression(data, node_class)
+        elements = data[:elements].map { |element_data| build_node(element_data) }
+        node_class.new(elements)
+      end
+
+      def build_cascade_expression(data, node_class)
+        cases = data[:cases].map { |case_data| build_node(case_data) }
+        node_class.new(cases)
+      end
+
+      def build_when_case_expression(data, node_class)
+        condition = build_node(data[:condition])
+        result = build_node(data[:result])
+        node_class.new(condition, result)
+      end
+
+      private
+
+      def deserialize_type(type_data)
+        # Handle simple types that weren't serialized with the new format
+        return type_data unless type_data.is_a?(Hash) && type_data.key?(:type)
+
+        case type_data[:type]
+        when "symbol"
+          type_data[:value].to_sym
+        when "array"
+          { array: deserialize_type(type_data[:element_type]) }
+        when "hash"
+          { hash: [deserialize_type(type_data[:key_type]), deserialize_type(type_data[:value_type])] }
+        when "literal", nil
+          type_data[:value]
+        end
+      end
+
+      def build_node(node_data)
+        type_name = node_data[:type]
+        node_class = NodeRegistry.class_for_type(type_name)
+
+        build_method = "build_#{type_name}"
+        raise Kumi::Export::Errors::DeserializationError, "No builder for type: #{type_name}" unless respond_to?(build_method, true)
+
+        send(build_method, node_data, node_class)
+      end
+
+      def deserialize_domain(domain_data)
+        return nil unless domain_data
+
+        case domain_data[:type]
+        when "range"
+          min, max = domain_data.values_at(:min, :max)
+          domain_data[:exclude_end] ? (min...max) : (min..max)
+        when "array"
+          domain_data[:values]
+        when "custom"
+          # For custom domains, we might need to eval or have a registry
+          domain_data[:value]
+        end
+      end
+
+      def coerce_to_type(value, type_name)
+        case type_name
+        when "Integer" then value.to_i
+        when "Float" then value.to_f
+        when "Symbol" then value.to_sym
+        else value
+        end
+      end
+
+      def restore_name_type(name_string, name_type)
+        case name_type
+        when "Symbol" then name_string.to_sym
+        when "String" then name_string.to_s
+        else name_string
+        end
+      end
+    end
+  end
+end

data/lib/kumi/export/node_registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Export
+    class NodeRegistry
+      # Maps AST classes to JSON type names
+      SERIALIZATION_MAP = {
+        "Kumi::Syntax::Root" => "root",
+        "Kumi::Syntax::Declarations::FieldDecl" => "field_declaration",
+        "Kumi::Syntax::Declarations::Attribute" => "attribute_declaration",
+        "Kumi::Syntax::Declarations::Trait" => "trait_declaration",
+        "Kumi::Syntax::Expressions::CallExpression" => "call_expression",
+        "Kumi::Syntax::TerminalExpressions::Literal" => "literal",
+        "Kumi::Syntax::TerminalExpressions::FieldRef" => "field_reference",
+        "Kumi::Syntax::TerminalExpressions::Binding" => "binding_reference",
+        "Kumi::Syntax::Expressions::ListExpression" => "list_expression",
+        "Kumi::Syntax::Expressions::CascadeExpression" => "cascade_expression",
+        "Kumi::Syntax::Expressions::WhenCaseExpression" => "when_case_expression"
+      }.freeze
+
+      # Maps JSON type names back to AST classes
+      DESERIALIZATION_MAP = SERIALIZATION_MAP.invert.freeze
+
+      def self.type_name_for(node)
+        SERIALIZATION_MAP[node.class.name] or
+          raise Kumi::Export::Errors::SerializationError, "Unknown node type: #{node.class.name}"
+      end
+
+      def self.class_for_type(type_name)
+        class_name = DESERIALIZATION_MAP[type_name] or
+          raise Kumi::Export::Errors::DeserializationError, "Unknown type name: #{type_name}"
+
+        # Resolve the class from string name
+        class_name.split("::").reduce(Object) { |const, name| const.const_get(name) }
+      end
+    end
+  end
+end

data/lib/kumi/export/node_serializers.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Export
+    module NodeSerializers
+      # Root node: top-level container
+      def serialize_root(node)
+        {
+          type: "root",
+          inputs: node.inputs.map { |input| serialize_node(input) },
+          attributes: node.attributes.map { |attr| serialize_node(attr) },
+          traits: node.traits.map { |trait| serialize_node(trait) }
+        }
+      end
+
+      # Field Declaration: preserves type info for analyzer
+      def serialize_field_declaration(node)
+        {
+          name: node.name.to_s,
+          name_type: node.name.class.name,
+          field_type: serialize_type(node.type),
+          domain: serialize_domain(node.domain)
+        }
+      end
+
+      # Attribute Declaration: preserves name and expression tree
+      def serialize_attribute_declaration(node)
+        {
+          name: node.name.to_s,
+          name_type: node.name.class.name,
+          expression: serialize_node(node.expression)
+        }
+      end
+
+      # Trait Declaration: preserves name and expression tree
+      def serialize_trait_declaration(node)
+        {
+          name: node.name.to_s,
+          name_type: node.name.class.name,
+          expression: serialize_node(node.expression)
+        }
+      end
+
+      # Call Expression: critical for dependency analysis
+      def serialize_call_expression(node)
+        {
+          function_name: node.fn_name.to_s,
+          function_name_type: node.fn_name.class.name,
+          arguments: node.args.map { |arg| serialize_node(arg) }
+        }
+      end
+
+      # Literal: preserve exact value and Ruby type
+      def serialize_literal(node)
+        {
+          value: node.value,
+          ruby_type: node.value.class.name
+        }
+      end
+
+      # Field Reference: critical for dependency resolution
+      def serialize_field_reference(node)
+        {
+          field_name: node.name.to_s,
+          name_type: node.name.class.name
+        }
+      end
+
+      # Binding Reference: critical for dependency resolution
+      def serialize_binding_reference(node)
+        {
+          binding_name: node.name.to_s,
+          name_type: node.name.class.name
+        }
+      end
+
+      # List Expression: preserve order and elements
+      def serialize_list_expression(node)
+        {
+          elements: node.elements.map { |element| serialize_node(element) }
+        }
+      end
+
+      # Cascade Expression: preserve condition/result pairs
+      def serialize_cascade_expression(node)
+        {
+          cases: node.cases.map { |case_node| serialize_node(case_node) }
+        }
+      end
+
+      # When Case Expression: individual case in cascade
+      def serialize_when_case_expression(node)
+        {
+          condition: serialize_node(node.condition),
+          result: serialize_node(node.result)
+        }
+      end
+
+      private
+
+      def serialize_type(type)
+        case type
+        when Symbol
+          { type: "symbol", value: type.to_s }
+        when Hash
+          if type.key?(:array)
+            { type: "array", element_type: serialize_type(type[:array]) }
+          elsif type.key?(:hash)
+            { type: "hash", key_type: serialize_type(type[:hash][0]), value_type: serialize_type(type[:hash][1]) }
+          else
+            { type: "hash", value: type }
+          end
+        when String, Integer, Float, TrueClass, FalseClass, NilClass
+          { type: "literal", value: type }
+        else
+          { type: "unknown", value: type.to_s }
+        end
+      end
+
+      def serialize_domain(domain)
+        return nil unless domain
+
+        case domain
+        when Range
+          { type: "range", min: domain.min, max: domain.max, exclude_end: domain.exclude_end? }
+        when Array
+          { type: "array", values: domain }
+        else
+          { type: "custom", value: domain.to_s }
+        end
+      end
+
+      def serialize_node(node)
+        type_name = NodeRegistry.type_name_for(node)
+
+        base_data = {
+          type: type_name,
+          **send("serialize_#{type_name}", node)
+        }
+
+        add_location_if_present(base_data, node) if @include_locations
+        base_data
+      end
+
+      def add_location_if_present(data, node)
+        return unless node.respond_to?(:loc) && node.loc
+
+        data[:location] = {
+          line: node.loc.line,
+          column: node.loc.column,
+          file: node.loc.file
+        }
+      end
+    end
+  end
+end

data/lib/kumi/export/serializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Export
+    class Serializer
+      include NodeSerializers
+
+      def initialize(pretty: false, include_locations: false)
+        @pretty = pretty
+        @include_locations = include_locations
+      end
+
+      def serialize(syntax_root)
+        json_data = {
+          kumi_version: VERSION,
+          ast: serialize_root(syntax_root)
+        }
+
+        @pretty ? JSON.pretty_generate(json_data) : JSON.generate(json_data)
+      end
+    end
+  end
+end