jmespath-ruby 0.1.2 → 0.1.3

data/lib/jmespath/explanation.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # @api private
+  class Explanation
+    OPERATORS = { eq: "==", ne: "!=", lt: "<", lte: "<=", gt: ">", gte: ">=" }.freeze
+    ROLES = {
+      group: "expression", subexpression: "step", pipe: "step", index: "input", slice: "input",
+      flatten: "input", projection: %w[input expression].freeze, value_projection: %w[input expression].freeze,
+      filter_projection: %w[input condition expression].freeze, expression_reference: "expression",
+      function: "argument", and: "operand", or: "operand", not: "operand",
+      comparison: %w[left right].freeze, multi_select_list: "element", multi_select_hash: "entry", entry: "expression"
+    }.freeze
+
+    def self.syntax_children(syntax)
+      return syntax.children unless syntax.kind == :filter_projection
+
+      [syntax.children.fetch(0), syntax.children.fetch(2), syntax.children.fetch(1)]
+    end
+
+    def self.build(source, root)
+      # @type var result: explanation
+      result = { source: source.encode(Encoding::UTF_8).freeze, root: new.node(root) }
+      result.freeze
+    end
+
+    def initialize
+      @next_id = 0
+    end
+
+    def node(syntax)
+      id = @next_id
+      @next_id += 1
+      operation = operation(syntax.kind)
+      # @type var range: [Integer, Integer]?
+      range = syntax.synthetic? ? nil : [syntax.start, syntax.finish].freeze
+      # @type var result: explanation_node
+      result = {
+        id: id, operation: operation,
+        source_range: range,
+        details: details(syntax).freeze, children: children(syntax, operation).freeze
+      }
+      result.freeze
+    end
+
+    private
+
+    def operation(kind)
+      return "comparison" if OPERATORS.key?(kind)
+      return "entry" if kind == :pair
+
+      kind.to_s.freeze
+    end
+
+    def details(syntax)
+      operator = OPERATORS[syntax.kind]
+      return { operator: operator } if operator
+
+      case syntax.kind
+      when :field, :function, :pair then { name: syntax.value.to_s.dup.freeze }
+      when :literal then { value: snapshot(syntax.value) }
+      when :index then { index: Integer(syntax.value) }
+      when :slice then slice_details(syntax.value)
+      else {}
+      end
+    end
+
+    def slice_details(value)
+      start, stop, step = Array(value)
+      { start: snapshot(start), stop: snapshot(stop), step: snapshot(step) }
+    end
+
+    def children(syntax, operation)
+      roles = ROLES.fetch(operation.to_sym, [])
+      syntax_children(syntax).each_with_index.map do |entry, index|
+        # @type var result: explanation_child
+        result = { role: roles.is_a?(String) ? roles : roles.fetch(index), node: node(entry) }
+        result.freeze
+      end
+    end
+
+    def syntax_children(syntax)
+      self.class.syntax_children(syntax)
+    end
+
+    def snapshot(value)
+      case value
+      when Hash then value.to_h { |key, entry| [key.to_s.dup.freeze, snapshot(entry)] }.freeze
+      when Array then value.map { |entry| snapshot(entry) }.freeze
+      when String then value.dup.freeze
+      else value
+      end
+    end
+  end
+end

data/lib/jmespath/expression.rb

@@ -12,7 +12,7 @@ module JMESPath
       @source = source.dup.freeze
       @root = root
       @options = options
-      @plan = Plan.build(root, options)
+      @plan = Plan.build(root, options) { |native_functions| @native_functions = native_functions }
       @max_depth = max_depth
       freeze
     end
@@ -23,18 +23,88 @@ module JMESPath
     # @param keywords [Hash] keyword evaluation options
     # @return [Object] the query result, including nil
     def search(data, options = Options::EMPTY, **keywords)
-      if options.equal?(Options::EMPTY) && keywords.empty?
-        return @plan.call(data.is_a?(Hash) ? data : Input.load(data))
-      end
+      FailureCapture.application do
+        if options.equal?(Options::EMPTY) && keywords.empty?
+          return @plan.call(data.is_a?(Hash) ? data : Input.load(data))
+        end
 
-      config = Options.new(options, keywords, default_depth: @max_depth, defaults: @options)
-      evaluate(Input.load(data), config)
+        config = Options.new(options, keywords, default_depth: @max_depth, defaults: @options)
+        evaluate(Input.load(data), config)
+      end
     end
 
     # Search input using the same options and behavior as {#search}.
     # @return [Object] the query result, including nil
     alias call search
 
+    # Search input and return its value or a library-owned failure.
+    # @param data [Object] the same input forms accepted by {#search}
+    # @param options [Hash] positional evaluation options
+    # @param keywords [Hash] keyword evaluation options
+    # @return [SearchResult] frozen outcome retaining the original value or error
+    # @raise [ArgumentError] evaluation options are invalid
+    # Application callback and conversion exceptions propagate unchanged.
+    # @example Distinguish successful null from failure
+    #   JMESPath.compile("missing").try_search({}).success? #=> true
+    #   JMESPath.compile("@").try_search(false).value #=> false
+    #   JMESPath.compile("length(@)").try_search(4).success? #=> false
+    def try_search(data, options = Options::EMPTY, **keywords)
+      fast = options.equal?(Options::EMPTY) && keywords.empty?
+      config = fast ? @options : Options.new(options, keywords, default_depth: @max_depth, defaults: @options)
+      FailureCapture.run do
+        if fast
+          @plan.call(data.is_a?(Hash) ? data : Input.load(data))
+        else
+          evaluate(Input.load(data), config)
+        end
+      end
+    end
+
+    # Search input and require a non-null result.
+    # @param data [Object] the same input forms accepted by {#search}
+    # @param options [Hash] positional evaluation options
+    # @param keywords [Hash] keyword evaluation options
+    # @return [Object] the query result, excluding nil
+    # @raise [Errors::NullResultError] evaluation returned nil
+    # @example Require a user's name
+    #   JMESPath.compile("user.name").fetch({user: {name: "Ada"}}) #=> "Ada"
+    def fetch(data, options = Options::EMPTY, **keywords)
+      value = search(data, options, **keywords)
+      raise Errors::NullResultError.new(expression: source) if value.nil?
+
+      value
+    end
+
+    # Explain query structure without evaluating input or resolving functions.
+    # @return [Hash] deeply frozen source text and logical operation tree
+    # @example Inspect a field chain
+    #   JMESPath.compile("user.name").explain[:root][:operation] #=> "subexpression"
+    def explain
+      Explanation.build(source, @root)
+    end
+
+    # Evaluate once with bounded diagnostics for null fields and omitted items.
+    # @param data [Object] the same input forms accepted by {#search}
+    # @param options [Hash] positional evaluation options
+    # @param limit [Integer] positive maximum number of retained events
+    # @param keywords [Hash] keyword evaluation options
+    # @return [Hash] frozen report with value, events, and truncated
+    # @raise [ArgumentError] limit or evaluation options are invalid
+    # @example Trace a missing field
+    #   JMESPath.compile("name").trace({})[:events].first[:type] #=> "field_null"
+    def trace(data, options = Options::EMPTY, limit: 1000, **keywords)
+      FailureCapture.application do
+        raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
+
+        fast = options.equal?(Options::EMPTY) && keywords.empty?
+        config = fast ? @options : Options.new(options, keywords, default_depth: @max_depth, defaults: @options)
+        collector = Tracing::Collector.new(root: @root, limit: limit)
+        collector.finish(trace_value(trace_input(data, fast), config, collector))
+      ensure
+        collector&.close
+      end
+    end
+
     # @api private
     def configured(options)
       return self if options.functions.equal?(Functions.default) && !options.disable_visit_errors
@@ -45,7 +115,7 @@ module JMESPath
     # @api private
     def evaluate(data, config)
       if @root.depth > config.max_depth
-        raise Errors::SyntaxError.new("Expression exceeds nesting limit", expression: source)
+        raise FailureCapture.owned(Errors::SyntaxError.new("Expression exceeds nesting limit", expression: source))
       end
 
       return @plan.call(data) if config.equal?(@options) || configured_for?(config)
@@ -56,6 +126,22 @@ module JMESPath
 
     private
 
+    def trace_input(data, fast)
+      return data if fast && data.is_a?(Hash)
+
+      Input.load(data)
+    end
+
+    def trace_value(data, config, collector)
+      if @root.depth > config.max_depth
+        raise Errors::SyntaxError.new("Expression exceeds nesting limit", expression: source)
+      end
+
+      evaluator = Tracing::Evaluator.new(config: config, collector: collector, root: @root,
+                                         planned: configured_for?(config), native_functions: @native_functions)
+      evaluator.evaluate(@root, data)
+    end
+
     def configured_for?(config)
       config.functions.equal?(@options.functions) && config.disable_visit_errors == @options.disable_visit_errors
     end

data/lib/jmespath/failure_capture.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # @api private
+  class FailureCapture
+    KEY = :jmespath_failure_capture
+    attr_reader :owned, :excluded
+
+    def initialize
+      @owned = {} # : Hash[StandardError, bool]
+               .compare_by_identity
+      @excluded = {} # : Hash[StandardError, bool]
+                  .compare_by_identity
+    end
+
+    def self.run(&)
+      previous = Thread.current[KEY]
+      context = new
+      Thread.current[KEY] = context
+      begin
+        context.result(&)
+      ensure
+        Thread.current[KEY] = previous
+      end
+    end
+
+    def result
+      SearchResult.new(value: yield, error: nil)
+    rescue Errors::Error, JSON::ParserError, IOError, SystemCallError => e
+      raise unless owned.key?(e) && !excluded.key?(e)
+
+      SearchResult.new(value: nil, error: e)
+    end
+
+    def self.owned(error)
+      context = Thread.current[KEY]
+      context.owned[error] = true if context
+      error
+    end
+
+    def self.active?
+      !Thread.current[KEY].nil?
+    end
+
+    def self.application
+      context = Thread.current[KEY]
+      return yield unless context
+
+      Thread.current[KEY] = nil
+      begin
+        yield
+      rescue StandardError => e
+        context.excluded[e] = true
+        raise
+      ensure
+        Thread.current[KEY] = context
+      end
+    end
+
+    def self.excluded?(error)
+      context = Thread.current[KEY]
+      context ? context.excluded.key?(error) : false
+    end
+  end
+end

data/lib/jmespath/functions/coercions.rb

@@ -13,25 +13,32 @@ module JMESPath
         return value if value.is_a?(Integer)
         return value if value.is_a?(Float) && value.finite?
 
-        raise type_failure(value, "Expected a finite number", [:number], context, position, stage)
+        raise FailureCapture.owned(type_failure(value, "Expected a finite number", [:number], context, position, stage))
       end
 
       def string(value, context: nil, position: nil)
-        DataAccess.string(value) || raise(type_failure(value, "Expected a string", [:string], context, position))
+        DataAccess.string(value) || raise(FailureCapture.owned(
+                                            type_failure(value, "Expected a string", [:string], context, position)
+                                          ))
       end
 
       def array(value, context: nil, position: nil)
-        DataAccess.array(value) || raise(type_failure(value, "Expected an array", [:array], context, position))
+        DataAccess.array(value) || raise(FailureCapture.owned(
+                                           type_failure(value, "Expected an array", [:array], context, position)
+                                         ))
       end
 
       def reference(value, context: nil, position: nil)
         return value if value.is_a?(ExpressionReference)
 
-        raise type_failure(value, "Expected an expression reference", [:expref], context, position)
+        raise FailureCapture.owned(type_failure(value, "Expected an expression reference", [:expref], context,
+                                                position))
       end
 
       def object(value, context: nil, position: nil)
-        DataAccess.object(value) || raise(type_failure(value, "Expected an object", [:object], context, position))
+        DataAccess.object(value) || raise(FailureCapture.owned(
+                                            type_failure(value, "Expected an object", [:object], context, position)
+                                          ))
       end
 
       private

data/lib/jmespath/functions/conversion.rb

@@ -13,11 +13,27 @@ module JMESPath
       end
 
       def to_string(value, **)
-        DataAccess.string(value) || JSON.generate(Types.normalize(value))
+        DataAccess.string(value) || generate_json(normalize_json(value))
       rescue JSON::NestingError
+        raise if FailureCapture.active?
+
         raise Errors::InvalidValueError, "Value is too deeply nested to serialize"
       end
 
+      def generate_json(value)
+        JSON.generate(value)
+      rescue JSON::NestingError => e
+        raise if FailureCapture.excluded?(e)
+
+        raise FailureCapture.owned(Errors::InvalidValueError.new("Value is too deeply nested to serialize"))
+      end
+
+      def normalize_json(value)
+        return Types.normalize(value) unless FailureCapture.active?
+
+        Normalizer.new(key: ->(key) { JSONValue.key(key) }) { |scalar| JSONValue.wrap(scalar) }.call(value)
+      end
+
       def to_number(value, **)
         return value if Types.number?(value)
 
@@ -30,3 +46,5 @@ module JMESPath
     end
   end
 end
+
+require_relative "json_value"

data/lib/jmespath/functions/function_call.rb

@@ -17,7 +17,7 @@ module JMESPath
         if implementation.is_a?(Symbol)
           send(implementation, *arguments, context: context)
         else
-          implementation.call(*arguments)
+          FailureCapture.application { implementation.call(*arguments) }
         end
       rescue Signature::TypeMismatch, Signature::ArityMismatch => e
         raise unless disable_visit_errors && e.origin.equal?(self)

data/lib/jmespath/functions/json_value.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JMESPath
+  class Functions
+    # @api private
+    class JSONValue
+      def self.wrap(value)
+        case value
+        when NilClass, TrueClass, FalseClass, Integer, Float then value
+        when String then Kernel.instance_method(:instance_of?).bind_call(value, String) ? value : new(value)
+        else new(value)
+        end
+      end
+
+      def self.key(value)
+        case value
+        when Symbol then value
+        when String then JSONKey.new(value)
+        else new(value)
+        end
+      end
+
+      def initialize(value)
+        @value = value
+      end
+
+      def to_json(state)
+        FailureCapture.application do
+          @value.respond_to?(:to_json) ? @value.to_json(state) : state.generate(String.new(@value.to_s))
+        end
+      end
+
+      def to_s
+        FailureCapture.application { @value.to_s }
+      end
+    end
+
+    # @api private
+    class JSONKey < String
+      def initialize(value)
+        super
+        @value = value
+      end
+
+      def to_s
+        FailureCapture.application { @value.to_s }
+      end
+    end
+  end
+end

data/lib/jmespath/functions/references.rb

@@ -58,18 +58,19 @@ module JMESPath
       def checked_type(value, expected, context:)
         type = Types.name(value)
         unless SORTABLE_TYPES.include?(type)
-          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
-          )
+          raise FailureCapture.owned(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 context.type_error(
-            "Expression keys must have one type",
-            position: 2, expected_types: [expected], actual_type: type,
-            origin: validation_origin, stage: :expression_result
-          )
+          raise FailureCapture.owned(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/signature.rb

@@ -44,8 +44,8 @@ module JMESPath
       def validate!(values, name, origin: nil, context: nil)
         context ||= ValidationContext.new(name, self)
         unless valid_arity?(values.length)
-          raise context.arity_error("Invalid number of arguments for #{name}", actual_arity: values.length,
-                                                                               origin: origin)
+          raise FailureCapture.owned(context.arity_error("Invalid number of arguments for #{name}",
+                                                         actual_arity: values.length, origin: origin))
         end
 
         values.each_with_index do |value, index|
@@ -60,8 +60,10 @@ module JMESPath
 
       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)
+        raise FailureCapture.owned(
+          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)

data/lib/jmespath/functions.rb

@@ -88,16 +88,20 @@ 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)
-      invoke(name, arguments, disable_visit_errors: disable_visit_errors)
+      FailureCapture.application { 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)
+        return FailureCapture.application do
+          if disable_visit_errors.nil?
+            call(name, arguments)
+          else
+            call(name, arguments, disable_visit_errors: disable_visit_errors)
+          end
+        end
       end
 
       invoke(name, arguments, source_range: source_range, disable_visit_errors: !!disable_visit_errors)
@@ -112,8 +116,10 @@ module JMESPath
 
     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))
+        raise FailureCapture.owned(
+          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

data/lib/jmespath/input.rb

@@ -8,6 +8,7 @@ module JMESPath
   module Input
     def self.load(data)
       return data if data.is_a?(Hash) || data.is_a?(Array) || data.is_a?(Struct)
+      return captured_load(data) if FailureCapture.active?
 
       case data
       when Pathname then File.open(data, "r", encoding: "UTF-8") { |file| JSON.parse(file.read) }
@@ -15,5 +16,41 @@ module JMESPath
       else data
       end
     end
+
+    def self.captured_load(data)
+      case data
+      when Pathname then load_file(data)
+      when IO, StringIO
+        text = read(data)
+        parse(FailureCapture.application { text.to_s })
+      else data
+      end
+    end
+
+    def self.load_file(data)
+      path = FailureCapture.application { File.path(data) }
+      File.open(path, "r", encoding: "UTF-8") { |file| parse(read(file)) }
+    rescue IOError, SystemCallError => e
+      raise FailureCapture.owned(e)
+    end
+
+    def self.read(data)
+      return FailureCapture.application { data.read } unless native_read?(data)
+
+      data.read
+    rescue IOError, SystemCallError => e
+      raise FailureCapture.owned(e)
+    end
+
+    def self.native_read?(data)
+      reader = Kernel.instance_method(:method).bind_call(data, :read)
+      [IO, StringIO].include?(reader.owner) && reader.source_location.nil?
+    end
+
+    def self.parse(text)
+      JSON.parse(text)
+    rescue JSON::ParserError => e
+      raise FailureCapture.owned(e)
+    end
   end
 end

data/lib/jmespath/normalizer.rb

@@ -3,9 +3,11 @@
 module JMESPath
   # @api private
   class Normalizer
-    def initialize
+    def initialize(key: nil, &scalar)
       @pending = []
       @active = {}
+      @scalar = scalar
+      @key = key
     end
 
     def call(value)
@@ -26,14 +28,27 @@ module JMESPath
 
     def visit(value, &assign)
       collection = DataAccess.array(value) || DataAccess.object(value)
-      return assign.call(DataAccess.string(value) || value) unless collection
+      return assign.call(scalar(value)) unless collection
 
+      id = activate(value)
+      @pending << -> { @active.delete(id) }
+      collection.is_a?(Array) ? array(collection, &assign) : object(collection, &assign)
+    end
+
+    def scalar(value)
+      value = DataAccess.string(value) || value
+      transform = @scalar
+      transform ? transform.call(value) : value
+    end
+
+    def activate(value)
       id = value.object_id
-      raise Errors::InvalidValueError, "Cyclic values cannot be compared or serialized" if @active[id]
+      if @active[id]
+        raise FailureCapture.owned(Errors::InvalidValueError.new("Cyclic values cannot be compared or serialized"))
+      end
 
       @active[id] = true
-      @pending << -> { @active.delete(id) }
-      collection.is_a?(Array) ? array(collection, &assign) : object(collection, &assign)
+      id
     end
 
     def array(values)
@@ -47,6 +62,8 @@ module JMESPath
       # @type var result: Hash[value, value]
       result = values.transform_values { nil }
       yield result
+      transform = @key
+      @pending << -> { result.transform_keys!(&transform) } if transform
       values.to_a.reverse_each { |key, value| enqueue(value) { |entry| result[key] = entry } }
     end
   end

data/lib/jmespath/parser/projections.rb

@@ -7,7 +7,7 @@ module JMESPath
 
     def prefix_bracket(token)
       if %i[number colon].include?(peek.type) || (peek.type == :star && @tokens.fetch(@index + 1).type == :rbracket)
-        return bracket_body(node(:current))
+        return bracket_body(node(:current, synthetic: true))
       end
 
       multi_select_list(token)
@@ -58,11 +58,11 @@ module JMESPath
     end
 
     def prefix_star(_token)
-      node(:value_projection, nil, [node(:current), projection_rhs(20)])
+      node(:value_projection, nil, [node(:current, synthetic: true), projection_rhs(20)])
     end
 
     def prefix_flatten(token)
-      infix_flatten(node(:current), token)
+      infix_flatten(node(:current, synthetic: true), token)
     end
 
     def infix_flatten(left, _token)
@@ -71,7 +71,7 @@ module JMESPath
     end
 
     def prefix_filter(token)
-      infix_filter(node(:current), token)
+      infix_filter(node(:current, synthetic: true), token)
     end
 
     def infix_filter(left, _token)
@@ -81,7 +81,7 @@ module JMESPath
     end
 
     def projection_rhs(power)
-      return node(:current) if POWER.fetch(peek.type, 0) < 10
+      return node(:current, synthetic: true) if POWER.fetch(peek.type, 0) < 10
       return expression(power) if %i[lbracket filter].include?(peek.type)
       return dot_rhs(power) if peek.type == :dot && advance