feat(jq): support external-argument flags (--arg, --argjson, --rawfile, --slurpfile, --args, --jsonargs)

[trieloff]

Adds faithful support for jq's entire external-argument family, verified against real jq 1.7.1-apple.

What

Named-argument flags bind a variable and populate $ARGS.named:

• --arg NAME VALUE (string)
• --argjson NAME JSON (parsed JSON value)
• --rawfile NAME FILE (file contents as a string)
• --slurpfile NAME FILE (array of JSON values from a file)

Positional-argument flags populate $ARGS.positional:

• --args (remaining args as strings)
• --jsonargs (remaining args as JSON values)

How

• Plumbed namedArgs / positionalArgs through EvaluateOptions into EvalContext.
• Resolved $NAME and the $ARGS object in the evaluator VarRef case, using a null-prototype object and isSafeKey guards to prevent prototype pollution.
• Reused the existing file reader and JSON stream parser.

Testing

• New unit tests for named + positional flags.
• Comparison tests recorded against real jq 1.7.1-apple (fixtures committed).
• Exact stdout + exit-code parity confirmed by an independent verifier: all flags, combined named+positional $ARGS, filter/positional boundary, empty $ARGS, and invalid-JSON errors (exit 2, no crash).
• build / typecheck / lint / knip clean.

Known minor deviations (non-blocking)

1. Invalid-JSON stderr omits real jq's "Use jq --help..." trailer; exit code 2 matches.
2. Unknown -- flag exits 1 (real jq exits 2) — pre-existing project-wide behavior, not introduced here.

[vercel]

@trieloff is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[trieloff]

Note on prior art: this PR builds on the approach in #162 (feat(jq): add --arg and --argjson flags by @pawaca), which first introduced --arg / --argjson by seeding the query engine variable map. Credit to that PR for the original direction and the maintainer feedback there.

This PR supersedes #162 by extending it to the full external-argument family:

• Adds --rawfile, --slurpfile, --args, and --jsonargs on top of --arg / --argjson.
• Exposes the $ARGS object ($ARGS.named / $ARGS.positional), ordered to match real jq.
• Matches real jq exit codes and error wording; guards $ARGS.named against prototype pollution.
• Adds full stdout/stderr/exit-code unit tests plus comparison tests with fixtures recorded against real jq 1.7.1.
• Uses the current packages/just-bash monorepo layout.

If this lands, #162 can be closed as superseded.

[Copilot]

Pull request overview

Adds full jq external-argument support to the jq command implementation, wiring named and positional arguments through the query engine so filters can access $NAME bindings and $ARGS.{named,positional} in a way that matches jq CLI behavior.

Changes:

• Implemented parsing for --arg, --argjson, --rawfile, --slurpfile, --args, and --jsonargs in jq.ts, including file-backed bindings via the shared file reader.
• Plumbed namedArgs / positionalArgs into the evaluator context and implemented $ARGS resolution with null-prototype objects plus unsafe-key filtering.
• Added unit tests and real-bash comparison tests + recorded fixtures for the new flags.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/just-bash/src/comparison-tests/jq-args-positional.comparison.test.ts	Adds real-bash comparison coverage for --args / --jsonargs behaviors.
packages/just-bash/src/comparison-tests/jq-arg.comparison.test.ts	Adds real-bash comparison coverage for named-argument flags and $ARGS.
packages/just-bash/src/comparison-tests/fixtures/jq-args-positional.comparison.fixtures.json	Recorded outputs for positional-argument comparison tests.
packages/just-bash/src/comparison-tests/fixtures/jq-arg.comparison.fixtures.json	Recorded outputs for named-argument comparison tests.
packages/just-bash/src/commands/query-engine/evaluator.ts	Threads named/positional args through EvalContext and implements $ARGS VarRef behavior.
packages/just-bash/src/commands/jq/jq.ts	Implements CLI parsing + semantics for jq external-argument flags and passes them into evaluation.
packages/just-bash/src/commands/jq/jq.args-positional.test.ts	Adds unit tests for positional-argument flags and combinations.
packages/just-bash/src/commands/jq/jq.arg.test.ts	Adds unit tests for named-argument flags, $ARGS, error cases, and safety coverage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cramforce]

Please add a changeset