kumi 0.0.0 → 0.0.3

data/lib/kumi/export.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kumi
+  module Export
+    # Core interface - only depends on Syntax::Root
+    def self.to_json(syntax_root, **options)
+      Serializer.new(**options).serialize(syntax_root)
+    end
+
+    def self.from_json(json_string, **options)
+      Deserializer.new(**options).deserialize(json_string)
+    end
+
+    # Convenience methods
+    def self.to_file(syntax_root, filepath, **options)
+      File.write(filepath, to_json(syntax_root, **options))
+    end
+
+    def self.from_file(filepath, **options)
+      from_json(File.read(filepath), **options)
+    end
+
+    # Validation without import
+    def self.valid?(json_string)
+      from_json(json_string)
+      true
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/kumi/function_registry/collection_functions.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Kumi
+  module FunctionRegistry
+    # Collection manipulation and query functions
+    module CollectionFunctions
+      def self.definitions
+        {
+          # Collection queries
+          empty?: FunctionBuilder.collection_unary(:empty?, "Check if collection is empty", :empty?),
+          size: FunctionBuilder.collection_unary(:size, "Get collection size", :size, return_type: :integer),
+          length: FunctionBuilder.collection_unary(:length, "Get collection length", :length, return_type: :integer),
+
+          # Element access
+          first: FunctionBuilder::Entry.new(
+            fn: lambda(&:first),
+            arity: 1,
+            param_types: [Kumi::Types.array(:any)],
+            return_type: :any,
+            description: "Get first element of collection"
+          ),
+
+          last: FunctionBuilder::Entry.new(
+            fn: lambda(&:last),
+            arity: 1,
+            param_types: [Kumi::Types.array(:any)],
+            return_type: :any,
+            description: "Get last element of collection"
+          ),
+
+          # Mathematical operations on collections
+          sum: FunctionBuilder::Entry.new(
+            fn: lambda(&:sum),
+            arity: 1,
+            param_types: [Kumi::Types.array(:float)],
+            return_type: :float,
+            description: "Sum all numeric elements in collection"
+          ),
+
+          min: FunctionBuilder::Entry.new(
+            fn: lambda(&:min),
+            arity: 1,
+            param_types: [Kumi::Types.array(:float)],
+            return_type: :float,
+            description: "Find minimum value in numeric collection"
+          ),
+
+          max: FunctionBuilder::Entry.new(
+            fn: lambda(&:max),
+            arity: 1,
+            param_types: [Kumi::Types.array(:float)],
+            return_type: :float,
+            description: "Find maximum value in numeric collection"
+          ),
+
+          # Collection operations
+          include?: FunctionBuilder::Entry.new(
+            fn: ->(collection, element) { collection.include?(element) },
+            arity: 2,
+            param_types: [Kumi::Types.array(:any), :any],
+            return_type: :boolean,
+            description: "Check if collection includes element"
+          ),
+
+          reverse: FunctionBuilder::Entry.new(
+            fn: lambda(&:reverse),
+            arity: 1,
+            param_types: [Kumi::Types.array(:any)],
+            return_type: Kumi::Types.array(:any),
+            description: "Reverse collection order"
+          ),
+
+          sort: FunctionBuilder::Entry.new(
+            fn: lambda(&:sort),
+            arity: 1,
+            param_types: [Kumi::Types.array(:any)],
+            return_type: Kumi::Types.array(:any),
+            description: "Sort collection"
+          ),
+
+          unique: FunctionBuilder::Entry.new(
+            fn: lambda(&:uniq),
+            arity: 1,
+            param_types: [Kumi::Types.array(:any)],
+            return_type: Kumi::Types.array(:any),
+            description: "Remove duplicate elements from collection"
+          )
+        }
+      end
+    end
+  end
+end

data/lib/kumi/function_registry/comparison_functions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kumi
+  module FunctionRegistry
+    # Comparison and equality functions
+    module ComparisonFunctions
+      def self.definitions
+        {
+          # Equality operators
+          :== => FunctionBuilder.equality(:==, "Equality comparison", :==),
+          :!= => FunctionBuilder.equality(:!=, "Inequality comparison", :!=),
+
+          # Comparison operators
+          :> => FunctionBuilder.comparison(:>, "Greater than comparison", :>),
+          :< => FunctionBuilder.comparison(:<, "Less than comparison", :<),
+          :>= => FunctionBuilder.comparison(:>=, "Greater than or equal comparison", :>=),
+          :<= => FunctionBuilder.comparison(:<=, "Less than or equal comparison", :<=),
+
+          # Range comparison
+          :between? => FunctionBuilder::Entry.new(
+            fn: ->(value, min, max) { value.between?(min, max) },
+            arity: 3,
+            param_types: %i[float float float],
+            return_type: :boolean,
+            description: "Check if value is between min and max"
+          )
+        }
+      end
+    end
+  end
+end

data/lib/kumi/function_registry/conditional_functions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Kumi
+  module FunctionRegistry
+    # Conditional and control flow functions
+    module ConditionalFunctions
+      def self.definitions
+        {
+          conditional: FunctionBuilder::Entry.new(
+            fn: ->(condition, true_value, false_value) { condition ? true_value : false_value },
+            arity: 3,
+            param_types: %i[boolean any any],
+            return_type: :any,
+            description: "Ternary conditional operator"
+          ),
+
+          if: FunctionBuilder::Entry.new(
+            fn: ->(condition, true_value, false_value = nil) { condition ? true_value : false_value },
+            arity: -1, # Variable arity (2 or 3)
+            param_types: %i[boolean any any],
+            return_type: :any,
+            description: "If-then-else conditional"
+          ),
+
+          coalesce: FunctionBuilder::Entry.new(
+            fn: ->(*values) { values.find { |v| !v.nil? } },
+            arity: -1, # Variable arity
+            param_types: [:any],
+            return_type: :any,
+            description: "Return first non-nil value"
+          )
+        }
+      end
+    end
+  end
+end

data/lib/kumi/function_registry/function_builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Kumi
+  module FunctionRegistry
+    # Utility class to reduce repetition in function definitions
+    class FunctionBuilder
+      Entry = Struct.new(:fn, :arity, :param_types, :return_type, :description, :inverse, keyword_init: true)
+
+      def self.comparison(_name, description, operation)
+        Entry.new(
+          fn: ->(a, b) { a.public_send(operation, b) },
+          arity: 2,
+          param_types: %i[float float],
+          return_type: :boolean,
+          description: description
+        )
+      end
+
+      def self.equality(_name, description, operation)
+        Entry.new(
+          fn: ->(a, b) { a.public_send(operation, b) },
+          arity: 2,
+          param_types: %i[any any],
+          return_type: :boolean,
+          description: description
+        )
+      end
+
+      def self.math_binary(_name, description, operation, return_type: :float)
+        Entry.new(
+          fn: lambda { |a, b|
+            a.public_send(operation, b)
+          },
+          arity: 2,
+          param_types: %i[float float],
+          return_type: return_type,
+          description: description
+        )
+      end
+
+      def self.math_unary(_name, description, operation, return_type: :float)
+        Entry.new(
+          fn: proc(&operation),
+          arity: 1,
+          param_types: [:float],
+          return_type: return_type,
+          description: description
+        )
+      end
+
+      def self.string_unary(_name, description, operation)
+        Entry.new(
+          fn: ->(str) { str.to_s.public_send(operation) },
+          arity: 1,
+          param_types: [:string],
+          return_type: :string,
+          description: description
+        )
+      end
+
+      def self.string_binary(_name, description, operation, return_type: :string)
+        Entry.new(
+          fn: ->(str, arg) { str.to_s.public_send(operation, arg.to_s) },
+          arity: 2,
+          param_types: %i[string string],
+          return_type: return_type,
+          description: description
+        )
+      end
+
+      def self.logical_variadic(_name, description, operation)
+        Entry.new(
+          fn: ->(conditions) { conditions.public_send(operation) },
+          arity: -1,
+          param_types: [:boolean],
+          return_type: :boolean,
+          description: description
+        )
+      end
+
+      def self.collection_unary(_name, description, operation, return_type: :boolean)
+        Entry.new(
+          fn: proc(&operation),
+          arity: 1,
+          param_types: [Kumi::Types.array(:any)],
+          return_type: return_type,
+          description: description
+        )
+      end
+    end
+  end
+end

data/lib/kumi/function_registry/logical_functions.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kumi
+  module FunctionRegistry
+    # Logical operations and boolean functions
+    module LogicalFunctions
+      def self.definitions
+        {
+          # Basic logical operations
+          and: FunctionBuilder::Entry.new(
+            fn: ->(*conditions) { conditions.all? },
+            arity: -1,
+            param_types: [:boolean],
+            return_type: :boolean,
+            description: "Logical AND of multiple conditions"
+          ),
+
+          or: FunctionBuilder::Entry.new(
+            fn: ->(*conditions) { conditions.any? },
+            arity: -1,
+            param_types: [:boolean],
+            return_type: :boolean,
+            description: "Logical OR of multiple conditions"
+          ),
+
+          not: FunctionBuilder::Entry.new(
+            fn: lambda(&:!),
+            arity: 1,
+            param_types: [:boolean],
+            return_type: :boolean,
+            description: "Logical NOT"
+          ),
+
+          # Collection logical operations
+          all?: FunctionBuilder.collection_unary(:all?, "Check if all elements in collection are truthy", :all?),
+          any?: FunctionBuilder.collection_unary(:any?, "Check if any element in collection is truthy", :any?),
+          none?: FunctionBuilder.collection_unary(:none?, "Check if no elements in collection are truthy", :none?)
+        }
+      end
+    end
+  end
+end

data/lib/kumi/function_registry/math_functions.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Kumi
+  module FunctionRegistry
+    # Mathematical operations
+    module MathFunctions
+      def self.definitions
+        {
+          # Basic arithmetic
+          add: FunctionBuilder.math_binary(:add, "Add two numbers", :+),
+          subtract: FunctionBuilder.math_binary(:subtract, "Subtract second number from first", :-),
+          multiply: FunctionBuilder.math_binary(:multiply, "Multiply two numbers", :*),
+          divide: FunctionBuilder.math_binary(:divide, "Divide first number by second", :/),
+          modulo: FunctionBuilder.math_binary(:modulo, "Modulo operation", :%),
+          power: FunctionBuilder.math_binary(:power, "Raise first number to power of second", :**),
+
+          # Unary operations
+          abs: FunctionBuilder.math_unary(:abs, "Absolute value", :abs),
+          floor: FunctionBuilder.math_unary(:floor, "Floor of number", :floor, return_type: :integer),
+          ceil: FunctionBuilder.math_unary(:ceil, "Ceiling of number", :ceil, return_type: :integer),
+
+          # Special operations
+          round: FunctionBuilder::Entry.new(
+            fn: ->(a, precision = 0) { a.round(precision) },
+            arity: -1,
+            param_types: [:float],
+            return_type: :float,
+            description: "Round number to specified precision"
+          ),
+
+          clamp: FunctionBuilder::Entry.new(
+            fn: ->(value, min, max) { value.clamp(min, max) },
+            arity: 3,
+            param_types: %i[float float float],
+            return_type: :float,
+            description: "Clamp value between min and max"
+          ),
+          piecewise_sum: FunctionBuilder::Entry.new(
+            # Tiered / piece‑wise accumulator ­­­­­­­­­­­­­­­­­­­­­­­­­
+            fn: lambda do |value, breaks, rates|
+              raise ArgumentError, "breaks & rates size mismatch" unless breaks.size == rates.size
+
+              acc      = 0.0
+              previous = 0.0
+              marginal = rates.last
+
+              breaks.zip(rates).each do |upper, rate|
+                if value <= upper
+                  marginal = rate
+                  acc += (value - previous) * rate
+                  break
+                else
+                  acc += (upper - previous) * rate
+                  previous = upper
+                end
+              end
+              [acc, marginal]                              # => [sum, marginal_rate]
+            end,
+            arity: 3,
+            param_types: [
+              :float,
+              Kumi::Types.array(:float),                   # breaks
+              Kumi::Types.array(:float)                    # rates
+            ],
+            return_type: Kumi::Types.array(:float),        # 2‑element [sum, marginal]
+            description: "Accumulate over tiered ranges; returns [sum, marginal_rate]"
+          )
+        }
+      end
+    end
+  end
+end

data/lib/kumi/function_registry/string_functions.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Kumi
+  module FunctionRegistry
+    # String manipulation functions
+    module StringFunctions
+      def self.definitions
+        {
+          # String transformations
+          upcase: FunctionBuilder.string_unary(:upcase, "Convert string to uppercase", :upcase),
+          downcase: FunctionBuilder.string_unary(:downcase, "Convert string to lowercase", :downcase),
+          capitalize: FunctionBuilder.string_unary(:capitalize, "Capitalize first letter of string", :capitalize),
+          strip: FunctionBuilder.string_unary(:strip, "Remove leading and trailing whitespace", :strip),
+
+          # String queries
+          string_length: FunctionBuilder::Entry.new(
+            fn: ->(str) { str.to_s.length },
+            arity: 1,
+            param_types: [:string],
+            return_type: :integer,
+            description: "Get string length"
+          ),
+
+          # Keep the original length for backward compatibility, but it will be overridden
+          length: FunctionBuilder::Entry.new(
+            fn: ->(str) { str.to_s.length },
+            arity: 1,
+            param_types: [:string],
+            return_type: :integer,
+            description: "Get string length"
+          ),
+
+          # String inclusion using different name to avoid conflict with collection include?
+          string_include?: FunctionBuilder.string_binary(:include?, "Check if string contains substring", :include?, return_type: :boolean),
+          includes?: FunctionBuilder.string_binary(:include?, "Check if string contains substring", :include?, return_type: :boolean),
+          contains?: FunctionBuilder.string_binary(:include?, "Check if string contains substring", :include?, return_type: :boolean),
+          
+          start_with?: FunctionBuilder.string_binary(:start_with?, "Check if string starts with prefix", :start_with?,
+                                                     return_type: :boolean),
+          end_with?: FunctionBuilder.string_binary(:end_with?, "Check if string ends with suffix", :end_with?, return_type: :boolean),
+
+          # String building
+          concat: FunctionBuilder::Entry.new(
+            fn: ->(*strings) { strings.join },
+            arity: -1,
+            param_types: [:string],
+            return_type: :string,
+            description: "Concatenate multiple strings"
+          )
+        }
+      end
+    end
+  end
+end

data/lib/kumi/function_registry/type_functions.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Kumi
+  module FunctionRegistry
+    # Type checking and conversion functions
+    module TypeFunctions
+      def self.definitions
+        {
+          fetch: FunctionBuilder::Entry.new(
+            fn: ->(hash, key, default = nil) { hash.fetch(key, default) },
+            arity: -1, # Variable arity (2 or 3)
+            param_types: [Kumi::Types.hash(:any, :any), :any, :any],
+            return_type: :any,
+            description: "Fetch value from hash with optional default"
+          ),
+
+          has_key?: FunctionBuilder::Entry.new(
+            fn: ->(hash, key) { hash.key?(key) },
+            arity: 2,
+            param_types: [Kumi::Types.hash(:any, :any), :any],
+            return_type: :boolean,
+            description: "Check if hash has the given key"
+          ),
+
+          keys: FunctionBuilder::Entry.new(
+            fn: lambda(&:keys),
+            arity: 1,
+            param_types: [Kumi::Types.hash(:any, :any)],
+            return_type: Kumi::Types.array(:any),
+            description: "Get all keys from hash"
+          ),
+
+          values: FunctionBuilder::Entry.new(
+            fn: lambda(&:values),
+            arity: 1,
+            param_types: [Kumi::Types.hash(:any, :any)],
+            return_type: Kumi::Types.array(:any),
+            description: "Get all values from hash"
+          ),
+          at: FunctionBuilder::Entry.new(
+            fn: ->(array, index) { array[index] },
+            arity: 2,
+            param_types: [Kumi::Types.array(:any), :integer],
+            return_type: :any,
+            description: "Get element at index from array"
+          )
+        }
+      end
+    end
+  end
+end

data/lib/kumi/function_registry.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Kumi
+  # Registry for functions that can be used in Kumi schemas
+  # This is the public interface for registering custom functions
+  module FunctionRegistry
+    class UnknownFunction < StandardError; end
+
+    # Re-export the Entry struct from FunctionBuilder for compatibility
+    Entry = FunctionBuilder::Entry
+
+    # Core operators that are always available
+    CORE_OPERATORS = %i[== > < >= <= != between?].freeze
+
+    # Build the complete function registry by combining all categories
+    CORE_OPERATIONS = {}.tap do |registry|
+      registry.merge!(ComparisonFunctions.definitions)
+      registry.merge!(MathFunctions.definitions)
+      registry.merge!(StringFunctions.definitions)
+      registry.merge!(LogicalFunctions.definitions)
+      registry.merge!(CollectionFunctions.definitions)
+      registry.merge!(ConditionalFunctions.definitions)
+      registry.merge!(TypeFunctions.definitions)
+    end.freeze
+
+    @functions = CORE_OPERATIONS.dup
+
+    class << self
+      # Public interface for registering custom functions
+      def register(name, &block)
+        raise ArgumentError, "Function #{name.inspect} already registered" if @functions.key?(name)
+
+        fn_lambda = block.is_a?(Proc) ? block : ->(*args) { yield(*args) }
+        register_with_metadata(name, fn_lambda, arity: fn_lambda.arity, param_types: [:any], return_type: :any)
+      end
+
+      # Register with custom metadata
+      def register_with_metadata(name, fn_lambda, arity:, param_types: [:any], return_type: :any, description: nil,
+                                 inverse: nil)
+        raise ArgumentError, "Function #{name.inspect} already registered" if @functions.key?(name)
+
+        @functions[name] = Entry.new(
+          fn: fn_lambda,
+          arity: arity,
+          param_types: param_types,
+          return_type: return_type,
+          description: description,
+          inverse: inverse
+        )
+      end
+
+      # Auto-register functions from modules
+      def auto_register(*modules)
+        modules.each do |mod|
+          mod.public_instance_methods(false).each do |method_name|
+            next if supported?(method_name)
+
+            register(method_name) do |*args|
+              mod.new.public_send(method_name, *args)
+            end
+          end
+        end
+      end
+
+      # Query interface
+      def supported?(name)
+        @functions.key?(name)
+      end
+
+      def operator?(name)
+        return false unless name.is_a?(Symbol)
+
+        @functions.key?(name) && CORE_OPERATORS.include?(name)
+      end
+
+      def fetch(name)
+        @functions.fetch(name) { raise UnknownFunction, "Unknown function: #{name}" }.fn
+      end
+
+      def signature(name)
+        entry = @functions.fetch(name) { raise UnknownFunction, "Unknown function: #{name}" }
+        {
+          arity: entry.arity,
+          param_types: entry.param_types,
+          return_type: entry.return_type,
+          description: entry.description
+        }
+      end
+
+      def all_functions
+        @functions.keys
+      end
+
+      # Alias for compatibility
+      def all
+        @functions.keys
+      end
+
+      # Category accessors for introspection
+      def comparison_operators
+        ComparisonFunctions.definitions.keys
+      end
+
+      def math_operations
+        MathFunctions.definitions.keys
+      end
+
+      def string_operations
+        StringFunctions.definitions.keys
+      end
+
+      def logical_operations
+        LogicalFunctions.definitions.keys
+      end
+
+      def collection_operations
+        CollectionFunctions.definitions.keys
+      end
+
+      def conditional_operations
+        ConditionalFunctions.definitions.keys
+      end
+
+      def type_operations
+        TypeFunctions.definitions.keys
+      end
+
+      # Development helpers
+      def reset!
+        @functions = CORE_OPERATIONS.dup
+      end
+
+      def freeze!
+        @functions.freeze
+      end
+    end
+  end
+end