jmespath-ruby 0.1.2 → 0.1.3

data/lib/jmespath/parser.rb

@@ -65,10 +65,10 @@ module JMESPath
       node(kind, nil, children)
     end
 
-    def node(kind, value = nil, children = [], start: nil)
+    def node(kind, value = nil, children = [], start: nil, synthetic: false)
       result = AST::Node.new(
         kind: kind, value: value, children: children,
-        start: start || children.first&.start || previous.start, finish: previous.finish
+        start: start || children.first&.start || previous.start, finish: previous.finish, synthetic: synthetic
       )
       syntax!("Expression exceeds nesting limit") if result.depth > @max_depth
       result

data/lib/jmespath/plan.rb

@@ -12,12 +12,20 @@ module JMESPath
     }.freeze
 
     def self.build(node, options = Options::DEFAULT)
-      Builder.new(options).build(node)
+      builder = Builder.new(options)
+      operation = builder.build(node)
+      native_functions = builder.native_functions&.freeze
+      builder.freeze
+      yield native_functions
+      operation
     end
 
     # @api private
     class Builder
+      attr_reader :native_functions
+
       def initialize(options)
+        @native_functions = nil
         @functions = options.functions
         @disable_visit_errors = options.disable_visit_errors
         @evaluator = if @functions.equal?(Functions.default) && !@disable_visit_errors
@@ -25,7 +33,6 @@ module JMESPath
                      else
                        Evaluator.new(functions: @functions, disable_visit_errors: @disable_visit_errors)
                      end
-        freeze
       end
 
       def build(node)
@@ -110,6 +117,14 @@ module JMESPath
           return function_call(name, node.children, source_range)
         end
 
+        build_native_string(node, name, source_range)
+      end
+
+      def build_native_string(node, name, source_range)
+        # @type var native_functions: Array[AST::Node]
+        native_functions = @native_functions || []
+        native_functions << node
+        @native_functions = native_functions
         string_function(name, build(node.children.fetch(0)), source_range)
       end
 

data/lib/jmespath/search_result.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # Immutable outcome of an expression search, retaining the original value or error.
+  class SearchResult
+    # @return [Object] the successful value, or nil on failure
+    attr_reader :value
+    # @return [StandardError, nil] the original library-owned failure
+    attr_reader :error
+
+    # @api private
+    def initialize(value:, error:)
+      @value = value
+      @error = error
+      freeze
+    end
+
+    # @return [Boolean] whether evaluation succeeded, including a null result
+    def success?
+      error.nil?
+    end
+  end
+end

data/lib/jmespath/syntax_diagnostic.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # Immutable syntax failure data returned by {JMESPath.validate}.
+  class SyntaxDiagnostic
+    # @return [String] reason without coordinates
+    attr_reader :reason
+    # @return [String] expression stored by the parser
+    attr_reader :expression
+    # @return [Integer, nil] zero-based byte offset, or nil for unknown locations
+    attr_reader :position
+    # @return [Integer, nil] one-based line, or nil for unknown locations
+    attr_reader :line
+    # @return [Integer, nil] one-based Unicode character column, or nil for unknown locations
+    attr_reader :column
+
+    # @api private
+    def initialize(error)
+      @reason = error.reason.dup.freeze
+      @expression = error.expression.dup.freeze
+      @position = error.position if error.location_known?
+      @line = error.line if error.location_known?
+      @column = error.column if error.location_known?
+      freeze
+    end
+
+    # @return [Boolean] whether parsing reported a source location
+    def location_known?
+      !position.nil?
+    end
+  end
+end

data/lib/jmespath/tracing/collector.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # @api private
+  module Tracing
+    # @api private
+    class Collector
+      def initialize(root:, limit:)
+        @ids = {} # : Hash[AST::Node, Integer]
+               .compare_by_identity
+        index(root)
+        @limit = limit
+        @events = []
+        @contexts = {}
+        @references = {}
+        @truncated = false
+        @closed = false
+        @mutex = Mutex.new
+      end
+
+      def operation_id(node)
+        @ids.fetch(node)
+      end
+
+      def within(node, index)
+        thread = Thread.current
+        stack = @mutex.synchronize do
+          unless @closed
+            context = (@contexts[thread] ||= [])
+            # @type var frame: trace_context
+            frame = { operation_id: operation_id(node), index: index }.freeze
+            context << frame
+            context
+          end
+        end
+        return yield unless stack
+
+        begin
+          yield
+        ensure
+          @mutex.synchronize do
+            stack.pop
+            @contexts.delete(thread) if stack.empty?
+          end
+        end
+      end
+
+      def reference(node, &)
+        index = @mutex.synchronize do
+          unless @closed
+            id = operation_id(node)
+            count = @references.fetch(id, 0)
+            @references[id] = count + 1
+            count
+          end
+        end
+        return yield if index.nil?
+
+        within(node, index, &)
+      end
+
+      def emit(type, node, details = {})
+        @mutex.synchronize do
+          return if @closed
+
+          if @events.length >= @limit
+            @truncated = true
+            return
+          end
+          # @type var event: trace_event
+          event = {
+            type: type.dup.freeze, operation_id: operation_id(node),
+            context: @contexts.fetch(Thread.current, []).dup.freeze,
+            details: details.transform_values { |value| value.dup.freeze }.freeze
+          }.freeze
+          @events << event
+        end
+      end
+
+      def finish(value)
+        @mutex.synchronize do
+          # @type var report: trace_report
+          report = { value: value, events: @events.freeze, truncated: @truncated }.freeze
+          clear
+          report
+        end
+      end
+
+      def close
+        @mutex.synchronize { clear }
+      end
+
+      private
+
+      def index(node)
+        @ids[node] = @ids.length
+        Explanation.syntax_children(node).each { |child| index(child) }
+      end
+
+      def clear
+        @closed = true
+        @ids.clear
+        @contexts.clear
+        @references.clear
+        @events = []
+      end
+    end
+  end
+end

data/lib/jmespath/tracing/evaluator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module Tracing
+    # @api private
+    class Evaluator < JMESPath::Evaluator
+      def initialize(config:, collector:, root:, planned:, native_functions:)
+        @collector = collector
+        @native_functions = planned ? native_functions : nil
+        @compiled_functions = {} # : Hash[AST::Node, bool]
+                              .compare_by_identity
+        index_plan(root) if planned
+        @compiled_functions.freeze
+        super(functions: config.functions, disable_visit_errors: config.disable_visit_errors)
+      end
+
+      def evaluate(node, data)
+        return super unless node.kind == :field
+
+        result, reason = FieldLookup.call(data, node.value.to_s)
+        @collector.emit("field_null", node, name: node.value.to_s, reason: reason) if reason
+        result
+      end
+
+      private
+
+      def index_plan(node)
+        return unless Plan::BUILDERS.key?(node.kind)
+
+        @compiled_functions[node] = true if node.kind == :function
+        node.children.each { |child| index_plan(child) }
+      end
+
+      def function(node, data)
+        return super unless @compiled_functions.key?(node) && !@disable_visit_errors
+
+        arguments = node.children.map { |child| evaluate(child, data) }
+        return native_string(node, arguments.fetch(0)) if @native_functions&.include?(node)
+
+        @functions.call_with_context(node.value.to_s, arguments, source_range: node.start...node.finish)
+      end
+
+      def native_string(node, value)
+        if value.is_a?(String)
+          node.value == "length" ? value.length : value.reverse
+        else
+          Functions.default.call_with_context(node.value.to_s, [value], source_range: node.start...node.finish)
+        end
+      end
+
+      def reference(node, _data)
+        ExpressionReference.new do |value|
+          @collector.reference(node) { evaluate(node.children.fetch(0), value) }
+        end
+      end
+
+      def project(node, values)
+        return nil unless values
+
+        index = -1
+        child = node.children.fetch(1)
+        result = values.map do |value|
+          index += 1
+          project_item(node, child, value, index)
+        end
+        result.compact!
+        result
+      end
+
+      def project_item(node, child, value, index)
+        @collector.within(node, index) do
+          result = evaluate(child, value)
+          @collector.emit("projection_omission", node) if nil.equal?(result)
+          result
+        end
+      end
+
+      def filter_projection(node, data)
+        values = DataAccess.array(evaluate(node.children.fetch(0), data))
+        indexes = [] # : Array[Integer]
+        index = -1
+        selected = values&.reject do |value|
+          index += 1
+          rejected = filter_rejected?(node, value, index)
+          indexes << index unless rejected
+          rejected
+        end
+        return nil unless selected
+
+        project_selected(node, selected, indexes)
+      end
+
+      def filter_rejected?(node, value, index)
+        @collector.within(node, index) do
+          rejected = Types.falsey?(evaluate(node.children.fetch(2), value))
+          @collector.emit("filter_exclusion", node) if rejected
+          rejected
+        end
+      end
+
+      def project_selected(node, selected, indexes)
+        position = -1
+        child = node.children.fetch(1)
+        selected.map! do |value|
+          position += 1
+          project_item(node, child, value, indexes.fetch(position))
+        end
+        selected.compact!
+        selected
+      end
+    end
+  end
+end

data/lib/jmespath/tracing/field_lookup.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module Tracing
+    # @api private
+    module FieldLookup
+      def self.call(value, name)
+        mapping = value.is_a?(Hash) ? value : DataAccess.object(value)
+        return [nil, "non_object"] unless mapping
+
+        initial = mapping[name]
+        return [initial, nil] unless initial.nil?
+
+        result, reason = fallback(mapping, name)
+        return [result, nil] unless nil.equal?(result)
+
+        [nil, classify(mapping, initial, reason)]
+      end
+
+      def self.fallback(mapping, name)
+        present = false
+        mapping.each_key do |key|
+          return [mapping[key], "null"] if key.is_a?(Symbol) && key.name == name
+
+          # Core checks avoid invoking custom key predicates or equality methods.
+          # rubocop:disable-next Style/CaseEquality
+          present = true if String === key && String.instance_method(:==).bind_call(key, name)
+        end
+        [nil, present ? "null" : "missing"]
+      end
+
+      def self.classify(mapping, initial, reason)
+        nil.equal?(initial) && native_lookup?(mapping) ? reason : "unknown"
+      end
+
+      def self.native_lookup?(mapping)
+        # A Struct can return a duck mapping; avoid invoking its own type predicate.
+        # rubocop:disable-next Style/CaseEquality
+        return false unless Hash === mapping
+
+        return false if Hash.instance_method(:compare_by_identity?).bind_call(mapping)
+
+        %i[[] each_key].all? do |name|
+          Object.instance_method(:method).bind_call(mapping, name).owner == Hash
+        end
+      end
+    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.2"
+  VERSION = "0.1.3"
 end

data/lib/jmespath.rb

@@ -2,6 +2,8 @@
 
 require_relative "jmespath/version"
 require_relative "jmespath/errors"
+require_relative "jmespath/failure_capture"
+require_relative "jmespath/syntax_diagnostic"
 require_relative "jmespath/diagnostic"
 require_relative "jmespath/token"
 require_relative "jmespath/lexer"
@@ -20,7 +22,12 @@ require_relative "jmespath/options"
 require_relative "jmespath/input"
 require_relative "jmespath/cache"
 require_relative "jmespath/plan"
+require_relative "jmespath/explanation"
+require_relative "jmespath/search_result"
 require_relative "jmespath/expression"
+require_relative "jmespath/tracing/collector"
+require_relative "jmespath/tracing/field_lookup"
+require_relative "jmespath/tracing/evaluator"
 
 # Search JSON-compatible Ruby values with JMESPath expressions.
 module JMESPath
@@ -44,15 +51,17 @@ module JMESPath
     #   JMESPath.search("items[*].name", {items: [{name: "Ada"}]}) #=> ["Ada"]
     # @return [Object] the query result, including nil
     def search(expression, data, options = Options::EMPTY, **keywords)
-      config = if options.equal?(Options::EMPTY) && keywords.empty?
-                 Options::DEFAULT
-               else
-                 Options.new(options, keywords)
-               end
-      raise ArgumentError, "Expression must be a String" unless expression.is_a?(String)
+      FailureCapture.application do
+        config = if options.equal?(Options::EMPTY) && keywords.empty?
+                   Options::DEFAULT
+                 else
+                   Options.new(options, keywords)
+                 end
+        raise ArgumentError, "Expression must be a String" unless expression.is_a?(String)
 
-      compiled = compile_syntax(expression, config.cache_expressions, config.max_depth)
-      compiled.evaluate(Input.load(data), config)
+        compiled = compile_syntax(expression, config.cache_expressions, config.max_depth)
+        compiled.evaluate(Input.load(data), config)
+      end
     end
 
     # Parse an expression for repeated searches.
@@ -75,6 +84,32 @@ module JMESPath
       config.equal?(Options::DEFAULT) ? compiled : compiled.configured(config)
     end
 
+    # Validate syntax without evaluating data or checking function availability.
+    # @param expression [String] query text
+    # @param max_depth [Integer] maximum nesting from 1 through 128
+    # @raise [ArgumentError] expression type or depth is invalid
+    # @example Validate syntax without an input document
+    #   JMESPath.validate("items[*].name") #=> []
+    #   failure = JMESPath.validate("items[?active").fetch(0)
+    #   failure.reason #=> "Expected rbracket, received eof"
+    #   failure.position #=> 13
+    #   failure.line #=> 1
+    #   failure.column #=> 14
+    # @return [Array<SyntaxDiagnostic>] frozen array containing zero or one immutable diagnostic
+    def validate(expression, max_depth: 128)
+      raise ArgumentError, "Expression must be a String" unless expression.is_a?(String)
+      unless max_depth.is_a?(Integer) && (1..128).cover?(max_depth)
+        raise ArgumentError, "max_depth must be an integer from 1 through 128"
+      end
+
+      Parser.new(expression, max_depth: max_depth).parse
+      # @type var diagnostics: Array[SyntaxDiagnostic]
+      diagnostics = []
+      diagnostics.freeze
+    rescue Errors::SyntaxError => e
+      [SyntaxDiagnostic.new(e)].freeze
+    end
+
     private
 
     def compile_syntax(expression, cache, depth)

data/sig/jmespath.rbs

@@ -1,16 +1,44 @@
 module JMESPath
+  type trace_context = { operation_id: Integer, index: Integer }
+  type trace_event = { type: String, operation_id: Integer, context: Array[trace_context], details: Hash[Symbol, json] }
+  type trace_report = { value: value, events: Array[trace_event], truncated: bool }
   VERSION: String
   type value = Object?
   type json = nil | bool | Integer | Float | String | Array[json] | Hash[String, json]
+  type explanation_details = Hash[Symbol, json]
+  type explanation_child = { role: String, node: explanation_node }
+  type explanation_node = {
+    id: Integer,
+    operation: String,
+    source_range: [Integer, Integer]?,
+    details: explanation_details,
+    children: Array[explanation_child]
+  }
+  type explanation = { source: String, root: explanation_node }
 
   def self.search: (String, value, ?Hash[Symbol, value], **value) -> value
   def self.compile: (String, ?cache_expressions: bool, ?max_depth: Integer, ?functions: Functions, ?disable_visit_errors: bool) -> Expression
+  def self.validate: (String, ?max_depth: Integer) -> Array[SyntaxDiagnostic]
+
+  class SyntaxDiagnostic
+    attr_reader reason: String
+    attr_reader expression: String
+    attr_reader position: Integer?
+    attr_reader line: Integer?
+    attr_reader column: Integer?
+    def initialize: (Errors::SyntaxError) -> void
+    def location_known?: () -> bool
+  end
 
   module Errors
     class Error < StandardError
     end
     class RuntimeError < Error
     end
+    class NullResultError < RuntimeError
+      attr_reader expression: String
+      def initialize: (expression: String) -> void
+    end
     class SyntaxError < Error
       attr_reader reason: String
       attr_reader expression: String
@@ -53,13 +81,23 @@ module JMESPath
   end
 
   module Diagnostic
-    def self.format: (Errors::SyntaxError) -> String
+    def self.format: (Errors::SyntaxError | SyntaxDiagnostic) -> String
+  end
+
+  class SearchResult
+    attr_reader value: value
+    attr_reader error: StandardError?
+    def success?: () -> bool
   end
 
   class Expression
     attr_reader source: String
     def search: (value, ?Hash[Symbol, value], **value) -> value
+    def try_search: (value, ?Hash[Symbol, value], **value) -> SearchResult
+    def fetch: (value, ?Hash[Symbol, value], **value) -> Object
+    def trace: (value, ?Hash[Symbol, value], ?limit: Integer, **value) -> trace_report
     alias call search
+    def explain: () -> explanation
   end
 
   class Functions
@@ -82,11 +120,17 @@ module JMESPath
   interface _Reader
     def read: () -> String?
   end
-  # Output stream protocol used by CLI.run.
+  # Input stream protocol for CLI.run in JSON Lines and interactive modes.
+  # Interactive readers may expose tty?; only terminal input receives prompts.
+  interface _LineReader
+    def gets: () -> String?
+  end
+  # Output stream protocol used by CLI.run. Interactive mode uses optional flush.
+  # Terminal prompts require print and flush on the diagnostic stream.
   interface _Writer
     def puts: (String) -> void
   end
   module CLI
-    def self.run: (Array[String], ?stdin: _Reader, ?stdout: _Writer, ?stderr: _Writer) -> Integer
+    def self.run: (Array[String], ?stdin: _Reader | _LineReader, ?stdout: _Writer, ?stderr: _Writer) -> Integer
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jmespath-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -64,9 +64,12 @@ files:
 - README.md
 - SECURITY.md
 - VERSIONING.md
+- completions/_jmespath
+- completions/jmespath.bash
 - docs/guides/comparison.md
 - docs/guides/compatibility.md
 - docs/guides/compilation.md
+- docs/guides/completion.md
 - docs/guides/errors.md
 - docs/guides/functions.md
 - docs/guides/performance.md
@@ -77,7 +80,12 @@ files:
 - lib/jmespath/ast.rb
 - lib/jmespath/cache.rb
 - lib/jmespath/cli.rb
+- lib/jmespath/cli/argument_parser.rb
+- lib/jmespath/cli/arguments.rb
 - lib/jmespath/cli/failure_diagnostic.rb
+- lib/jmespath/cli/function_listing.rb
+- lib/jmespath/cli/help.rb
+- lib/jmespath/cli/interactive_session.rb
 - lib/jmespath/data_access.rb
 - lib/jmespath/diagnostic.rb
 - lib/jmespath/errors.rb
@@ -87,13 +95,16 @@ files:
 - lib/jmespath/evaluation/scalars.rb
 - lib/jmespath/evaluation/slices.rb
 - lib/jmespath/evaluator.rb
+- lib/jmespath/explanation.rb
 - lib/jmespath/expression.rb
 - lib/jmespath/expression_reference.rb
+- lib/jmespath/failure_capture.rb
 - lib/jmespath/functions.rb
 - lib/jmespath/functions/coercions.rb
 - lib/jmespath/functions/collections.rb
 - lib/jmespath/functions/conversion.rb
 - lib/jmespath/functions/function_call.rb
+- lib/jmespath/functions/json_value.rb
 - lib/jmespath/functions/references.rb
 - lib/jmespath/functions/scalar.rb
 - lib/jmespath/functions/signature.rb
@@ -107,7 +118,12 @@ files:
 - lib/jmespath/parser/expressions.rb
 - lib/jmespath/parser/projections.rb
 - lib/jmespath/plan.rb
+- lib/jmespath/search_result.rb
+- lib/jmespath/syntax_diagnostic.rb
 - lib/jmespath/token.rb
+- lib/jmespath/tracing/collector.rb
+- lib/jmespath/tracing/evaluator.rb
+- lib/jmespath/tracing/field_lookup.rb
 - lib/jmespath/types.rb
 - lib/jmespath/version.rb
 - sig/jmespath.rbs