kumi 0.0.0 → 0.0.3

data/lib/kumi/domain/validator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "range_analyzer"
+require_relative "enum_analyzer"
+require_relative "violation_formatter"
+
+module Kumi
+  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

data/lib/kumi/domain/violation_formatter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Kumi
+  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

data/lib/kumi/domain.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Domain
+  end
+end
+
+require_relative "domain/validator"

data/lib/kumi/error_reporter.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Kumi
+  # 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 has_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 #{loc}"
+        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(&:has_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(&:has_location?),
+        errors_without_location: errors.reject(&:has_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.has_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

data/lib/kumi/error_reporting.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Kumi
+  # 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: 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

data/lib/kumi/errors.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Kumi
+  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 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

data/lib/kumi/evaluation_wrapper.rb

@@ -0,0 +1,20 @@
+module Kumi
+  EvaluationWrapper = Struct.new(:ctx) do
+    def initialize(ctx)
+      @ctx = ctx
+      @__schema_cache__ = {} # memoization cache for bindings
+    end
+
+    def [](key)
+      @ctx[key]
+    end
+
+    def keys
+      @ctx.keys
+    end
+
+    def key?(key)
+      @ctx.key?(key)
+    end
+  end
+end