kumi 0.0.7 → 0.0.8

data/lib/kumi/core/domain/range_analyzer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Domain
+      class RangeAnalyzer
+        def self.analyze(range)
+          {
+            type: :range,
+            min: range.begin,
+            max: range.end,
+            exclusive_end: range.exclude_end?,
+            size: calculate_size(range),
+            sample_values: generate_samples(range),
+            boundary_values: [range.begin, range.end],
+            invalid_samples: generate_invalid_samples(range)
+          }
+        end
+
+        def self.calculate_size(range)
+          return :infinite if range.begin.nil? || range.end.nil?
+          return :large if range.end - range.begin > 1000
+
+          if integer_range?(range)
+            range.exclude_end? ? range.end - range.begin : range.end - range.begin + 1
+          else
+            :continuous
+          end
+        end
+
+        def self.generate_samples(range)
+          samples = [range.begin]
+
+          samples << calculate_midpoint(range) if numeric_range?(range)
+
+          samples << calculate_endpoint(range)
+          samples.uniq
+        end
+
+        def self.generate_invalid_samples(range)
+          invalid = []
+
+          invalid << calculate_before_start(range) if range.begin.is_a?(Numeric)
+
+          invalid << calculate_after_end(range) if range.end.is_a?(Numeric)
+
+          invalid
+        end
+
+        private_class_method def self.integer_range?(range)
+          range.begin.is_a?(Integer) && range.end.is_a?(Integer)
+        end
+
+        private_class_method def self.numeric_range?(range)
+          range.begin.is_a?(Numeric) && range.end.is_a?(Numeric)
+        end
+
+        private_class_method def self.calculate_midpoint(range)
+          mid = (range.begin + range.end) / 2.0
+          range.begin.is_a?(Integer) ? mid.round : mid
+        end
+
+        private_class_method def self.calculate_endpoint(range)
+          if range.exclude_end?
+            range.end - (range.begin.is_a?(Integer) ? 1 : 0.1)
+          else
+            range.end
+          end
+        end
+
+        private_class_method def self.calculate_before_start(range)
+          range.begin - (range.begin.is_a?(Integer) ? 1 : 0.1)
+        end
+
+        private_class_method def self.calculate_after_end(range)
+          if range.exclude_end?
+            range.end
+          else
+            range.end + (range.end.is_a?(Integer) ? 1 : 0.1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/domain/validator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Domain
+      class Validator
+        def self.validate_field(_field_name, value, domain)
+          return true if domain.nil?
+
+          case domain
+          when Range
+            domain.cover?(value)
+          when Array
+            domain.include?(value)
+          when Proc
+            domain.call(value)
+          else
+            true
+          end
+        end
+
+        def self.validate_context(context, input_meta)
+          violations = []
+
+          context.each do |field, value|
+            meta = input_meta[field]
+            next unless meta&.dig(:domain)
+
+            violations << create_violation(field, value, meta[:domain]) unless validate_field(field, value, meta[:domain])
+          end
+
+          violations
+        end
+
+        def self.extract_domain_metadata(input_meta)
+          metadata = {}
+
+          input_meta.each do |field, meta|
+            domain = meta[:domain]
+            next unless domain
+
+            metadata[field] = analyze_domain(field, domain)
+          end
+
+          metadata
+        end
+
+        def self.create_violation(field, value, domain)
+          {
+            field: field,
+            value: value,
+            domain: domain,
+            message: ViolationFormatter.format_message(field, value, domain)
+          }
+        end
+
+        def self.analyze_domain(_field, domain)
+          case domain
+          when Range
+            RangeAnalyzer.analyze(domain)
+          when Array
+            EnumAnalyzer.analyze(domain)
+          when Proc
+            {
+              type: :custom,
+              description: "Custom constraint function",
+              sample_values: [],
+              invalid_samples: []
+            }
+          else
+            {
+              type: :unknown,
+              constraint: domain,
+              sample_values: [],
+              invalid_samples: []
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/domain/violation_formatter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Domain
+      class ViolationFormatter
+        def self.format_message(field, value, domain)
+          case domain
+          when Range
+            format_range_violation(field, value, domain)
+          when Array
+            format_array_violation(field, value, domain)
+          when Proc
+            format_proc_violation(field, value)
+          else
+            format_default_violation(field, value, domain)
+          end
+        end
+
+        private_class_method def self.format_range_violation(field, value, range)
+          if range.exclude_end?
+            "Field :#{field} value #{value.inspect} is outside domain #{range.begin}...#{range.end} (exclusive)"
+          else
+            "Field :#{field} value #{value.inspect} is outside domain #{range.begin}..#{range.end}"
+          end
+        end
+
+        private_class_method def self.format_array_violation(field, value, array)
+          "Field :#{field} value #{value.inspect} is not in allowed values #{array.inspect}"
+        end
+
+        private_class_method def self.format_proc_violation(field, value)
+          "Field :#{field} value #{value.inspect} does not satisfy custom domain constraint"
+        end
+
+        private_class_method def self.format_default_violation(field, value, domain)
+          "Field :#{field} value #{value.inspect} violates domain constraint #{domain.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/error_reporter.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    # Centralized error reporting interface for consistent location handling
+    # and error message formatting across the entire codebase.
+    #
+    # This module provides a unified way to:
+    # 1. Report errors with consistent location information
+    # 2. Format error messages uniformly
+    # 3. Handle missing location data gracefully
+    # 4. Support both immediate raising and error accumulation patterns
+    module ErrorReporter
+      # Standard error structure for internal use
+      ErrorEntry = Struct.new(:location, :message, :type, :context, keyword_init: true) do
+        def to_s
+          location_str = format_location(location)
+          "#{location_str}: #{message}"
+        end
+
+        def location?
+          location && !location.is_a?(Symbol)
+        end
+
+        private
+
+        def format_location(loc)
+          case loc
+          when nil
+            "at ?"
+          when Symbol
+            "at #{loc}"
+          when Syntax::Location
+            "at #{loc.file}:#{loc.line}:#{loc.column}"
+          else
+            "at <unknown>"
+          end
+        end
+      end
+
+      module_function
+
+      # Create a standardized error entry
+      #
+      # @param message [String] The error message
+      # @param location [Syntax::Location, Symbol, nil] Location information
+      # @param type [Symbol] Optional error category (:syntax, :semantic, :type, etc.)
+      # @param context [Hash] Optional additional context
+      # @return [ErrorEntry] Structured error entry
+      def create_error(message, location: nil, type: :semantic, context: {})
+        ErrorEntry.new(
+          location: location,
+          message: message,
+          type: type,
+          context: context
+        )
+      end
+
+      # Add an error to an accumulator array (for analyzer passes)
+      #
+      # @param errors [Array] Error accumulator array
+      # @param message [String] The error message
+      # @param location [Syntax::Location, Symbol, nil] Location information
+      # @param type [Symbol] Error category
+      # @param context [Hash] Additional context
+      def add_error(errors, message, location: nil, type: :semantic, context: {})
+        entry = create_error(message, location: location, type: type, context: context)
+        errors << entry
+        entry
+      end
+
+      # Immediately raise a localized error (for parser)
+      #
+      # @param message [String] The error message
+      # @param location [Syntax::Location, Symbol, nil] Location information
+      # @param error_class [Class] Exception class to raise
+      # @param type [Symbol] Error category
+      # @param context [Hash] Additional context
+      def raise_error(message, location: nil, error_class: Errors::SemanticError, type: :semantic, context: {})
+        entry = create_error(message, location: location, type: type, context: context)
+        # Pass both the formatted message and the original location to the error constructor
+        raise error_class.new(entry.to_s, location)
+      end
+
+      # Format multiple errors into a single message
+      #
+      # @param errors [Array<ErrorEntry>] Array of error entries
+      # @return [String] Formatted error message
+      def format_errors(errors)
+        errors.map(&:to_s).join("\n")
+      end
+
+      # Group errors by type for better organization
+      #
+      # @param errors [Array<ErrorEntry>] Array of error entries
+      # @return [Hash] Errors grouped by type
+      def group_errors_by_type(errors)
+        errors.group_by(&:type)
+      end
+
+      # Check if any errors lack location information
+      #
+      # @param errors [Array<ErrorEntry>] Array of error entries
+      # @return [Array<ErrorEntry>] Errors without location info
+      def missing_location_errors(errors)
+        errors.reject(&:location?)
+      end
+
+      # Enhanced error reporting with suggestions and context
+      #
+      # @param message [String] Base error message
+      # @param location [Syntax::Location, nil] Location information
+      # @param suggestions [Array<String>] Suggested fixes
+      # @param similar_names [Array<String>] Similar names for typo suggestions
+      # @param type [Symbol] Error category
+      # @return [ErrorEntry] Enhanced error entry
+      def create_enhanced_error(message, location: nil, suggestions: [], similar_names: [], type: :semantic)
+        enhanced_message = build_enhanced_message(message, suggestions, similar_names)
+        create_error(enhanced_message, location: location, type: type, context: {
+                       suggestions: suggestions,
+                       similar_names: similar_names
+                     })
+      end
+
+      # Validate that location information is present where expected
+      #
+      # @param errors [Array<ErrorEntry>] Array of error entries
+      # @param expected_with_location [Array<Symbol>] Error types that should have locations
+      # @return [Hash] Validation report
+      def validate_error_locations(errors, expected_with_location: %i[syntax semantic type])
+        report = {
+          total_errors: errors.size,
+          errors_with_location: errors.count(&:location?),
+          errors_without_location: errors.reject(&:location?),
+          location_coverage: 0.0
+        }
+
+        report[:location_coverage] = (report[:errors_with_location].to_f / report[:total_errors]) * 100 if report[:total_errors].positive?
+
+        # Check specific types that should have locations
+        report[:problematic_errors] = errors.select do |error|
+          expected_with_location.include?(error.type) && !error.location?
+        end
+
+        report
+      end
+
+      private
+
+      def build_enhanced_message(base_message, suggestions, similar_names)
+        parts = [base_message]
+
+        parts << "Did you mean: #{similar_names.map { |name| "`#{name}`" }.join(', ')}?" unless similar_names.empty?
+
+        unless suggestions.empty?
+          parts << "Suggestions:"
+          suggestions.each { |suggestion| parts << "  - #{suggestion}" }
+        end
+
+        parts.join("\n")
+      end
+
+      module_function :build_enhanced_message
+    end
+  end
+end

data/lib/kumi/core/error_reporting.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    # Mixin module providing error reporting capabilities to classes
+    # that need to report localized errors consistently.
+    #
+    # Usage:
+    #   class MyAnalyzer
+    #     include ErrorReporting
+    #
+    #     def analyze(errors)
+    #       report_error(errors, "Something went wrong", location: some_location)
+    #       raise_localized_error("Critical error", location: some_location)
+    #     end
+    #   end
+    module ErrorReporting
+      # Report an error to an accumulator (analyzer pattern)
+      #
+      # @param errors [Array] Error accumulator array
+      # @param message [String] Error message
+      # @param location [Syntax::Location, Symbol, nil] Location info
+      # @param type [Symbol] Error category (:syntax, :semantic, :type, etc.)
+      # @param context [Hash] Additional context
+      # @return [ErrorReporter::ErrorEntry] The created error entry
+      def report_error(errors, message, location: nil, type: :semantic, context: {})
+        ErrorReporter.add_error(errors, message, location: location, type: type, context: context)
+      end
+
+      # Immediately raise a localized error (parser pattern)
+      #
+      # @param message [String] Error message
+      # @param location [Syntax::Location, Symbol, nil] Location info
+      # @param error_class [Class] Exception class to raise
+      # @param type [Symbol] Error category
+      # @param context [Hash] Additional context
+      def raise_localized_error(message, location: nil, error_class: Errors::SemanticError, type: :semantic, context: {})
+        ErrorReporter.raise_error(message, location: location, error_class: error_class, type: type, context: context)
+      end
+
+      # Report a syntax error to an accumulator
+      def report_syntax_error(errors, message, location: nil, context: {})
+        report_error(errors, message, location: location, type: :syntax, context: context)
+      end
+
+      # Report a type error to an accumulator
+      def report_type_error(errors, message, location: nil, context: {})
+        report_error(errors, message, location: location, type: :type, context: context)
+      end
+
+      # Report a semantic error to an accumulator
+      def report_semantic_error(errors, message, location: nil, context: {})
+        report_error(errors, message, location: location, type: :semantic, context: context)
+      end
+
+      # Immediately raise a syntax error
+      def raise_syntax_error(message, location: nil, context: {})
+        raise_localized_error(message, location: location, error_class: Kumi::Core::Errors::SyntaxError, type: :syntax, context: context)
+      end
+
+      # Immediately raise a type error
+      def raise_type_error(message, location: nil, context: {})
+        raise_localized_error(message, location: location, error_class: Errors::TypeError, type: :type, context: context)
+      end
+
+      # Create an enhanced error with suggestions
+      #
+      # @param errors [Array] Error accumulator array
+      # @param message [String] Base error message
+      # @param location [Syntax::Location, nil] Location info
+      # @param suggestions [Array<String>] Suggested fixes
+      # @param similar_names [Array<String>] Similar names for typos
+      # @param type [Symbol] Error category
+      def report_enhanced_error(errors, message, location: nil, suggestions: [], similar_names: [], type: :semantic)
+        entry = ErrorReporter.create_enhanced_error(
+          message,
+          location: location,
+          suggestions: suggestions,
+          similar_names: similar_names,
+          type: type
+        )
+        errors << entry
+        entry
+      end
+
+      # Get current location from caller stack (fallback method)
+      #
+      # @return [Syntax::Location] Location based on caller stack
+      def inferred_location
+        fallback = caller_locations.find(&:absolute_path)
+        return nil unless fallback
+
+        Syntax::Location.new(file: fallback.path, line: fallback.lineno, column: 0)
+      end
+    end
+  end
+end

data/lib/kumi/core/errors.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Errors
+      class Error < StandardError; end
+
+      class LocatedError < Error
+        attr_reader :location
+
+        def initialize(message, location = nil)
+          super(message)
+          @location = location
+        end
+
+        def to_s
+          if @location
+            "#{super} at #{@location.file}:#{@location.line}:#{@location.column}"
+          else
+            super
+          end
+        end
+      end
+
+      class UnknownFunction < Error; end
+
+      class SemanticError < LocatedError; end
+
+      class TypeError < SemanticError; end
+
+      class FieldMetadataError < SemanticError; end
+
+      class SyntaxError < LocatedError; end
+
+      class RuntimeError < Error; end
+
+      class DomainViolationError < Error
+        attr_reader :violations
+
+        def initialize(violations)
+          @violations = violations
+          super(format_message)
+        end
+
+        def single_violation?
+          violations.size == 1
+        end
+
+        def multiple_violations?
+          violations.size > 1
+        end
+
+        private
+
+        def format_message
+          if single_violation?
+            violations.first[:message]
+          else
+            "Multiple domain violations:\n#{violations.map { |v| "  - #{v[:message]}" }.join("\n")}"
+          end
+        end
+      end
+
+      class InputValidationError < Error
+        attr_reader :violations
+
+        def initialize(violations)
+          @violations = violations
+          super(format_message)
+        end
+
+        def single_violation?
+          violations.size == 1
+        end
+
+        def multiple_violations?
+          violations.size > 1
+        end
+
+        def type_violations
+          violations.select { |v| v[:type] == :type_violation }
+        end
+
+        def domain_violations
+          violations.select { |v| v[:type] == :domain_violation }
+        end
+
+        def type_violations?
+          type_violations.any?
+        end
+
+        def domain_violations?
+          domain_violations.any?
+        end
+
+        private
+
+        def format_message
+          if single_violation?
+            violations.first[:message]
+          else
+            message_parts = []
+
+            if type_violations?
+              message_parts << "Type violations:"
+              type_violations.each { |v| message_parts << "  - #{v[:message]}" }
+            end
+
+            if domain_violations?
+              message_parts << "Domain violations:"
+              domain_violations.each { |v| message_parts << "  - #{v[:message]}" }
+            end
+
+            message_parts.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/evaluation_wrapper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    EvaluationWrapper = Struct.new(:ctx) do
+      def initialize(ctx)
+        super
+        @__schema_cache__ = {} # memoization cache for bindings
+      end
+
+      def [](key)
+        ctx[key]
+      end
+
+      def []=(key, value)
+        ctx[key] = value
+      end
+
+      def keys
+        ctx.keys
+      end
+
+      def key?(key)
+        ctx.key?(key)
+      end
+
+      def clear
+        @__schema_cache__.clear
+      end
+
+      def clear_cache(*keys)
+        if keys.empty?
+          @__schema_cache__.clear
+        else
+          keys.each { |key| @__schema_cache__.delete(key) }
+        end
+      end
+    end
+  end
+end