Merge branch 'json_out'

Author: ibabushkin

README.md

@@ -107,6 +107,8 @@ Options:
                         Do not activate the `default` feature
         --compact       Only output the suggested version on stdout for
                         further processing
+    -j, --json          Output a JSON-formatted description of all collected
+                        data on stdout.
     -s, --stable-path PATH
                         use local path as stable/old crate
     -c, --current-path PATH
@@ -142,6 +144,92 @@ cargo semver | tee semver_out
 Make sure you do the above with access to a nightly toolchain. Check your CI provider's
 documentation on how to do that.
 
+### JSON output
+
+By passing the `-j` flag, all output on standard out is formatted as a machine-readable
+JSON blob. This can be useful for integration with other tools, and always generates all
+possible output (ignoring other output-related flags). The output format is defined as
+follows:
+
+The top level object contains the keys `old_version`, `new_version` and `changes`. The
+former two hold a version number in the format `major.minor.patch`, the latter an object
+describing changes between the crate versions, which contains two arrays in the keys
+`path_changes` and `changes`.
+
+The `path_changes` array contains objects describing item additions and removals, which
+have the following keys:
+
+* `name`: The name of the item.
+* `def_span`: An object describing the location of the item in one of the crates.
+* `additions`: An array of spans that describe locations where the item has been added.
+* `removals`: An array of spans that describe locations where the item has been removed.
+
+An example object might look like this:
+
+```json
+{
+  "name": "NFT_META_CGROUP",
+  "def_span": {
+    "file": "/path/to/libc-0.2.48/src/unix/notbsd/linux/other/mod.rs",
+    "line_lo": 776,
+    "line_hi": 776,
+    "col_lo": 0,
+    "col_hi": 40
+  },
+  "additions": [
+    {
+      "file": "/path/to/libc-0.2.48/src/lib.rs",
+      "line_lo": 195,
+      "line_hi": 195,
+      "col_lo": 16,
+      "col_hi": 23
+    }
+  ],
+  "removals": []
+}
+```
+
+
+The `changes` array contains objects describing all other changes, which have the
+following keys:
+
+* `name`: The name of the item
+* `max_category`: the most severe change category for this item, as a string.
+  * Possible values are `Patch`, `NonBreaking`, `TechnicallyBreaking`, and `Breaking`.
+* `new_span`: an object describing the location of the item in the new crate (see example).
+* `changes`: an array of 2-element sequences containing an error message and an optional
+  sub-span (`null` if none is present)
+
+An example object might look like this:
+
+```json
+{
+  "name": "<new::util::enumerate::Enumerate<T> as new::prelude::Stream>",
+  "max_category": "TechnicallyBreaking",
+  "new_span": {
+    "file": "/path/to/tokio-0.1.17/src/util/enumerate.rs",
+    "line_lo": 46,
+    "line_hi": 63,
+    "col_lo": 0,
+    "col_hi": 1
+  },
+  "changes": [
+    [
+      "trait impl generalized or newly added",
+      null
+    ]
+  ]
+}
+```
+
+For reference, all objects describing spans have the same keys:
+
+* `file`: A file name.
+* `line_lo`: The line the span starts on.
+* `line_hi`: The line the span ends on.
+* `col_lo`: The column the span starts on.
+* `col_hi`: The column the span ends on.
+
 ## Functionality
 
 The guideline used to implement semver compatibility is the [API evolution

src/bin/cargo_semver.rs

@@ -107,6 +107,7 @@ fn run(config: &cargo::Config, matches: &getopts::Matches) -> Result<()> {
 
     let explain = matches.opt_present("e");
     let compact = matches.opt_present("compact");
+    let json = matches.opt_present("json");
 
     // Obtain WorkInfo for the "current"
     let current = if let Some(name_and_version) = matches.opt_str("C") {
@@ -122,6 +123,7 @@ fn run(config: &cargo::Config, matches: &getopts::Matches) -> Result<()> {
     };
     let name = current.package.name().to_owned();
 
+    // TODO: JSON output here
     if matches.opt_present("show-public") {
         let (current_rlib, current_deps_output) =
             current.rlib_and_dep_output(config, &name, true, matches)?;
@@ -224,6 +226,7 @@ fn run(config: &cargo::Config, matches: &getopts::Matches) -> Result<()> {
         .env("RUST_SEMVER_CRATE_VERSION", stable_version)
         .env("RUST_SEMVER_VERBOSE", format!("{}", explain))
         .env("RUST_SEMVER_COMPACT", format!("{}", compact))
+        .env("RUST_SEMVER_JSON", format!("{}", json))
         .env(
             "RUST_SEMVER_API_GUIDELINES",
             if matches.opt_present("a") {
@@ -308,6 +311,11 @@ mod cli {
             "compact",
             "Only output the suggested version on stdout for further processing",
         );
+        opts.optflag(
+            "j",
+            "json",
+            "Output a JSON-formatted description of all collected data on stdout.",
+        );
         opts.optopt(
             "s",
             "stable-path",

src/bin/rust_semverver.rs

@@ -46,6 +46,8 @@ fn main() {
                         env::var("RUST_SEMVER_VERBOSE") == Ok("true".to_string());
                     let compact =
                         env::var("RUST_SEMVER_COMPACT") == Ok("true".to_string());
+                    let json =
+                        env::var("RUST_SEMVER_JSON") == Ok("true".to_string());
                     let api_guidelines =
                         env::var("RUST_SEMVER_API_GUIDELINES") == Ok("true".to_string());
                     let version = if let Ok(ver) = env::var("RUST_SEMVER_CRATE_VERSION") {
@@ -81,7 +83,11 @@ fn main() {
                         if let [(_, old_def_id), (_, new_def_id)] = *crates.as_slice() {
                             debug!("running semver analysis");
                             let changes = run_analysis(tcx, old_def_id, new_def_id);
-                            changes.output(tcx.sess, &version, verbose, compact, api_guidelines);
+                            if json {
+                                changes.output_json(tcx.sess, &version);
+                            } else {
+                                changes.output(tcx.sess, &version, verbose, compact, api_guidelines);
+                            }
                         } else {
                             tcx.sess.err("could not find `old` and `new` crates");
                         }