Route all errors through reporter (#399)

* Decouple app & plugin UIs. Make UI extensible class consumed by plugin.

* Add flags to force loading truffle lib module from different sources (global, plugin)  

* Route all error output through UI Class 

* Add error checking for solcover.js loading 

* Add truffle lib bundle map

Author: cgewecke

.circleci/config.yml

@@ -26,6 +26,10 @@ jobs:
           name: Install yarn
           command: |
             npm install -g yarn
+      - run:
+          name: Install truffle (globally)
+          command: |
+            npm install -g truffle
       - run:
           name: Install dependencies
           command: |

README.md

@@ -47,6 +47,8 @@ truffle run coverage [options]
 |--------------|--------------------------------|-------------|
 | `--file`       | `--file="test/registry/*.js"`    | Filename or glob describing a subset of JS tests to run. (Globs must be enclosed by quotes.)|
 | `--solcoverjs` | `--solcoverjs ./../.solcover.js` | Relative path from working directory to config. Useful for monorepo packages that share settings. (Path must be "./" prefixed) |
+| `--useGlobalTruffle`    |                       | Force use of truffle library module from globally installed truffle. (Default: false)|
+| `--usePluginTruffle`    |                       | Force use of truffle library module from plugin provided copy (Truffle v5.0.31.) Requires you have locally installed Truffle V5 <= 5.0.30 (Default: false)|
 | `--version`    |                                | Version info |
 | `--help`       |                                | Usage notes  |
 |<img width=250/>|<img width=500/>              |<img width=100/>|

dist/truffle.library.js renamed to dist/plugin-assets/truffle.library.js

@@ -0,0 +1,76 @@
+const UI = require('./../../lib/ui').UI;
+
+/**
+ * Truffle Plugin logging
+ */
+class PluginUI extends UI {
+  constructor(log){
+    super(log);
+  }
+
+  /**
+   * Writes a formatted message via log
+   * @param  {String}   kind  message selector
+   * @param  {String[]} args  info to inject into template
+   */
+  report(kind, args=[]){
+    const c = this.chalk;
+    const ct = c.bold.green('>');
+    const ds = c.bold.yellow('>');
+    const w = ":warning:";
+
+    const kinds = {
+
+      'sol-tests': `\n${w}  ${c.red("This plugin cannot run Truffle's native solidity tests: ")}`+
+                           `${args[0]} test(s) will be skipped.\n`,
+
+
+      'lib-local':  `\n${ct} ${c.grey('Using Truffle library from local node_modules.')}\n`,
+      'lib-global': `\n${ct} ${c.grey('Using Truffle library from global node_modules.')}\n`,
+
+      'lib-warn':   `${w}  ${c.red('Unable to require Truffle library locally or globally.\n')}`+
+                    `${w}  ${c.red('Using fallback Truffle library module instead (v5.0.31)')}\n` +
+                    `${w}  ${c.red('Truffle V5 must be a local dependency for fallback to work.')}\n`,
+
+
+      'help': `Usage: truffle run coverage [options]\n\n` +
+              `Options:\n` +
+              `  --file:       path (or glob) to subset of JS test files. (Quote your globs)\n` +
+              `  --solcoverjs: relative path to .solcover.js (ex: ./../.solcover.js)\n` +
+              `  --version:    version info\n`,
+
+
+      'truffle-version':  `${ct} ${c.bold('truffle')}:           v${args[0]}`,
+      'ganache-version':  `${ct} ${c.bold('ganache-core')}:      ${args[0]}`,
+      'coverage-version': `${ct} ${c.bold('solidity-coverage')}: v${args[0]}`,
+    }
+
+    this._write(kinds[kind]);
+  }
+
+  /**
+   * Returns a formatted message. Useful for error message.
+   * @param  {String}   kind  message selector
+   * @param  {String[]} args  info to inject into template
+   * @return {String}         message
+   */
+  generate(kind, args=[]){
+    const c = this.chalk;
+
+    const kinds = {
+      'lib-fail':  `${c.red('Unable to load plugin copy of Truffle library module. ')}` +
+                   `${c.red('Try installing Truffle >= v5.0.31 locally or globally.\n')}` +
+                   `Caught error message: ${args[0]}\n`,
+
+      'solcoverjs-fail': `${c.red('Could not load .solcover.js config file. ')}` +
+                         `${c.red('This can happen if it has a syntax error or ')}` +
+                         `${c.red('the path you specified for it is wrong.')}`,
+
+    }
+
+
+    return this._format(kinds[kind])
+  }
+}
+
+module.exports = PluginUI;

dist/plugin-assets/truffle.library.js.map

@@ -1,31 +1,6 @@
-/*
-  TruffleConfig Paths
-  ===========================
-  build_directory            /users/myPath/to/someProject/build
-  contracts_directory.       /users/myPath/to/someProject/contracts
-  working_directory          /users/myPath/to/someProject
-  contracts_build_directory  /users/myPath/to/someProject/build/contracts
-
-  Compilation options override
-  ----------------------------
-  build_directory            /users/myPath/to/someProject/.coverageArtifacts
-  contracts_directory        /users/myPath/to/someProject/.coverageContracts
-
-  Test options override
-  ---------------------
-  contracts_directory,       /users/myPath/to/someProject/.coverageContracts
-  contracts_build_directory, /users/myPath/to/someProject/.coverageArtifacts/contracts
-  provider                   ganache.provider (async b/c vm must be resolved)
-  logger                     add filter for unused variables...
-
-  Truffle Lib API
-  ===============
-  load:         const truffle = require("truffle") (or require("sc-truffle"))
-  compilation:  await truffle.contracts.compile(config)
-  test:         await truffle.test.run(config)
-*/
-
 const App = require('./../lib/app');
+const PluginUI = require('./plugin-assets/truffle.ui');
+
 const pkg = require('./../package.json');
 const req = require('req-cwd');
 const death = require('death');
@@ -34,79 +9,78 @@ const dir = require('node-dir');
 const Web3 = require('web3');
 const util = require('util');
 const globby = require('globby');
+const shell = require('shelljs');
 const globalModules = require('global-modules');
 
+/**
+ * Truffle Plugin: `truffle run coverage [options]`
+ * @param  {Object}   truffleConfig   @truffle/config config
+ * @return {Promise}
+ */
 async function plugin(truffleConfig){
+  let ui;
   let app;
   let error;
   let truffle;
   let testsErrored = false;
-  let coverageConfig;
-  let solcoverjs;
 
-  // Load truffle lib, .solcover.js & launch app
+  // This needs it's own try block because this logic
+  // runs before app.cleanUp is defined.
   try {
-    (truffleConfig.solcoverjs)
-      ? solcoverjs = path.join(truffleConfig.working_directory, truffleConfig.solcoverjs)
-      : solcoverjs = path.join(truffleConfig.working_directory, '.solcover.js');
-
-    coverageConfig = req.silent(solcoverjs) || {};
-    coverageConfig.cwd = truffleConfig.working_directory;
-    coverageConfig.originalContractsDir = truffleConfig.contracts_directory;
-    coverageConfig.log = coverageConfig.log || truffleConfig.logger.log;
+    ui = new PluginUI(truffleConfig.logger.log);
 
-    app = new App(coverageConfig);
+    if(truffleConfig.help) return ui.report('help'); // Bail if --help
 
-    if (truffleConfig.help){
-      return app.ui.report('truffle-help')
-    }
+    truffle = loadTruffleLibrary(ui, truffleConfig);
+    app = new App(loadSolcoverJS(ui, truffleConfig));
 
-    truffle = loadTruffleLibrary(app);
+  } catch (err) { throw err }
 
-  } catch (err) {
-    throw err;
-  }
-
-  // Instrument and test..
   try {
-    death(app.cleanUp); // This doesn't work...
+    // Catch interrupt signals
+    death(app.cleanUp);
 
-    // Launch in-process provider
+    // Provider / Server launch
     const provider = await app.provider(truffle.ganache);
     const web3 = new Web3(provider);
     const accounts = await web3.eth.getAccounts();
     const nodeInfo = await web3.eth.getNodeInfo();
     const ganacheVersion = nodeInfo.split('/')[1];
 
-    app.ui.report('truffle-version', [truffle.version]);
-    app.ui.report('ganache-version', [ganacheVersion]);
-    app.ui.report('coverage-version',[pkg.version]);
+    // Version Info
+    ui.report('truffle-version', [truffle.version]);
+    ui.report('ganache-version', [ganacheVersion]);
+    ui.report('coverage-version',[pkg.version]);
 
-    // Bail early if user ran: --version
-    if (truffleConfig.version) return;
+    if (truffleConfig.version) return app.cleanUp(); // Bail if --version
 
-    // Write instrumented sources to temp folder
+    // Instrument
+    app.sanityCheckContext();
+    app.generateStandardEnvironment();
     app.instrument();
 
-    // Ask truffle to use temp folders
+    // Filesystem & Compiler Re-configuration
     truffleConfig.contracts_directory = app.contractsDir;
     truffleConfig.build_directory = app.artifactsDir;
-    truffleConfig.contracts_build_directory = paths.artifacts(truffleConfig, app);
 
-    // Additional config
+    truffleConfig.contracts_build_directory = path.join(
+      app.artifactsDir,
+      path.basename(truffleConfig.contracts_build_directory)
+    );
+
     truffleConfig.all = true;
-    truffleConfig.test_files = tests(app, truffleConfig);
+    truffleConfig.test_files = getTestFilePaths(ui, truffleConfig);
     truffleConfig.compilers.solc.settings.optimizer.enabled = false;
 
-    // Compile
+    // Compile Instrumented Contracts
     await truffle.contracts.compile(truffleConfig);
 
-    // Launch in-process provider
+    // Network Re-configuration
     const networkName = 'soliditycoverage';
     truffleConfig.network = networkName;
 
-    // Truffle alternately complains that fields are and
-    // are not manually set
+    // Truffle complains that these keys *are not* set when running plugin fn directly.
+    // But throws saying they *cannot* be manually set when running as truffle command.
     try {
       truffleConfig.network_id = "*";
       truffleConfig.provider = provider;
@@ -133,6 +107,7 @@ async function plugin(truffleConfig){
     error = e;
   }
 
+
   // Finish
   await app.cleanUp();
 
@@ -142,68 +117,112 @@ async function plugin(truffleConfig){
 
 // -------------------------------------- Helpers --------------------------------------------------
 
-function tests(app, truffle){
+/**
+ * Returns a list of test files to pass to mocha.
+ * @param  {Object}   ui      reporter utility
+ * @param  {Object}   truffle truffleConfig
+ * @return {String[]}         list of files to pass to mocha
+ */
+function getTestFilePaths(ui, truffle){
   let target;
 
+  // Handle --file <path|glob> cli option (subset of tests)
   (typeof truffle.file === 'string')
     ? target = globby.sync([truffle.file])
     : target = dir.files(truffle.test_directory, { sync: true }) || [];
 
+  // Filter native solidity tests and warn that they're skipped
   const solregex = /.*\.(sol)$/;
   const hasSols = target.filter(f => f.match(solregex) != null);
 
-  if (hasSols.length > 0) app.ui.report('sol-tests', [hasSols.length]);
+  if (hasSols.length > 0) ui.report('sol-tests', [hasSols.length]);
 
+  // Return list of test files
   const testregex = /.*\.(js|ts|es|es6|jsx)$/;
   return target.filter(f => f.match(testregex) != null);
 }
 
 
-function loadTruffleLibrary(app){
 
-  // Case: from local node_modules
+/**
+ * Tries to load truffle module library and reports source. User can force use of
+ * a non-local version using cli flags (see option). Load order is:
+ *
+ * 1. local node_modules
+ * 2. global node_modules
+ * 3. fail-safe (truffle lib v 5.0.31 at ./plugin-assets/truffle.library)
+ *
+ * @param  {Object} ui            reporter utility
+ * @param  {Object} truffleConfig config
+ * @return {Module}
+ */
+function loadTruffleLibrary(ui, truffleConfig){
+
+  // Local
   try {
+    if (truffleConfig.useGlobalTruffle || truffleConfig.usePluginTruffle) throw null;
+
     const lib = require("truffle");
-    app.ui.report('truffle-local');
+    ui.report('lib-local');
     return lib;
 
   } catch(err) {};
 
-  // Case: global
+  // Global
   try {
+    if (truffleConfig.usePluginTruffle) throw null;
+
     const globalTruffle = path.join(globalModules, 'truffle');
     const lib = require(globalTruffle);
-    app.ui.report('truffle-global');
+    ui.report('lib-global');
     return lib;
 
   } catch(err) {};
 
-  // Default: fallback
+  // Plugin Copy @ v 5.0.31
   try {
+    if (truffleConfig.forceLibFailure) throw null; // For err unit testing
 
-    app.ui.report('truffle-warn');
-    return require("./truffle.library")}
+    ui.report('lib-warn');
+    return require("./plugin-assets/truffle.library")
 
-  catch(err) {
-    const msg = app.ui.generate('truffle-fail', [err]);
+  } catch(err) {
+    const msg = ui.generate('lib-fail', [err]);
     throw new Error(msg);
   };
 
 }
 
-/**
- * Functions to generate substitute paths for instrumented contracts and artifacts.
- * @type {Object}
- */
-const paths = {
+function loadSolcoverJS(ui, truffleConfig){
+  let coverageConfig;
+  let solcoverjs;
 
-  // "contracts_build_directory":
-  artifacts: (truffle, app) => {
-    return path.join(
-      app.artifactsDir,
-      path.basename(truffle.contracts_build_directory)
-    )
+  // Handle --solcoverjs flag
+  (truffleConfig.solcoverjs)
+    ? solcoverjs = path.join(truffleConfig.working_directory, truffleConfig.solcoverjs)
+    : solcoverjs = path.join(truffleConfig.working_directory, '.solcover.js');
+
+  // Catch solcoverjs syntax errors
+  if (shell.test('-e', solcoverjs)){
+
+    try {
+      coverageConfig = require(solcoverjs);
+    } catch(error){
+      error.message = ui.generate('solcoverjs-fail') + error.message;
+      throw new Error(error)
+    }
+
+  // Config is optional
+  } else {
+    coverageConfig = {};
   }
+
+  coverageConfig.log = truffleConfig.logger.log;
+  coverageConfig.cwd = truffleConfig.working_directory;
+  coverageConfig.originalContractsDir = truffleConfig.contracts_directory;
+
+  return coverageConfig;
 }
 
+
 module.exports = plugin;