chore(npm): add shrinkwrap to our project

npm-shrinkwrap.readme.md

@@ -0,0 +1,58 @@
+All of our npm dependencies are locked via the `npm-shrinkwrap.json` file for the following reasons:
+
+- our project has lots of dependencies which update at unpredictable times, so it's important that
+  we update them explicitly once in a while rather than implicitly when any of us runs npm install
+- locked dependencies allow us to do reuse npm cache on travis, significantly speeding up our builds
+  (by 5min or more)  
+- locked dependencies allow us to detect when node_modules folder is out of date after a branch switch
+  which allows us to build the project with the correct dependencies every time
+
+However npm's shrinkwrap is known to be buggy, so we need to take some extra steps to deal with this.
+The most important step is generating the npm-shrinkwrap.clean.js which is used during code reviews
+or debugging to easily review what has actually changed. 
+See https://github.com/npm/npm/issues/3581 for related npm issue.
+
+To add a new dependency do the following:
+
+1. add a new dependency via `npm install -D <packagename>`
+2. run `./tools/npm/clean-shrinkwrap.js`
+3. these steps should change 3 files: `package.json`, `npm-shrinkwrap.json` and `npm-shrinkwrap.clean.json`
+4. commit changes to these three files and you are done
+
+
+To update existing dependency do the following:
+
+1. update `package.json`
+2. run `npm install <packagename>`
+3. relock the dependencies with `npm shrinkwrap --dev`
+4. clean up the shrinkwrap file for review with `./tools/npm/clean-shrinkwrap.js`
+5. these steps should change 3 files: `package.json`, `npm-shrinkwrap.json` and `npm-shrinkwrap.clean.json`
+6. commit changes to these three files and you are done
+
+
+If updating the `tsd` project a special steps need to be taken due to
+https://github.com/Bartvds/minitable/issues/2:
+
+Update `tsd` by following the steps above but before you run `npm shrinkwrap --dev`, you'll have to
+manually patch `node_modules/tsd/node_modules/minitable/package.json` and remove the `minichain` from
+the `peerDependencies` section.
+
+before:
+
+```
+ "peerDependencies": {
+    "minichain": "~X.Y.Z",
+    ...
+  },
+```
+
+
+after:
+
+```
+ "peerDependencies": {
+    ...
+  },
+```
+
+Then resume the shrinkwrap update and cleaning steps.

package.json

@@ -89,6 +89,7 @@
     "protractor": "2.0.0",
     "q": "^1.0.1",
     "run-sequence": "^0.3.6",
+    "sorted-object": "^1.0.0",
     "source-map": "^0.3.0",
     "sprintf-js": "1.0.*",
     "systemjs-builder": "^0.10.3",

tools/npm/clean-shrinkwrap.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+/**
+ * this script is just a temporary solution to deal with the issue of npm outputting the npm
+ * shrinkwrap file in an unstable manner.
+ *
+ * See: https://github.com/npm/npm/issues/3581
+ */
+
+var _ = require('lodash');
+var sorted = require('sorted-object');
+var fs = require('fs');
+var path = require('path');
+
+
+function cleanModule(moduleRecord, name) {
+
+  // keep `resolve` properties for git dependencies, delete otherwise
+  delete moduleRecord.from;
+  if (!(moduleRecord.resolved && moduleRecord.resolved.match(/^git(\+[a-z]+)?:\/\//))) {
+    delete moduleRecord.resolved;
+  }
+
+  _.forEach(moduleRecord.dependencies, function(mod, name) {
+    cleanModule(mod, name);
+  });
+}
+
+
+console.log('Reading npm-shrinkwrap.json');
+var shrinkwrap = require('../../npm-shrinkwrap.json');
+
+console.log('Cleaning shrinkwrap object');
+cleanModule(shrinkwrap, shrinkwrap.name);
+
+var cleanShrinkwrapPath = path.join(__dirname, '..', '..', 'npm-shrinkwrap.clean.json');
+console.log('Writing cleaned to', cleanShrinkwrapPath);
+fs.writeFileSync(cleanShrinkwrapPath, JSON.stringify(sorted(shrinkwrap), null, 2) + "\n");