jmespath-ruby 0.1.1 → 0.1.2

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

data/lib/jmespath/functions.rb

@@ -4,7 +4,31 @@ module JMESPath
   # Immutable definitions for functions available to an expression.
   class Functions
     # @api private
-    Definition = Data.define(:signature, :implementation)
+    Definition = Data.define(:signature, :implementation, :description)
+
+    # Immutable public description of a registered function.
+    class Metadata
+      # @return [String] function identifier
+      attr_reader :name
+      # @return [Array<Array<Symbol>>] accepted types for each declared argument
+      attr_reader :signature
+      # @return [String, nil] optional description
+      attr_reader :description
+
+      # @api private
+      def initialize(name, signature, variadic, description)
+        @name = name.dup.freeze
+        @signature = signature.map { |types| types.dup.freeze }.freeze
+        @variadic = variadic
+        @description = description&.dup&.freeze
+        freeze
+      end
+
+      # @return [Boolean] whether the final required argument repeats
+      def variadic?
+        @variadic
+      end
+    end
 
     # Create an empty immutable function registry.
     def initialize
@@ -19,23 +43,42 @@ module JMESPath
     # @param signature [Array<Array<Symbol>>] accepted types for each argument
     # @param variadic [Boolean] repeat the final argument type
     # @param override [Boolean] explicitly replace a definition
+    # @param description [String, nil] optional description, replaced on override
     # @yieldparam arguments [Object] evaluated arguments
     # @yieldreturn [Object] the function result
     # @raise [ArgumentError] the definition is invalid or duplicates an existing name
     # @return [Functions] the extended registry
-    def with(name, signature:, variadic: false, override: false, &block)
+    def with(name, signature:, variadic: false, override: false, description: nil, &block)
       raise ArgumentError, "A function block is required" unless block
+      raise ArgumentError, "Invalid function description" unless description.nil? || description.is_a?(String)
 
-      definition = Definition.new(Signature.new(signature, variadic: variadic), block)
+      definition = Definition.new(Signature.new(signature, variadic: variadic), block, description&.dup&.freeze)
       add(name, definition, override: override)
     end
 
     # @api private
-    def with_builtin(name, signature:, handler:, variadic: false)
-      definition = Definition.new(Signature.new(signature, variadic: variadic), handler)
+    def with_builtin(name, signature:, handler:, description:, variadic: false)
+      definition = Definition.new(Signature.new(signature, variadic: variadic), handler, description.dup.freeze)
       add(name, definition, override: false)
     end
 
+    # List names in ascending, case-sensitive lexical order.
+    # @return [Array<String>] frozen names in a frozen array
+    def names
+      @definitions.keys.sort.freeze
+    end
+
+    # Inspect a definition without executing its implementation.
+    # @param name [String] function identifier
+    # @return [Metadata, nil] immutable metadata, or nil if absent
+    def metadata(name)
+      definition = @definitions[name]
+      return unless definition
+
+      signature = definition.signature
+      Metadata.new(name, signature.arguments, signature.variadic?, definition.description)
+    end
+
     # Evaluate a registered function with checked arguments.
     # @param name [String] function identifier
     # @param arguments [Array<Object>] evaluated values
@@ -45,9 +88,19 @@ module JMESPath
     # @raise [Errors::InvalidTypeError] argument types are incompatible
     # @raise [Errors::InvalidArityError] the number of arguments is invalid
     def call(name, arguments, disable_visit_errors: false)
-      definition = @definitions.fetch(name) { raise Errors::UnknownFunctionError, "Unknown function: #{name}" }
-      invocation = disable_visit_errors ? FunctionCall.new : FunctionCall::STRICT
-      invocation.call(definition, name, arguments, disable_visit_errors: disable_visit_errors)
+      invoke(name, arguments, disable_visit_errors: disable_visit_errors)
+    end
+
+    # @api private
+    def call_with_context(name, arguments, source_range:, disable_visit_errors: nil)
+      # Preserve compiled keyword omission separately from the evaluator's explicit false.
+      unless method(:call).owner.equal?(Functions)
+        return call(name, arguments) if disable_visit_errors.nil?
+
+        return call(name, arguments, disable_visit_errors: disable_visit_errors)
+      end
+
+      invoke(name, arguments, source_range: source_range, disable_visit_errors: !!disable_visit_errors)
     end
 
     # @api private
@@ -57,6 +110,16 @@ module JMESPath
 
     private
 
+    def invoke(name, arguments, disable_visit_errors:, source_range: nil)
+      definition = @definitions.fetch(name) do
+        raise Errors::UnknownFunctionError.new("Unknown function: #{name}", function_name: name,
+                                                                            suggestions: Suggestions.for(name, names))
+      end
+      context = ValidationContext.new(name, definition.signature, source_range: source_range)
+      invocation = disable_visit_errors ? FunctionCall.new : FunctionCall::STRICT
+      invocation.call(definition, name, arguments, disable_visit_errors: disable_visit_errors, context: context)
+    end
+
     def add(name, definition, override:)
       unless name.is_a?(String) && name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
         raise ArgumentError, "Invalid function name"
@@ -71,3 +134,4 @@ module JMESPath
 end
 
 require_relative "functions/signature"
+require_relative "functions/validation_context"

data/lib/jmespath/plan.rb

@@ -104,25 +104,26 @@ module JMESPath
 
       def function(node)
         name = node.value.to_s
+        source_range = (node.start...node.finish)
         unless !@disable_visit_errors && %w[length reverse].include?(name) && node.children.length == 1 &&
                native_function?(name)
-          return function_call(name, node.children)
+          return function_call(name, node.children, source_range)
         end
 
-        string_function(name, build(node.children.fetch(0)))
+        string_function(name, build(node.children.fetch(0)), source_range)
       end
 
       def native_function?(name)
         @functions.instance_of?(Functions) && @functions.definition(name).equal?(Functions.default.definition(name))
       end
 
-      def string_function(name, child)
+      def string_function(name, child, source_range)
         lambda do |data|
           value = child.call(data)
           if value.is_a?(String)
             name == "length" ? value.length : value.reverse
           else
-            Functions.default.call(name, [value])
+            Functions.default.call_with_context(name, [value], source_range: source_range)
           end
         end
       end
@@ -132,15 +133,20 @@ module JMESPath
         ->(data) { evaluator.evaluate(node, data) }
       end
 
-      def function_call(name, nodes)
+      def function_call(name, nodes, source_range)
         arguments = nodes.map { |node| build(node) }.freeze
         functions = @functions
         if @disable_visit_errors
           lambda do |data|
-            functions.call(name, arguments.map { |argument| argument.call(data) }, disable_visit_errors: true)
+            functions.call_with_context(name, arguments.map { |argument| argument.call(data) },
+                                        source_range: source_range, disable_visit_errors: true)
           end
         else
-          ->(data) { functions.call(name, arguments.map { |argument| argument.call(data) }) }
+          lambda do |data|
+            functions.call_with_context(name, arguments.map do |argument|
+              argument.call(data)
+            end, source_range: source_range)
+          end
         end
       end
 

data/lib/jmespath/version.rb

@@ -3,5 +3,5 @@
 # Queries JSON-compatible Ruby values using JMESPath expressions.
 module JMESPath
   # The semantic version of this implementation.
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/jmespath.rb

@@ -2,6 +2,7 @@
 
 require_relative "jmespath/version"
 require_relative "jmespath/errors"
+require_relative "jmespath/diagnostic"
 require_relative "jmespath/token"
 require_relative "jmespath/lexer"
 require_relative "jmespath/expression_reference"
@@ -10,6 +11,7 @@ require_relative "jmespath/types"
 require_relative "jmespath/ast"
 require_relative "jmespath/parser"
 require_relative "jmespath/functions"
+require_relative "jmespath/functions/suggestions"
 require_relative "jmespath/evaluator"
 require_relative "jmespath/functions/scalar"
 require_relative "jmespath/functions/collections"

data/sig/jmespath.rbs

@@ -12,20 +12,48 @@ module JMESPath
     class RuntimeError < Error
     end
     class SyntaxError < Error
+      attr_reader reason: String
       attr_reader expression: String
       attr_reader position: Integer
       def initialize: (String, ?expression: String, ?position: Integer) -> void
+      def location_known?: () -> bool
       def line: () -> Integer
       def column: () -> Integer
     end
     class InvalidTypeError < RuntimeError
+      include FunctionFailure
+      attr_reader argument_position: Integer?
+      attr_reader expected_types: Array[Symbol]?
+      attr_reader actual_type: Symbol?
+      attr_reader validation_stage: Symbol?
+      def initialize: (?String?, ?argument_position: Integer?, ?expected_types: Array[Symbol]?, ?actual_type: Symbol?, ?validation_stage: Symbol?, ?function_name: String?, ?signature: Array[Array[Symbol]]?, ?variadic: bool?, ?source_range: Range[Integer]?) -> void
     end
     class InvalidValueError < RuntimeError
     end
     class InvalidArityError < RuntimeError
+      include FunctionFailure
+      attr_reader expected_arity: Integer?
+      attr_reader actual_arity: Integer?
+      def initialize: (?String?, ?expected_arity: Integer?, ?actual_arity: Integer?, ?function_name: String?, ?signature: Array[Array[Symbol]]?, ?variadic: bool?, ?source_range: Range[Integer]?) -> void
     end
     class UnknownFunctionError < RuntimeError
+      attr_reader function_name: String?
+      attr_reader suggestions: Array[String]
+      def initialize: (?String?, ?function_name: String?, ?suggestions: Array[String]) -> void
     end
+
+    module FunctionFailure
+      @variadic: bool?
+      attr_reader function_name: String?
+      attr_reader signature: Array[Array[Symbol]]?
+      attr_reader source_range: Range[Integer]?
+      def initialize: (?String?, ?function_name: String?, ?signature: Array[Array[Symbol]]?, ?variadic: bool?, ?source_range: Range[Integer]?) -> void
+      def variadic?: () -> bool?
+    end
+  end
+
+  module Diagnostic
+    def self.format: (Errors::SyntaxError) -> String
   end
 
   class Expression
@@ -35,9 +63,18 @@ module JMESPath
   end
 
   class Functions
+    class Metadata
+      attr_reader name: String
+      attr_reader signature: Array[Array[Symbol]]
+      attr_reader description: String?
+      def variadic?: () -> bool
+    end
+
     def initialize: () -> void
     def self.default: () -> Functions
-    def with: (String, signature: Array[Array[Symbol]], ?variadic: bool, ?override: bool) ?{ (*value) -> value } -> Functions
+    def with: (String, signature: Array[Array[Symbol]], ?variadic: bool, ?override: bool, ?description: String?) ?{ (*value) -> value } -> Functions
+    def names: () -> Array[String]
+    def metadata: (String) -> Metadata?
     def call: (String, Array[value], ?disable_visit_errors: bool) -> value
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jmespath-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -77,7 +77,9 @@ files:
 - lib/jmespath/ast.rb
 - lib/jmespath/cache.rb
 - lib/jmespath/cli.rb
+- lib/jmespath/cli/failure_diagnostic.rb
 - lib/jmespath/data_access.rb
+- lib/jmespath/diagnostic.rb
 - lib/jmespath/errors.rb
 - lib/jmespath/evaluation/construction.rb
 - lib/jmespath/evaluation/logic.rb
@@ -95,6 +97,8 @@ files:
 - lib/jmespath/functions/references.rb
 - lib/jmespath/functions/scalar.rb
 - lib/jmespath/functions/signature.rb
+- lib/jmespath/functions/suggestions.rb
+- lib/jmespath/functions/validation_context.rb
 - lib/jmespath/input.rb
 - lib/jmespath/lexer.rb
 - lib/jmespath/normalizer.rb