kumi 0.0.6 → 0.0.8

data/lib/kumi/explain.rb

@@ -1,281 +0,0 @@
-# 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 Kumi::Syntax::InputReference
-          "input.#{expr.name}"
-        when Kumi::Syntax::DeclarationReference
-          expr.name.to_s
-        when Kumi::Syntax::Literal
-          format_value(expr.value)
-        when Kumi::Syntax::CallExpression
-          format_call_expression(expr, indent_context: indent_context, nested: nested)
-        when Kumi::Syntax::ArrayExpression
-          "[#{expr.elements.map { |e| format_expression(e, indent_context: indent_context, nested: nested) }.join(', ')}]"
-        when Kumi::Syntax::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: 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 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?(Kumi::Syntax::Literal)
-                format_expression(op, indent_context: 0, nested: true)
-              else
-                arg_value = format_value(evaluate_expression(op))
-                if op.is_a?(Kumi::Syntax::DeclarationReference) && 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)} ")
-
-          else
-            # Regular pretty formatting for non-chain expressions
-            symbolic_args = expr.args.map { |arg| format_expression(arg, indent_context: 0, nested: true) }
-            symbolic_format = display_format(fn_name, symbolic_args)
-
-            evaluated_args = expr.args.map do |arg|
-              if arg.is_a?(Kumi::Syntax::Literal)
-                format_expression(arg, indent_context: 0, nested: true)
-              else
-                arg_value = format_value(evaluate_expression(arg))
-                if arg.is_a?(Kumi::Syntax::DeclarationReference) &&
-                   expr.args.count { |a| !a.is_a?(Kumi::Syntax::Literal) } > 1
-                  "(#{format_expression(arg, indent_context: 0, nested: true)} = #{arg_value})"
-                else
-                  arg_value
-                end
-              end
-            end
-            evaluated_format = display_format(fn_name, evaluated_args)
-
-          end
-          "#{symbolic_format} = #{evaluated_format}"
-        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) }
-          display_format(fn_name, args)
-        end
-      end
-
-      def 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?(Kumi::Syntax::CallExpression) && arg.fn_name == fn_name
-        end
-      end
-
-      def flatten_operator_chain(expr, operator)
-        operands = []
-
-        expr.args.each do |arg|
-          if arg.is_a?(Kumi::Syntax::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 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?(Kumi::Syntax::Literal) ||
-             (arg.is_a?(Kumi::Syntax::ArrayExpression) && arg.elements.all?(Kumi::Syntax::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?(Kumi::Syntax::Literal) &&
-            !(arg.is_a?(Kumi::Syntax::ArrayExpression) && arg.elements.all?(Kumi::Syntax::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 Kumi::Syntax::DeclarationReference
-          @compiled_schema.evaluate_binding(expr.name, @inputs)
-        when Kumi::Syntax::InputReference
-          @inputs[expr.name]
-        when Kumi::Syntax::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

@@ -1,39 +0,0 @@
-# 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

@@ -1,12 +0,0 @@
-# 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

@@ -1,140 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 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::InputDeclaration" => "field_declaration",
-        "Kumi::Syntax::ValueDeclaration" => "attribute_declaration", 
-        "Kumi::Syntax::TraitDeclaration" => "trait_declaration",
-        "Kumi::Syntax::CallExpression" => "call_expression",
-        "Kumi::Syntax::ArrayExpression" => "list_expression",
-        "Kumi::Syntax::HashExpression" => "hash_expression",
-        "Kumi::Syntax::CascadeExpression" => "cascade_expression",
-        "Kumi::Syntax::CaseExpression" => "when_case_expression",
-        "Kumi::Syntax::Literal" => "literal",
-        "Kumi::Syntax::InputReference" => "field_reference",
-        "Kumi::Syntax::DeclarationReference" => "binding_reference"
-      }.freeze
-
-      # Maps JSON type names back to AST classes (using new canonical class names)
-      DESERIALIZATION_MAP = {
-        "root" => "Kumi::Syntax::Root",
-        "field_declaration" => "Kumi::Syntax::InputDeclaration",
-        "attribute_declaration" => "Kumi::Syntax::ValueDeclaration", 
-        "trait_declaration" => "Kumi::Syntax::TraitDeclaration",
-        "call_expression" => "Kumi::Syntax::CallExpression",
-        "list_expression" => "Kumi::Syntax::ArrayExpression",
-        "hash_expression" => "Kumi::Syntax::HashExpression",
-        "cascade_expression" => "Kumi::Syntax::CascadeExpression",
-        "when_case_expression" => "Kumi::Syntax::CaseExpression",
-        "literal" => "Kumi::Syntax::Literal",
-        "field_reference" => "Kumi::Syntax::InputReference",
-        "binding_reference" => "Kumi::Syntax::DeclarationReference"
-      }.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

@@ -1,156 +0,0 @@
-# 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
-
-      # DeclarationReference 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