☔ The latest upstream changes (presumably #143337) made this pull request unmergeable. Please resolve the merge conflicts.

(cc @aDotInTheVoid)

Sorry for taking so long to review this. Thanks for working on it, especially the repetitive test migration.

I don't think it'll be a good idea to construct a JSONPath-jq transpiler because it'll look really awkward for new contributors

What do you mean by this? The idea was to use the transpiler to migrate all the assertions in the tests, leaving them in jq. New contributors should never need to know it existed.

I expect jsondocck to have just 2 directives: jq and arg

I think this is a quite bad idea. It means we loose any sort of good error reporting. With this PR at the moment, we can only say that a check failed, but not why (in the case that the query matched the wrong value). Having this is really important I think.

The job tidy failed! Check out the build log: (web) (plain enhanced) (plain)

All checks passed!
checking python file formatting
28 files already formatted
checking C++ file formatting
some tidy checks failed
Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:01:20
 local time: Thu Jul 10 22:52:06 UTC 2025
 network time: 2025年7月10日 22:52:06 GMT
##[error]Process completed with exit code 1.
Post job cleanup.

What do you mean by this? The idea was to use the transpiler to migrate all the assertions in the tests, leaving them in jq. New contributors should never need to know it existed.

Sorry, I somehow thought that you propose to leave tests as is and integrate the transpiler into jsondocck so that it'll convert all directive every test run. Nevertheless, while your idea to make transpiler for a test migration is great, I think manual migration will look much better and may even catch some mistakes, like I just found in target_feature.rs:

I think this is a quite bad idea. It means we loose any sort of good error reporting.

I see. I've added 2 directives eq & ne. They act like is & !is and report what values they received in case of mismatch. You can see how it looks in the attrs/ tests directory. So, in total, arg, jq, eq, and ne. Would that be enough?

☔ The latest upstream changes (presumably #143810) made this pull request unmergeable. Please resolve the merge conflicts.

I see. I've added 2 directives eq & ne. They act like is & !is and report what values they received in case of mismatch. You can see how it looks in the attrs/ tests directory. So, in total, arg, jq, eq, and ne. Would that be enough?

I don't think this PR needs to change the directives that exist at all to be honest. Why do you think that's the right approach?

What's the benefit of renaming is/!is to eq/ne (and set to arg)? It seems like it's churn for no gain, but maybe I'm missing something.

I think the best approach would be to keep all the existing directives, and not do a general jq directive. (That behavior could be with something like //@ is '.some.jq.query' true, but I don't think this should be encouraged). But this is based just on thinking about it, and you've written a load of tests in jq. I'm curious which way you think makes sense, and why.

I think that porting the current directives instead of declaring new ones might confuse devs that got used to how the current directives work since they won't be exactly they same.

For example, I'm not sure whether has can be ported at all because you can't just check a path existence the same way you do in JSONPath. For nonexistent paths, jq returns null, but if an existing path contains null, you'll get null, too. Instead, you need to use the special has function, which defeats the purpose of the has directive, replacing it with is/jq:

// true (if returns any value, null returned in this case)
//@ has .non_existent_field
// false
//@ jq .exisiting_field_with_null
// false
//@ jq .non_existent_field
// a right way
//@ is has("exisiting_field_with_null"), true
//@ is has("non_existent_field"), false

What I'm also trying to do is shift as much work as possible to jq, so that there'd be a minimal set of absolutely obvious directives for contributors that are already familiar with jq without diving into details about using a more appropriate directive instead of using just jq.

For example, with count we'd have multiple ways to count matches:

//@ count .some_array_field, 42
//@ is .some_array_field | length, 42

Without - just the last one.

With ismany, I'd need to get shlex back along with tons of quotes and have multiple ways to assert objects:

//@ ismany '.index[].inner.static.expr' '""' '""' '""' '""' '""' '""' '""' '""'
//@ is '[.index[].inner.static.expr]' '["", "", "", "", "", "", "", ""]'

Without - just the last one.

As some kind of a middle-ground, I can suggest to avoid renaming and port only 3 directives: set, is, and !is. And use

• is length, 42 instead of count
• is [.], [1, 2, 3] instead of ismany
• is has("field")/is contains(42)/is ., {"field":42} instead of has

not do a general jq directive. (That behavior could be with something like //@ is '.some.jq.query' true, but I don't think this should be encouraged).

Okay, I'll remove it and use (!)is instead. jq is indeed quite generic in comparison to the current directives. And is can be compacted to automatically assert a value with true, if it has no second argument.

What do you think?

For nonexistent paths, jq returns null, but if an existing path contains null, you'll get null, too

Wah, that's very unfortunate. We should probably ban //@ is .some.path null, as that's super footgunny. It also messes us 1 argument //@ has .path (with no value, just checking the path exists).

If we got rid of it completely, what would this look like?

• is [.], [1, 2, 3] instead of ismany

This isn't the same semantics. ismany doens't care about order (#99474).

And is can be compacted to automatically assert a value with true, if it has no second argument.

I don't think this is worth it, I'd rather use an explicit true.

With ismany, I'd need to get shlex back along with tons of quotes and have multiple ways to assert objects:

What are you using to split the jq filter and the values in eq/ne now?