jmespath-ruby 0.1.0 → 0.1.2

data/docs/guides/errors.md

@@ -12,7 +12,50 @@ SyntaxError derives from that base; evaluation errors derive from RuntimeError.
 | `UnknownFunctionError` | Function absent from the supplied registry |
 
 SyntaxError exposes the expression, a zero-based byte position, and one-based line and character column.
-This distinguishes byte offsets from Unicode display positions.
+Character columns count Unicode code points, independently of byte offsets and terminal display widths.
+
+Use `JMESPath::Diagnostic.format(error)` to get the reason, source coordinates, query line, and caret as a string.
+The formatter returns UTF-8 without a trailing newline and does not print output or read an input document.
+For example, rescue a compilation failure and format it:
+
+```ruby
+error = begin
+  JMESPath.compile("items[?active")
+rescue JMESPath::Errors::SyntaxError => failure
+  failure
+end
+JMESPath::Diagnostic.format(error) #=> "Expected rbracket, received eof at line 1, column 14\nitems[?active\n             ^"
+```
+
+The resulting diagnostic is:
+
+```text
+Expected rbracket, received eof at line 1, column 14
+items[?active
+             ^
+```
+
+`error.reason` returns the failure reason without the byte-offset suffix in `error.message`.
+`error.location_known?` reports whether an explicit source position was supplied.
+An omitted position retains the compatibility value zero but does not identify a precise failure location.
+An explicitly supplied zero identifies the beginning of the expression, including an empty expression.
+
+For unknown locations, unusable encodings, and invalid byte offsets, the formatter returns only the reason.
+Invalid offsets include negative values, values beyond the expression, and positions within a multibyte character.
+Invalid-encoding failures and compiled-expression nesting failures without a precise location use this fallback.
+End-of-input failures place the caret after the last character, or on an empty final line after a trailing LF.
+
+The excerpt expands tabs to four-column stops and escapes other C0 controls and DEL.
+The formatted reason uses the same escaping, including visible escapes for embedded line breaks.
+The stored reason and exception message retain their original text.
+LF separates source lines; a carriage return appears as `\r`.
+Caret indentation follows the rendered prefix, including tab expansion and visible escapes.
+Each Unicode code point counts as one column.
+Combining marks, emoji, and wide characters can therefore display differently from the caret's character-based alignment.
+The formatter adds no colors and preserves exception messages.
+The CLI uses it to render syntax failures.
+
+Runtime failures use the error classes below:
 
 ```ruby
 JMESPath.search("length(@)", 7) # raises JMESPath::Errors::InvalidTypeError
@@ -25,6 +68,151 @@ Only library argument-type and arity failures are suppressed by `disable_visit_e
 Syntax, unknown-function, invalid-value, adapter, and callback failures remain visible.
 Missing fields and out-of-range indices normally return nil.
 
+## Function validation data
+
+Library-owned `InvalidTypeError` and `InvalidArityError` failures expose immutable metadata.
+Read these fields directly instead of parsing the message.
+
+| Field | Meaning |
+| --- | --- |
+| `function_name` | Identifier of the failing function |
+| `signature` | Complete declared signature as arrays of accepted type symbols |
+| `variadic?` | Whether the final declared argument repeats |
+| `source_range` | Exclusive range of zero-based byte offsets for the function call, or nil for direct calls |
+
+Use this Ruby example to inspect a type failure:
+
+```ruby
+error = begin
+  JMESPath.search("join(',', names)", {names: [1, 2]})
+rescue JMESPath::Errors::InvalidTypeError => failure
+  failure
+end
+error.function_name #=> "join"
+error.signature #=> [[:string], [:array_string]]
+error.argument_position #=> 2
+error.expected_types #=> [:array_string]
+error.actual_type #=> :array
+error.validation_stage #=> :argument
+error.source_range #=> (0...16)
+```
+
+Type errors expose `argument_position`, `expected_types`, `actual_type`, and `validation_stage`.
+Argument positions start at one, including trailing variadic arguments.
+Type symbols match function registration: `:array_number` and `:array_string` describe homogeneous arrays.
+An accepted-types array describes a union; empty arrays satisfy both homogeneous-array constraints.
+For homogeneous-array element failures, `expected_types` retains the declared array constraint and `actual_type` describes the outer array.
+Metadata includes no element values or indices.
+
+The declared `signature` describes all arguments; `expected_types` describes the specific failing check.
+For example, `contains` accepts any second argument in its signature but requires a string when searching a string.
+`validation_stage` distinguishes an `:argument` failure from an `:expression_result` failure.
+Functions such as `sort_by` require expression results to be numbers or strings of one consistent type.
+After the first valid result, `expected_types` contains only that result's type.
+An error inside a referenced function identifies that inner function and its source range.
+
+Arity errors expose `expected_arity` and `actual_arity`.
+`expected_arity` is exact unless `variadic?` is true, when it is the minimum count.
+Use this Ruby example for a direct call without source context:
+
+```ruby
+error = begin
+  JMESPath::Functions.default.call("merge", [])
+rescue JMESPath::Errors::InvalidArityError => failure
+  failure
+end
+error.function_name #=> "merge"
+error.expected_arity #=> 1
+error.actual_arity #=> 0
+error.variadic? #=> true
+error.source_range #=> nil
+```
+
+Offsets refer to the original query's bytes, including bytes before multibyte characters.
+Metadata contains no argument values or input documents.
+Diagnostics preserve adapter conversion order and counts.
+`actual_type` is `:unknown` when identifying a more specific type would require another adapter conversion.
+Manually constructed errors can have nil metadata; application exceptions retain their identity, backtrace, and original metadata.
+Custom registry overrides of `Functions#call` retain their dispatch contract and may raise errors without source context.
+
+## Unknown function data
+
+Library-owned `UnknownFunctionError` failures expose `function_name` and `suggestions`.
+The name identifies the missing function; suggestions contain up to three ranked names from the active registry.
+The name, suggestion strings, and suggestions array are immutable copies.
+Use these fields instead of parsing the error message.
+
+Use this Ruby example to inspect a misspelled function:
+
+```ruby
+error = begin
+  JMESPath.search("lenght(name)", {name: "Ada"})
+rescue JMESPath::Errors::UnknownFunctionError => failure
+  failure
+end
+error.function_name #=> "lenght"
+error.suggestions #=> ["length"]
+error.message #=> "Unknown function: lenght. Did you mean length?"
+```
+
+Messages retain `Unknown function: NAME` when no similar names exist.
+Otherwise, they append `. Did you mean NAME1, NAME2?` using the ranked suggestions.
+The CLI prints this message and exits with status 1.
+`Diagnostic.format` accepts syntax errors; unknown-function diagnostics use `error.message`.
+See [matching rules](functions.md#unknown-function-suggestions) for thresholds and ranking.
+
+Lookup remains part of evaluation and follows argument evaluation.
+Unsuppressed argument failures take precedence over a missing outer function, including callback failures when visit errors are disabled.
+Unknown-function failures are not suppressed by `disable_visit_errors`.
+Callback exceptions retain their identity, backtrace, and metadata.
+Manually constructed errors default to a nil `function_name` and empty `suggestions`; positional message construction remains supported.
+
 Invalid JSON streams raise the JSON parser's error class.
 Invalid options raise ArgumentError.
-The CLI translates expected input failures to status 1 and usage failures to status 2.
+
+## CLI diagnostics
+
+Both `jmespath` and `jmespath.rb` print expected input and query failures to stderr and exit with status 1.
+Failures before output starts leave stdout empty.
+Successful queries print one JSON result to stdout.
+Usage failures print usage to stderr and exit with status 2 without reading stdin.
+Help and version requests exit with status 0 without reading stdin.
+
+To inspect a function type failure, run this command in a shell:
+
+```sh
+printf '%s\n' '4' | jmespath 'length(@)'
+```
+
+The command exits with status 1 and prints this diagnostic to stderr:
+
+```text
+Invalid argument 1 for length: expected string, array, or object; received number at line 1, column 1
+length(@)
+^
+```
+
+Syntax failures show the reason, coordinates, query line, and caret through `Diagnostic.format`.
+Function type failures report the argument position, expected types, and received type.
+Expression-reference failures identify the rejected expression result and its argument position.
+Arity failures report the expected and received counts, with `at least` marking a variadic minimum.
+
+Type and arity carets identify the start of the failing function call, including nested calls.
+They do not identify the exact invalid argument.
+The CLI uses the formatter's character columns, tab expansion, and visible control escapes.
+Wide characters, emoji, and combining marks can display differently from character-based caret alignment.
+Missing or unusable source ranges omit coordinates, the query line, and the caret.
+Incomplete validation metadata retains the escaped exception message and any usable source location.
+Unknown-function diagnostics retain suggestions; invalid-value failures use message-only diagnostics.
+
+Malformed stdin JSON prints `Invalid JSON input` without parser messages or document fragments.
+For example, run this command in a shell:
+
+```sh
+printf '%s\n' '{"private_marker":BROKEN}' | jmespath '@'
+```
+
+The command prints `Invalid JSON input` to stderr, leaves stdout empty, and exits with status 1.
+Stream and operating-system failures retain escaped messages.
+Diagnostics add no colors, application backtraces, or input-document values.
+Unrelated application exceptions propagate.

data/docs/guides/functions.md

@@ -5,6 +5,11 @@ Expression references, written as `&expression`, defer evaluation until a functi
 
 ## Standard functions
 
+Validation failures expose the full signature, rejected type, argument position, and optional source range.
+See [function validation data](errors.md#function-validation-data) for examples and nullable fields.
+Checks inside built-ins can impose narrower constraints than their declared signatures.
+For example, `sort_by`, `min_by`, and `max_by` require expression-reference results to have one consistent number or string type.
+
 | Function | Accepted arguments | Result |
 | --- | --- | --- |
 | `abs` | number | Absolute value |
@@ -63,3 +68,67 @@ Registration returns a new frozen registry and leaves the original intact.
 Callbacks receive evaluated Ruby values and may retain selected object identity.
 Return a supported value and avoid mutating shared input.
 Callback exceptions propagate with their original object and backtrace.
+
+## Registry inspection
+
+Use `names` to list functions in the active registry, including custom registrations and overrides.
+Names use ascending, case-sensitive lexical order.
+An empty registry returns an empty array.
+
+Use these calls in Ruby to register a description and inspect the function:
+
+```ruby
+functions = JMESPath::Functions.new.with("double", signature: [[:number]], description: "Double a number.") do |value|
+  value * 2
+end
+functions.names #=> ["double"]
+metadata = functions.metadata("double")
+metadata.name #=> "double"
+metadata.signature #=> [[:number]]
+metadata.variadic? #=> false
+metadata.description #=> "Double a number."
+functions.metadata("missing") #=> nil
+JMESPath::Functions.default.metadata("length").description #=> "Character or element count."
+```
+
+`metadata(name)` returns a `JMESPath::Functions::Metadata` record, or `nil` if the function is absent.
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Function identifier |
+| `signature` | Accepted type symbols for each declared argument |
+| `variadic?` | Whether the final declared argument repeats and remains required |
+| `description` | Optional string, or `nil` when omitted |
+
+Signatures preserve unions and typed arrays such as `[:string, :null]` and `[:array_number]`.
+They describe declared arguments; runtime checks can impose further constraints, such as homogeneous results from a `sort_by` expression.
+Return types are not inferred.
+
+All built-ins have descriptions.
+Custom descriptions accept strings, including empty strings, or `nil`.
+Other values raise `ArgumentError`.
+An override replaces all metadata, so omitting its description yields `nil`.
+
+Inspection does not invoke function implementations.
+The returned arrays, records, strings, and nested signature arrays are frozen.
+Registration copies supplied strings and signature arrays without freezing the caller's objects.
+Later registrations or changes to supplied inputs cannot alter earlier snapshots.
+Shared registries support concurrent inspection; object identity across inspection calls is not guaranteed.
+
+## Unknown function suggestions
+
+An unknown function raises `UnknownFunctionError` with up to three similar names from the active registry.
+Candidates include custom functions; overrides appear once.
+Empty registries and unrelated names yield no suggestions.
+Names from other registries are excluded.
+
+Matching is case-sensitive and uses optimal string alignment distance.
+Insertion, deletion, replacement, and an adjacent letter swap each cost one edit.
+The same substring cannot be edited twice, which distinguishes this distance from unrestricted transposition matching.
+The maximum distance is one when the longer name has at most four characters, and two otherwise.
+Candidates are ranked by ascending distance, then ascending lexical order.
+
+Suggestions inspect registered names without executing candidate callbacks.
+Function lookup happens during evaluation, after the arguments have been evaluated.
+Compilation does not reject an unavailable function, and suggestions never correct or execute a query automatically.
+See [unknown function data](errors.md#unknown-function-data) for structured fields and messages.

data/docs/guides/performance.md

@@ -1,5 +1,8 @@
 # Performance
 
+For the current comparison across published Ruby implementations, see [implementation comparison](comparison.md).
+The measurements below preserve earlier revisions, private-node diagnostics, and memory experiments against jmespath.rb.
+
 Compile an expression explicitly when evaluating it against many documents.
 The convenience cache avoids parsing repeated queries, while explicit compilation also avoids cache lookup.
 

data/lib/jmespath/cli/failure_diagnostic.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    module FailureDiagnostic
+      class << self
+        def format(error, expression)
+          return JMESPath::Diagnostic.format(error) if error.is_a?(Errors::SyntaxError)
+
+          position = source_position(error, expression)
+          diagnostic = if position
+                         Errors::SyntaxError.new(message(error), expression: expression || "", position: position)
+                       else
+                         Errors::SyntaxError.new(message(error))
+                       end
+          JMESPath::Diagnostic.format(diagnostic)
+        end
+
+        private
+
+        def message(error)
+          return "Invalid JSON input" if error.is_a?(JSON::ParserError)
+
+          details = case error
+                    when Errors::InvalidTypeError then type_message(error)
+                    when Errors::InvalidArityError then arity_message(error)
+                    end
+          details || error.message
+        end
+
+        def type_message(error)
+          subject = type_subject(error)
+          types = error.expected_types
+          actual = error.actual_type
+          return unless subject && types && actual
+          return if types.empty?
+
+          "#{subject}: expected #{expected_types(types)}; received #{type_name(actual)}"
+        end
+
+        def type_subject(error)
+          name = error.function_name
+          position = error.argument_position
+          return unless name && position&.positive?
+
+          case error.validation_stage
+          when :argument then "Invalid argument #{position} for #{name}"
+          when :expression_result then "Invalid expression result for argument #{position} of #{name}"
+          end
+        end
+
+        def arity_message(error)
+          name = error.function_name
+          expected = error.expected_arity
+          actual = error.actual_arity
+          return unless name && expected && actual
+          return if expected.negative? || actual.negative?
+
+          count = arity_count(expected, error.variadic?)
+          return unless count
+
+          "Invalid number of arguments for #{name}: expected #{count}; received #{actual}"
+        end
+
+        def arity_count(expected, variadic)
+          return if variadic.nil?
+
+          variadic ? "at least #{expected}" : expected.to_s
+        end
+
+        def expected_types(types)
+          names = types.map { |type| type_name(type) }
+          return names.join(" or ") if names.length < 3
+
+          "#{names.take(names.length - 1).join(', ')}, or #{names.last}"
+        end
+
+        def type_name(type)
+          case type
+          when :array_string then "array of strings"
+          when :array_number then "array of numbers"
+          else type.to_s
+          end
+        end
+
+        def source_position(error, expression)
+          return unless expression&.valid_encoding?
+          return unless error.is_a?(Errors::InvalidTypeError) || error.is_a?(Errors::InvalidArityError)
+
+          range = error.source_range
+          range.begin if range && valid_range?(range, expression)
+        end
+
+        def valid_range?(range, expression)
+          start = range.begin
+          finish = range.end
+          return false unless start && finish && range.exclude_end?
+          return false unless valid_bounds?(start, finish, expression)
+
+          expression.byteslice(0, start).to_s.valid_encoding? && expression.byteslice(0, finish).to_s.valid_encoding?
+        end
+
+        def valid_bounds?(start, finish, expression)
+          start >= 0 && finish > start && finish <= expression.bytesize
+        end
+      end
+    end
+  end
+end

data/lib/jmespath/cli.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 require_relative "../jmespath"
+require_relative "cli/failure_diagnostic"
 
 module JMESPath
   # Runs one JMESPath query against a JSON document from standard input.
   module CLI
     USAGE = "Usage: jmespath EXPRESSION < document.json"
+    HELP = "#{USAGE}\n" \
+           "Function arguments and expression-reference results are validated; failures exit with status 1.\n" \
+           "Unknown functions suggest similar registered names.\n" \
+           "Query failures include source locations when available.".freeze
 
     # @param argv [Array<String>] command-line arguments
     # @param stdin [IO, StringIO] source JSON stream
@@ -23,13 +28,13 @@ module JMESPath
       stdout.puts(JSON.generate(JMESPath.search(argv.fetch(0), data)))
       0
     rescue JSON::ParserError, Errors::Error, IOError, SystemCallError => e
-      stderr.puts(e.message)
+      stderr.puts(FailureDiagnostic.format(e, argv.first))
       1
     end
 
     # @api private
     def self.information(argv, output)
-      output.puts(argv == ["--version"] ? "jmespath-ruby #{VERSION}" : USAGE)
+      output.puts(argv == ["--version"] ? "jmespath-ruby #{VERSION}" : HELP)
       0
     end
   end

data/lib/jmespath/diagnostic.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # Plain-text presentation of query syntax failures.
+  module Diagnostic
+    class << self
+      # Format a syntax failure without reading data or printing output.
+      # @param error [Errors::SyntaxError] the syntax failure
+      # @return [String] UTF-8 diagnostic without a trailing newline
+      # @example Format a located failure
+      #   error = JMESPath::Errors::SyntaxError.new("Bad query", expression: "$", position: 0)
+      #   JMESPath::Diagnostic.format(error) #=> "Bad query at line 1, column 1\n$\n^"
+      def format(error)
+        reason = render(error.reason.encode(Encoding::UTF_8, invalid: :replace, undef: :replace))
+        parts = source_parts(error)
+        return reason unless parts
+
+        located(reason, parts[0], parts[1])
+      end
+
+      private
+
+      def located(reason, source, prefix)
+        line = prefix.count("\n") + 1
+        line_prefix = prefix.rpartition("\n").last
+        excerpt = source.split("\n", -1).fetch(line - 1, "")
+        caret = "#{' ' * render(line_prefix).length}^"
+        "#{reason} at line #{line}, column #{line_prefix.length + 1}\n#{render(excerpt)}\n#{caret}"
+      end
+
+      def source_parts(error)
+        source = error.expression
+        return unless error.location_known? && error.position.between?(0, source.bytesize)
+
+        prefix = source.byteslice(0, error.position).to_s
+        return unless source.valid_encoding? && prefix.valid_encoding?
+
+        [source.encode(Encoding::UTF_8), prefix.encode(Encoding::UTF_8)]
+      rescue EncodingError
+        nil
+      end
+
+      def render(line)
+        column = 0
+        line.each_char.with_object(+"") do |character, result|
+          text = render_character(character, column)
+          result << text
+          column += text.length
+        end
+      end
+
+      def render_character(character, column)
+        return " " * (4 - (column % 4)) if character == "\t"
+        return character.dump[1...-1].to_s if character.ord < 32 || character.ord == 127
+
+        character
+      end
+    end
+  end
+end

data/lib/jmespath/errors.rb

@@ -10,6 +10,8 @@ module JMESPath
 
     # A malformed expression with a byte position and readable coordinates.
     class SyntaxError < Error
+      # @return [String] the reason parsing failed, without coordinates
+      attr_reader :reason
       # @return [String] the expression text
       attr_reader :expression
       # @return [Integer] zero-based byte offset
@@ -18,10 +20,17 @@ module JMESPath
       # @param message [String] the reason parsing failed
       # @param expression [String] expression text
       # @param position [Integer] zero-based byte offset
-      def initialize(message, expression: "", position: 0)
+      def initialize(message, expression: "", position: nil)
+        @reason = message.dup.freeze
         @expression = expression.dup.freeze
-        @position = position
-        super("#{message} at byte #{position}")
+        @location_known = !position.nil?
+        @position = position || 0
+        super("#{message} at byte #{@position}")
+      end
+
+      # @return [Boolean] whether the caller supplied a source position
+      def location_known?
+        @location_known
       end
 
       # @return [Integer] one-based line number
@@ -41,13 +50,116 @@ module JMESPath
       end
     end
 
+    # @api private
+    module FunctionFailure
+      # @return [String, nil] function identifier
+      attr_reader :function_name
+      # @return [Array<Array<Symbol>>, nil] complete declared signature
+      attr_reader :signature
+      # @return [Range<Integer>, nil] exclusive byte range of the function call
+      attr_reader :source_range
+
+      # @api private
+      def initialize(message = nil, function_name: nil, signature: nil, variadic: nil, source_range: nil)
+        @function_name = function_name.dup.freeze
+        @signature = signature&.map { |types| types.dup.freeze }&.freeze
+        @variadic = variadic
+        @source_range = source_range.dup.freeze
+        super(message)
+      end
+
+      # @return [Boolean, nil] whether the last declared argument repeats
+      def variadic?
+        @variadic
+      end
+    end
+
     # A function received an unsupported value type.
-    class InvalidTypeError < RuntimeError; end
+    # @example Inspect a validation failure
+    #   error = begin
+    #     JMESPath.search("length(@)", 4)
+    #   rescue JMESPath::Errors::InvalidTypeError => failure
+    #     failure
+    #   end
+    #   error.expected_types #=> [:string, :array, :object]
+    #   error.argument_position #=> 1
+    class InvalidTypeError < RuntimeError
+      include FunctionFailure
+
+      # @!attribute [r] function_name
+      #   @return [String, nil] function identifier
+      # @!attribute [r] signature
+      #   @return [Array<Array<Symbol>>, nil] complete declared signature
+      # @!attribute [r] source_range
+      #   @return [Range<Integer>, nil] exclusive byte range of the function call
+      # @!method variadic?
+      #   @return [Boolean, nil] whether the last declared argument repeats
+
+      # @return [Integer, nil] one-based actual argument position
+      attr_reader :argument_position
+      # @return [Array<Symbol>, nil] types accepted by the failing check
+      attr_reader :expected_types
+      # @return [Symbol, nil] rejected type, including :unknown
+      attr_reader :actual_type
+      # @return [Symbol, nil] :argument or :expression_result
+      attr_reader :validation_stage
+
+      # @api private
+      def initialize(message = nil, argument_position: nil, expected_types: nil, actual_type: nil, # rubocop:disable Metrics/ParameterLists
+                     validation_stage: nil, **context)
+        @argument_position = argument_position
+        @expected_types = expected_types&.dup&.freeze
+        @actual_type = actual_type
+        @validation_stage = validation_stage
+        super(message, **context)
+      end
+    end
+
     # A value is invalid for the requested operation.
     class InvalidValueError < RuntimeError; end
+
     # A function received an incorrect number of arguments.
-    class InvalidArityError < RuntimeError; end
+    class InvalidArityError < RuntimeError
+      include FunctionFailure
+
+      # @!attribute [r] function_name
+      #   @return [String, nil] function identifier
+      # @!attribute [r] signature
+      #   @return [Array<Array<Symbol>>, nil] complete declared signature
+      # @!attribute [r] source_range
+      #   @return [Range<Integer>, nil] exclusive byte range of the function call
+      # @!method variadic?
+      #   @return [Boolean, nil] whether the last declared argument repeats
+
+      # @return [Integer, nil] exact argument count, or minimum when variadic
+      attr_reader :expected_arity
+      # @return [Integer, nil] actual argument count
+      attr_reader :actual_arity
+
+      # @api private
+      def initialize(message = nil, expected_arity: nil, actual_arity: nil, **context)
+        @expected_arity = expected_arity
+        @actual_arity = actual_arity
+        super(message, **context)
+      end
+    end
+
     # A function name is not registered.
-    class UnknownFunctionError < RuntimeError; end
+    class UnknownFunctionError < RuntimeError
+      # @return [String, nil] unregistered function identifier
+      attr_reader :function_name
+      # @return [Array<String>] up to three similar names from the active registry
+      attr_reader :suggestions
+
+      # @param message [String, nil] failure message
+      # @param function_name [String, nil] unregistered function identifier
+      # @param suggestions [Array<String>] ranked registered names
+      def initialize(message = nil, function_name: nil, suggestions: [])
+        @function_name = function_name&.dup&.freeze
+        @suggestions = suggestions.map { |name| name.dup.freeze }.freeze
+        message = "#{message}. Did you mean #{@suggestions.join(', ')}?" unless @suggestions.empty?
+        super(message)
+      end
+    end
   end
 end

data/lib/jmespath/evaluation/scalars.rb

@@ -43,7 +43,8 @@ module JMESPath
 
     def function(node, data)
       arguments = node.children.map { |child| evaluate(child, data) }
-      @functions.call(node.value.to_s, arguments, disable_visit_errors: @disable_visit_errors)
+      @functions.call_with_context(node.value.to_s, arguments, source_range: node.start...node.finish,
+                                                               disable_visit_errors: @disable_visit_errors)
     end
   end
 end