Explicitly version the JSON schema

We now include a `"version": "X.Y.Z"` entry in the top-level JSON map that gets
generated for each MIR JSON file, where `X.Y.Z` represents the version of the
JSON schema that is used to generate the file. Going forward, any changes to
the JSON schema will be accompanied by a corresponding schema version bump
according to the version bumping principles laid out in [Semantic
Versioning](https://semver.org/).

Fixes #45.

Cargo.toml

@@ -18,6 +18,7 @@ cargo_metadata = { version = "0.14.2" }
 cargo = { version = "0.62", features = [ "vendored-openssl" ] }
 toml_edit = { version = "0.13.4", features = [ "easy" ] }
 clap = "3.1.0"
+semver = "1.0.23"
 
 [[bin]]
 name = "cargo-crux-test"

README.md

@@ -36,5 +36,21 @@ book](https://doc.rust-lang.org/book/2018-edition/ch01-01-installation.html)).
 
 See the [crux-mir][crux-mir-repo] README for usage instructions.
 
+## JSON schema
+
+`mir-json` and related tools produce MIR JSON files as output, which the
+contain the intermediate MIR code from the compiled program in a
+machine-readable format. Downstream tools are sensitive to the particular
+schema that a MIR JSON file uses, so we explicitly record the version of the
+JSON schema in each MIR JSON file (in the `"version"` field).
+
+Any time that `mir-json` is updated such that the JSON schema must also be
+changed, we will also update the schema version number. This version number
+follows [Semantic Versioning](https://semver.org/). As such, an update to the
+major version constitutes a backwards-incompatible change to the JSON schema,
+and an update to the minor version constitutes a backwards-compatible addition
+to the schema. (The patch number is not currently used.) Each change to the
+schema is described in the [`SCHEMA_VERSIONING.md`](SCHEMA_VERSIONING.md) file.
+
 
 [crux-mir-repo]: https://github.com/GaloisInc/crucible/tree/master/crux-mir

SCHEMA_CHANGELOG.md

@@ -0,0 +1,8 @@
+The following document describes the changes to the JSON schema that
+`mir-json`–produced files adhere to. (This document should not be interpreted
+as a changelog for the code in the `mir-json` tools themselves, which are
+versioned separately.)
+
+## 0.1.0
+
+Initial schema version.

src/analyz/mod.rs

@@ -32,6 +32,7 @@ mod ty_json;
 use analyz::to_json::*;
 use analyz::ty_json::*;
 use lib_util::{self, JsonOutput, EntryKind};
+use schema_ver::SCHEMA_VER;
 
 basic_json_enum_impl!(mir::BinOp);
 
@@ -1168,6 +1169,7 @@ pub fn analyze_nonstreaming<'tcx>(
     let total_items = out.fns.len() + out.adts.len() + out.statics.len() + out.vtables.len() +
         out.traits.len() + out.intrinsics.len();
     let j = json!({
+        "version": SCHEMA_VER.to_string(),
         "fns": out.fns,
         "adts": out.adts,
         "statics": out.statics,

src/lib.rs

@@ -1,6 +1,7 @@
 #![feature(rustc_private)]
 #![feature(never_type)]
 
+extern crate semver;
 extern crate serde;
 #[macro_use] extern crate serde_json;
 extern crate serde_cbor;
@@ -24,5 +25,6 @@ extern crate rustc_target;
 pub mod analyz;
 pub mod lib_util;
 pub mod link;
+pub mod schema_ver;
 
 mod tar_stream;

src/lib_util.rs

@@ -28,6 +28,7 @@ use serde_cbor;
 use serde_json;
 use tar;
 
+use crate::schema_ver::SCHEMA_VER;
 use crate::tar_stream::{TarStream, TarEntryStream};
 
 #[derive(Debug, Default, Serialize, Deserialize)]
@@ -296,6 +297,7 @@ impl<W: Write> Emitter<W> {
 
     pub fn emit_crate(&mut self, j: &JsonValue) -> io::Result<()> {
         write!(self.writer, "{{")?;
+        write!(self.writer, "\"version\":{:?},", SCHEMA_VER.to_string())?;
         self.emit_table_from(EntryKind::Fn, j)?;
         write!(self.writer, ",")?;
         self.emit_table_from(EntryKind::Adt, j)?;

src/link.rs

@@ -5,6 +5,7 @@ use serde_cbor;
 use serde_json;
 
 use crate::lib_util::{self, CrateIndex, InternTable, EntryKind, StringId};
+use crate::schema_ver::SCHEMA_VER;
 
 
 fn read_crates<R: Read + Seek>(
@@ -117,6 +118,7 @@ where R: Read + Seek, W: Write {
 
     // Write tables to the output, copying the serialized content of each entry.
     write!(output, "{{")?;
+    write!(output, "\"version\":{:?},", SCHEMA_VER.to_string())?;
     for (i, kind) in EntryKind::each().enumerate() {
         if i > 0 {
             write!(output, ",")?;

src/schema_ver.rs

@@ -0,0 +1,13 @@
+use semver::Version;
+
+/// The version of the JSON schema that `mir-json` follows. This is intended for
+/// use by downstream tools to quickly determine if they are ingesting a MIR
+/// JSON file that is compatible with the version of the schema that they are
+/// expecting.
+///
+/// This version number follows [Semantic Versioning](https://semver.org/). As
+/// such, an update to the major version constitutes a backwards-incompatible
+/// change to the JSON schema, and an update to the minor version constitutes
+/// a backwards-compatible addition to the schema. (The patch number is not
+/// currently used.)
+pub const SCHEMA_VER: Version = Version::new(1, 0, 0);