[FEATURE] Present information in https://catalystcode.github.io/spk/commands on changes in commands between releases

docs/commands/change-rels.js

@@ -0,0 +1,330 @@
+/* eslint-disable */
+var changeTemplate =
+  '<div class="change-container"><div class="change-header" id="change_rel_@@id-version@@">@@version@@</div><div class="change-content">@@changes@@</div></div>';
+var commandAddedTemplate =
+  '<div class="change-item-header">Commands Added</div><ul class="change-list">@@changes@@</ul>';
+var commandRemovedTemplate =
+  '<div class="change-item-header">Commands Removed</div><ul class="change-list">@@changes@@</ul>';
+var commandValueChangedTemplate =
+  '<div class="change-option-header">Command Values Changed</div><ul class="change-list">@@changes@@</ul>';
+var optionAddedTemplate =
+  '<div class="change-option-header">Options Added</div><ul class="change-list">@@changes@@</ul>';
+var optionRemovedTemplate =
+  '<div class="change-option-header">Options Removed</div><ul class="change-list">@@changes@@</ul>';
+var optionChangedTemplate =
+  '<div class="change-option-header">Options Changed</div><ul class="change-list">@@changes@@</ul>';
+
+/**
+ * Returns variable name associate with an argument.
+ * e.g. --service-principal-id -> servicePrincipalId
+ * @param arg arugment
+ */
+function argToVariableName(arg) {
+  var match = arg.match(/\s?--([-\w]+)\s?/);
+  if (match) {
+    return match[1]
+      .replace(/\.?(-[a-z])/g, (_, y) => {
+        return y.toUpperCase();
+      })
+      .replace(/-/g, "");
+  }
+  return null;
+}
+
+/**
+ * Compare two versions to figure out what new commands are added
+ *
+ * @param prev Previous version
+ * @param cur  Current version
+ */
+function compareVersionDiff(prev, cur) {
+  var prevKeys = Object.keys(prev);
+  var results = Object.keys(cur).filter(function (k) {
+    return prevKeys.indexOf(k) === -1;
+  });
+  return results.length > 0 ? results : undefined;
+}
+
+/**
+ * Compare two set of options in the same command to figure out what new options are added.
+ *
+ * @param prev set of options in the same command in previous release
+ * @param cur  set of options in the same command in current release
+ */
+function compareArgsDiff(prev, cur) {
+  var prevKeys = prev.map(function (opt) {
+    return opt.arg;
+  });
+
+  return cur
+    .filter(function (opt) {
+      return prevKeys.indexOf(opt.arg) === -1;
+    })
+    .map(function (opt) {
+      return opt.arg;
+    });
+}
+
+/**
+ * Compare two set of options in the same command to figure out the changes.
+ * New options added, Option removed, Option args changed.
+ *
+ * @param prev set of options in the same command in previous release
+ * @param cur  set of options in the same command in current release
+ */
+function compareArgsChanged(prev, cur) {
+  var optionsPrev = prev.options || [];
+  var optionsCur = cur.options || [];
+  var changes = {};
+  var aliases = {};
+  var aliasChanged = [];
+  var aliasesRm = {};
+
+  var removed = compareArgsDiff(optionsCur, optionsPrev);
+  if (removed.length > 0) {
+    removed.forEach(function (r) {
+      var m = r.match(/^-([a-zA-Z]),\s/);
+      if (m) {
+        var varName = argToVariableName(r);
+        aliases[varName] = m[1];
+        aliasesRm[varName] = r;
+      }
+    });
+  }
+
+  // to figure out the change in options by comparing
+  // old vs new
+  var added = (compareArgsDiff(optionsPrev, optionsCur) || []).filter(function (
+    add
+  ) {
+    var m = add.match(/^-([a-zA-Z]),\s/);
+    if (m) {
+      var varName = argToVariableName(add);
+      if (varName in aliases) {
+        var idx = removed.indexOf(aliasesRm[varName]);
+        removed.splice(idx, 1);
+        aliasChanged.push(
+          'change "' + aliasesRm[varName] + '" to "' + add + '"'
+        );
+        return false;
+      }
+    }
+    return true;
+  });
+
+  if (removed.length > 0) {
+    changes.removed = removed;
+  }
+
+  if (added.length > 0) {
+    changes.added = added;
+  }
+
+  if (aliasChanged.length > 0) {
+    changes.changed = aliasChanged;
+  }
+
+  return Object.keys(changes).length > 0 ? changes : null;
+}
+
+/**
+ * Compare changes in two set of commands. one from previous
+ * release and one from current release
+ *
+ * @param prev set of commands from previous release
+ * @param cur set of commands from current release
+ */
+function compareVersionChanged(prev, cur) {
+  var changes = {};
+  var curKeys = Object.keys(cur);
+  var commonKeys = Object.keys(prev).filter(function (k) {
+    return curKeys.indexOf(k) !== -1;
+  });
+
+  commonKeys.forEach(function (k) {
+    var newCmd = cur[k];
+    var prevCmd = prev[k];
+    var modified = {};
+
+    if (newCmd.command !== prevCmd.command) {
+      modified["command"] = prevCmd.command + " to " + newCmd.command;
+    }
+
+    if (newCmd.alias !== prevCmd.alias) {
+      modified["alias"] = {
+        prev: prevCmd.alias,
+        newCmd: newCmd.alias,
+      };
+    }
+
+    var optChanges = compareArgsChanged(prevCmd, newCmd);
+
+    if (optChanges) {
+      modified.options = optChanges;
+    }
+
+    if (Object.keys(modified).length > 0) {
+      changes[k] = modified;
+    }
+  });
+
+  return Object.keys(changes).length > 0 ? changes : undefined;
+}
+
+/**
+ * Compare two releases/versions e.g. master against 0.6.0
+ *
+ * @param prev previous version number e.g. 0.5.8
+ * @param cur  current version number e.g. 0.5.9
+ */
+function compareVersion(prev, cur) {
+  var prevData = dataCache[prev];
+  var curData = dataCache[cur];
+  var data = {};
+
+  var added = compareVersionDiff(prevData, curData);
+  if (added) {
+    data.added = added;
+  }
+
+  var removed = compareVersionDiff(curData, prevData);
+  if (removed) {
+    data.removed = removed;
+  }
+
+  var changed = compareVersionChanged(prevData, curData);
+  if (changed) {
+    data.changed = changed;
+  }
+
+  return Object.keys(data).length > 0 ? data : undefined;
+}
+
+/**
+ * Returns HTML for each command change
+ *
+ * @param oChanges changes information
+ */
+function getChangesHTML(oChanges) {
+  changes = "";
+  if (oChanges.added) {
+    changes = commandAddedTemplate.replace(
+      "@@changes@@",
+      oChanges.added
+        .map(function (add) {
+          return "<li>spk " + sanitize(add) + "</li>";
+        })
+        .join("")
+    );
+  }
+  if (oChanges.removed) {
+    changes += commandRemovedTemplate.replace(
+      "@@changes@@",
+      oChanges.removed
+        .map(function (rm) {
+          return "<li>spk " + sanitize(rm) + "</li>";
+        })
+        .join("")
+    );
+  }
+  if (oChanges.changed) {
+    var optionChanges = "";
+    Object.keys(oChanges.changed).forEach(function (k) {
+      optionChanges +=
+        '<div class="option-change"><div class="option-change-title">' +
+        k +
+        "</div>";
+
+      if (oChanges.changed[k].command) {
+        optionChanges += commandValueChangedTemplate.replace(
+          "@@changes@@",
+          sanitize(oChanges.changed[k].command)
+        );
+      }
+
+      if (oChanges.changed[k].options) {
+        var options = oChanges.changed[k].options;
+
+        if (options.added) {
+          optionChanges += optionAddedTemplate.replace(
+            "@@changes@@",
+            options.added
+              .map(function (add) {
+                return "<li>" + sanitize(add) + "</li>";
+              })
+              .join("")
+          );
+        }
+        if (options.removed) {
+          optionChanges += optionRemovedTemplate.replace(
+            "@@changes@@",
+            options.removed
+              .map(function (rm) {
+                return "<li>" + sanitize(rm) + "</li>";
+              })
+              .join("")
+          );
+        }
+        if (options.changed) {
+          optionChanges += optionChangedTemplate.replace(
+            "@@changes@@",
+            options.changed
+              .map(function (chg) {
+                return "<li>" + sanitize(chg) + "</li>";
+              })
+              .join("")
+          );
+        }
+      }
+      optionChanges += "</div>";
+    });
+
+    return (
+      changes +
+      '<div class="change-item-header">Commands Changed</div>' +
+      optionChanges
+    );
+  }
+}
+
+/**
+ * Insert HTML element for command changes DIV.
+ */
+function compareVersions() {
+  var versions = Object.keys(dataCache);
+  versions.sort();
+  var cur = versions.shift();
+  var dataChanges = {};
+
+  versions.forEach(function (ver) {
+    dataChanges[ver] = compareVersion(cur, ver);
+    cur = ver;
+  });
+  versions.reverse();
+
+  $("#changes").append(
+    versions
+      .map(function (v) {
+        var oChanges = dataChanges[v];
+        var changes = oChanges ? getChangesHTML(oChanges) : "no changes";
+        return changeTemplate
+          .replace(/@@id-version@@/g, v.replace(/\./g, "_"))
+          .replace(/@@version@@/g, v)
+          .replace("@@changes@@", changes);
+      })
+      .join("")
+  );
+  if (window.location.hash && window.location.hash.startsWith("#change_rel_")) {
+    try {
+      var oDiv = $(window.location.hash);
+      if (oDiv && oDiv[0]) {
+        oDiv[0].scrollIntoView();
+      }
+    } catch (e) {
+      console.log(e);
+    }
+  }
+  $(".change-header").click(function () {
+    window.location.hash = "#" + $(this).prop("id");
+  });
+}

docs/commands/index.html

@@ -5,10 +5,12 @@
 	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <link rel="stylesheet" href="styles/feb02e3b.site-ltr.css">
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
+  <link rel="stylesheet" href="styles/ms.css ">
   <link rel="stylesheet" href="styles/spk.css ">
   <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.3.1.min.js" integrity="sha384-tsQFqpEReu7ZLhBV2VZlAu7zcOV+rXbYlF2cqB8txI/8aZajjp4Bqd+V6D5IgvKT" crossorigin="anonymous"></script>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/showdown/1.9.1/showdown.min.js"></script>
   <script src="./spk.js"></script>
+  <script src="./change-rels.js"></script>
   <title>SPK Commands</title>
 </head>
 <body>
@@ -36,8 +38,24 @@
 	</div>
   <div id="header">
     <div class="header-left-text">
-      <div><img width="30px" src="images/mslogo.png"></div>
-      <div class="header-text">SPK</div>
+      <header id="azure-header" class="azure-header">
+        <div class="logo-container">
+          <div><img width="30px" src="images/mslogo.png"></div>
+          <div class="header-text">SPK</div>
+        </div>
+
+        <nav class="nav-main" aria-label="Site navigation"></nav>
+        <nav class="nav-basic" aria-label="Utility navigation">
+          <ul id="nav-main-links" class="nav-main-links">    
+            <li id="navigation-overview">
+              <a href="javascript:showCommandView();">Command</a>
+            </li>
+            <li>
+              <a href="javascript:showChangesView();">Changes</a>
+            </li>
+          </ul>
+        </nav>
+      </header>
     </div>
   </div>
   <div id="subheader">
@@ -50,11 +68,10 @@
       <span class="tinyfont">Share</span>
     </div>
   </div>
-  <div id="content">
+  <div id="content" class="page">
     <div class="content-left">
     <div class="title">SPK Commands</div>
     <div>
-
       <div class="moniker-picker2" data-bi-name="moniker-picker" style="width:90%;margin-left:4px">
         <div class="dropdown has-margin-bottom-small">
           <button id="btnSelectRelease" class="dropdown-trigger has-flex-justify-content-start is-full-width button is-small has-border has-inner-focus" aria-expanded="false" aria-controls="ax-3">
@@ -84,6 +101,11 @@
 
     <div id="spk-details" class="content-right"></div>
   </div>
-
+
+  <div id="changes" class="page" style="display: none">
+    <div class="title">Changes over releases</div>
+
+  </div>
+
 </body>
 </html>