Update to Truffle3, refactor CLI, add CLI unit tests, fix misc bugs

.eslintignore

@@ -0,0 +1 @@
+test/cli/truffle-crash.js

.gitignore

@@ -2,3 +2,5 @@ allFiredEvents
 coverage.json
 coverage/
 node_modules/
+.changelog
+.DS_Store

README.md

@@ -1,75 +1,118 @@
-#SolCover
+# SolCover
 
 ![CircleCI Status](https://circleci.com/gh/JoinColony/solcover.svg?style=shield&circle-token=53d5360d290ef593c7bdce505b86ae8b9414e684)
 [![codecov](https://codecov.io/gh/JoinColony/solcover/branch/master/graph/badge.svg)](https://codecov.io/gh/JoinColony/solcover)
 
-
-###Code coverage for Solidity testing
+### Code coverage for Solidity testing
 ![coverage example](https://cdn-images-1.medium.com/max/800/1*uum8t-31bUaa6dTRVVhj6w.png)
 
-For more details about what this is, how it work and potential limitations, see 
+For more details about what this is, how it works and potential limitations, see 
 [the accompanying article](https://blog.colony.io/code-coverage-for-solidity-eecfa88668c2).
 
-###Installation and preparation
+### Install
+```
+$ npm install --save-dev https://github.com/JoinColony/solcover.git#truffle3
+```
 
-From your truffle directory, clone this repo:
+### Run 
 ```
-git clone http://github.com/JoinColony/solcover.git
-cd solcover
-npm install
+$ ./node_modules/solcover/exec.js
 ```
 
-Until [Truffle allows the `--network` flag for the `test` command](https://github.com/ConsenSys/truffle/issues/239), in `truffle.js` you have to set a large gas amount for deployment. While this is set, uninstrumented tests likely won't run correctly, so this should only be set when running the coverage tests. An appropriately modified `truffle.js` might look like
+Tests run signficantly slower while coverage is being generated. A 1 to 2 minute delay 
+between the end of Truffle compilation and the beginning of test execution is possible if your
+test suite is large. Large solidity files can also take a while to instrument.
 
-```
+### Configuration
+
+By default, Solcover generates a stub `truffle.js` that accomodates its special gas needs and 
+connects to a modified version of testrpc on port 8555. If your tests will run on the development network
+using a standard `truffle.js` and a testrpc instance with no special options, you shouldn't have to 
+do any configuration. If your tests depend on logic added to `truffle.js` - for example: 
+[zeppelin-solidity](https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/truffle.js) 
+uses the file to expose a babel polyfill that its suite requires - you can override the 
+default behavior by declaring a coverage network in `truffle.js`. Solcover will use your 'truffle.js'
+instead of a dynamically generated one. 
+
+**Example coverage network config**
+```javascript
 module.exports = {
-  rpc: {
-    host: 'localhost',
-    gasPrice: 20e9,
-    gas: 0xfffffff,
+  networks: {
+    development: {
+      host: "localhost",
+      port: 8545,
+      network_id: "*" // Match any network id
+    },
+    coverage: {
+      host: "localhost",
+      network_id: "*", 
+      port: 8555,         // <-- Use port 8555  
+      gas: 0xfffffffffff, // <-- Use this high gas value
+      gasPrice: 0x01      // <-- Use this low gas price
+    }
   }
- };
+};
 ```
-In the future, hopefully just adding the 'coverage' network to `truffle.js` will be enough. This will look like
 
+You can also create a `.solcover.js` config file in the root directory of your project and specify 
+some additional options:
++ **port**: <Number> The port you want Solcover to run testrpc on / have truffle connect to.
++ **testrpcOptions**: <String> A string of options to be appended to a command line invocation 
+of testrpc. 
+  + Example: `--account="0x89a...b1f',10000" --port 8777`". 
+  + Note: you should specify the port in your `testrpcOptions` string AND as a `port` option.
++ **testCommand**: <String> By default Solcover runs `truffle test` or `truffle test --network coverage`. 
+This option lets you run tests some other way: ex: `mocha --timeout 5000`. You 
+will probably also need to make sure the web3 provider for your tests explicitly connects to the port Solcover's 
+testrpc is set to run on, e.g: 
+  + `var web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8555"))`  
+
+**Example .solcover.js config file**
 ```
 module.exports = {
-  rpc: {
-    host: 'localhost',
-    gasPrice: 20e9,
-  },
-  networks:{
-    "coverage":{
-    	gas: 0xfffffff,
-    }
-  }
-}
+    port: 6545,
+    testrpcOptions: '-p 6545 -u 0x54fd80d6ae7584d8e9a19fe1df43f04e5282cc43',
+    testCommand: 'mocha --timeout 5000'
+};
 ```
-and will not interfere with normal `truffle test` - or other commands - being run during development.
-
-Note that if you have hardcoded gas costs into your tests, some of them may fail when using SolCover. This is because the instrumentation process increases the gas costs for using the contracts, due to the extra events. If this is the case, then the coverage may be incomplete. To avoid this, using `estimateGas` to estimate your gas costs should be more resilient in most cases.
-
-###Execution
 
-Firstly, make sure that your contracts in your truffle directory are saved elsewhere too - this script moves them and modifies them to do the instrumentation and allow `truffle` to run the tests with the instrumented contracts. It returns them after the tests are complete, but if something goes wrong, then `originalContracts` in the truffle directory should contain the unmodified contracts.
+### Known Issues
 
-SolCover runs its own (modified) `testrpc` to get the coverage data, so make sure that you've not left a previous instance running on port 8545, otherwise the coverage reported will be.... sparse...
+**Hardcoded gas costs**: If you have hardcoded gas costs into your tests some of them may fail when using SolCover. 
+This is because the instrumentation process increases the gas costs for using the contracts, due to 
+the extra events. If this is the case, then the coverage may be incomplete. To avoid this, using 
+`estimateGas` to estimate your gas costs should be more resilient in most cases.
 
-From inside the SolCover directory, run 
+**Events testing**: Because Solcover injects events into your contracts to log which lines your tests reach,
+any tests that ask how many events are fired or where the event sits in the logs array
+will probably error while coverage is being generated.
 
-```node ./runCoveredTests.js```
+**Using `require` in `migrations.js` files**: Truffle overloads Node's `require` function but
+implements a simplified search algorithm for node_modules packages 
+([see issue #383 at Truffle](https://github.com/trufflesuite/truffle/issues/383)). 
+Because Solcover copies an instrumented version of your project into a temporary folder, `require` 
+statements handled by Truffle internally won't resolve correctly.  
 
-Upon completion of the tests, open the `./coverage/lcov-report/index.html` file to browse the HTML coverage report.
+**Coveralls / CodeCov**: These CI services take the Istanbul reports generated by Solcover and display 
+line coverage. Istanbul's own html report publishes significantly more detail and can show whether 
+your tests actually reach all the conditional branches in your code. It can be found inside the 
+`coverage` folder at `index.html` after you run the tool. 
 
-###A few, uh, provisos, a, a couple of quid pro quos...
-It is very likely that there are valid Solidity statements that this tool won't instrument correctly, as it's only been developed against a small number of contracts. If (and when) you find such cases, please raise an issue.
+### Examples
 
++ **Metacoin**: The default truffle project
+  + [HTML reports](https://sc-forks.github.io/metacoin/)
+  + [Metacoin with Solcover installed](https://github.com/sc-forks/metacoin) (simple, without configuration)
++ **zeppelin-solidity** at commit 453a19825013a586751b87c67bebd551a252fb50
+  + [HTML reports]( https://sc-forks.github.io/zeppelin-solidity/)
+  + [Zeppelin with Solcover installed](https://github.com/sc-forks/zeppelin-solidity) (declares own coverage network in truffle.js)
++ **numeraire** at commit 5ac3fa432c6b4192468c95a66e52ca086c804c95
+  + [HTML reports](https://sc-forks.github.io/contract/)
+  + [Numeraire with Solcover installed](https://github.com/sc-forks/contract) (uses .solcover.js)
 
-###TODO
+### TODO
 
-- [ ] **TESTS**
 - [ ] Turn into a true command line tool, rather than just a hacked-together script
 - [ ] Release on NPM 
-- [ ] Do not modify the `../contract/` directory at all during operation (might need changes to truffle)
 - [ ] Support for arbitrary testing commands
 - [ ] [You tell me](http://github.com/JoinColony/solcover/issues)

coverageMap.js

@@ -5,11 +5,7 @@
  */
 const SolidityCoder = require('web3/lib/solidity/coder.js');
 const path = require('path');
-
-const lineTopic = 'b8995a65f405d9756b41a334f38d8ff0c93c4934e170d3c1429c3e7ca101014d';
-const functionTopic = 'd4ce765fd23c5cc3660249353d61ecd18ca60549dd62cb9ca350a4244de7b87f';
-const branchTopic = 'd4cf56ed5ba572684f02f889f12ac42d9583c8e3097802060e949bfbb3c1bff5';
-const statementTopic = 'b51abbff580b3a34bbc725f2dc6f736e9d4b45a41293fd0084ad865a31fde0c8';
+const keccak = require('keccakjs');
 
 /**
  * Converts solcover event data into an object that can be
@@ -20,6 +16,10 @@ module.exports = class CoverageMap {
 
   constructor() {
     this.coverage = {};
+    this.lineTopics = [];
+    this.functionTopics = [];
+    this.branchTopics = [];
+    this.statementTopics = [];
   }
 
   /**
@@ -29,6 +29,7 @@ module.exports = class CoverageMap {
    * @param {String} canonicalContractPath target file location
    * @return {Object} coverage map with all values set to zero
    */
+
   addContract(info, canonicalContractPath) {
     this.coverage[canonicalContractPath] = {
       l: {},
@@ -56,6 +57,17 @@ module.exports = class CoverageMap {
     for (let x = 1; x <= Object.keys(info.statementMap).length; x++) {
       this.coverage[canonicalContractPath].s[x] = 0;
     }
+
+    const keccakhex = (x => {
+      const hash = new keccak(256); // eslint-disable-line new-cap
+      hash.update(x);
+      return hash.digest('hex');
+    });
+
+    this.lineTopics.push(keccakhex('__Coverage' + info.contractName + '(string,uint256)'));
+    this.functionTopics.push(keccakhex('__FunctionCoverage' + info.contractName + '(string,uint256)'));
+    this.branchTopics.push(keccakhex('__BranchCoverage' + info.contractName + '(string,uint256,uint256)'));
+    this.statementTopics.push(keccakhex('__StatementCoverage' + info.contractName + '(string,uint256)'));
   }
 
   /**
@@ -68,19 +80,20 @@ module.exports = class CoverageMap {
   generate(events, pathPrefix) {
     for (let idx = 0; idx < events.length; idx++) {
       const event = JSON.parse(events[idx]);
-      if (event.topics.indexOf(lineTopic) >= 0) {
+
+      if (event.topics.filter(t => this.lineTopics.indexOf(t) >= 0).length > 0) {
         const data = SolidityCoder.decodeParams(['string', 'uint256'], event.data.replace('0x', ''));
         const canonicalContractPath = data[0];
         this.coverage[canonicalContractPath].l[data[1].toNumber()] += 1;
-      } else if (event.topics.indexOf(functionTopic) >= 0) {
+      } else if (event.topics.filter(t => this.functionTopics.indexOf(t) >= 0).length > 0) {
         const data = SolidityCoder.decodeParams(['string', 'uint256'], event.data.replace('0x', ''));
         const canonicalContractPath = data[0];
         this.coverage[canonicalContractPath].f[data[1].toNumber()] += 1;
-      } else if (event.topics.indexOf(branchTopic) >= 0) {
+      } else if (event.topics.filter(t => this.branchTopics.indexOf(t) >= 0).length > 0) {
         const data = SolidityCoder.decodeParams(['string', 'uint256', 'uint256'], event.data.replace('0x', ''));
         const canonicalContractPath = data[0];
         this.coverage[canonicalContractPath].b[data[1].toNumber()][data[2].toNumber()] += 1;
-      } else if (event.topics.indexOf(statementTopic) >= 0) {
+      } else if (event.topics.filter(t => this.statementTopics.indexOf(t) >= 0).length > 0) {
         const data = SolidityCoder.decodeParams(['string', 'uint256'], event.data.replace('0x', ''));
         const canonicalContractPath = data[0];
         this.coverage[canonicalContractPath].s[data[1].toNumber()] += 1;