feat(jq): add a diff_test helper

This is useful in rules_swc where we want to check that tsconfig.json and .swcrc have matching paths, and most users will want that too

docs/jq.md

@@ -2,6 +2,31 @@
 
 Public API for jq
 
+<a id="assert_json_matches"></a>
+
+## assert_json_matches
+
+<pre>
+assert_json_matches(<a href="#assert_json_matches-name">name</a>, <a href="#assert_json_matches-file1">file1</a>, <a href="#assert_json_matches-filter1">filter1</a>, <a href="#assert_json_matches-file2">file2</a>, <a href="#assert_json_matches-filter2">filter2</a>)
+</pre>
+
+Assert that the given json files have the same semantic content.
+
+Uses jq to filter each file. Use `"."` as the filter to compare the whole file.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="assert_json_matches-name"></a>name |  name of resulting diff_test target   |  none |
+| <a id="assert_json_matches-file1"></a>file1 |  a json file   |  none |
+| <a id="assert_json_matches-filter1"></a>filter1 |  a jq filter to apply to file1   |  none |
+| <a id="assert_json_matches-file2"></a>file2 |  another json file   |  none |
+| <a id="assert_json_matches-filter2"></a>filter2 |  a jq filter to apply to file2   |  none |
+
+
 <a id="jq"></a>
 
 ## jq

lib/BUILD.bazel

@@ -65,7 +65,10 @@ bzl_library(
     name = "jq",
     srcs = ["jq.bzl"],
     visibility = ["//visibility:public"],
-    deps = ["//lib/private/docs:jq"],
+    deps = [
+        "//lib/private/docs:jq",
+        "@bazel_skylib//rules:diff_test",
+    ],
 )
 
 bzl_library(

lib/jq.bzl

@@ -1,6 +1,45 @@
 """Public API for jq"""
 
 load("//lib/private:jq.bzl", _jq_lib = "jq_lib")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+
+def assert_json_matches(name, file1, filter1, file2, filter2):
+    """Assert that the given json files have the same semantic content.
+
+    Uses jq to filter each file. Use `"."` as the filter to compare the whole file.
+
+    Args:
+        name: name of resulting diff_test target
+        file1: a json file
+        file2: another json file
+        filter1: a jq filter to apply to file1
+        filter2: a jq filter to apply to file2
+    """
+    name1 = "_{}_jq1".format(name)
+    name2 = "_{}_jq2".format(name)
+    jq(
+        name = name1,
+        srcs = [file1],
+        filter = filter1,
+    )
+
+    jq(
+        name = name2,
+        srcs = [file2],
+        filter = filter2,
+    )
+
+    diff_test(
+        name = name,
+        file1 = name1,
+        file2 = name2,
+        failure_message = "'{}' from {} doesn't match '{}' from {}".format(
+            filter1,
+            file1,
+            filter2,
+            file2,
+        ),
+    )
 
 _jq_rule = rule(
     attrs = _jq_lib.attrs,