jmespath-ruby 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4b7ecb0c9ca2ab8eaaf5a69595600e5c2ba575ab4dcc11847325b0ff0379eae
-  data.tar.gz: a1717f3a5ec852e59c787dba29d6718fc234a2dd004d8da5d6010eecd7c5f359
+  metadata.gz: f9f2db0a8d51af9e3258964210daf3aa1391f97370fca0d0e5610045aad9e012
+  data.tar.gz: ec560bc1d5607e14175267d6b1bb82329a3d126686d99393c2cd6a8e7bc62585
 SHA512:
-  metadata.gz: 04e8205ad8044b27b98099646b4bc7bbc529a2d1a4c9d0bc67a4261597ecb5859421471df1105c90ffca08e620429fba5765f9e344553ad7745a5ec2f8f4eba1
-  data.tar.gz: 40391ec7795107985e8e0bdcd6902fb942814663c4a08eeba37d8d9d36552fcffeae05ee173e76ab5eec2711abe06213a6dc1ada955bf18f61caac8dabacc08f
+  metadata.gz: b8b8a4b5d663ae5b6ac54d093867c94ea420d836d44f1de5de1b781c21a984277a8211f7a6343392b335d0e451b7f3f749802e0ad910fc0af45d573fb305d2b9
+  data.tar.gz: 985c5eddf2e47265eaa74f37afd4ea73094ae84f6a87ec90ec0c0501be1af03b3c46a4d95207be57d42ec47f4b94dc2b632a1e87b5eabfa712e3ba4232753794

data/CHANGELOG.md

@@ -5,6 +5,20 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) for t
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-11-02
+
+### Added
+
+- Add `JMESPath::Diagnostic.format` for syntax reasons, source coordinates, query excerpts, and carets.
+- Expose immutable function validation data, including argument positions, expected and actual types, arity, and query byte ranges.
+- Add `Functions#names`, `Functions#metadata`, and optional custom function descriptions for immutable registry inspection.
+- Suggest similar names from the active registry for unknown functions; expose the missing name and ranked suggestions on the error.
+
+### Changed
+
+- Show located CLI syntax, function type, and arity diagnostics; describe validation and suggestions in CLI help.
+- Report malformed CLI input as `Invalid JSON input` without exposing JSON parser messages or document fragments.
+
 ## [0.1.1] - 2026-11-01
 
 ### Changed
@@ -31,6 +45,7 @@ Initial implementation for Ruby 3.3 and later.
 The compatibility guide documents intentional corrections and limits.
 Applications that depend on the gem name `jmespath` must change that dependency explicitly.
 
-[unreleased]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.1...HEAD
+[unreleased]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/svyatov/jmespath-ruby/releases/tag/v0.1.0

data/README.md

@@ -12,7 +12,7 @@ Search JSON and Ruby data with reusable queries and typed custom functions.
 In your Ruby project, add the gem with Bundler. Run `bundle init` first if the project has no Gemfile.
 
 ```sh
-bundle add jmespath-ruby --version "~> 0.1.0"
+bundle add jmespath-ruby --version "~> 0.1.2"
 ```
 
 Save this Ruby example as `example.rb`:
@@ -33,10 +33,10 @@ On MRI 4.0.9, jmespath-ruby beats each competing implementation on every workloa
 
 | Implementation | Version | Correct workloads | jmespath-ruby public-search speedup |
 | --- | --- | ---: | ---: |
-| **jmespath-ruby** | **0.1.0** | **✅ 18/18** | **Baseline** |
-| jmespath (jmespath.rb) | 1.6.2 | ✅ 18/18 | **7.97x** |
-| BurtPath | 1.1.2 | ❌ 15/18 | **9.99x** |
-| Jamespath | 0.5.1 | ❌ 13/18 | **8.07x** |
+| **jmespath-ruby** | **0.1.0** | **18/18** | **Baseline** |
+| jmespath (jmespath.rb) | 1.6.2 | 18/18 | **7.97x** |
+| BurtPath | 1.1.2 | 15/18 | **9.99x** |
+| Jamespath | 0.5.1 | 13/18 | **8.07x** |
 
 Speedups use geometric means of median times across each competitor's correctly evaluated workloads.
 Measurements use five rounds of 20,000 searches on an Apple M1 Pro.
@@ -60,11 +60,11 @@ The [comparison with existing implementations](docs/guides/comparison.md) includ
 
 | Feature | jmespath-ruby | jmespath | BurtPath | Jamespath | jmespath-jruby |
 | --- | --- | --- | --- | --- | --- |
-| Public query compilation | ✅ | ❌ | ❌ | ✅ | ✅ |
-| Documented typed function registry | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Packaged RBS signatures | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Pure Ruby implementation | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Ordinary `JMESPath.search` calls | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Public query compilation | Yes | No | No | Yes | Yes |
+| Documented typed function registry | Yes | No | No | No | No |
+| Packaged RBS signatures | Yes | No | No | No | No |
+| Pure Ruby implementation | Yes | Yes | Yes | Yes | No |
+| Ordinary `JMESPath.search` calls | Yes | Yes | Yes | No | No |
 
 `jmespath` and BurtPath support reuse through private runtime classes.
 The [full comparison](docs/guides/comparison.md) distinguishes those classes from public compilation APIs.
@@ -76,7 +76,7 @@ Replace that Gemfile entry:
 
 ```diff
 -gem "jmespath"
-+gem "jmespath-ruby", "~> 0.1.0"
++gem "jmespath-ruby", "~> 0.1.2"
 ```
 
 Run `bundle install`. Your Ruby code keeps the same entry points:
@@ -144,6 +144,25 @@ Registration returns a separate immutable registry.
 An existing function requires `override: true` to replace it.
 Every argument, including variadic arguments, is validated before the callback runs.
 
+Inspect registered functions in Ruby without executing their callbacks:
+
+```ruby
+JMESPath::Functions.default.names.include?("length") #=> true
+metadata = JMESPath::Functions.default.metadata("length")
+metadata.signature #=> [[:string, :array, :object]]
+metadata.description #=> "Character or element count."
+```
+
+Use `description:` when registering a custom function to include its description in immutable metadata.
+See [registry inspection](docs/guides/functions.md#registry-inspection) for all fields and override behavior.
+
+## Errors and diagnostics
+
+Format syntax failures in Ruby with `JMESPath::Diagnostic.format(error)` to get source coordinates, a query excerpt, and a caret.
+Function type and arity errors expose immutable validation data, including the function name, signature, argument counts or types, and available source ranges.
+Unknown-function errors expose the missing name and up to three suggestions from the active registry.
+See [errors and diagnostics](docs/guides/errors.md) for examples, nullable fields, and source-location limits.
+
 ## Command line
 
 Both `jmespath` and `jmespath.rb` accept an expression and a JSON document on standard input.
@@ -153,7 +172,12 @@ printf '%s\n' '{"user":{"name":"Ada"}}' | jmespath 'user.name'
 ```
 
 The result goes to standard output as JSON.
-Errors go to standard error with a nonzero status.
+Syntax, function type, and arity failures include source coordinates, a query excerpt, and a caret when available.
+Unknown functions suggest similar registered names.
+Malformed JSON input reports `Invalid JSON input` without including document fragments.
+These failures go to standard error and exit with status 1.
+Usage failures exit with status 2; `--help` and `--version` exit with status 0 without reading input.
+See [CLI diagnostics](docs/guides/errors.md#cli-diagnostics) for examples and fallback behavior.
 
 ## Guides
 

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/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