kumi 0.0.0 → 0.0.4

data/lib/kumi/parser/schema_builder.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Parser
+    class SchemaBuilder
+      include GuardRails
+      include Syntax
+      include ErrorReporting
+
+      DSL_METHODS = %i[value trait input ref literal fn].freeze
+
+      def initialize(context)
+        @context = context
+      end
+
+      def value(name = nil, expr = nil, &blk)
+        update_location
+        validate_value_args(name, expr, blk)
+
+        expression = blk ? build_cascade(&blk) : ensure_syntax(expr)
+        @context.attributes << Attribute.new(name, expression, loc: @context.current_location)
+      end
+
+      def trait(*args, **kwargs)
+        update_location
+        raise_syntax_error("keyword trait syntax not supported", location: @context.current_location) unless kwargs.empty?
+        build_positional_trait(args)
+      end
+
+      def input(&blk)
+        return InputProxy.new(@context) unless block_given?
+
+        raise_syntax_error("input block already defined", location: @context.current_location) if @context.input_block_defined?
+        @context.mark_input_block_defined!
+
+        update_location
+        input_builder = InputBuilder.new(@context)
+        input_builder.instance_eval(&blk)
+      end
+
+      def ref(name)
+        update_location
+        Binding.new(name, loc: @context.current_location)
+      end
+
+      def literal(value)
+        update_location
+        Literal.new(value, loc: @context.current_location)
+      end
+
+      def fn(fn_name, *args)
+        update_location
+        expr_args = args.map { |a| ensure_syntax(a) }
+        CallExpression.new(fn_name, expr_args, loc: @context.current_location)
+      end
+
+      def method_missing(method_name, *args, &block)
+        if args.empty? && !block_given?
+          update_location
+          Binding.new(method_name, loc: @context.current_location)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(_method_name, _include_private = false)
+        true
+      end
+
+      private
+
+      def update_location
+        # Use caller_locations(2, 1) to skip the DSL method and get the actual user code location
+        # Stack: [0] update_location, [1] DSL method (value/trait/etc), [2] user's DSL code
+        caller_location = caller_locations(2, 1).first
+
+        @context.current_location = Location.new(
+          file: caller_location.path,
+          line: caller_location.lineno,
+          column: 0
+        )
+      end
+
+      def validate_value_args(name, expr, blk)
+        raise_syntax_error("value requires a name as first argument", location: @context.current_location) if name.nil?
+        unless name.is_a?(Symbol)
+          raise_syntax_error("The name for 'value' must be a Symbol, got #{name.class}",
+                             location: @context.current_location)
+        end
+
+        has_expr = !expr.nil?
+        has_block = blk
+
+        if has_expr && has_block
+          raise_syntax_error("value '#{name}' cannot be called with both an expression and a block", location: @context.current_location)
+        elsif !has_expr && !has_block
+          raise_syntax_error("value '#{name}' requires an expression or a block", location: @context.current_location)
+        end
+      end
+
+      def build_positional_trait(args)
+        case args.size
+        when 0
+          raise_syntax_error("trait requires a name and expression", location: @context.current_location)
+        when 1
+          name = args.first
+          raise_syntax_error("trait '#{name}' requires an expression", location: @context.current_location)
+        when 2
+          name, expression = args
+          validate_trait_name(name)
+          expr = ensure_syntax(expression)
+          @context.traits << Trait.new(name, expr, loc: @context.current_location)
+        else
+          handle_deprecated_trait_syntax(args)
+        end
+      end
+
+      def handle_deprecated_trait_syntax(args)
+        if args.size == 3
+          name, = args
+          raise_syntax_error("trait '#{name}' requires exactly 3 arguments: lhs, operator, and rhs", location: @context.current_location)
+        end
+
+        # warn "DEPRECATION: trait(:name, lhs, operator, rhs) syntax is deprecated. Use: trait :name, (lhs operator rhs)"
+
+        if args.size == 4
+          name, lhs, operator, rhs = args
+          build_deprecated_trait(name, lhs, operator, [rhs])
+        else
+          name, lhs, operator, *rhs = args
+          build_deprecated_trait(name, lhs, operator, rhs)
+        end
+      end
+
+      def build_deprecated_trait(name, lhs, operator, rhs)
+        validate_trait_name(name)
+        validate_operator(operator)
+
+        rhs_exprs = rhs.map { |r| ensure_syntax(r) }
+        expr = CallExpression.new(operator, [ensure_syntax(lhs)] + rhs_exprs, loc: @context.current_location)
+        @context.traits << Trait.new(name, expr, loc: @context.current_location)
+      end
+
+      def validate_trait_name(name)
+        return if name.is_a?(Symbol)
+
+        raise_syntax_error("The name for 'trait' must be a Symbol, got #{name.class}", location: @context.current_location)
+      end
+
+      def validate_operator(operator)
+        unless operator.is_a?(Symbol)
+          raise_syntax_error("expects a symbol for an operator, got #{operator.class}", location: @context.current_location)
+        end
+
+        return if FunctionRegistry.operator?(operator)
+
+        raise_syntax_error("unsupported operator `#{operator}`", location: @context.current_location)
+      end
+
+      def build_cascade(&blk)
+        expression_converter = ExpressionConverter.new(@context)
+        cascade_builder = DslCascadeBuilder.new(expression_converter, @context.current_location)
+        cascade_builder.instance_eval(&blk)
+        CascadeExpression.new(cascade_builder.cases, loc: @context.current_location)
+      end
+
+      def ensure_syntax(obj)
+        ExpressionConverter.new(@context).ensure_syntax(obj)
+      end
+    end
+  end
+end

data/lib/kumi/parser/sugar.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Parser
+    module Sugar
+      include Syntax
+
+      ARITHMETIC_OPS = { :+ => :add, :- => :subtract, :* => :multiply,
+                         :/ => :divide, :% => :modulo, :** => :power }.freeze
+      COMPARISON_OPS = %i[< <= > >= == !=].freeze
+      LITERAL_TYPES = [Integer, String, Symbol, TrueClass, FalseClass, Float, Regexp].freeze
+
+      def self.ensure_literal(obj)
+        return Literal.new(obj) if LITERAL_TYPES.any? { |type| obj.is_a?(type) }
+        return obj if obj.is_a?(Syntax::Node)
+        return obj.to_ast_node if obj.respond_to?(:to_ast_node)
+
+        Literal.new(obj)
+      end
+
+      def self.syntax_expression?(obj)
+        obj.is_a?(Syntax::Node) || obj.respond_to?(:to_ast_node)
+      end
+
+      module ExpressionRefinement
+        refine Syntax::Node do
+          ARITHMETIC_OPS.each do |op, op_name|
+            define_method(op) do |other|
+              other_node = Sugar.ensure_literal(other)
+              Syntax::CallExpression.new(op_name, [self, other_node])
+            end
+          end
+
+          COMPARISON_OPS.each do |op|
+            define_method(op) do |other|
+              other_node = Sugar.ensure_literal(other)
+              Syntax::CallExpression.new(op, [self, other_node])
+            end
+          end
+
+          def [](index)
+            Syntax::CallExpression.new(:at, [self, Sugar.ensure_literal(index)])
+          end
+
+          def -@
+            Syntax::CallExpression.new(:subtract, [Sugar.ensure_literal(0), self])
+          end
+
+          def &(other)
+            Syntax::CallExpression.new(:and, [self, Sugar.ensure_literal(other)])
+          end
+        end
+      end
+
+      module NumericRefinement
+        [Integer, Float].each do |klass|
+          refine klass do
+            ARITHMETIC_OPS.each do |op, op_name|
+              define_method(op) do |other|
+                if Sugar.syntax_expression?(other)
+                  other_node = other.respond_to?(:to_ast_node) ? other.to_ast_node : other
+                  Syntax::CallExpression.new(op_name, [Syntax::Literal.new(self), other_node])
+                else
+                  super(other)
+                end
+              end
+            end
+
+            COMPARISON_OPS.each do |op|
+              define_method(op) do |other|
+                if Sugar.syntax_expression?(other)
+                  other_node = other.respond_to?(:to_ast_node) ? other.to_ast_node : other
+                  Syntax::CallExpression.new(op, [Syntax::Literal.new(self), other_node])
+                else
+                  super(other)
+                end
+              end
+            end
+          end
+        end
+      end
+
+      module StringRefinement
+        refine String do
+          def +(other)
+            if Sugar.syntax_expression?(other)
+              other_node = other.respond_to?(:to_ast_node) ? other.to_ast_node : other
+              Syntax::CallExpression.new(:concat, [Syntax::Literal.new(self), other_node])
+            else
+              super
+            end
+          end
+
+          %i[== !=].each do |op|
+            define_method(op) do |other|
+              if Sugar.syntax_expression?(other)
+                other_node = other.respond_to?(:to_ast_node) ? other.to_ast_node : other
+                Syntax::CallExpression.new(op, [Syntax::Literal.new(self), other_node])
+              else
+                super(other)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/schema.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module Kumi
+  module Schema
+    Inspector = Struct.new(:syntax_tree, :analyzer_result, :compiled_schema) do
+      def inspect
+        "#<#{self.class} syntax_tree: #{syntax_tree.inspect}, analyzer_result: #{analyzer_result.inspect}, schema: #{schema.inspect}>"
+      end
+    end
+
+    def from(context)
+      raise("No schema defined") unless @__compiled_schema__
+
+      # Validate input types and domain constraints
+      input_meta = @__analyzer_result__.state[:input_meta] || {}
+      violations = Input::Validator.validate_context(context, input_meta)
+
+      raise Errors::InputValidationError, violations unless violations.empty?
+
+      SchemaInstance.new(@__compiled_schema__, @__analyzer_result__.definitions, context)
+    end
+
+    def explain(context, *keys)
+      raise("No schema defined") unless @__compiled_schema__
+
+      # Validate input types and domain constraints
+      input_meta = @__analyzer_result__.state[:input_meta] || {}
+      violations = Input::Validator.validate_context(context, input_meta)
+
+      raise Errors::InputValidationError, violations unless violations.empty?
+
+      keys.each do |key|
+        puts Kumi::Explain.call(self, key, inputs: context)
+      end
+
+      nil
+    end
+
+    def schema(&block)
+      @__syntax_tree__ = Kumi::Parser::Dsl.build_syntax_tree(&block).freeze
+      @__analyzer_result__ = Analyzer.analyze!(@__syntax_tree__).freeze
+      @__compiled_schema__ = Compiler.compile(@__syntax_tree__, analyzer: @__analyzer_result__).freeze
+
+      Inspector.new(@__syntax_tree__, @__analyzer_result__, @__compiled_schema__)
+    end
+  end
+end

data/lib/kumi/schema_instance.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Kumi
+  # A bound pair of <compiled schema + context>.  Immutable.
+  #
+  # Public API ----------------------------------------------------------
+  #   instance.evaluate                # => full Hash of all bindings
+  #   instance.evaluate(:tax_due, :rate)
+  #   instance.slice(:tax_due)         # alias for evaluate(*keys)
+  #   instance.explain(:tax_due)       # pretty trace string
+  #   instance.input                   # original context (read‑only)
+  #
+  class SchemaInstance
+    def initialize(compiled_schema, analysis, context)
+      @compiled_schema = compiled_schema # Kumi::CompiledSchema
+      @analysis = analysis # Analyzer result (for deps)
+      @context  = context.is_a?(EvaluationWrapper) ? context : EvaluationWrapper.new(context)
+    end
+
+    # Hash‑like read of one or many bindings
+    def evaluate(*key_names)
+      if key_names.empty?
+        @compiled_schema.evaluate(@context)
+      else
+        @compiled_schema.evaluate(@context, *key_names)
+      end
+    end
+
+    def slice(*key_names)
+      return {} if key_names.empty?
+
+      evaluate(*key_names)
+    end
+
+    def [](key_name)
+      evaluate(key_name)[key_name]
+    end
+
+    def input
+      @context
+    end
+  end
+end

data/lib/kumi/syntax/declarations.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    module Declarations
+      Attribute = Struct.new(:name, :expression) do
+        include Node
+        def children = [expression]
+      end
+
+      Trait = Struct.new(:name, :expression) do
+        include Node
+        def children = [expression]
+      end
+
+      # For field metadata declarations inside input blocks
+      FieldDecl = Struct.new(:name, :domain, :type) do
+        include Node
+        def children = []
+      end
+    end
+  end
+end

data/lib/kumi/syntax/expressions.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    module Expressions
+      CallExpression = Struct.new(:fn_name, :args) do
+        include Node
+        def children = args
+      end
+      CascadeExpression = Struct.new(:cases) do
+        include Node
+        def children = cases
+      end
+
+      WhenCaseExpression = Struct.new(:condition, :result) do
+        include Node
+        def children = [condition, result]
+      end
+
+      ListExpression = Struct.new(:elements) do
+        include Node
+        def children = elements
+
+        def size
+          elements.size
+        end
+      end
+    end
+  end
+end

data/lib/kumi/syntax/node.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    # A struct to hold standardized source location information.
+    Location = Struct.new(:file, :line, :column, keyword_init: true)
+
+    # Base module included by all AST nodes to provide a standard
+    # interface for accessing source location information..
+    module Node
+      attr_accessor :loc
+
+      def initialize(*args, loc: nil, **kwargs)
+        @loc = loc
+        super(*args, **kwargs)
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          # for Struct-based nodes
+          (if respond_to?(:members)
+             members.all? { |m| self[m] == other[m] }
+           else
+             instance_variables.reject { |iv| iv == :@loc }
+                                        .all? do |iv|
+               instance_variable_get(iv) ==
+                                            other.instance_variable_get(iv)
+             end
+           end
+          )
+      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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    # Represents the root of the Abstract Syntax Tree.
+    # It holds all the top-level declarations parsed from the source.
+    Root = Struct.new(:inputs, :attributes, :traits) do
+      include Node
+      def children = [inputs, attributes, traits]
+    end
+  end
+end

data/lib/kumi/syntax/terminal_expressions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "node"
+
+module Kumi
+  module Syntax
+    module TerminalExpressions
+      # Leaf expressions that represent a value or reference and terminate a branch.
+
+      Literal = Struct.new(:value) do
+        include Node
+        def children = []
+      end
+
+      # For field usage/reference in expressions (input.field_name)
+      FieldRef = Struct.new(:name) do
+        include Node
+        def children = []
+      end
+
+      Binding = Struct.new(:name) do
+        include Node
+        def children = []
+      end
+    end
+  end
+end

data/lib/kumi/syntax.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Syntax
+    include Declarations
+    include Expressions
+    include TerminalExpressions
+  end
+end

data/lib/kumi/types/builder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Types
+    # Builds complex type structures
+    class Builder
+      def self.array(elem_type)
+        raise ArgumentError, "Invalid array element type: #{elem_type}" unless Validator.valid_type?(elem_type)
+
+        { array: elem_type }
+      end
+
+      def self.hash(key_type, val_type)
+        raise ArgumentError, "Invalid hash key type: #{key_type}" unless Validator.valid_type?(key_type)
+        raise ArgumentError, "Invalid hash value type: #{val_type}" unless Validator.valid_type?(val_type)
+
+        { hash: [key_type, val_type] }
+      end
+    end
+  end
+end

data/lib/kumi/types/compatibility.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Types
+    # Handles type compatibility and unification
+    class Compatibility
+      # Check if two types are compatible
+      def self.compatible?(type1, type2)
+        # Any type is compatible with anything
+        return true if type1 == :any || type2 == :any
+
+        # Exact match
+        return true if type1 == type2
+
+        # Numeric compatibility
+        return true if numeric_compatible?(type1, type2)
+
+        # Array compatibility
+        return array_compatible?(type1, type2) if array_types?(type1, type2)
+
+        # Hash compatibility
+        return hash_compatible?(type1, type2) if hash_types?(type1, type2)
+
+        false
+      end
+
+      # Find the most specific common type between two types
+      def self.unify(type1, type2)
+        return type1 if type1 == type2
+
+        # :any unifies to the other type (more specific)
+        return type2 if type1 == :any
+        return type1 if type2 == :any
+
+        # Numeric unification
+        if numeric_compatible?(type1, type2)
+          return :integer if type1 == :integer && type2 == :integer
+
+          return :float # One or both are float
+        end
+
+        # Array unification
+        if array_types?(type1, type2)
+          elem1 = type1[:array]
+          elem2 = type2[:array]
+          unified_elem = unify(elem1, elem2)
+          return Kumi::Types.array(unified_elem)
+        end
+
+        # Hash unification
+        if hash_types?(type1, type2)
+          key1, val1 = type1[:hash]
+          key2, val2 = type2[:hash]
+          unified_key = unify(key1, key2)
+          unified_val = unify(val1, val2)
+          return Kumi::Types.hash(unified_key, unified_val)
+        end
+
+        # Fall back to :any for incompatible types
+        :any
+      end
+
+      def self.numeric_compatible?(type1, type2)
+        numeric_types = %i[integer float]
+        numeric_types.include?(type1) && numeric_types.include?(type2)
+      end
+
+      def self.array_types?(type1, type2)
+        Validator.array_type?(type1) && Validator.array_type?(type2)
+      end
+
+      def self.hash_types?(type1, type2)
+        Validator.hash_type?(type1) && Validator.hash_type?(type2)
+      end
+
+      def self.array_compatible?(type1, type2)
+        compatible?(type1[:array], type2[:array])
+      end
+
+      def self.hash_compatible?(type1, type2)
+        compatible?(type1[:hash][0], type2[:hash][0]) &&
+          compatible?(type1[:hash][1], type2[:hash][1])
+      end
+    end
+  end
+end

data/lib/kumi/types/formatter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Types
+    # Formats types for display and debugging
+    class Formatter
+      # Convert types to string representation
+      def self.type_to_s(type)
+        case type
+        when Hash
+          if type[:array]
+            "array(#{type_to_s(type[:array])})"
+          elsif type[:hash]
+            "hash(#{type_to_s(type[:hash][0])}, #{type_to_s(type[:hash][1])})"
+          else
+            type.to_s
+          end
+        else
+          type.to_s
+        end
+      end
+    end
+  end
+end