[ADF-3230] Changes to stop doc tools from updating files unnecessarily (#3519)

* [ADF-3230] Added basic change detector to doc tools

* [ADF-3230] Updates to type linker to fix before/after inconsistencies

* [ADF-3230] Fixed comparison error caused by adjacent text blocks

* [ADF-3230] Added basic change detector to doc tools

* [ADF-3230] Updates to type linker to fix before/after inconsistencies

* [ADF-3230] Fixed comparison error caused by adjacent text blocks

* [ADF-3230] Modified props tool to remove spaces from union types

* [ADF-3230] Made ToC tool before/after state consistent

tools/doc/docProcessor.js

@@ -1,11 +1,13 @@
 var fs = require("fs");
 var path = require("path");
 var program = require("commander");
+var lodash = require("lodash");
 
 var remark = require("remark");
 var parse = require("remark-parse");
 var stringify = require("remark-stringify");
 var frontMatter = require("remark-frontmatter");
+var mdCompact = require("mdast-util-compact");
 
 
 // "Aggregate" data collected over the whole file set.
@@ -51,14 +53,16 @@ function updatePhase(filenames, aggData) {
 
     for (var i = 0; i < filenames.length; i++) {
         errorMessages = [];
-        var pathname = filenames[i]; // path.resolve(srcFolder, filenames[i]);
+        var pathname = filenames[i];
         
         if (program.verbose) {
-            console.log(pathname);
+            console.log("Reading " + pathname);
         }
         
         var src = fs.readFileSync(pathname);
-        var tree = remark().use(frontMatter, ["yaml"]).parse(src)
+        var tree = remark().use(frontMatter, ["yaml"]).parse(src);
+
+        var original = minimiseTree(tree);
 
         var modified = false;
 
@@ -70,17 +74,45 @@ function updatePhase(filenames, aggData) {
             showErrors(pathname, errorMessages);
         }
 
+        tree = minimiseTree(tree);
+       
         if (program.json) {
+            let filename = path.basename(pathname);
+
+            console.log(`\nFile "${filename}" before processing:`);
+            console.log(JSON.stringify(original));
+            console.log(`\nFile "${filename}" after processing:`);
             console.log(JSON.stringify(tree));
         }
+        
+        modified = !lodash.isEqual(tree, original);
 
         if (modified) {
+            if (program.verbose) {
+                console.log(`Modified: ${pathname}`);
+            }
+
             fs.writeFileSync(filenames[i], remark().use(frontMatter, {type: 'yaml', fence: '---'}).data("settings", {paddedTable: false, gfm: false}).stringify(tree));
         }
     }
 }
 
 
+function deepCopy(obj) {
+    // Despite how it looks, this technique is apparently quite efficient
+    // because the JSON routines are implemented in C code and faster
+    // than the equivalent JavaScript loops ;-)
+    return JSON.parse(JSON.stringify(obj));
+}
+
+
+function minimiseTree(tree) {
+    let minPropsTree = JSON.parse(JSON.stringify(tree, (key, value) => key === "position" ? undefined : value));
+    mdCompact(minPropsTree);
+    return minPropsTree;
+}
+
+
 function showErrors(filename, errorMessages) {
     console.log(filename);