Implement an install command (#654)

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

Author: jviotti

.github/workflows/package.yml

@@ -69,7 +69,7 @@ jobs:
     steps:
       - name: Install dependencies (Alpine)
         if: matrix.platform.type == 'container'
-        run: apk add --no-cache cmake make g++ zsh bash jq pipx git
+        run: apk add --no-cache cmake make g++ zsh bash jq pipx git perl-utils
 
       - name: Install pre-commit
         run: pipx install pre-commit

.github/workflows/test.yml

@@ -69,7 +69,7 @@ jobs:
 
       - name: Install dependencies (Alpine)
         if: matrix.platform.type == 'container'
-        run: apk add --no-cache cmake make g++ zsh bash jq shellcheck pipx git
+        run: apk add --no-cache cmake make g++ zsh bash jq shellcheck pipx git perl-utils
 
       - name: Install pre-commit
         run: pipx install pre-commit

DEPENDENCIES

@@ -1,7 +1,7 @@
 vendorpull https://github.com/sourcemeta/vendorpull 1dcbac42809cf87cb5b045106b863e17ad84ba02
 core https://github.com/sourcemeta/core 1f1d7951e85a8d20badd1a64f739cbdf8d2baff8
 jsonbinpack https://github.com/sourcemeta/jsonbinpack 3898774a945ebf7392bad8a9015ead97a0518a19
-blaze https://github.com/sourcemeta/blaze 7019b65837396044116e21beecb264c47a2cd265
+blaze https://github.com/sourcemeta/blaze cb4ceae89411e939ae79d4cc6edf700e50efa93e
 hydra https://github.com/sourcemeta/hydra c5f9542519bce7b6ac90ec8638329ef53aa46450
 codegen https://github.com/sourcemeta/codegen 7733b3071cb140bc0d09406ebb9c3f306d71f7bf
 ctrf https://github.com/ctrf-io/ctrf 93ea827d951390190171d37443bff169cf47c808

Dockerfile.test.alpine

@@ -1,5 +1,5 @@
 FROM alpine:3.21
-RUN apk add --no-cache cmake make g++ zsh bash jq
+RUN apk add --no-cache cmake make g++ zsh bash jq perl-utils
 WORKDIR /src
 COPY CMakeLists.txt .
 COPY cmake cmake

README.markdown

@@ -86,10 +86,11 @@ documentation:
 - [`jsonschema codegen`](./docs/codegen.markdown) (for generating code from schemas)
 - [`jsonschema encode`](./docs/encode.markdown) (for binary compression)
 - [`jsonschema decode`](./docs/decode.markdown)
+- [`jsonschema install`](./docs/install.markdown) (for fetching external schema dependencies)
 
 > See [`jsonschema.json`](./docs/configuration.markdown) for an _experimental_
 manifest for describing JSON Schema data models inspired by NPM's
-`package.json`.
+`package.json`, including dependency management.
 
 Note that YAML is supported in most commands!
 

completion/jsonschema.bash

@@ -11,9 +11,9 @@ _jsonschema() {
     previous=""
   fi
 
-  commands="validate metaschema compile test fmt lint bundle inspect canonicalize encode decode codegen version help"
+  commands="validate metaschema compile test fmt lint bundle inspect canonicalize encode decode codegen install version help"
 
-  global_options="--verbose -v --resolve -r --default-dialect -d --json -j --http -h"
+  global_options="--verbose -v --resolve -r --default-dialect -d --json -j --http -h --debug -g"
 
   if [ "${COMP_CWORD}" -eq 1 ]
   then
@@ -173,6 +173,13 @@ _jsonschema() {
         COMPREPLY=( $(compgen -f -X '!*.json' -X '!*.yaml' -X '!*.yml' -- "${current}") )
       fi
       ;;
+    install)
+      local options="--force -f"
+      if [[ ${current} == -* ]]
+      then
+        COMPREPLY=( $(compgen -W "${options} ${global_options}" -- "${current}") )
+      fi
+      ;;
     version|help)
       COMPREPLY=()
       ;;

completion/jsonschema.zsh

@@ -19,6 +19,7 @@ _jsonschema() {
     'encode:Encode JSON using JSON BinPack'
     'decode:Decode JSON using JSON BinPack'
     'codegen:Generate code from a JSON Schema'
+    'install:Fetch and install external schema dependencies'
     'version:Print version information'
     'help:Print help information'
   )
@@ -30,6 +31,7 @@ _jsonschema() {
     '(--default-dialect -d)'{--default-dialect,-d}'[Specify default dialect URI]:dialect URI:_jsonschema_dialects'
     '(--json -j)'{--json,-j}'[Prefer JSON output if supported]'
     '(--http -h)'{--http,-h}'[Enable HTTP resolution]'
+    '(--debug -g)'{--debug,-g}'[Enable debug output]'
   )
 
   _arguments -C \
@@ -140,6 +142,11 @@ _jsonschema() {
             '(--target -t)'{--target,-t}'[Specify target language]:target:(typescript)' \
             '1:schema file:_files -g "*.json *.yaml *.yml"'
           ;;
+        install)
+          _arguments \
+            ${global_options[@]} \
+            '(--force -f)'{--force,-f}'[Re-fetch all dependencies]'
+          ;;
         version|help)
           ;;
       esac

docs/configuration.markdown

@@ -50,6 +50,7 @@ describes the available configuration options:
 | `defaultDialect` | String | The default JSON Schema dialect to use when a schema doesn't specify `$schema` | - |
 | `extension` | String / String[] | The schema extension/s used by the project | `.json` / `.yaml` / `.yml` |
 | `resolve` | Object | A mapping of URIs to local file paths or other URIs for schema resolution remapping | `{}` |
+| `dependencies` | Object | A mapping of URIs to relative file paths for external schema dependencies to install (see [`jsonschema install`](./install.markdown)) | `{}` |
 
 Lookup Algorithm
 ----------------

docs/install.markdown

@@ -0,0 +1,72 @@
+Installing Dependencies
+=======================
+
+```sh
+jsonschema install
+  [--force/-f] [--verbose/-v] [--debug/-g] [--json/-j]
+```
+
+Many applications rely on consuming schemas authored and maintained by others.
+These schemas are typically published over HTTP(S) through registries like
+[schemas.sourcemeta.com](https://schemas.sourcemeta.com) (a free public
+registry) or self-hosted solutions like [Sourcemeta
+One](https://one.sourcemeta.com). While you could manually download these
+schemas or write a custom fetching script, doing so quickly gets complicated:
+schemas often reference other schemas that also need to be fetched, and the
+results need to be
+[bundled](https://json-schema.org/blog/posts/bundling-json-schema-compound-documents)
+to inline those references for local consumption. The `install` command solves
+this in a single step.
+
+To get started, create a
+[`jsonschema.json`](./configuration.markdown) configuration file in your
+project and declare your dependencies as a mapping of schema URIs to local file
+paths. For example, to pull in the [JSON-RPC 2.0
+Response](https://schemas.sourcemeta.com/sourcemeta/std/v0/jsonrpc/v2.0/response)
+schema from the public registry:
+
+```json
+{
+  "dependencies": {
+    "https://schemas.sourcemeta.com/sourcemeta/std/v0/jsonrpc/v2.0/response": "./vendor/response.json"
+  }
+}
+```
+
+Then run `jsonschema install`. Each dependency is fetched, bundled, and written
+to the specified path. A `jsonschema.lock.json` lock file is created alongside
+`jsonschema.json` to record the hash of each installed dependency. On
+subsequent runs, only dependencies that are missing, modified, or not yet
+tracked in the lock file are fetched again.
+
+> [!TIP]
+> We recommend committing `jsonschema.lock.json` to version control (similar to
+> `package-lock.json`) to enable reproducible installs across environments.
+
+> [!WARNING]
+> If a dependency uses a custom meta-schema that is itself an external
+> dependency, make sure to list both the meta-schema and the schema that uses
+> it in the `dependencies` map. The install command will resolve the
+> meta-schema during bundling regardless of processing order. We are working
+> on resolving this automatically in a future release.
+
+Examples
+--------
+
+### Install all dependencies
+
+```sh
+jsonschema install
+```
+
+### Force re-fetch all dependencies
+
+```sh
+jsonschema install --force
+```
+
+### Install with verbose output
+
+```sh
+jsonschema install --verbose
+```

src/CMakeLists.txt

@@ -12,7 +12,8 @@ add_executable(jsonschema_cli
   command_decode.cc
   command_compile.cc
   command_canonicalize.cc
-  command_codegen.cc)
+  command_codegen.cc
+  command_install.cc)
 
 sourcemeta_add_default_options(PRIVATE jsonschema_cli)
 set_target_properties(jsonschema_cli PROPERTIES OUTPUT_NAME jsonschema)