@1inch/solidity-utils 2.0.13 → 2.0.14

package/README.md

@@ -64,3 +64,96 @@ Add to `package.json` file solidity compiler version and shortcut to run command
 ```
 
 ...
+
+#### Test documentation generator (test-docgen)
+Script generates documentation for tests in markdown format.
+Give descriptions for `describe` and `it` sections and build documentation using these descriptions.
+
+##### Example
+Test described as shown below
+
+```JavaScript
+// Test suite
+describe('My feature', function() {
+    // Nested test suite 
+    describe("My subfeature", function() {
+        /*
+            **Test case 1**
+            Test case should work
+         */
+        it("My case", function() {
+        // code here
+        })
+    })
+})
+```
+will generated the following output
+```Markdown
+
+# My feature
+
+Test suite
+
+## My subfeature
+
+Nested test suite 
+
+### My case
+
+**Test case 1**
+Test case should work
+```
+
+##### Installation
+- Before use install documentation parser
+```
+yarn add acquit --dev
+```
+- Optionally configure script for default usage. Add to `script` section in `package.json` 
+```
+"test:docs": "npx test-docgen"
+```
+- Optionally configure script for generating test list only. Add to `script` section in `package.json` 
+```
+"test:docs": "npx test-docgen -l"
+```
+
+##### Usage
+If script configured
+```
+yarn test:docs
+```
+or
+```
+npx test-docgen
+```
+
+Available parameters
+```
+Options:
+  -i, --input <input>      tests directory (default: "test")
+  -x, --exclude [exclude]  exclude directories and files. omit argument to exclude all subdirectories (default: false)
+  -o, --output <output>    file to write output (default: "TESTS.md")
+  -c, --code               include code (default: false)
+  -l, --list               list tests only, do not include description (default: false)
+  -d, --debug              debug mode (default: false)
+  -h, --help               display help for command
+```
+##### Examples
+Generate docs with default input and output
+```
+npx test-docgen
+```
+
+Generate docs for files in folders `tests/mocks` and `tests/utils`
+```
+npx test-docgen -i "tests/mocks;tests/utils"
+```
+Exclude from docs file `test/mock-exclude.js` and `test/utils folder`
+```
+npx test-docgen -x "tests/mock-exclude.js;tests/utils"
+```
+Generate list of tests only
+```
+npx test-docgen -l
+```

package/contracts/libraries/UniERC20.sol

@@ -6,16 +6,18 @@ pragma abicoder v1;
 import "@openzeppelin/contracts/utils/math/SafeMath.sol";
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
-import "./RevertReasonParser.sol";
+import "./RevertReasonForwarder.sol";
 import "./StringUtil.sol";
 
 library UniERC20 {
     using SafeMath for uint256;
     using SafeERC20 for IERC20;
 
+    error ApproveCalledOnETH();
     error NotEnoughValue();
     error FromIsNotSender();
     error ToIsNotThis();
+    error ERC20OperationFailed();
 
     IERC20 private constant _ETH_ADDRESS = IERC20(0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE);
     IERC20 private constant _ZERO_ADDRESS = IERC20(address(0));
@@ -67,7 +69,7 @@ library UniERC20 {
     }
 
     function uniApprove(IERC20 token, address to, uint256 amount) internal {
-        require(!isETH(token), "Approve called on ETH");
+        if (isETH(token)) revert ApproveCalledOnETH();
 
         // solhint-disable-next-line avoid-low-level-calls
         (bool success, bytes memory returndata) = address(token).call(abi.encodeWithSelector(token.approve.selector, to, amount));
@@ -123,11 +125,11 @@ library UniERC20 {
         // solhint-disable-next-line avoid-low-level-calls
         (bool success, bytes memory result) = address(token).call(data);
         if (!success) {
-            revert(RevertReasonParser.parse(result, "Low-level call failed: "));
+            RevertReasonForwarder.reRevert();
         }
 
         if (result.length > 0) { // Return data is optional
-            require(abi.decode(result, (bool)), "ERC20 operation did not succeed");
+            if (!abi.decode(result, (bool))) revert ERC20OperationFailed();
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1inch/solidity-utils",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -47,6 +47,8 @@
     "@types/node": "17.0.23",
     "@typescript-eslint/eslint-plugin": "5.18.0",
     "@typescript-eslint/parser": "5.18.0",
+    "acquit": "1.2.1",
+    "commander": "^9.1.0",
     "create-ts-index": "^1.14.0",
     "cross-spawn": "7.0.3",
     "dotenv": "16.0.0",
@@ -68,7 +70,8 @@
     "typescript": "4.6.3"
   },
   "bin": {
-    "solidity-utils-docify": "utils/docify.utils.js"
+    "solidity-utils-docify": "utils/docify.utils.js",
+    "test-docgen": "utils/test-docgen.js"
   },
   "bugs": {
     "url": "https://github.com/1inch/solidity-utils/issues"

package/utils/acquit-markdown.js

@@ -0,0 +1,53 @@
+'use strict';
+
+module.exports = plugin;
+
+function plugin(instance, options) {
+  if (instance) {
+    instance.output(markdown(options, instance));
+  } else {
+    const acquit = require('acquit');
+    acquit.output(markdown(options, acquit));
+  }
+};
+
+plugin.markdown = markdown;
+
+function markdown(options, acquit) {
+  return function(res) {
+    return recurse(res, 0, options, acquit);
+  };
+}
+
+function recurse(blocks, level, options, acquit) {
+  var str = '';
+  var hashes = getHashes(level + 1);
+  for (var i = 0; i < blocks.length; ++i) {
+    if (blocks[i].contents) {
+      str += hashes + ' ' + (blocks[i].type === 'it' ? (!options || !options.it ? 'It ': '') : '') +
+        blocks[i].contents;
+    }
+    str += '\n\n';
+    for (var j = 0; j < blocks[i].comments.length; ++j) {
+      str += acquit.trimEachLine(blocks[i].comments[j]);
+      str += '\n\n';
+    }
+    if (blocks[i].type === 'describe') {
+      str += recurse(blocks[i].blocks, level + 1, options, acquit);
+    } else if (blocks[i].code.trim() && options.code) {
+      str += ['```javascript', blocks[i].code, '```'].join('\n');
+    }
+    if (i + 1 < blocks.length) {
+      str += '\n\n';
+    }
+  }
+  return str;
+}
+
+function getHashes(level) {
+  var str = '';
+  for (var i = 0; i < level; ++i) {
+    str += '#';
+  }
+  return str;
+}

package/utils/test-docgen.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+const commander = require('commander');
+const fs  = require('fs');
+const path = require('path');
+const program = new commander.Command();
+
+
+program
+    .option('-i, --input <input>', 'tests directory', 'test')
+    .option('-x, --exclude [exclude]', 'exclude directories and files. omit argument to exclude all subdirectories', false)
+    .option('-o, --output <output>', 'file to write output', 'TESTS.md')
+    .option('-c, --code', 'include code', false)
+    .option('-l, --list', 'list tests only, do not include description', false)
+    .option('-d, --debug', 'debug mode', false);
+
+
+program.parse(process.argv);
+
+const options = program.opts();
+const debugMode = options.debug;
+const includeCode = options.code ? true : false;
+const listOnly = options.list ? true : false;
+const includeSubs = !(options.exclude === true);
+const inputDir = options.input.split(';');
+const outputFile = options.output;
+const excludeDirs = (typeof options.exclude == 'boolean') ? [] : options.exclude.split(';');
+
+if (debugMode){
+    console.log('----- DEBUG MODE -----');
+    console.log('options:', options);
+    console.log();
+    console.log('parsed options:');
+    console.log(
+        '  includeCode:', includeCode,
+        '\n  listOnly:', listOnly,
+        '\n  inputDir:', inputDir,
+        '\n  outputFile:', outputFile,
+        '\n  includeSubs:', includeSubs,
+        '\n  excludeDirs:', excludeDirs,
+        '\n  debugMode:', debugMode
+    );
+    console.log('\nRemaining arguments: ', program.args);
+    console.log('\nFiles and directories found:');
+}
+
+let files = [];
+function throughDirectory (directory, includeSubs, excludeDirs) {
+    if (!fs.existsSync(directory)) {
+        console.log('WARNING! Directory does not exist:', directory, '=> skipped');
+        return;
+    }
+
+    fs.readdirSync(directory).forEach(file => {
+        const absolute = path.join(directory, file);
+        if (debugMode) console.log(absolute);
+        if (!excludeDirs.includes(absolute)) {
+            if (fs.statSync(absolute).isDirectory()){
+                if (includeSubs) throughDirectory(absolute, includeSubs, excludeDirs);
+            }
+            else files.push(absolute);
+        }
+    });
+}
+
+inputDir.forEach(dir => {
+    throughDirectory(dir, includeSubs, excludeDirs);
+});
+
+if (debugMode) console.log('\nfiles:', files);
+
+
+
+//Script
+const acquitMd = require('acquit')();
+const acquitJson = require('acquit')();
+require('./acquit-markdown.js')(acquitMd, { code: includeCode, it: true });
+
+const legend = {};
+let content;
+let markdown = '';
+let legendMd = '';
+
+if (debugMode) console.log('\nFiles processed:');
+files.forEach((file) => {
+    content = fs.readFileSync(file).toString();
+    legend.blocks = acquitJson.parse(content);
+    legend.contents = file;
+    legendMd += buildLegend(legend, 1, listOnly);
+    markdown += acquitMd.parse(content).toString();
+    markdown += '\n';
+    if (debugMode) console.log(' ', file, '=> done');
+});
+
+content = listOnly ? legendMd : legendMd + markdown;
+
+fs.writeFileSync(outputFile, content);
+console.log('done');
+
+function buildLegend (block, depth, listOnly) {
+    // console.log(depth, block.contents);
+    const url = (block.contents == null)
+        ? ''
+        : block.contents.toLowerCase().trim()
+            .split(' ').join('-')
+            .split(/,|\+|\/|:|\(|\)/).join('')
+            .replace('--', '-');
+    let legend = listOnly
+        ? Array(depth).join('    ') + '* ' + block.contents + '\n'
+        : Array(depth).join('    ') + '* [' + block.contents + '](#' + url + ')\n';
+    if (block.blocks) {
+        legend += block.blocks.map(function (child) {
+            return buildLegend(child, depth + 1, listOnly);
+        }).join('');
+    }
+    return legend;
+}