feat: show a tested full end-to-end example

Author: chickenandpork

.bazelignore

@@ -0,0 +1,2 @@
+# see "Ignored" section in full-examples/README.md
+full-examples

.github/cspell.yaml

@@ -18,13 +18,22 @@ language: en
 # words - list of words to be always considered correct: an Allowlist per-se
 words:
   - allanc
+  - argsjson
   - bazel
   - bazelisk
   - bazelrc
+  - bitrot
+  - buildifier
   - bzlmod
   - chickenandpork
   - ibazel
   - jqlang
   - ruleset
   - slamdev
   - starlark
+  - genrule
+  - kwargs
+  - runfiles
+  - softlinks
+  - srcs
+  - stardoc

.github/workflows/ci.bazelrc

@@ -7,4 +7,5 @@ build --repository_cache=$HOME/.cache/bazel-repo
 
 # XDG_CACHE_HOME is where bazelisk -- if used -- will cache downloads; workflows use setup-bazelisk
 # which aliases 'bazel' to bazelisk.  We inject this into the test runner env like an action_env
-test --test_env=XDG_CACHE_HOME
+# used with "common" rather than "test" because "test" differing from build discards analysis cache.
+common --test_env=XDG_CACHE_HOME

.github/workflows/ci.yaml

@@ -23,7 +23,7 @@ jobs:
           # https://github.com/bazelbuild/rules_docker/issues/1524
           # https://github.com/bazelbuild/rules_docker/issues/1438
           # - windows-latest
-        bazel: [ 4.2.1, 5.0.0rc4 ]
+        bazel: [4.2.4, 5.4.1, 6.2.0]
     # The type of runner that the job will run on
     runs-on: ${{ matrix.os }}
 
@@ -58,3 +58,17 @@ jobs:
           # Bazelisk will download bazel to here
           XDG_CACHE_HOME: ~/.cache/bazel-repo
         run: bazel --bazelrc=.github/workflows/ci.bazelrc --bazelrc=.bazelrc test ...
+      - name: Build examples to ensure functionality
+        # linux and latest
+        if: ${{ matrix.os == 'ubuntu-latest' && startsWith(matrix.bazel, '6.') }}
+        run: |
+          for d in $(find full-examples -name WORKSPACE -exec dirname {} \; ); do
+          echo "::group::example: ${d}"
+          echo ${{ matrix.bazel }} > ${d}/.bazelversion
+          case ${RUNNER_ENVIRONMENT}:${d} in
+              # opportunity to skip really big tests
+              # github-hosted:full-examples/huggingface_transformer_question_answering) echo "TOO big: skip in github-hosted" ;;
+              *) (cd ${d} && bazel --bazelrc=../../.github/workflows/ci.bazelrc --bazelrc=../../.bazelrc test ... && bazel clean );;
+          esac
+          echo "::endgroup::"
+          done

.github/workflows/release.yml

@@ -40,7 +40,7 @@ jobs:
           body: |
             ```starlark
             http_archive(
-                name = "bazel_rules_jq",
+                name = "rules_jq",
                 sha256 = "${{ env.RELEASE_CHECKSUM }}",
                 url = "https://github.com/jqlang/bazel_rules_jq/releases/download/${{ env.RELEASE_VERSION }}/bazel_rules_jq-v${{ env.RELEASE_VERSION }}.tar.gz",
             )

.pre-commit-config.yaml

@@ -20,10 +20,7 @@ repos:
     rev: v1.32.0
     hooks:
       - id: yamllint
-        args: [
-          '-d',
-          '{extends: relaxed, rules: {line-length: {max: 120}}}'
-        ]
+        args: ["-d", "{extends: relaxed, rules: {line-length: {max: 120}}}"]
   # Enforce that commit messages allow for later changelog generation
   - repo: https://github.com/commitizen-tools/commitizen
     rev: 3.12.0
@@ -63,5 +60,5 @@ repos:
         # a local allowlist of dictionary words in .github/cspell.yaml.  This can get comical --
         # adding new words in every PR -- but the cost/benefit balance may avoid some embarassing
         # typos
-        args: [ '--config', '.github/cspell.yaml' ]
+        args: ["--config", ".github/cspell.yaml"]
         types: [file, markdown]

BUILD.bazel

@@ -1,6 +1,6 @@
+load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@rules_pkg//:pkg.bzl", "pkg_tar")
-load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 
 gazelle_binary(
     name = "gazelle_bin",

README.md

@@ -8,30 +8,38 @@ Examples will be created in the "examples" directory that should be cut-n-pasted
 (and soon your MODULE.bazel).
 
 The intent of this work is to:
- * offer a traditional WORKSPACE and newer bzlmod capability
- * re-home slamdev's work in making binaries available,
- * address the wider array of jq binaries now produced in a release,
- * adapt to the new naming schema, and
- * offer a fallback of building JQ if a release is not available or the user so chooses
 
+- offer a traditional WORKSPACE and newer bzlmod capability
+- re-home slamdev's work in making binaries available,
+- address the wider array of jq binaries now produced in a release,
+- adapt to the new naming schema, and
+- offer a fallback of building JQ if a release is not available or the user so chooses
 
 ## Installation
 
 ### Traditional WORKSPACE
 
-(soon)
-
-Goal is something as simple as Slamdev's work:
 ```starlark
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
-http_archive( name = "rules_jq", ...)
+http_archive(
+   name = "rules_jq",
+   sha256 = "52771b5f7fb5017b0f5a3816b46624d2b9a336ddc178b261de988d969cd329d8",
+   url = "https://github.com/jqlang/bazel_rules_jq/releases/download/0.0.1/bazel_rules_jq-v0.0.1.tar.gz",
+)
+
+load("@rules_jq//jq:repositories.bzl", "jq_register_toolchains", "rules_jq_dependencies")
 
-load("@rules_jq//some_file.bzl", "jq_register_toolchains", "rules_jq_dependencies")
 rules_jq_dependencies()
-jq_register_toolchains(name = "jq")
+
+jq_register_toolchains(
+    name = "jq",
+    jq_version = "1.6",
+)
 ```
-(resulting in a @jq//:jq binary or similar)
+
+The resulting JQ binary cannot be directly called, but can be used via `jq_eval()`
+(see example/eval) or as a Makefile-style variable (see example/genrule)
 
 ### bzlmod Modular Format
 

WORKSPACE

@@ -19,10 +19,11 @@ jq_register_toolchains(
     jq_version = "1.6",
 )
 
+load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
+
 ############################################
 # Gazelle, for generating bzl_library targets
 load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
-load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
 
 go_rules_dependencies()
 

example/eval/BUILD.bazel

@@ -1,5 +1,5 @@
-load("@bazel_skylib//rules:write_file.bzl", "write_file")
 load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
 load("//jq:defs.bzl", "jq_eval")
 
 jq_eval(

example/eval/sample.yaml

@@ -1,5 +1 @@
-{
-  "a": {
-    "b": "123"
-  }
-}
+{ "a": { "b": "123" } }

example/genrule/BUILD.bazel

@@ -1,5 +1,5 @@
-load("@bazel_skylib//rules:write_file.bzl", "write_file")
 load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
 
 genrule(
     name = "actual",

full-examples/README.md

@@ -0,0 +1,27 @@
+## Full Examples
+
+These examples are intended to show more completely how to use the `jq` rules: rather than just
+snippets of untested code that may bitrot over time, these examples are tested on each PR, and are
+nearly identical to what a consumer of the rules would use -- except that the local_repository()
+rule should be replaced with a http_archive() rule as documented in WORKSPACE (and MODULE.bazel if
+appropriate)
+
+Sure, the actual examples are those used as validation in the "example" directory, but I intend to
+add to them. ...and test on every PR (at least with a linux build on the latest bazel)
+
+## Running Full Examples
+
+with reference to the changes in ci.yaml, you can run a full-example as follows:
+
+```
+    (cd full-examples/basic && bazel build //...)
+```
+
+Of course, if you have an HTTP cache or federated bazel cache, you can reuse the work done in a
+build at the root workspace.
+
+## Ignored
+
+NOTE that the `full-examples` directory is ignored from a wildcard build: the `bazel-*` softlinks,
+and the recursive nature of the resulting tree-transversal after a build is done, becomes a really
+problematic endless loop. Don't remove them.

full-examples/basic/BUILD.bazel

@@ -0,0 +1,25 @@
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load("@rules_jq//jq:defs.bzl", "jq_eval")
+
+jq_eval(
+    name = "actual",
+    srcs = ["sample.yaml"],
+    filter = ".a.b",
+    raw_output = True,
+)
+
+write_file(
+    name = "expected",
+    out = "out.yaml",
+    content = [
+        "123",
+        "",
+    ],
+)
+
+diff_test(
+    name = "check_eval",
+    file1 = ":expected",
+    file2 = ":actual",
+)

full-examples/basic/WORKSPACE

@@ -0,0 +1,27 @@
+workspace(name = "basic")
+
+# When using in your project, this can be a direct cut-n-paste, however you should replace the
+# local_repository with a http_archive() block similar to the following, using the version and
+# sha256 matching your desired release
+#
+# load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+#
+# http_archive(
+#    name = "rules_jq",
+#    sha256 = "52771b5f7fb5017b0f5a3816b46624d2b9a336ddc178b261de988d969cd329d8",
+#    url = "https://github.com/jqlang/bazel_rules_jq/releases/download/0.0.1/bazel_rules_jq-v0.0.1.tar.gz",
+#)
+
+local_repository(
+    name = "rules_jq",
+    path = "../..",
+)
+
+load("@rules_jq//jq:repositories.bzl", "jq_register_toolchains", "rules_jq_dependencies")
+
+rules_jq_dependencies()
+
+jq_register_toolchains(
+    name = "jq",
+    jq_version = "1.6",
+)

full-examples/basic/sample.yaml

@@ -0,0 +1 @@
+{ "a": { "b": "123" } }

jq/private/rules/eval.bzl

@@ -1,6 +1,5 @@
 "jq_eval rule"
 
-load("@bazel_skylib//lib:collections.bzl", "collections")
 load("@bazel_skylib//lib:shell.bzl", "shell")
 
 _DOC = "Defines a jq eval execution."