#540 Add a version to the serialized graph

When changing the structure of a PatternGraph, users might still have an old version, so we need to rebuild all patterns and the whole graph.

Author: Tobias Brennecke

core/lib/pattern_graph.js

@@ -9,6 +9,13 @@ const CompileState = require('./object_factory').CompileState;
 const PatternGraphDot = require('./pattern_graph_dot');
 const PatternRegistry = require('./pattern_registry');
 
+/**
+ * The most recent version of the pattern graph. This is used to rebuild the graph when
+ * the version of a serialized graph does not match the current version.
+ * @type {number}
+ */
+const PATTERN_GRAPH_VERSION = 1;
+
 /**
  * Wrapper around a graph library to build a dependency graph of patterns.
  * Each node in the graph will maintain a {@link CompileState}. This allows finding all
@@ -21,13 +28,14 @@ const PatternRegistry = require('./pattern_registry');
  *
  * @param {Graph} graph  The graphlib graph object
  * @param {int} timestamp The unix timestamp
+ * @param {int} version The graph version.
  *
  * @returns {{PatternGraph: PatternGraph}}
 
  * @see PatternGraph#fromJson
  * @see <a href="https://github.com/pattern-lab/patternlab-node/issues/540">#540</a>
  */
-const PatternGraph = function (graph, timestamp) {
+const PatternGraph = function (graph, timestamp, version) {
 
   this.graph = graph || new Graph({
     directed: true
@@ -38,6 +46,7 @@ const PatternGraph = function (graph, timestamp) {
   // The idea here is to make a pattern known to the graph as soon as it exists
   this.patterns = new PatternRegistry();
   this.timestamp = timestamp || new Date().getTime();
+  this.version = version || PATTERN_GRAPH_VERSION;
 };
 
 // shorthand. Use relPath as it is always unique, even with subPatternType
@@ -53,7 +62,7 @@ PatternGraph.prototype = {
   clone: function () {
     const json = graphlib.json.write(this.graph);
     const graph = graphlib.json.read(json);
-    return new PatternGraph(graph, this.timestamp);
+    return new PatternGraph(graph, this.timestamp, this.version);
   },
 
   /**
@@ -267,6 +276,7 @@ PatternGraph.prototype = {
    */
   toJson: function () {
     return {
+      version: this.version,
       timestamp: this.timestamp,
       graph: graphlib.json.write(this.graph)
     };
@@ -277,26 +287,56 @@ PatternGraph.prototype = {
    */
   nodes: function () {
     return this.graph.nodes();
+  },
+
+  /**
+   * Updates the version to the most recent one
+   */
+  upgradeVersion: function () {
+    this.version = PATTERN_GRAPH_VERSION;
   }
 };
 
 /**
  * Creates an empty graph with a unix timestamp of 0 as last compilation date.
- *
+ * @param {int} [version=PATTERN_GRAPH_VERSION]
  * @return {PatternGraph}
  */
-PatternGraph.empty = function () {
-  return new PatternGraph(null, 0);
+PatternGraph.empty = function (version) {
+  return new PatternGraph(null, 0, version || PATTERN_GRAPH_VERSION);
+};
+
+/**
+ * Checks if the version of
+ * @param {PatternGraph|Object} graphOrJson
+ * @return {boolean}
+ */
+PatternGraph.checkVersion = function(graphOrJson) {
+  return graphOrJson.version === PATTERN_GRAPH_VERSION;
 };
 
+/**
+ * Error that is thrown if the given version does not match the current graph version.
+ *
+ * @param oldVersion
+ * @constructor
+ */
+function VersionMismatch(oldVersion) {
+  this.message = `Version of graph on disk ${oldVersion} != current version ${PATTERN_GRAPH_VERSION}. Please clean your patterns output directory.`;
+  this.name = "VersionMismatch";
+}
+
 /**
  * Parse the graph from a JSON object.
  * @param {object} o The JSON object to read from
  * @return {PatternGraph}
  */
 PatternGraph.fromJson = function (o) {
+  if (!PatternGraph.checkVersion(o)) {
+    throw new VersionMismatch(o.version);
+  }
   const graph = graphlib.json.read(o.graph);
-  return new PatternGraph(graph, o.timestamp);
+  return new PatternGraph(graph, o.timestamp, o.version);
 };
 
 /**
@@ -328,6 +368,9 @@ PatternGraph.loadFromFile = function (patternlab, file) {
   }
 
   const obj = fs.readJSONSync(jsonGraphFile);
+  if (!PatternGraph.checkVersion(obj)) {
+    return PatternGraph.empty(obj.version)
+  }
   return this.fromJson(obj);
 };
 
@@ -356,5 +399,6 @@ PatternGraph.exportToDot = function (patternlab, file) {
 };
 
 module.exports = {
-  PatternGraph: PatternGraph
+  PatternGraph: PatternGraph,
+  PATTERN_GRAPH_VERSION: PATTERN_GRAPH_VERSION
 };

core/lib/patternlab.js

@@ -513,8 +513,17 @@ var patternlab_engine = function (config) {
 
     let patternsToBuild = patternlab.patterns;
 
+    let graphNeedsUpgrade = !PatternGraph.checkVersion(patternlab.graph);
+    // Incremental builds are enabled, but we cannot use them
+    if (!deletePatternDir && graphNeedsUpgrade) {
+      plutils.log.info("Due to an upgrade, a complete rebuild is required. " +
+        "Incremental build is available again on the next run.");
+      // Ensure that the freshly built graph has the latest version again.
+      patternlab.graph.upgradeVersion();
+    }
     //delete the contents of config.patterns.public before writing
-    if (deletePatternDir) {
+    //Also if the serialized graph must be updated
+    if (deletePatternDir || graphNeedsUpgrade) {
       fs.removeSync(paths.public.patterns);
       fs.emptyDirSync(paths.public.patterns);
     } else {

test/pattern_graph_tests.js

@@ -2,6 +2,7 @@
 
 
 var PatternGraph = require('../core/lib/pattern_graph').PatternGraph;
+var VERSION = require('../core/lib/pattern_graph').PATTERN_GRAPH_VERSION;
 var Pattern = require('../core/lib/object_factory').Pattern;
 var CompileState = require('../core/lib/object_factory').CompileState;
 var tap = require('tap');
@@ -20,6 +21,16 @@ var mockGraph = function () {
   return PatternGraph.empty();
 };
 
+tap.test("checkVersion - Current version returns true", (test) => {
+  test.same(PatternGraph.checkVersion({"version": VERSION}), true);
+  test.end();
+});
+
+tap.test("checkVersion - Older version returns false", (test) => {
+  test.same(PatternGraph.checkVersion({"version": VERSION - 1}), false);
+  test.end();
+});
+
 tap.test("Loading an empty graph works", (test) => {
   var g = PatternGraph.loadFromFile(patternlab, "does not exist");
   tap.equal(g.graph.nodes().length, 0,"foo");
@@ -34,6 +45,14 @@ tap.test("PatternGraph.fromJson() - Loading a graph from JSON", (test) => {
   test.end();
 });
 
+tap.test("PatternGraph.fromJson() - Loading a graph from JSON using an older version throws error", (test) => {
+  test.throws(function () {
+    PatternGraph.fromJson({version: 0});
+  }, {}, /Version of graph on disk.*/g);
+
+  test.end();
+});
+
 tap.test("toJson() - Storing a graph to JSON correctly", (test) => {
   var graph = mockGraph();
   graph.timestamp = 1337;
@@ -43,7 +62,7 @@ tap.test("toJson() - Storing a graph to JSON correctly", (test) => {
   graph.add(moleculeFoo);
   graph.link(moleculeFoo, atomFoo);
   test.same(graph.toJson(),
-  {"timestamp":1337,"graph":{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"atom-foo","value":{"compileState":"clean"}},{"v":"molecule-foo","value":{"compileState":"clean"}}],"edges":[{"v":"molecule-foo","w":"atom-foo","value":{}}]}});
+  {"version": VERSION, "timestamp":1337,"graph":{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"atom-foo","value":{"compileState":"clean"}},{"v":"molecule-foo","value":{"compileState":"clean"}}],"edges":[{"v":"molecule-foo","w":"atom-foo","value":{}}]}});
   // For generating the above output:console.log(JSON.stringify(graph.toJson()));
   test.end();
 });
@@ -61,6 +80,7 @@ tap.test("Storing and loading a graph from JSON return the identical graph", (te
   var newGraph = PatternGraph.fromJson(oldGraph.toJson());
 
   // assert
+  test.same(newGraph.version, VERSION);
   test.same(newGraph.timestamp, 1337);
   test.same(newGraph.graph.nodes(), ["atom-foo", "molecule-foo"]);
   test.same(newGraph.graph.edges(), [ {w: "atom-foo", v:"molecule-foo"}]);
@@ -83,6 +103,7 @@ tap.test("clone()", (test) => {
   var newGraph = oldGraph.clone();
 
   // assert
+  test.same(newGraph.version, VERSION);
   test.same(newGraph.timestamp, 1337);
   test.same(newGraph.graph.nodes(), ["atom-foo", "molecule-foo"]);
   test.same(newGraph.graph.edges(), [ {w: "atom-foo", v:"molecule-foo"}]);

test/public/testDependencyGraph.json

@@ -1 +1 @@
-{"timestamp":1337,"graph":{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"atom-foo","value":{"compileState":"clean"}},{"v":"molecule-foo","value":{"compileState":"clean"}}],"edges":[{"v":"molecule-foo","w":"atom-foo","value":{}}]}}
+{"version":1,"timestamp":1337,"graph":{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"atom-foo","value":{"compileState":"clean"}},{"v":"molecule-foo","value":{"compileState":"clean"}}],"edges":[{"v":"molecule-foo","w":"atom-foo","value":{}}]}}