RhoeJSON jq Compatibility Roadmap

RhoeJSON ships a jq-inspired filter surface for command-line muscle memory. It does not yet claim full jq compatibility. This roadmap keeps the compatibility story precise while we progressively close the high-impact semantic gaps.

Compatibility Labels

• exact-compatible: Behavior is intended to match jq for the documented case

and is covered by local tests or the pinned jq subset conformance harness.

• inspired: The spelling or workflow is familiar to jq users, but behavior

is intentionally narrower or RhoeJSON-specific.

• deferred: The feature is a planned compatibility candidate but is not part

of the current release surface.

• intentionally-unsupported: The feature is outside the current public

contract.

Implemented First: Path And Generator Semantics

The current implementation supports jq path arrays and generator-backed mutation for the most important document editing workflows:

• path(.field[index])
• path(.items[].field)
• paths
• paths(predicate)
• leaf_paths
• getpath(pathArray)
• setpath(pathArray; value)
• delpaths(pathArrayList)
• generator assignment such as .records[].score += 1
• generator deletion such as del(.records[].active)

The pinned subset cases live in Tests/RhoeJSONFilterTests/Fixtures/jq-conformance/subset-cases.json. Maintainers can compare those cases against an installed jq binary with:

bash Scripts/validate-jq-subset-conformance.sh

The offline Swift unit test suite also loads Tests/RhoeJSONFilterTests/Fixtures/jq-conformance/golden-cases.json, a checked-in manifest of exact-compatible jq filters and expected output streams. Those golden fixtures give the public package deterministic regression coverage without requiring jq at test time, while the conformance script re-checks the same checked-in expectations against a local jq oracle when available.

Second Cliff: Variables, Functions, Reduce

The first lexical evaluation slice is implemented:

• as $name bindings
• destructuring bindings such as as {name: $name} and as [$a, $b]
• $name references
• variable field/index suffixes such as $record.name
• reduce stream as $name (initial; update)
• foreach stream as $name (initial; update)
• foreach stream as $name (initial; update; extract)
• try expression catch handler, plus try expression as an empty-on-error form
• while(condition; update)
• until(condition; update)
• recurse, recurse(step), and recurse(step; condition)
• walk(filter)
• error(message) and try error(...) catch ...
• halt and halt_error(status) with CLI-level exit-code propagation
• no-argument def name: filter; ... filters
• filter-argument def name(f; g): ...; functions
• recursive user-defined functions
• RhoeJSON-inspired forward references to later def definitions

The jq-oracle harness labels forward references as inspired, not exact-compatible, because jq itself rejects calls to functions that are defined later in the same program. The remaining work in this cliff is narrower non-local control-flow semantics:

• label and break

The evaluator environment now carries input value, lexical bindings, function definitions, filter-argument bindings, and a shared input provider for input/inputs. A later diagnostic pass should add source ranges and clearer recursion-depth failure messages.

Then: Regex And String Fidelity

The first regex fidelity slice is implemented:

• test(regex) and test(regex; flags)
• match(regex) and match(regex; flags)
• capture(regex) and capture(regex; flags)
• scan(regex) and scan(regex; flags)
• sub(regex; replacement) and sub(regex; replacement; flags)
• gsub(regex; replacement) and gsub(regex; replacement; flags)
• i, m, s, x, and g regex flags where applicable
• named capture interpolation in replacement strings using \(.name)
• jq-style string interpolation with "\(...)", including embedded filters

that produce multiple output strings or no output via empty

• ltrimstr(...)
• rtrimstr(...)
• explode
• implode

The remaining string fidelity lane should cover:

• replacement expressions that produce streams.
• broader explicit Unicode normalization behavior notes for edge cases beyond

scalar code point conversion.

Then: Format Encoders And Math Utilities

The next utility slice is implemented for high-frequency shell workflows:

• @text
• @json
• @html
• @uri
• @csv
• @tsv
• @sh
• @base64
• @base64d
• jq formatter string semantics where literal text remains literal and

\(...) interpolation holes are formatted

• deterministic math helpers: abs, floor, ceil, round, sqrt, sin,

cos, tan, log, and exp

The current math contract is intentionally pinned to deterministic finite inputs covered by the subset harness. Broader floating-point edge cases (nan, infinities, platform-specific transcendental rounding) remain outside the 0.1.0 compatibility claim.

Then: jq-Style CLI Flags

The current rhoejson jq command supports these exact-compatible jq-style input/output flags:

• -n / --null-input
• -R / --raw-input
• -s / --slurp
• -r / --raw-output
• --raw-output0
• -j / --join-output
• -a / --ascii-output
• -c / --compact-output
• -S / --sort-keys
• --indent n, including jq's -1 tab-indentation mode
• --tab
• -e / --exit-status
• -f file / --from-file file

Program-file loading reads one jq-inspired filter source from disk. RhoeJSON now accepts multiple JSON input paths, parses multiple whitespace-separated JSON texts, and exposes jq-style input and inputs over the shared input stream.

It also supports exact jq variable binding flags:

• --arg name value
• --argjson name JSON
• --rawfile name path
• --slurpfile name path
• --args
• --jsonargs

--args and --jsonargs follow jq's tail-consuming shell grammar: every remaining value token is exposed through $ARGS.positional. As in jq, use the -- end-of-options marker after --args or --jsonargs when a positional value itself begins with -.

The staged public preview also accepts these RhoeJSON convenience forms:

• --arg name=value
• --argjson name=json
• --rawfile name=path
• --slurpfile name=path

A fuller jq-compatible shell surface would add:

• -L module search paths
• color and monochrome-output flags

Later Compatibility Candidates

• Modules: include, import, namespaces, and metadata.
• Streaming: --stream, tostream, fromstream, and truncate_stream.
• Dates and time: now, fromdate, todate, strptime, and strftime.
• Non-local control flow: label and break.
• I/O and environment beyond the implemented input stream: debug, stderr,

env, and $ENV, with explicit determinism and security boundaries. Raw environment exposure is deliberately deferred because public CLI environments often contain tokens and other secrets.

Conformance Strategy

The harness starts with a pinned behavioral subset manifest maintained in this repo. Before claiming broader jq compatibility, we should add a licensing review and pinned import strategy for upstream jq tests, then classify each imported case as exact-compatible, jq-inspired, deferred, or unsupported.