Add ABI diff logic (#598)

Author: cgewecke

README.md

@@ -101,8 +101,9 @@ module.exports = {
 | measureStatementCoverage | *boolean* | `true` | Computes statement (in addition to line) coverage. [More...][34] |
 | measureFunctionCoverage | *boolean* | `true` | Computes function coverage. [More...][34] |
 | measureModifierCoverage | *boolean* | `true` | Computes each modifier invocation as a code branch. [More...][34] |
-| matrixOutputPath | *String* | `./testMatrix.json` | Relative path to write test matrix JSON object to. [More...][39] |
 | modifierWhitelist | *String[]* | `[]` | List of modifier names (ex: "onlyOwner") to exclude from branch measurement. (Useful for modifiers which prepare something instead of acting as a gate.)) |
+| matrixOutputPath | *String* | `./testMatrix.json` | Relative path to write test matrix JSON object to. [More...][39] |
+| abiOutputPath | *String* | `./humanReadableAbis.json` | Relative path to write diff-able ABI data to |
 | istanbulFolder | *String* | `./coverage` |  Folder location for Istanbul coverage reports. |
 | istanbulReporter | *Array* | `['html', 'lcov', 'text', 'json']` | [Istanbul coverage reporters][2]  |
 | mocha | *Object* | `{ }` | [Mocha options][3] to merge into existing mocha config. `grep` and `invert` are useful for skipping certain tests under coverage using tags in the test descriptions.|

lib/abi.js

@@ -0,0 +1,99 @@
+const ethersABI = require("@ethersproject/abi");
+const difflib = require('difflib');
+
+class AbiUtils {
+
+  diff(orig={}, cur={}){
+    let plus = 0;
+    let minus = 0;
+
+    const unifiedDiff = difflib.unifiedDiff(
+      orig.humanReadableAbiList,
+      cur.humanReadableAbiList,
+      {
+        fromfile: orig.contractName,
+        tofile: cur.contractName,
+        fromfiledate: `sha: ${orig.sha}`,
+        tofiledate: `sha: ${cur.sha}`,
+        lineterm: ''
+      }
+    );
+
+    // Count changes (unified diff always has a plus & minus in header);
+    if (unifiedDiff.length){
+      plus = -1;
+      minus = -1;
+    }
+
+    unifiedDiff.forEach(line => {
+      if (line[0] === `+`) plus++;
+      if (line[0] === `-`) minus++;
+    })
+
+    return {
+      plus,
+      minus,
+      unifiedDiff
+    }
+  }
+
+  toHumanReadableFunctions(contract){
+    const human = [];
+    const ethersOutput = new ethersABI.Interface(contract.abi).functions;
+    const signatures = Object.keys(ethersOutput);
+
+    for (const sig of signatures){
+      const method = ethersOutput[sig];
+      let returns = '';
+
+      method.outputs.forEach(output => {
+        (returns.length)
+          ? returns += `, ${output.type}`
+          : returns += output.type;
+      });
+
+      let readable = `${method.type} ${sig} ${method.stateMutability}`;
+
+      if (returns.length){
+        readable += ` returns (${returns})`
+      }
+
+      human.push(readable);
+    }
+
+    return human;
+  }
+
+  toHumanReadableEvents(contract){
+    const human = [];
+    const ethersOutput = new ethersABI.Interface(contract.abi).events;
+    const signatures = Object.keys(ethersOutput);
+
+    for (const sig of signatures){
+      const method = ethersOutput[sig];
+      const readable = `${ethersOutput[sig].type} ${sig}`;
+      human.push(readable);
+    }
+
+    return human;
+  }
+
+  generateHumanReadableAbiList(_artifacts, sha){
+    const list = [];
+    if (_artifacts.length){
+      for (const item of _artifacts){
+        const fns = this.toHumanReadableFunctions(item);
+        const evts = this.toHumanReadableEvents(item);
+        const all = fns.concat(evts);
+        list.push({
+          contractName: item.contractName,
+          sha: sha,
+          humanReadableAbiList: all
+        })
+      }
+    }
+    return list;
+  }
+}
+
+module.exports = AbiUtils;

lib/api.js

@@ -12,13 +12,15 @@ const Instrumenter = require('./instrumenter');
 const Coverage = require('./coverage');
 const DataCollector = require('./collector');
 const AppUI = require('./ui').AppUI;
+const AbiUtils = require('./abi');
 
 /**
  * Coverage Runner
  */
 class API {
   constructor(config={}) {
-    this.validator = new ConfigValidator()
+    this.validator = new ConfigValidator();
+    this.abiUtils = new AbiUtils();
     this.config = config || {};
     this.testMatrix = {};
 
@@ -31,6 +33,7 @@ class API {
     this.testsErrored = false;
 
     this.cwd = config.cwd || process.cwd();
+    this.abiOutputPath = config.abiOutputPath || "humanReadableAbis.json";
     this.matrixOutputPath = config.matrixOutputPath || "testMatrix.json";
     this.matrixReporterPath = config.matrixReporterPath || "solidity-coverage/plugins/resources/matrix.js"
 
@@ -360,6 +363,11 @@ class API {
     fs.writeFileSync(matrixPath, JSON.stringify(mapping, null, ' '));
   }
 
+  saveHumanReadableAbis(data){
+    const abiPath = path.join(this.cwd, this.abiOutputPath);
+    fs.writeFileSync(abiPath, JSON.stringify(data, null, ' '));
+  }
+
   // =====
   // Paths
   // =====

lib/validator.js

@@ -14,7 +14,9 @@ const configSchema = {
     client: {type: "object"},
     cwd:    {type: "string"},
     host:   {type: "string"},
-
+    abiOutputPath:      {type: "string"},
+    matrixOutputPath:   {type: "string"},
+    matrixReporterPath: {type: "string"},
     port:                 {type: "number"},
     providerOptions:      {type: "object"},
     silent:               {type: "boolean"},

package.json

@@ -25,10 +25,12 @@
   "license": "ISC",
   "dependencies": {
     "@solidity-parser/parser": "^0.14.0",
+    "@ethersproject/abi": "^5.0.9",
     "@truffle/provider": "^0.2.24",
     "chalk": "^2.4.2",
     "death": "^1.1.0",
     "detect-port": "^1.3.0",
+    "difflib": "^0.2.4",
     "fs-extra": "^8.1.0",
     "ghost-testrpc": "^0.0.2",
     "global-modules": "^2.0.0",

plugins/resources/nomiclabs.utils.js

@@ -181,6 +181,35 @@ function collectTestMatrixData(args, env, api){
   }
 }
 
+/**
+ * Returns all Hardhat artifacts.
+ * @param  {HRE} env
+ * @return {Artifact[]}
+ */
+async function getAllArtifacts(env){
+  const all = [];
+  const qualifiedNames = await env.artifacts.getArtifactPaths();
+  for (const name of qualifiedNames){
+    all.push(await env.artifacts.readArtifact(name));
+  }
+  return all;
+}
+
+/**
+ * Compiles project
+ * Collects all artifacts from Hardhat project,
+ * Converts them to a format that can be consumed by api.abiUtils.diff
+ * Saves them to `api.abiOutputPath`
+ * @param  {HRE}    env
+ * @param  {SolidityCoverageAPI} api
+ */
+async function generateHumanReadableAbiList(env, api){
+  await env.run(TASK_COMPILE);
+  const _artifacts = getAllArtifacts(env);
+  const list = api.abiUtils.generateHumanReadableAbiList(_artifacts)
+  api.saveHumanReadableAbis(list);
+}
+
 /**
  * Sets the default `from` account field in the network that will be used.
  * This needs to be done after accounts are fetched from the launched client.
@@ -233,6 +262,7 @@ module.exports = {
   setupHardhatNetwork,
   getTestFilePaths,
   setNetworkFrom,
-  collectTestMatrixData
+  collectTestMatrixData,
+  getAllArtifacts
 }
 

plugins/resources/truffle.utils.js

@@ -35,6 +35,39 @@ async function getTestFilePaths(config){
   return target.filter(f => f.match(testregex) != null);
 }
 
+/**
+ * Returns all Truffle artifacts.
+ * @param  {TruffleConfig} config
+ * @return {Artifact[]}
+ */
+function getAllArtifacts(config){
+  const all = [];
+  const artifactsGlob = path.join(config.artifactsDir, '/**/*.json');
+  const files = globby.sync([artifactsGlob])
+  for (const file of files){
+    const candidate = require(file);
+    if (candidate.contractName && candidate.abi){
+      all.push(candidate);
+    }
+  }
+  return all;
+}
+
+/**
+ * Compiles project
+ * Collects all artifacts from Truffle project,
+ * Converts them to a format that can be consumed by api.abiUtils.diff
+ * Saves them to `api.abiOutputPath`
+ * @param  {TruffleConfig} config
+ * @param  {TruffleAPI}    truffle
+ * @param  {SolidityCoverageAPI} api
+ */
+async function generateHumanReadableAbiList(config, truffle, api){
+  await truffle.compile(config);
+  const _artifacts = getAllArtifacts(config);
+  const list = api.abiUtils.generateHumanReadableAbiList(_artifacts)
+  api.saveHumanReadableAbis(list);
+}
 
 /**
  * Configures the network. Runs before the server is launched.

test/sources/solidity/contracts/diff/addition.sol

@@ -0,0 +1,38 @@
+pragma solidity ^0.7.0;
+
+contract Old {
+  uint public y;
+
+  function a() public {
+    bool x = true;
+  }
+
+  function b() external {
+    bool x = true;
+  }
+
+  function c() external {
+    bool x = true;
+  }
+}
+
+contract New {
+  uint public y;
+
+  function a() public {
+    bool x = true;
+  }
+
+  function b() external {
+    bool x = true;
+  }
+
+  function c() external {
+    bool x = true;
+  }
+
+  function d() external {
+    bool x = true;
+  }
+}
+

test/sources/solidity/contracts/diff/events.sol

@@ -0,0 +1,23 @@
+pragma solidity ^0.7.0;
+
+contract Old {
+  uint y;
+
+  event Evt(uint x, bytes8 y);
+
+  function a() public {
+    bool x = true;
+  }
+}
+
+contract New {
+  uint y;
+
+  function a() public {
+    bool x = true;
+  }
+
+  event aEvt(bytes8);
+  event _Evt(bytes8 x, bytes8 y);
+}
+

test/sources/solidity/contracts/diff/no-change.sol

@@ -0,0 +1,34 @@
+pragma solidity ^0.7.0;
+
+contract Old {
+  uint y;
+
+  function a() public {
+    bool x = true;
+  }
+
+  function b() external {
+    bool x = true;
+  }
+
+  function c() external {
+    bool x = true;
+  }
+}
+
+contract New {
+  uint y;
+
+  function a() public {
+    bool x = true;
+  }
+
+  function b() external {
+    bool x = true;
+  }
+
+  function c() external {
+    bool x = true;
+  }
+}
+