placed preference to npm over Bower modules, fixed option nesting for environment variables, bump minor version

Author: benholloway

config/add/common.js

@@ -37,8 +37,8 @@ function common(loaderRoot, options) {
         alias   : {
           npm: path.resolve('node_modules')
         },
-        root    : path.resolve('bower_components'),
-        fallback: path.resolve('node_modules')
+        root    : path.resolve('node_modules'),
+        fallback: path.resolve('bower_components')
       },
       resolveLoader: {
         root    : loaderRoot,

lib/default-options.js

@@ -1,5 +1,9 @@
 'use strict';
 
+/**
+ * The default options of the application.
+ * @returns {object}
+ */
 function defaultOptions() {
   return {
     appDir    : './app',

lib/parse-options.js

@@ -3,13 +3,21 @@
 var camelcase  = require('camelcase'),
     objectPath = require('object-path');
 
+/**
+ * Parse the given options where keys may be in camel-case or as environment variable.
+ * Nested fields are supported by dot-delimited camel-case, or double-underscore delimited uppercase
+ * IEEE Std 1003.1-2001.
+ * @param {object} options A hash of options
+ * @param {object} defaults A hash of the default values of all valid options
+ * @returns {object} A complete set, preferring options and using defaults otherwise
+ */
 function parseOptions(options, defaults) {
   return Object.keys(options)
     .reduce(eachOptionKey, defaults);
 
   function eachOptionKey(reduced, key) {
     var expectedKey = key
-      .split('.')
+      .split('__')
       .map(eachElement)
       .join('.');
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "webpack-angularity-solution",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Requisite configuration and modules to build Angularity projects with Webpack",
   "main": "index.js",
   "repository": {

readme.md

@@ -191,9 +191,28 @@ stats     : {            // console output
 
 Note that if you have an `angularity.json` file then its `port` property will be used as the default value, rather than `55555`.
 
+#### Environment variables
+
+All options may be parsed from uppercase environment variables.
+
+Use an underscrore to delimit camel-case, meaning `buildDir` is written as environment variable `BUILD_DIR`.
+ 
+Use a double underscore to delimit a nested field, meaning `stats.warnings` is written as environment variable `STATS__WARNINGS`.
+
+For example, to **suppress warnings** during the build:
+
+```json
+{
+  "scripts": {
+    "silent": "cross-env STATS__WARNINGS=false webpack -d --progress"
+    ...
+  }
+}
+```
+
 #### Full customisation
 
-These settings deviate from the Angularity standard project structure
+These additional settings may be used to deviate from Angularity's optinionated project structure.
 
 ```javascript
 appDir    : './app',           // your composition roots
@@ -203,20 +222,18 @@ releaseDir: './app-release',   // output of the release build
 testGlob  : '**/*.spec.js'     // identify your test files
 ```
 
-#### Environment variables
+### Bower
 
-All options may be parsed from uppercase environment variables. Use a dot to delimit depth.
+Bower packages may be imported like node modules but if there is a node module of the same name available then it will be used in preference.
 
-For example, to **suppress warnings** during the build:
+Inline loader statements (see shimming) cannot be used when requiring bower packages. If the package requires globals (such as jQuery) then then need to be set in the Angularity options.
+
+### Shimming
+
+If a package does not export anything, or requires some global, then it may be [shimmed](https://github.com/webpack/docs/wiki/shimming-modules) on an as-used basis.
+
+Since the **Angular** package does not export anything it would normally require the `export-loader?angular` statement to be used. However this is already taken care of in the common configuration and you do not need to take further action.
 
-```json
-{
-  "scripts": {
-    "silent": "cross-env STATS.WARNINGS=false webpack -d --progress"
-    ...
-  }
-}
-```
 
 ## Extensability
 
@@ -238,22 +255,42 @@ The result of `angularity()` is an instance with a number of accessors - `app`,
 
 ### Resolving
 
-While webpack-configurator provides methods for extensibility of the configuration it is not a valid webpack configuration until `configurator.resolve()` is called. This is done automatically by the `angularity.resolve()` method, negating the need to iterate over the configurator instance(s).
+While [webpack-configurator](https://www.npmjs.com/package/webpack-configurator) provides methods for extensibility of the configuration it is not a valid webpack configuration until `configurator.resolve()` is called.
+
+This is done automatically by the `angularity.resolve()` method, removing the need to iterate over the (possibly numerous) configurator instances.
 
 ```javascript
 module.exports = angularity(...)
   .resolve(function() {
     // this === angularity instance (i.e. this.app | this.test | this.release)
     // return a webpack-configurator or Array.<webpack-configurator>
-	//   the .resolve() method will be called on each element returned
+    //   the .resolve() method will be called on each element returned
   });
 ```
 
 ### Operators
 
 In order to create the configurators for each **mode**, a number of additional **operators** are added to `webpack-configurator`.
 
-The default operators include:
+You may add your own operator using the `extend()` method. Each operator is called with the current instance of the Configurator as `this` and should return the same or a new Configurator.
+
+For example, to add the `foo` operator:
+
+```javascript
+module.exports = angularity(...)
+  .extend({
+    foo: function foo() {
+      return this
+        .merge({...});  // use the fluent webpack-configurator API
+    }
+  })
+  .resolve(function () {
+    return this.test
+      .foo();  // operators are available on any Configurator instances comming out of 'test'
+  })
+```
+
+There are a number of operators used internally. These include:
 
 * `addBrowserSync(directory:string, port:number):Configurator`
 
@@ -285,22 +322,4 @@ The default operators include:
 
 * `addTestSuiteGeneration(outputFile:string, testGlob:string):Configurator`
 
-	Locate all specification files and generate a file that require()s them all.
-	
-You may alter these operators or add your own using the `extend()` method.
-For example, if you want to re-implement the common configuration then override the `addCommon` operator:
-
-```javascript
-var oldCommon = require('webpack-angularity-solution/config/add/common');
-
-module.exports = angularity(...)
-  .extend({
-    addCommon: function(loaderRoot, options) {
-	  return oldCommon.call(this, loaderRoot, options)
-        .merge({...})
-	}
-  })
-  .resolve(function() {
-    ...
-  });
-```
+	Locate all specification files and generate a file that require()s them all.