feat: add JSON format versioning (#657)

* feat: add JSON format versioning

* docs: bump snippets, add PR

docs/release-notes.md

@@ -27,6 +27,9 @@ of `zizmor`.
 * The [cache-poisoning] audit is now aware of @jdx/mise-action (#645)
 * The [cache-poisoning] audit is now significantly more accurate
   when analyzing workflows that use @docker/setup-buildx-action (#644)
+* `--format=json` is now an alias for `--format=json-v1`, enabling
+  future JSON formats. The policy for the `--format=json` alias is
+  documented under [Output formats - JSON](./usage.md#json) (#657)
 
 ### Bug Fixes 🐛
 
@@ -52,7 +55,7 @@ of `zizmor`.
 
 ### Upcoming Changes 🚧
 
-* The official [PyPI builds](./installation.md/#pypi) for `zizmor`
+* The official [PyPI builds](./installation.md#pypi) for `zizmor`
   will support fewer architectures in the next release, due to
   cross-compilation and testing difficulties. This should have
   **no effect** on the overwhelming majority of users.

docs/snippets/help.txt

@@ -25,7 +25,7 @@ Options:
       --no-progress
           Don't show progress bars, even if the terminal supports them
       --format <FORMAT>
-          The output format to emit. By default, cargo-style diagnostics will be emitted [default: plain] [possible values: plain, json, sarif, github]
+          The output format to emit. By default, cargo-style diagnostics will be emitted [default: plain] [possible values: plain, json, json-v1, sarif, github]
       --color <MODE>
           Control the use of color in output [possible values: auto, always, never]
   -c, --config <CONFIG>

docs/usage.md

@@ -135,12 +135,26 @@ This format can also be explicitly selected with `--format=plain`:
 
 !!! important
 
-    The JSON format is currently a flat array of findings, and is not
-    currently versioned.
+    The JSON format is versioned, and `--format=json` is an alias for the
+    current version.
 
-    Future versions of `zizmor` may change the top-level structure of the
-    JSON output,
+    The current version of the JSON format is `v1`. You can use
+    `--format=json-v1` to explicitly select the current version.
 
+    The following compatibility policy is used for JSON format versions:
+
+    1. The current version of the format is always aliased as `json`.
+    2. When a new version of the JSON format is added, `--format=json`
+       will show a deprecation warning, and will transition to the new version
+       with the next major release.
+    3. When a new version of the JSON format is added, explicit uses of the
+       old version will show a deprecation warning.
+    4. The old version will be removed in the *subsequent* major release
+       (i.e., the major release after the one that transitions the `json` alias).
+
+!!! important
+
+    `--format=json-v1` is available in `v1.6.0` and later.
 
 With `--format=json`, `zizmor` will produce a flat array of findings in
 JSON format:

src/main.rs

@@ -139,8 +139,13 @@ pub(crate) enum OutputFormat {
     /// cargo-style output.
     #[default]
     Plain,
-    /// JSON-formatted output.
+    // NOTE: clap doesn't support visible aliases for enum variants yet,
+    // so we need an explicit Json variant here.
+    // See: https://github.com/clap-rs/clap/pull/5480
+    /// JSON-formatted output (currently v1).
     Json,
+    /// "v1" JSON format.
+    JsonV1,
     /// SARIF-formatted output.
     Sarif,
     /// GitHub Actions workflow command-formatted output.
@@ -538,7 +543,9 @@ fn run() -> Result<ExitCode> {
 
     match app.format {
         OutputFormat::Plain => output::plain::render_findings(&app, &registry, &results),
-        OutputFormat::Json => serde_json::to_writer_pretty(stdout(), &results.findings())?,
+        OutputFormat::Json | OutputFormat::JsonV1 => {
+            serde_json::to_writer_pretty(stdout(), &results.findings())?
+        }
         OutputFormat::Sarif => {
             serde_json::to_writer_pretty(stdout(), &output::sarif::build(results.findings()))?
         }