jmespath-ruby 0.1.3 → 1.0.0

data/docs/guides/command-line.md

@@ -0,0 +1,233 @@
+# Command-line reference
+
+## Quick start
+
+
+Both `jmespath` and `jmespath.rb` accept an expression and a JSON document from stdin or `--file PATH`.
+Use `--query-file PATH` to read the expression from a UTF-8 file.
+See [shell completion](completion.md) for manual Bash and Zsh setup for both executable names.
+
+```sh
+printf '%s\n' '{"user":{"name":"Ada"}}' | jmespath 'user.name'
+jmespath --file document.json 'user.name'
+jmespath 'user.name' --file document.json
+jmespath --file 'my document.json' 'user.name'
+jmespath --file=--document.json 'user.name'
+jmespath --file ./--document.json 'user.name'
+jmespath --file - 'user.name'
+jmespath --file document.json -- 'user.name'
+jmespath --query-file query.jmespath < document.json
+jmespath --query-file query.jmespath --file document.json
+jmespath --pretty 'items' < document.json
+jmespath --raw-output 'user.name' < document.json
+```
+
+## Input
+
+Document files are read as UTF-8 and closed after parsing, before query evaluation in single-document mode.
+File input leaves stdin unused; omitting `--file` selects stdin.
+Paths are literal: `--file -` reads a file named `-`.
+Quote filenames with spaces; use the equals form or `./` prefix for option-like filenames.
+Options can precede or follow the expression; `--` ends option parsing.
+Supply exactly one query source: a positional expression or `--query-file PATH`.
+Repeated file options, unknown options, missing values, and conflicting or absent query sources are usage failures.
+Version flags must appear alone; help accepts one optional topic, as described under [Help](#help).
+
+Query files retain all source text, including trailing newlines and Unicode diagnostic coordinates.
+An empty query file produces a syntax failure.
+Query files close after reading, before document input is accessed.
+Missing or unreadable query files leave document input untouched.
+In single-document mode, execution parses JSON before compiling the expression.
+Query paths follow the document path rules: `--query-file -` reads a literal file named `-`.
+
+## Output
+
+The result goes to standard output as compact JSON followed by a newline.
+Use `--pretty` for JSON with two-space indentation and one final newline.
+Both formats support objects, arrays, strings, numbers, booleans, and null, with Unicode preserved.
+Pretty output works with positional or file queries and either document source.
+Repeated `--pretty` options are usage failures.
+Pretty formatting preserves stderr diagnostics, source coordinates, and exit statuses; failures before output starts leave stdout empty.
+Use `--raw-output` to print string results without JSON quotes or escape encoding.
+Other result types retain compact JSON encoding.
+Raw output appends one newline and preserves every embedded and trailing newline in the result.
+An empty string produces one newline; a string ending with one newline produces two.
+Repeated `--raw-output` options and combinations with `--pretty` are usage failures.
+Raw output preserves stderr diagnostics, source coordinates, and exit statuses; failures before output starts leave stdout empty.
+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.
+
+### Record processing
+
+Process independent JSON records with these shell commands:
+
+```sh
+jmespath --json-lines 'user.name' < events.jsonl
+jmespath --json-lines --file events.jsonl --query-file query.jmespath
+```
+
+JSON Lines mode compiles the query once before opening document input or reading stdin.
+Each physical line must contain one complete JSON value; blank and whitespace-only lines fail.
+LF, CRLF, and a final record without a newline are accepted.
+Each result is compact JSON followed by a newline, including `null` and `false`.
+Empty input succeeds without output when the query is valid; an invalid query still fails.
+
+Processing stops at the first failure with status 1 and an `Input line N:` diagnostic prefix.
+Earlier results remain on stdout; check the exit status before treating output as complete.
+Query compilation and file-open errors have no input line prefix.
+Memory is proportional to the current record, its evaluation, and its serialized result, plus the compiled query.
+Output uses normal buffering.
+Owned files close after processing; caller-owned streams remain open.
+Injected `CLI.run` input needs `gets` for JSON Lines or `read` for document mode; output needs only `puts`.
+Repeated `--json-lines` flags and combinations with `--pretty`, `--raw-output`, or validation are usage failures.
+
+## Validation
+
+Validate syntax without providing a JSON document by running this shell command:
+
+```sh
+jmespath --validate 'items[*].name'
+jmespath --validate --query-file query.jmespath
+jmespath --query-file query.jmespath --validate
+```
+
+Both executables support `--validate EXPRESSION` without reading standard input.
+File validation also leaves stdin untouched and rejects document options such as `--file`.
+Combining `--pretty` with validation is a usage failure, rejected before opening input files or reading stdin.
+Combining `--raw-output` with validation follows the same rule.
+The exact two-argument form `--validate EXPRESSION` always treats the second argument as query text, including flag-like text.
+Thus `jmespath --validate --pretty` validates the literal expression `--pretty`.
+Likewise, `jmespath --validate --raw-output` validates the literal expression `--raw-output`.
+Valid syntax produces no output and exits with status 0.
+Query failures print a diagnostic to standard error and exit with status 1; incorrect usage exits with status 2.
+Validation does not check function availability or runtime argument types.
+The Ruby interface is `JMESPath.validate(expression, max_depth: 128)`.
+See [CLI diagnostics](errors.md#cli-diagnostics) for examples and fallback behavior.
+
+## Functions
+
+List built-in functions from the shell without reading stdin:
+
+```sh
+jmespath --functions
+```
+
+Each line shows a name, accepted argument types, and the description from public function metadata.
+The listing is alphabetical and ends with a notation legend.
+Unions use `|`, homogeneous arrays use `array<T>`, and expression references use `expref`.
+A final `...` means the last argument repeats and remains required.
+Runtime checks can be narrower than the declared types.
+See [the function listing](functions.md#command-line-reference) for examples.
+
+Use `--functions` alone; queries, paths, other modes, repeated flags, and values are usage failures.
+The two-argument form `--validate --functions` retains literal query validation.
+Listing exits with status 0 on success, 1 for output failures, or 2 for usage failures.
+Usage failures leave stdout empty and print usage guidance on stderr.
+
+## Interactive
+
+Start a session against one loaded document:
+
+```sh
+jmespath --interactive --file document.json
+```
+
+Enter one UTF-8 query per line; empty lines and lines containing only spaces or tabs are ignored.
+Use `:help` for session instructions and `:quit` to finish, or end input with EOF.
+Queries accept LF, CRLF, and a final line without a newline.
+Each successful query prints compact JSON and a final newline to stdout, then flushes when the stream supports it.
+Prompts appear only when stdin is a terminal; prompts, help, and diagnostics use stderr.
+The document loads once and its file closes before the first prompt or command read.
+
+Queries can also come from a pipe without prompts:
+
+```sh
+printf 'user.name\nlength(user.name)\n' | jmespath --interactive --file document.json
+```
+
+Query errors, unknown commands, and invalid UTF-8 query lines produce diagnostics and allow the session to continue.
+Failed queries produce no JSON result; successful results remain available.
+EOF and `:quit` return status 0 even after query failures.
+Document and stream failures terminate with status 1; usage failures return status 2.
+Interactive mode requires `--file PATH` and rejects positional queries, `--query-file`, other modes, information flags, and repeated flags.
+Readers supplied to `CLI.run` need `gets`; `tty?` is optional and absent detection means no prompts.
+Writers need `puts`; `flush` is optional except for terminal prompts, whose diagnostic stream needs both `print` and `flush`.
+Caller-owned streams remain open.
+
+On supported terminals, Reline provides single-line editing and previous-query recall.
+Editing requires terminal IO on stdin and stderr and a usable `TERM`; redirected stdout remains available for JSON results.
+Keep up to 500 submitted queries in memory for the session, including failed queries and duplicates.
+Commands, blanks, and invalid UTF-8 input are excluded; the oldest query is discarded when the limit is reached.
+History starts empty for each session and creates no files or shell configuration.
+Ctrl-C discards the current edit without evaluating partial input.
+Pasted physical lines are submitted as separate queries after confirmation.
+Pipes, injected readers, redirected stderr, and unsupported terminals use the plain line reader without loading Reline.
+The plain reader retains its interruption behavior.
+Tab completes built-in function names at the cursor, replacing the complete name token while preserving surrounding Unicode text.
+Completion inserts no parentheses or spaces and does not inspect the document or evaluate queries.
+Quoted identifiers, single-quoted strings, and backtick literals remain unchanged.
+A unique match inserts the name; multiple matches extend their common prefix when possible.
+When no extension is possible, sorted alternatives appear on stderr and the query remains unchanged.
+Empty and unknown prefixes remain unchanged without diagnostics.
+Multiline editing and document reloads are unavailable.
+Terminal editing is tested on macOS through a pseudo terminal.
+CI includes Linux checks on Ruby 3.3, 3.4, and 4.0 and a macOS terminal check; Windows terminal behavior is unverified.
+
+Use `:functions` to list built-in names, signatures, descriptions, and the type legend on stderr.
+Use `:explain QUERY` to inspect an operation tree without evaluating the document.
+Each tree node shows its public operation ID, role, details, source line and character column, and byte range.
+Byte ranges have exclusive ends; missing source locations are labeled explicitly.
+The query is the complete remainder after the command separator, preserving trailing whitespace.
+Explanations show unknown function names without checking their availability.
+Both commands work with terminal or piped input and leave stdout empty.
+Command errors produce diagnostics and leave the session usable.
+Tab completes function names within explanation arguments on supported terminals.
+For structured inspection, use the public [explanation API](compilation.md#query-inspection).
+
+Use `:trace QUERY` to evaluate once and inspect null fields, filter exclusions, and omitted projection results.
+The readable report uses stderr; the successful value is written once as compact JSON on stdout, including null and false.
+Events retain public operation IDs, source locations, reasons, and zero-based item context.
+Traces retain at most 1,000 events; a truncation notice states that evaluation completed.
+An empty report prints `Trace: no diagnostic events.`
+Serialization failures produce diagnostics without a report or result; the session remains usable.
+Stream failures terminate the session with status 1.
+Tab completes function names in trace arguments on supported terminals.
+Reports use private text layouts; use the [tracing API](compilation.md#evaluation-tracing) for structured data.
+
+## Help
+
+Run `jmespath --help` or `jmespath -h` for usage, options, common examples, and topic commands.
+Read detailed rules without accessing stdin or opening document or query files:
+
+```sh
+jmespath --help input
+jmespath --help output
+jmespath --help validate
+jmespath --help functions
+jmespath --help interactive
+```
+
+Both executable names accept `-h TOPIC` as an alias.
+Help must be the first argument, with zero or one exact, case-sensitive topic name.
+Abbreviations, equals forms, unknown topics, extra arguments, and combinations with execution flags are usage failures.
+Invalid help requests leave stdout empty and print usage guidance to stderr without accessing any input.
+Valid help writes to stdout with status 0; output failures return 1 and usage failures return 2.
+The exact two-argument form `jmespath --validate --help` still validates the literal query `--help`.
+
+Run `jmespath --version` for the gem version.
+The version flag must appear alone and leaves document and query input untouched.
+
+## Exit statuses
+
+| Status | Meaning |
+| --- | --- |
+| 0 | Successful execution, validation, information output, or normal session termination |
+| 1 | Query, document, file, or stream failure |
+| 2 | Invalid command-line usage |
+
+Usage failures leave stdout empty and write usage guidance to stderr before accessing input.
+Function arguments and expression-reference results are validated; failures exit with status 1.
+See [CLI diagnostics](errors.md#cli-diagnostics) for source locations and fallback messages.

data/docs/guides/compilation.md

@@ -321,7 +321,8 @@ Trace state is separate for each call, including concurrent calls and nested cal
 Ordinary search builds no trace collector or operation map.
 Tracing propagates original evaluation and input exceptions without attaching a report or retrying evaluation.
 Suppression retains its ordinary behavior; a suppressed nil result can produce a downstream omission.
-There is no dedicated validation-failure event, automatic logging, module-level trace method, or CLI trace flag.
+There is no dedicated validation-failure event, automatic logging, or module-level trace method.
+Interactive sessions expose tracing through `:trace QUERY`; see the [command-line guide](command-line.md#interactive).
 
 ## Saved options
 

data/docs/guides/completion.md

@@ -2,6 +2,7 @@
 
 The gem includes Bash and Zsh completion definitions for `jmespath` and `jmespath.rb`.
 They suggest option names and filesystem paths after `--file` and `--query-file`.
+They also suggest `input`, `output`, `validate`, `functions`, and `interactive` after an initial `--help` or `-h`.
 Both `--file PATH` and `--file=PATH` forms support completion, including spaces in filenames.
 
 ## Bash setup
@@ -54,6 +55,8 @@ These examples show the key as `<Tab>`:
 jmespath --que<Tab>
 jmespath --query-file queries/rep<Tab>
 jmespath.rb --file=my<Tab>
+jmespath --help val<Tab>
+jmespath.rb -h int<Tab>
 ```
 
 Directories remain available for further path completion, without filtering by file extension.
@@ -63,6 +66,8 @@ Hyphen-leading filenames follow the CLI's literal-path rules, such as `--file=--
 Options remain available before or after an expression until a standalone `--` delimiter.
 Repeated or conflicting options remain visible; the CLI validates combinations when you run the command.
 Completion does not suggest JMESPath expressions or complete arguments after the delimiter.
+Help topics are offered only as the first argument after an initial help flag, with no suggestions after the topic.
+The literal-validation form `--validate --help` does not offer help topics.
 It lists filesystem names without running the CLI, evaluating queries, or reading document or query contents.
 Ruby runs only during the installation-path lookup shown above.
 

data/lib/jmespath/cli/arguments.rb

@@ -12,16 +12,13 @@ module JMESPath
 
     # @api private
     def self.parse_arguments(argv)
-      if argv.one? && !argv.fetch(0).start_with?("-")
-        return [argv.fetch(0), nil, nil, false, false, false, false, false]
-      end
+      return [argv.fetch(0), nil, nil, nil] if argv.one? && !argv.fetch(0).start_with?("-")
 
       paths = {} # : Hash[String, String]
       arguments = argument_parser(paths).permute(argv)
-      check_sources(arguments, paths)
+      mode = check_sources(arguments, paths)
 
-      [arguments.first, paths["file"], paths["query-file"], paths.key?("validate"), paths.key?("pretty"),
-       paths.key?("raw-output"), paths.key?("json-lines"), paths.key?("interactive")]
+      [arguments.first, paths["file"], paths["query-file"], mode]
     end
 
     # @api private
@@ -41,8 +38,8 @@ module JMESPath
     def self.check_modes(paths)
       modes = paths.keys & %w[validate pretty raw-output json-lines interactive]
       raise OptionParser::InvalidArgument, "conflicting modes" if modes.length > 1
-      return unless paths.key?("validate")
-      return if paths.key?("query-file") && !paths.key?("file")
+      return modes.first unless paths.key?("validate")
+      return modes.first if paths.key?("query-file") && !paths.key?("file")
 
       raise OptionParser::InvalidArgument, "validation requires a query file"
     end

data/lib/jmespath/cli/help.rb

@@ -1,43 +1,125 @@
 # frozen_string_literal: true
 
+require_relative "interactive_help"
+
 module JMESPath
   module CLI
     USAGE = "Usage: jmespath [--pretty | --raw-output | --json-lines] [--file PATH] " \
             "(EXPRESSION | --query-file PATH)\n       " \
             "jmespath --validate (EXPRESSION | --query-file PATH)\n       jmespath --functions\n       " \
             "jmespath --interactive --file PATH"
-    HELP = "#{USAGE}\n" \
-           "Read one UTF-8 JSON document from --file PATH, or stdin when omitted.\n" \
-           "Supply one query as EXPRESSION or --query-file PATH, read as UTF-8 without trimming.\n" \
-           "Options may precede or follow EXPRESSION; -- ends option parsing.\n" \
-           "Quote spaces: --file 'my document.json'. Use --file=--document.json for option-like names.\n" \
-           "Paths are literal: --file - reads the file named -.\n" \
-           "Query paths follow the same rules: --query-file - reads the query file named -.\n" \
-           "Output is compact JSON by default; --pretty uses two-space indentation and a final newline.\n" \
-           "Use --raw-output for literal string results; other results remain compact JSON.\n" \
-           "Raw strings retain all their newlines and receive one additional output newline.\n" \
-           "Output flags cannot be repeated or combined with each other or --validate.\n" \
-           "Use --json-lines for one JSON record per physical input line and one compact result per record.\n" \
-           "JSON Lines compiles once before input; empty input succeeds with a valid query.\n" \
-           "Blank records are invalid; failures report the input line, retain earlier output, and exit 1.\n" \
-           "Memory follows the current record and result; output uses normal buffering.\n" \
-           "The --json-lines flag cannot be repeated or combined with --pretty, --raw-output, or --validate.\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.\n" \
-           "Use --interactive --file PATH for successive queries against one loaded document.\n" \
-           "Enter one query per line; blank lines are ignored. :help shows help; :quit or EOF exits successfully.\n" \
-           "Query errors are reported and the session continues; startup or stream failures exit 1.\n" \
-           "Results are compact JSON on stdout; prompts and diagnostics use stderr.\n" \
-           "Prompts appear only when stdin is a terminal; results are flushed after each query.\n" \
-           "Interactive mode requires --file and rejects query sources, other modes, and information flags.\n" \
-           "Use --validate to check syntax only, without reading stdin; unknown functions remain valid.\n" \
-           "Validate saved queries with --validate --query-file PATH; --file is unavailable during validation.\n" \
-           "The two-argument form --validate EXPRESSION always treats EXPRESSION as query text.\n" \
-           "Validation exits with status 0 for valid syntax, 1 for query failures, and 2 for usage failures.\n" \
-           "Use standalone --functions to list built-in signatures and descriptions without reading stdin.\n" \
-           "The --functions flag cannot be repeated or combined with queries, paths, modes, or information flags.\n" \
-           "Listing exits with status 0 on success, 1 for output failures, and 2 for usage failures.\n" \
-           "Manual Bash and Zsh completion: docs/guides/completion.md.\n#{FunctionListing::LEGEND}".freeze
+
+    # @api private
+    module Help
+      GUIDE = "Reference: docs/guides/command-line.md (included in the gem).\n" \
+              "https://github.com/svyatov/jmespath-ruby/blob/main/docs/guides/command-line.md\n"
+      TOPICS = {
+        "input" => <<~TEXT,
+          Input: jmespath --file document.json 'user.name'
+                 jmespath --query-file query.jmespath < document.json
+          Read one UTF-8 JSON document from --file PATH, or stdin when omitted.
+          Supply exactly one query: EXPRESSION or --query-file PATH, read as UTF-8 without trimming.
+          Query text retains newlines and Unicode coordinates; an empty query file is a syntax failure.
+          Query files close before document input; missing or unreadable queries leave documents untouched.
+          In single-document mode, JSON is parsed before query compilation.
+          Document files close after parsing, before evaluation. Caller-owned streams remain open.
+          Options may precede or follow EXPRESSION; -- ends option parsing. Option names match exactly.
+          Quote spaces: --file 'my document.json'. Use --file=--document.json or ./--document.json.
+          Paths are literal: --file - and --query-file - read files named -.
+          Repeated options, unknown options, missing values, and conflicting or absent queries fail before input.
+          CLI.run document input needs read; line modes need gets; output needs puts.
+          Query failures include source locations when available. Unknown functions suggest similar registered names.
+          Malformed JSON reports Invalid JSON input without document fragments.
+          Results use stdout; diagnostics use stderr. Success returns status 0, input/query/stream failures 1,
+          and usage failures 2 with empty stdout. Information modes never access document or query input.
+          Version and function listing flags must stand alone; help accepts only one optional topic.
+        TEXT
+        "output" => <<~TEXT,
+          Output: jmespath --pretty 'items' < document.json
+                  jmespath --raw-output 'user.name' < document.json
+                  jmespath --json-lines --file events.jsonl --query-file query.jmespath
+          Output is compact JSON by default; --pretty uses two-space indentation and a final newline.
+          Both preserve Unicode and support objects, arrays, strings, numbers, booleans, and null.
+          Pretty output supports either query and document source.
+          --raw-output prints strings literally; other results remain compact JSON.
+          Raw strings retain all embedded and trailing newlines and receive one additional output newline.
+          An empty string prints one newline; a string ending in one newline prints two.
+          Output flags cannot be repeated or combined with each other or --validate.
+          JSON Lines compiles once before opening document input; valid empty input succeeds without output.
+          Each physical line must contain one JSON value; blank and whitespace-only records are invalid.
+          LF, CRLF, and a final record without a newline are accepted.
+          Each result is compact JSON plus a newline, including null and false.
+          Processing stops on failure; earlier stdout remains. Check status before treating output as complete.
+          Record failures use Input line N: on stderr; compilation and file-open errors have no line prefix.
+          Memory follows the current record, evaluation, and result plus the compiled query.
+          Output uses normal buffering. Owned files close; caller-owned streams remain open.
+          CLI.run line input needs gets and output needs puts.
+          Formatting preserves diagnostics and source coordinates; failures before output leave stdout empty.
+          Results use stdout; diagnostics use stderr. Success returns status 0, query/input/output failures 1,
+          and usage failures 2. See jmespath --help input for query and path rules.
+        TEXT
+        "validate" => <<~TEXT,
+          Validation: jmespath --validate EXPRESSION
+                      jmespath --validate 'items[*].name'
+                      jmespath --validate --query-file query.jmespath
+                      jmespath --query-file query.jmespath --validate
+          Check syntax only, without reading stdin. Unknown functions and invalid runtime types remain valid syntax.
+          Query files follow input topic rules. --file, output flags, and interactive mode are unavailable.
+          Invalid combinations fail before opening files or reading stdin.
+          The exact two-argument form --validate EXPRESSION always treats EXPRESSION as query text.
+          Thus --validate --help, --validate -h, --validate --pretty, and --validate --raw-output validate literals.
+          Validation exits with status 0 for valid syntax, 1 for query failures, and 2 for usage failures.
+          Valid syntax produces no stdout or stderr; failures leave stdout empty and print diagnostics to stderr.
+          Query failures include source locations when available.
+          Ruby callers can use JMESPath.validate(expression, max_depth: 128).
+        TEXT
+        "functions" => <<~TEXT + FunctionListing::LEGEND,
+          Functions: jmespath --functions
+          Use standalone --functions to list built-in signatures and descriptions without reading stdin.
+          Names are alphabetical and use public function metadata; the listing ends with a notation legend.
+          --functions cannot be repeated or combined with queries, paths, modes, information flags, or values.
+          The two-argument form --validate --functions validates the literal query.
+          Function arguments and expression-reference results are validated; failures exit with status 1.
+          Unknown functions suggest similar registered names. Query failures include source locations when available.
+          Listing writes to stdout with empty stderr and returns status 0; output failures return 1.
+          Usage failures return 2, leave stdout empty, and print usage guidance to stderr before accessing input.
+        TEXT
+        "interactive" => InteractiveHelp::TEXT
+      }.freeze
+
+      def self.render(topic)
+        return HELP unless topic
+
+        TOPICS.fetch(topic) { raise OptionParser::InvalidArgument, "unknown help topic" } + GUIDE
+      end
+    end
+
+    HELP = <<~TEXT.freeze
+      #{USAGE}
+             jmespath --help [TOPIC]
+      Options:
+        --file PATH         Read a JSON document (default: stdin)
+        --query-file PATH   Read the UTF-8 query instead of EXPRESSION
+        --pretty            Print indented JSON
+        --raw-output        Print string results literally
+        --json-lines        Search each JSON input line
+        --validate          Check query syntax without a document
+        --interactive       Run successive queries against --file PATH
+        --functions         List built-in functions
+        --version           Print the gem version
+        -h, --help [TOPIC]   Show help
+      Examples:
+        jmespath --file document.json 'user.name'
+        jmespath --pretty 'items' < document.json
+        jmespath --validate 'items[*].name'
+      Topic help (also accepts -h TOPIC):
+        jmespath --help input
+        jmespath --help output
+        jmespath --help validate
+        jmespath --help functions
+        jmespath --help interactive
+      Manual Bash and Zsh completion: docs/guides/completion.md.
+      #{Help::GUIDE}
+    TEXT
   end
 end

data/lib/jmespath/cli/inspection_report.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    class InspectionReport
+      def self.explain(explanation)
+        new(explanation).explain
+      end
+
+      def self.trace(explanation, report, limit:)
+        new(explanation).trace(report, limit: limit)
+      end
+
+      def initialize(explanation)
+        @source = explanation[:source]
+        @root = explanation[:root]
+      end
+
+      def explain
+        tree(@root).join("\n")
+      end
+
+      def trace(report, limit:)
+        locations = {} # : Hash[Integer, String]
+        index_locations(@root, locations)
+        lines = report[:events].map { |event| event_line(event, locations) }
+        lines << "Trace: no diagnostic events." if lines.empty?
+        lines << "Trace truncated: showing first #{limit} events; evaluation completed." if report[:truncated]
+        lines.join("\n")
+      end
+
+      private
+
+      def index_locations(node, locations)
+        locations[node[:id]] = location(node[:source_range])
+        node[:children].each { |child| index_locations(child[:node], locations) }
+      end
+
+      def event_line(event, locations)
+        [event[:type], "##{event[:operation_id]}", locations.fetch(event[:operation_id]),
+         details(event[:details]), context(event[:context])].reject(&:empty?).join(" ")
+      end
+
+      def context(frames)
+        return "" if frames.empty?
+
+        entries = frames.map { |frame| "##{frame[:operation_id]} index=#{frame[:index]}" }
+        "context=[#{entries.join(', ')}]"
+      end
+
+      def tree(node, indent = "", role = nil)
+        line = indent + [role, label(node)].compact.join(": ")
+        [line] + node[:children].flat_map { |child| tree(child[:node], "#{indent}  ", child[:role]) }
+      end
+
+      def label(node)
+        ["##{node[:id]}", node[:operation], location(node[:source_range]), details(node[:details])]
+          .reject(&:empty?).join(" ")
+      end
+
+      def location(range)
+        return "location unavailable" unless range
+
+        prefix = @source.byteslice(0, range[0]).to_s
+        line = prefix.count("\n") + 1
+        column = prefix.rpartition("\n").last.length + 1
+        "line #{line}, column #{column} (bytes #{range[0]}...#{range[1]})"
+      end
+
+      def details(values)
+        values.map { |key, value| "#{key}=#{value.inspect}" }.join(" ")
+      end
+    end
+  end
+end

data/lib/jmespath/cli/interactive_commands.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "inspection_report"
+
+module JMESPath
+  module CLI
+    # @api private
+    module InteractiveCommands
+      TRACE_LIMIT = 1000
+
+      def self.call(line, data:)
+        parts = line.sub(/\A[ \t]+/, "").split(/[ \t]+/, 2)
+        query = parts.fetch(1, "")
+        execute(parts.fetch(0), query, line, data)
+      rescue JSON::NestingError
+        ["Invalid JSON result", nil]
+      rescue Errors::Error, JSON::GeneratorError => e
+        [FailureDiagnostic.format(e, query), nil]
+      end
+
+      def self.execute(name, query, line, data)
+        case name
+        when ":functions" then [functions(query), nil]
+        when ":explain" then [explain(query), nil]
+        when ":trace" then trace(query, data)
+        else
+          command = line.sub(/\A[ \t]+/, "").reverse.sub(/\A[ \t]+/, "").reverse
+          raise Errors::Error, "Unknown command: #{command}"
+        end
+      end
+
+      def self.functions(query)
+        raise Errors::Error, ":functions does not accept arguments" unless query.empty?
+
+        FunctionListing.render(Functions.default)
+      end
+
+      def self.explain(query)
+        InspectionReport.explain(compile(query, ":explain").explain)
+      end
+
+      def self.compile(query, command)
+        raise Errors::Error, "#{command} requires a query" if query.empty?
+
+        JMESPath.compile(query)
+      end
+
+      def self.trace(query, data)
+        expression = compile(query, ":trace")
+        report = expression.trace(data, limit: TRACE_LIMIT)
+        result = JSON.generate(report[:value])
+        [InspectionReport.trace(expression.explain, report, limit: TRACE_LIMIT), result]
+      end
+
+      private_class_method :execute, :functions, :explain, :compile, :trace
+    end
+  end
+end