jmespath-ruby 0.1.0 → 0.1.2

data/lib/jmespath/functions/coercions.rb

@@ -6,33 +6,49 @@ module JMESPath
     module Coercions
       extend self
 
-      def number(value)
+      NATIVE_TYPES = { String => :string, NilClass => :null, TrueClass => :boolean, FalseClass => :boolean,
+                       Array => :array, Hash => :object, ExpressionReference => :expref }.freeze
+
+      def number(value, context: nil, position: nil, stage: :argument)
         return value if value.is_a?(Integer)
         return value if value.is_a?(Float) && value.finite?
 
-        raise Signature::TypeMismatch.new("Expected a finite number", origin: validation_origin)
+        raise type_failure(value, "Expected a finite number", [:number], context, position, stage)
       end
 
-      def string(value)
-        DataAccess.string(value) || raise(Signature::TypeMismatch.new("Expected a string", origin: validation_origin))
+      def string(value, context: nil, position: nil)
+        DataAccess.string(value) || raise(type_failure(value, "Expected a string", [:string], context, position))
       end
 
-      def array(value)
-        DataAccess.array(value) || raise(Signature::TypeMismatch.new("Expected an array", origin: validation_origin))
+      def array(value, context: nil, position: nil)
+        DataAccess.array(value) || raise(type_failure(value, "Expected an array", [:array], context, position))
       end
 
-      def reference(value)
+      def reference(value, context: nil, position: nil)
         return value if value.is_a?(ExpressionReference)
 
-        raise Signature::TypeMismatch.new("Expected an expression reference", origin: validation_origin)
+        raise type_failure(value, "Expected an expression reference", [:expref], context, position)
       end
 
-      def object(value)
-        DataAccess.object(value) || raise(Signature::TypeMismatch.new("Expected an object", origin: validation_origin))
+      def object(value, context: nil, position: nil)
+        DataAccess.object(value) || raise(type_failure(value, "Expected an object", [:object], context, position))
       end
 
       private
 
+      def type_failure(value, message, types, context, position, stage = :argument) # rubocop:disable Metrics/ParameterLists
+        return Signature::TypeMismatch.new(message, origin: validation_origin) unless context
+
+        context.type_error(message, position: position, expected_types: types, actual_type: native_type(value),
+                                    origin: validation_origin, stage: stage)
+      end
+
+      def native_type(value)
+        return :number if Types.number?(value)
+
+        NATIVE_TYPES.find { |klass, _type| value.is_a?(klass) }&.last || :unknown
+      end
+
       def validation_origin
         nil
       end

data/lib/jmespath/functions/collections.rb

@@ -14,60 +14,84 @@ module JMESPath
         "min_by" => [[:array], [:expref]], "max_by" => [[:array], [:expref]]
       }.freeze
 
+      DESCRIPTIONS = {
+        "avg" => "Mean, or null for an empty array.",
+        "sum" => "Sum, including zero for an empty array.",
+        "min" => "Minimum, or null for an empty array.",
+        "max" => "Maximum, or null for an empty array.",
+        "sort" => "Stable sorted array of numbers or strings.",
+        "join" => "Join strings with a separator.",
+        "keys" => "Object keys as strings.",
+        "values" => "Object values.",
+        "merge" => "Merge objects, with later values winning.",
+        "map" => "Map an expression over an array, including null results.",
+        "sort_by" => "Stable array sorted by homogeneous expression results.",
+        "min_by" => "Input element with minimum expression result, or null for an empty array.",
+        "max_by" => "Input element with maximum expression result, or null for an empty array."
+      }.freeze
+
       def self.register(registry)
         SIGNATURES.reduce(registry) do |result, (name, signature)|
-          result.with_builtin(name, signature: signature, handler: name.to_sym, variadic: name == "merge")
+          result.with_builtin(name, signature: signature, handler: name.to_sym,
+                                    description: DESCRIPTIONS.fetch(name), variadic: name == "merge")
         end
       end
 
       private
 
-      def sum(value)
-        array(value).sum { |item| number(item) }
+      def sum(value, context:)
+        element_context = context.array_element(1)
+        array(value, context: context, position: 1).sum { |item| number(item, context: element_context, position: 1) }
       end
 
-      def avg(value)
-        values = array(value)
-        number(sum(value)).fdiv(values.length) unless values.empty?
+      def avg(value, context:)
+        values = array(value, context: context, position: 1)
+        return if values.empty?
+
+        number(sum(value, context: context), context: context.array_element(1), position: 1).fdiv(values.length)
       end
 
-      def min(value)
-        array(value).min_by { |item| sort_key(item) }
+      def min(value, context:)
+        element_context = context.array_element(1)
+        array(value, context: context, position: 1).min_by { |item| sort_key(item, context: element_context) }
       end
 
-      def max(value)
-        array(value).max_by { |item| sort_key(item) }
+      def max(value, context:)
+        element_context = context.array_element(1)
+        array(value, context: context, position: 1).max_by { |item| sort_key(item, context: element_context) }
       end
 
-      def sort(value)
-        array(value).each_with_index.sort_by do |item, index|
-          [sort_key(item), index]
+      def sort(value, context:)
+        element_context = context.array_element(1)
+        array(value, context: context, position: 1).each_with_index.sort_by do |item, index|
+          [sort_key(item, context: element_context), index]
         end.map(&:first)
       end
 
-      def join(separator, value)
-        array(value).map do |item|
-          string(item)
-        end.join(string(separator))
+      def join(separator, value, context:)
+        element_context = context.array_element(2)
+        array(value, context: context, position: 2).map do |item|
+          string(item, context: element_context, position: 2)
+        end.join(string(separator, context: context, position: 1))
       end
 
-      def keys(value)
-        object(value).keys.map(&:to_s)
+      def keys(value, context:)
+        object(value, context: context, position: 1).keys.map(&:to_s)
       end
 
-      def values(value)
-        object(value).values
+      def values(value, context:)
+        object(value, context: context, position: 1).values
       end
 
-      def merge(*values)
+      def merge(*values, context:)
         # @type var result: Hash[value, value]
         result = {}
-        values.each { |value| result.merge!(object(value)) }
+        values.each_with_index { |value, index| result.merge!(object(value, context: context, position: index + 1)) }
         result
       end
 
-      def sort_key(value)
-        DataAccess.string(value) || number(value)
+      def sort_key(value, context:, position: 1, stage: :argument)
+        DataAccess.string(value) || number(value, context: context, position: position, stage: stage)
       end
     end
 

data/lib/jmespath/functions/conversion.rb

@@ -8,17 +8,17 @@ module JMESPath
 
       private
 
-      def to_array(value)
+      def to_array(value, **)
         DataAccess.array(value) || [value]
       end
 
-      def to_string(value)
+      def to_string(value, **)
         DataAccess.string(value) || JSON.generate(Types.normalize(value))
       rescue JSON::NestingError
         raise Errors::InvalidValueError, "Value is too deeply nested to serialize"
       end
 
-      def to_number(value)
+      def to_number(value, **)
         return value if Types.number?(value)
 
         text = DataAccess.string(value)&.strip

data/lib/jmespath/functions/function_call.rb

@@ -10,10 +10,15 @@ module JMESPath
 
       private :number, :string, :array, :reference, :object
 
-      def call(definition, name, arguments, disable_visit_errors: false)
-        definition.signature.validate!(arguments, name, origin: self)
+      def call(definition, name, arguments, disable_visit_errors: false, context: nil)
+        context ||= ValidationContext.new(name, definition.signature)
+        definition.signature.validate!(arguments, name, origin: self, context: context)
         implementation = definition.implementation
-        implementation.is_a?(Symbol) ? send(implementation, *arguments) : implementation.call(*arguments)
+        if implementation.is_a?(Symbol)
+          send(implementation, *arguments, context: context)
+        else
+          implementation.call(*arguments)
+        end
       rescue Signature::TypeMismatch, Signature::ArityMismatch => e
         raise unless disable_visit_errors && e.origin.equal?(self)
 

data/lib/jmespath/functions/references.rb

@@ -8,51 +8,68 @@ module JMESPath
 
       private
 
-      def map(expression, value)
-        reference = reference(expression)
-        array(value).map { |item| reference.call(item) }
+      def map(expression, value, context:)
+        reference = reference(expression, context: context, position: 1)
+        array(value, context: context, position: 2).map { |item| reference.call(item) }
       end
 
-      def sort_by(value, expression)
-        reference = reference(expression)
+      def sort_by(value, expression, context:)
+        reference = reference(expression, context: context, position: 2)
         # @type var expected: Symbol?
         expected = nil
+        # @type var result_context: ValidationContext?
+        result_context = nil
         index = 0
-        array(value).sort_by do |item|
+        array(value, context: context, position: 1).sort_by do |item|
           key = reference.call(item)
-          expected = checked_type(key, expected)
+          type = checked_type(key, expected, context: context)
+          expected = type
+          key_context = result_context || context.with_types([type])
+          result_context = key_context
           index += 1
-          [sort_key(key), index]
+          [sort_key(key, context: key_context, position: 2, stage: :expression_result), index]
         end
       end
 
-      def min_by(value, expression)
-        keyed(value, expression).min_by(&:first)&.last
+      def min_by(value, expression, context:)
+        keyed(value, expression, context: context).min_by(&:first)&.last
       end
 
-      def max_by(value, expression)
-        keyed(value, expression).max_by(&:first)&.last
+      def max_by(value, expression, context:)
+        keyed(value, expression, context: context).max_by(&:first)&.last
       end
 
-      def keyed(value, expression)
-        reference = reference(expression)
+      def keyed(value, expression, context:)
+        reference = reference(expression, context: context, position: 2)
         # @type var expected: Symbol?
         expected = nil
-        array(value).map do |item|
+        # @type var result_context: ValidationContext?
+        result_context = nil
+        array(value, context: context, position: 1).map do |item|
           key = reference.call(item)
-          expected = checked_type(key, expected)
-          [sort_key(key), item]
+          type = checked_type(key, expected, context: context)
+          expected = type
+          key_context = result_context || context.with_types([type])
+          result_context = key_context
+          [sort_key(key, context: key_context, position: 2, stage: :expression_result), item]
         end
       end
 
-      def checked_type(value, expected)
+      def checked_type(value, expected, context:)
         type = Types.name(value)
         unless SORTABLE_TYPES.include?(type)
-          raise Signature::TypeMismatch.new("Expression keys must be numbers or strings", origin: validation_origin)
+          raise context.type_error(
+            "Expression keys must be numbers or strings",
+            position: 2, expected_types: expected ? [expected] : SORTABLE_TYPES, actual_type: type,
+            origin: validation_origin, stage: :expression_result
+          )
         end
         if expected && expected != type
-          raise Signature::TypeMismatch.new("Expression keys must have one type",
-                                            origin: validation_origin)
+          raise context.type_error(
+            "Expression keys must have one type",
+            position: 2, expected_types: [expected], actual_type: type,
+            origin: validation_origin, stage: :expression_result
+          )
         end
 
         type

data/lib/jmespath/functions/scalar.rb

@@ -13,57 +13,74 @@ module JMESPath
         "to_number" => [[:any]], "not_null" => [[:any]]
       }.freeze
 
+      DESCRIPTIONS = {
+        "abs" => "Absolute value.",
+        "ceil" => "Integer rounded upward.",
+        "floor" => "Integer rounded downward.",
+        "contains" => "Test string or array membership.",
+        "ends_with" => "Test whether a string ends with a suffix.",
+        "starts_with" => "Test whether a string starts with a prefix.",
+        "length" => "Character or element count.",
+        "reverse" => "Reverse a string or array.",
+        "type" => "JMESPath type name.",
+        "to_array" => "Wrap a value in an array, preserving arrays.",
+        "to_string" => "String or compact JSON representation.",
+        "to_number" => "Number when convertible, otherwise null.",
+        "not_null" => "First non-null value."
+      }.freeze
+
       def self.register(registry)
         SIGNATURES.reduce(registry) do |result, (name, signature)|
           handler = %w[contains ends_with starts_with].include?(name) ? "#{name}?" : name
-          result.with_builtin(name, signature: signature, handler: handler.to_sym, variadic: name == "not_null")
+          result.with_builtin(name, signature: signature, handler: handler.to_sym,
+                                    description: DESCRIPTIONS.fetch(name), variadic: name == "not_null")
         end
       end
 
       private
 
-      def abs(value)
-        number(value).abs
+      def abs(value, context:)
+        number(value, context: context, position: 1).abs
       end
 
-      def ceil(value)
-        number(value).ceil
+      def ceil(value, context:)
+        number(value, context: context, position: 1).ceil
       end
 
-      def floor(value)
-        number(value).floor
+      def floor(value, context:)
+        number(value, context: context, position: 1).floor
       end
 
-      def contains?(subject, search)
+      def contains?(subject, search, context:)
         text = DataAccess.string(subject)
-        return text.include?(string(search)) if text
+        return text.include?(string(search, context: context, position: 2)) if text
 
-        array(subject).any? { |item| Types.equal?(item, search) }
+        array(subject, context: context, position: 1).any? { |item| Types.equal?(item, search) }
       end
 
-      def ends_with?(text, suffix)
-        string(text).end_with?(string(suffix))
+      def ends_with?(text, suffix, context:)
+        string(text, context: context, position: 1).end_with?(string(suffix, context: context, position: 2))
       end
 
-      def starts_with?(text, prefix)
-        string(text).start_with?(string(prefix))
+      def starts_with?(text, prefix, context:)
+        string(text, context: context, position: 1).start_with?(string(prefix, context: context, position: 2))
       end
 
-      def length(value)
-        collection = DataAccess.string(value) || DataAccess.array(value) || object(value)
+      def length(value, context:)
+        collection = DataAccess.string(value) || DataAccess.array(value) || object(value, context: context, position: 1)
         collection.length
       end
 
-      def reverse(value)
-        (DataAccess.string(value) || array(value)).reverse
+      def reverse(value, context:)
+        (DataAccess.string(value) || array(value, context: context, position: 1)).reverse
       end
 
-      def type(value)
+      def type(value, **)
         name = Types.name(value)
         name.to_s unless name == :unknown
       end
 
-      def not_null(*values)
+      def not_null(*values, **)
         values.find { |value| !value.nil? }
       end
     end

data/lib/jmespath/functions/signature.rb

@@ -10,9 +10,9 @@ module JMESPath
       module FailureOrigin
         attr_reader :origin
 
-        def initialize(message = nil, origin: nil)
+        def initialize(message = nil, origin: nil, **metadata)
           @origin = origin
-          super(message)
+          super(message, **metadata)
         end
       end
 
@@ -26,6 +26,12 @@ module JMESPath
         include FailureOrigin
       end
 
+      attr_reader :arguments
+
+      def variadic?
+        @variadic
+      end
+
       def initialize(arguments, variadic: false)
         raise ArgumentError, "Invalid function signature" unless valid_definition?(arguments)
         raise ArgumentError, "Variadic signatures require an argument" if variadic && arguments.empty?
@@ -35,21 +41,29 @@ module JMESPath
         freeze
       end
 
-      def validate!(values, name, origin: nil)
+      def validate!(values, name, origin: nil, context: nil)
+        context ||= ValidationContext.new(name, self)
         unless valid_arity?(values.length)
-          raise ArityMismatch.new("Invalid number of arguments for #{name}", origin: origin)
+          raise context.arity_error("Invalid number of arguments for #{name}", actual_arity: values.length,
+                                                                               origin: origin)
         end
 
         values.each_with_index do |value, index|
           types = @arguments.fetch(index) { @arguments.fetch(-1) }
           next if types.any? { |type| matches?(value, type) }
 
-          raise TypeMismatch.new("Invalid argument #{index + 1} for #{name}: #{Types.name(value)}", origin: origin)
+          reject_type!(value, index, types, name, origin, context)
         end
       end
 
       private
 
+      def reject_type!(value, index, types, name, origin, context) # rubocop:disable Metrics/ParameterLists
+        actual_type = Types.name(value)
+        raise context.type_error("Invalid argument #{index + 1} for #{name}: #{actual_type}",
+                                 position: index + 1, expected_types: types, actual_type: actual_type, origin: origin)
+      end
+
       def valid_definition?(arguments)
         arguments.is_a?(Array) && arguments.all? do |types|
           types.is_a?(Array) && !types.empty? && (types - TYPES).empty?

data/lib/jmespath/functions/suggestions.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module JMESPath
+  class Functions
+    # @api private
+    module Suggestions
+      class << self
+        def for(name, names)
+          names.filter_map { |candidate| ranked(name, candidate) }.sort.first(3).map(&:last)
+        end
+
+        private
+
+        def ranked(name, candidate)
+          threshold = [name.length, candidate.length].max <= 4 ? 1 : 2
+          return if (name.length - candidate.length).abs > threshold
+
+          score = distance(name, candidate)
+          [score, candidate] if score <= threshold
+        end
+
+        def distance(left, right)
+          left = left.chars
+          right = right.chars
+          previous = (0..right.length).to_a
+          older = previous
+          left.each_index do |index|
+            current = row(left, right, index, previous, older)
+            older = previous
+            previous = current
+          end
+          previous.fetch(right.length)
+        end
+
+        def row(left, right, index, previous, older)
+          current = [index + 1]
+          right.each_index do |column|
+            score = [previous.fetch(column + 1) + 1, current.fetch(column) + 1,
+                     substitution(left, right, index, column, previous)]
+            score << (older.fetch(column - 1) + 1) if swap?(left, right, index, column)
+            current << score.min
+          end
+          current
+        end
+
+        def substitution(left, right, index, column, previous)
+          previous.fetch(column) + (left[index] == right[column] ? 0 : 1)
+        end
+
+        def swap?(left, right, index, column)
+          index.positive? && column.positive? && left[index] == right[column - 1] && left[index - 1] == right[column]
+        end
+      end
+    end
+  end
+end

data/lib/jmespath/functions/validation_context.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module JMESPath
+  class Functions
+    # @api private
+    class ValidationContext
+      def initialize(name, signature, source_range: nil, expected_types: nil, actual_type: nil)
+        @name = name.dup.freeze
+        @signature = signature
+        @source_range = source_range&.dup&.freeze
+        @expected_types = expected_types&.dup&.freeze
+        @actual_type = actual_type
+        freeze
+      end
+
+      def type_error(message, position:, expected_types:, actual_type:, origin:, stage: :argument) # rubocop:disable Metrics/ParameterLists
+        Signature::TypeMismatch.new(
+          message,
+          **metadata,
+          origin: origin, argument_position: position,
+          expected_types: @expected_types || expected_types,
+          actual_type: @actual_type || actual_type, validation_stage: stage
+        )
+      end
+
+      def arity_error(message, actual_arity:, origin:)
+        Signature::ArityMismatch.new(
+          message, **metadata, origin: origin,
+                               expected_arity: @signature.arguments.length, actual_arity: actual_arity
+        )
+      end
+
+      def array_element(position)
+        with_types(@signature.arguments.fetch(position - 1), actual_type: :array)
+      end
+
+      def with_types(types, actual_type: nil)
+        self.class.new(@name, @signature, source_range: @source_range, expected_types: types, actual_type: actual_type)
+      end
+
+      private
+
+      def metadata
+        { function_name: @name, signature: @signature.arguments, variadic: @signature.variadic?,
+          source_range: @source_range }
+      end
+    end
+  end
+end