Merge pull request #26 from 201-created/add-shrinkwrap

Add support for npm-shrinkwrap.json

Author: quaertym

README.md

@@ -1,7 +1,7 @@
 ember-cli-dependency-checker [![Build Status](https://travis-ci.org/quaertym/ember-cli-dependency-checker.svg?branch=master)](https://travis-ci.org/quaertym/ember-cli-dependency-checker)
 ============================
 
-Ember CLI addon that checks for missing npm and bower dependencies before running ember commands
+An Ember CLI addon that checks for missing npm and bower dependencies before running ember commands.
 
 ### Installation
 
@@ -11,6 +11,77 @@ In your Ember CLI app (>= v1.2.0) run the following:
 npm install --save-dev ember-cli-dependency-checker
 ```
 
+### Usage
+
+Upon being included in a project (when running `ember build` for example), the dependency checker
+will confirm versions according to several signals of intent:
+
+* `bower.json` will be compared to the contents of `bower_components` (or your Ember-CLI
+  configured bower directory)
+* `package.json` will be compared to the contents of `node_modules`. This check only
+  takes the top-level of dependencies into account. Nested dependencies are not confirmed.
+* `npm-shrinkwrap.json`, if present, will be compared to the contents of `node_modules`. This
+  is done only if a `package.json` check does not find any unsatisfied dependencies. Nested
+  dependencies are confirmed.
+
+### Shrinkwrap Workflow
+
+**This workflow presumes npm v2.7.6 - v3.0.0**, though it may work well for earlier versions.
+
+When installing dependencies, it is important that `npm shrinkwrap --dev` is run and the resulting
+`npm-shrinkwrap.json` file committed. For example, to install the [Torii](https://github.com/Vestorly/torii)
+library:
+
+```
+npm install --save-dev torii
+npm shrinkwrap --dev
+git add package.json npm-shrinkwrap.json
+git commit -m"Install Torii"
+```
+
+**If the npm-shrinkwrap.json file is not committed, nested dependencies cannot be confirmed**.
+Remembering to execute `npm shrinkwrap --dev` and commit `npm-shrinkwrap.json` is akin to committing
+the `Gemfile.lock` file when using Ruby's Bundler library.
+
+If `ember` is run and the contents of `node_modules/` differs from the contents of `package.json`
+and `npm-shrinkwrap.json` an error will be raised. To resolve a difference in dependencies,
+you must destroy the `node_modules/` directory and re-run `npm install`. With a blank
+directory, `npm install` will respect the versions pinned in `npm-shrinkwrap.json`.
+
+In some rare cases there may be un-resolvable conflicts between installable versions of
+dependencies and those pinned. Upgrading packages after deleting the `npm-shrinkwrap.json`
+file or changing the version of a dependency requested in `package.json` may be the only
+way to resolve theses cases.
+
+### Deployment with Shrinkwrap
+
+Ember-CLI projects may be built on Travis or another dedicated build tool like Jenkins. To
+ensure that versions of dependencies (including of nested dependencies) are the same during
+builds as they are on the authoring developer's computer, it is recommended
+that you confirm dependencies before a build. Do this by running `ember version` to
+begin a dependency check, then if needed clearing the `node_modules/` and `bower_components/` folder
+and installing dependencies. For example:
+
+```
+ember version || (rm -rf node_modules/ bower_components/ && npm install && bower install)
+ember build -e production
+```
+
+### Caveats
+
+Due to the limited information available in configuration files and packages, git
+dependencies may fall out of sync. Using shrinkwrap will confirm that they are correct
+upon installation, but they cannot be confirmed at runtime until improvements are
+made to the `npm-shrinkwrap.json` file.
+
+Pinning solely to versioned releases should be preferred.
+
+### Tests
+
+To run tests:
+
+`npm test`
+
 ### LICENSE
 
 MIT

index.js

@@ -1,3 +1,14 @@
 'use strict';
 
-module.exports = require('./lib/dependency-checker');
+var Reporter = require('./lib/reporter');
+var DependencyChecker = require('./lib/dependency-checker');
+
+module.exports = function emberCliDependencyCheckerAddon(project) {
+  var reporter = new Reporter();
+  var dependencyChecker = new DependencyChecker(project, reporter);
+  dependencyChecker.checkDependencies();
+
+  return {
+    name: 'ember-cli-dependency-checker'
+  };
+};

lib/dependency-checker.js

@@ -13,32 +13,47 @@ function isUnsatisfied(pkg) {
   return !!pkg.needsUpdate;
 }
 
-function EmberCLIDependencyChecker(project) {
-  this.name    = 'ember-cli-dependency-checker';
+function EmberCLIDependencyChecker(project, reporter) {
   this.project = project;
-  this.checkDependencies();
+  this.reporter = reporter;
 }
 
 EmberCLIDependencyChecker.prototype.checkDependencies = function() {
-
-  if(alreadyChecked || process.env.SKIP_DEPENDENCY_CHECKER) {
+  if (alreadyChecked || process.env.SKIP_DEPENDENCY_CHECKER) {
     return;
   }
 
   var bowerDeps = this.readBowerDependencies();
-  var unsatisfiedBowerDeps = bowerDeps.filter(isUnsatisfied);
+  this.reporter.unsatisifedPackages('bower', bowerDeps.filter(isUnsatisfied));
 
   var npmDeps = this.readNPMDependencies();
-  var unsatisfiedNPMDeps = npmDeps.filter(isUnsatisfied);
+  var unsatisfiedDeps = npmDeps.filter(isUnsatisfied);
+  this.reporter.unsatisifedPackages('npm', unsatisfiedDeps);
+
+  if (unsatisfiedDeps.length === 0) {
+    var shrinkWrapDeps = this.readShrinkwrapDeps();
+    this.reporter.unsatisifedPackages('npm-shrinkwrap', shrinkWrapDeps.filter(isUnsatisfied));
+  }
 
-  var message = '';
-  message += this.reportUnsatisfiedPackages('npm', unsatisfiedNPMDeps);
-  message += this.reportUnsatisfiedPackages('bower', unsatisfiedBowerDeps);
   EmberCLIDependencyChecker.setAlreadyChecked(true);
 
-  if (message !== '') {
-    var DependencyError = require('./dependency-error');
-    throw new DependencyError(message);
+  this.reporter.report();
+};
+
+EmberCLIDependencyChecker.prototype.readShrinkwrapDeps = function() {
+  var filePath = path.join(this.project.root, 'npm-shrinkwrap.json');
+  if (fileExists(filePath)) {
+    var ShrinkWrapChecker = require('./shrinkwrap-checker');
+    var shrinkWrapBody = readFile(filePath);
+    var shrinkWrapJSON = {};
+    try {
+      shrinkWrapJSON = JSON.parse(shrinkWrapBody);
+    } catch(e) {
+      // JSON parse error
+    }
+    return ShrinkWrapChecker.checkDependencies(this.project.root, shrinkWrapJSON);
+  } else {
+    return [];
   }
 };
 
@@ -96,27 +111,6 @@ EmberCLIDependencyChecker.prototype.readNPMDependencies = function() {
   }, this);
 };
 
-EmberCLIDependencyChecker.prototype.reportUnsatisfiedPackages = function(type, packages) {
-  this.chalk = this.chalk || require('chalk');
-  this.EOL   = this.EOL || require('os').EOL;
-
-  var chalk = this.chalk;
-  var EOL   = this.EOL;
-  var message = '';
-  if (packages.length > 0) {
-    message += EOL + chalk.red('Missing ' + type + ' packages: ') + EOL;
-
-    packages.map(function(pkg) {
-      message += chalk.reset('Package: ') + chalk.cyan(pkg.name) + EOL;
-      message += chalk.grey('  * Specified: ') + chalk.reset(pkg.versionSpecified) + EOL;
-      message += chalk.grey('  * Installed: ') + chalk.reset(pkg.versionInstalled || '(not installed)') + EOL + EOL;
-    });
-
-    message += chalk.red('Run `'+ type +' install` to install missing dependencies.') + EOL;
-  }
-  return message;
-};
-
 EmberCLIDependencyChecker.setAlreadyChecked = function(value) {
   alreadyChecked = value;
 };

lib/package.js

@@ -1,15 +1,19 @@
 'use strict';
 
-function Package(name, versionSpecified, versionInstalled) {
-  this.name = name;
-  this.versionSpecified = versionSpecified;
-  this.versionInstalled = versionInstalled;
-  this.needsUpdate = this.updateRequired();
+function Package() {
+  this.init.apply(this, arguments);
 }
 
 Package.prototype = Object.create({});
 Package.prototype.constructor = Package;
 
+Package.prototype.init = function(name, versionSpecified, versionInstalled) {
+  this.name = name;
+  this.versionSpecified = versionSpecified;
+  this.versionInstalled = versionInstalled;
+  this.needsUpdate = this.updateRequired();
+};
+
 Package.prototype.updateRequired = function() {
   if (!this.versionInstalled) {
     return true;

lib/reporter.js

@@ -0,0 +1,50 @@
+'use strict';
+
+function installCommand(type) {
+  switch (type) {
+  case 'npm':
+    return 'npm install';
+  case 'npm-shrinkwrap':
+    return 'rm -rf node_modules/ && npm install';
+  case 'bower':
+    return 'bower install';
+  }
+}
+
+var Reporter = function() {
+  this.messages = [];
+};
+
+Reporter.prototype.unsatisifedPackages = function(type, packages) {
+  this.chalk = this.chalk || require('chalk');
+  this.EOL   = this.EOL || require('os').EOL;
+
+  var chalk = this.chalk;
+  var EOL   = this.EOL;
+
+  if (packages.length > 0) {
+    var message = '';
+    message += EOL + chalk.red('Missing ' + type + ' packages: ') + EOL;
+
+    packages.forEach(function(pkg) {
+      message += chalk.reset('Package: ') + chalk.cyan(pkg.name) + EOL;
+      if (pkg.parents) {
+        message += chalk.reset('Required by: ') + chalk.cyan(pkg.parents.join(' / ')) + EOL;
+      }
+      message += chalk.grey('  * Specified: ') + chalk.reset(pkg.versionSpecified) + EOL;
+      message += chalk.grey('  * Installed: ') + chalk.reset(pkg.versionInstalled || '(not installed)') + EOL + EOL;
+    });
+
+    message += chalk.red('Run `'+ installCommand(type) +'` to install missing dependencies.') + EOL;
+    this.messages.push(message);
+  }
+};
+
+Reporter.prototype.report = function() {
+  if (this.messages.length) {
+    var DependencyError = require('./dependency-error');
+    throw new DependencyError(this.messages.join(''));
+  }
+};
+
+module.exports = Reporter;

lib/shrinkwrap-checker.js

@@ -0,0 +1,63 @@
+'use strict';
+
+var readPackageJSON = require('./utils/read-package-json');
+var ShrinkwrapPackage = require('./shrinkwrap-package');
+var path = require('path');
+
+var ShrinkwrapChecker = function(root, name, versionSpecified, parents){
+  this.root = root;
+  this.name = name;
+  this.versionSpecified = versionSpecified;
+  this.parents = parents;
+};
+
+ShrinkwrapChecker.prototype.check = function() {
+  var packageJSON = readPackageJSON(this.root) || {};
+  var versionInstalled = packageJSON.version;
+
+  return new ShrinkwrapPackage(
+    this.name, this.versionSpecified, versionInstalled, this.parents);
+};
+
+ShrinkwrapChecker.checkDependencies = function(root, shrinkWrapJSON) {
+  var resolvedDependencies = [];
+  var currentNode;
+
+  var nodesToCheck = [{
+    root: root,
+    parents: [],
+    childDependencies: shrinkWrapJSON.dependencies,
+    name: shrinkWrapJSON.name,
+    version: shrinkWrapJSON.version
+  }];
+
+  var checker, resolved;
+
+  while (currentNode = nodesToCheck.pop()) {
+    checker = new ShrinkwrapChecker(
+      currentNode.root, currentNode.name, currentNode.version, currentNode.parents);
+
+    resolved = checker.check();
+    resolvedDependencies.push(resolved);
+
+    if (!resolved.needsUpdate && currentNode.childDependencies) {
+      /* jshint loopfunc:true*/
+      var parents = currentNode.parents.concat(currentNode.name);
+      Object.keys(currentNode.childDependencies).forEach(function(childDepName){
+        var childDep = currentNode.childDependencies[childDepName];
+
+        nodesToCheck.push({
+          root: path.join(currentNode.root, 'node_modules', childDepName),
+          parents: parents,
+          name: childDepName,
+          childDependencies: childDep.dependencies,
+          version: childDep.version
+        });
+      });
+    }
+  }
+
+  return resolvedDependencies;
+};
+
+module.exports = ShrinkwrapChecker;

lib/shrinkwrap-package.js

@@ -0,0 +1,22 @@
+'use strict';
+
+var Package = require('./package');
+
+function ShrinkwrapPackage(name, versionSpecified, versionInstalled, parents) {
+  this._super$init.call(this, name, versionSpecified, versionInstalled);
+  this.init(name, versionSpecified, versionInstalled, parents);
+}
+
+ShrinkwrapPackage.prototype = Object.create(Package.prototype);
+ShrinkwrapPackage.prototype.constructor = ShrinkwrapPackage;
+
+ShrinkwrapPackage.prototype._super$init = Package.prototype.init;
+ShrinkwrapPackage.prototype.init = function(name, versionSpecified, versionInstalled, parents) {
+  this.parents = parents;
+};
+
+ShrinkwrapPackage.prototype.updateRequired = function() {
+  return this.versionSpecified !== this.versionInstalled;
+};
+
+module.exports = ShrinkwrapPackage;

lib/utils/read-package-json.js

@@ -0,0 +1,18 @@
+'use strict';
+
+var path = require('path');
+var fs = require('fs');
+function readFile(path){
+  if (fs.existsSync(path)) {
+    return fs.readFileSync(path);
+  }
+}
+
+module.exports = function readPackageJSON(projectRoot) {
+  var filePath = path.join(projectRoot, 'package.json');
+  try {
+    return JSON.parse(readFile(filePath));
+  } catch (e) {
+    return null;
+  }
+};