@1inch/solidity-utils 2.0.11 → 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/EthReceiver.sol

@@ -4,8 +4,10 @@ pragma solidity ^0.8.0;
 pragma abicoder v1;
 
 abstract contract EthReceiver {
+    error EthDepositRejected();
+
     receive() external payable {
         // solhint-disable-next-line avoid-tx-origin
-        require(msg.sender != tx.origin, "ETH deposit rejected");
+        if (msg.sender == tx.origin) revert EthDepositRejected();
     }
 }

package/contracts/GasChecker.sol

@@ -3,17 +3,13 @@
 pragma solidity ^0.8.0;
 pragma abicoder v1;
 
-import "@openzeppelin/contracts/utils/Strings.sol";
-
 contract GasChecker {
-    using Strings for uint256;
+    error GasCostDiffers(uint256 expected, uint256 actual);
 
-    modifier checkGasCost(uint256 expectedGasCost) {
+    modifier checkGasCost(uint256 expected) {
         uint256 gas = gasleft();
         _;
-        gas -= gasleft();
-        if (expectedGasCost > 0) {
-            require (gas == expectedGasCost, string(abi.encodePacked("Gas cost differs: expected ", expectedGasCost.toString(), ", actual: ", gas.toString())));
-        }
+        unchecked { gas -= gasleft(); }
+        if (expected > 0 && gas != expected) revert GasCostDiffers(expected, gas);
     }
 }

package/contracts/OnlyWethReceiver.sol

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+pragma abicoder v1;
+
+abstract contract OnlyWethReceiver {
+    error EthDepositRejected();
+
+    // solhint-disable-next-line var-name-mixedcase
+    address internal immutable _WETH;
+
+    constructor(address weth) {
+        _WETH = weth;
+    }
+
+    receive() external payable {
+        // solhint-disable-next-line avoid-tx-origin
+        if (msg.sender != _WETH) revert EthDepositRejected();
+    }
+}

package/contracts/Permitable.sol

@@ -5,25 +5,26 @@ pragma abicoder v1;
 
 import "@openzeppelin/contracts/token/ERC20/extensions/draft-IERC20Permit.sol";
 import "./interfaces/IDaiLikePermit.sol";
+import "./libraries/RevertReasonForwarder.sol";
 
 contract Permitable {
     error BadPermitLength();
-    error PermitFailed();
 
     function _permit(address token, bytes calldata permit) internal virtual {
         if (permit.length > 0) {
             bool success;
-            bytes memory result;
             if (permit.length == 32 * 7) {
                 // solhint-disable-next-line avoid-low-level-calls
-                (success, result) = token.call(abi.encodePacked(IERC20Permit.permit.selector, permit));
+                (success,) = token.call(abi.encodePacked(IERC20Permit.permit.selector, permit));
             } else if (permit.length == 32 * 8) {
                 // solhint-disable-next-line avoid-low-level-calls
-                (success, result) = token.call(abi.encodePacked(IDaiLikePermit.permit.selector, permit));
+                (success,) = token.call(abi.encodePacked(IDaiLikePermit.permit.selector, permit));
             } else {
                 revert BadPermitLength();
             }
-            if (!success) revert PermitFailed();
+            if (!success) {
+                RevertReasonForwarder.reRevert();
+            }
         }
     }
 }

package/contracts/libraries/AddressArray.sol

@@ -35,33 +35,39 @@ library AddressArray {
         if (len > output.length) revert OutputArrayTooSmall();
         if (len > 0) {
             output[0] = address(uint160(lengthAndFirst));
-            for (uint i = 1; i < len; i++) {
-                output[i] = address(uint160(self._raw[i]));
+            unchecked {
+                for (uint i = 1; i < len; i++) {
+                    output[i] = address(uint160(self._raw[i]));
+                }
             }
         }
         return output;
     }
 
     function push(Data storage self, address account) internal returns(uint256) {
-        uint256 lengthAndFirst = self._raw[0];
-        uint256 len = lengthAndFirst >> 160;
-        if (len == 0) {
-            self._raw[0] = (1 << 160) + uint160(account);
-        }
-        else {
-            self._raw[0] = lengthAndFirst + (1 << 160);
-            self._raw[len] = uint160(account);
+        unchecked {
+            uint256 lengthAndFirst = self._raw[0];
+            uint256 len = lengthAndFirst >> 160;
+            if (len == 0) {
+                self._raw[0] = (1 << 160) + uint160(account);
+            }
+            else {
+                self._raw[0] = lengthAndFirst + (1 << 160);
+                self._raw[len] = uint160(account);
+            }
+            return len + 1;
         }
-        return len + 1;
     }
 
     function pop(Data storage self) internal {
-        uint256 lengthAndFirst = self._raw[0];
-        uint256 len = lengthAndFirst >> 160;
-        if (len == 0) revert PopFromEmptyArray();
-        self._raw[len - 1] = 0;
-        if (len > 1) {
-            self._raw[0] = lengthAndFirst - (1 << 160);
+        unchecked {
+            uint256 lengthAndFirst = self._raw[0];
+            uint256 len = lengthAndFirst >> 160;
+            if (len == 0) revert PopFromEmptyArray();
+            self._raw[len - 1] = 0;
+            if (len > 1) {
+                self._raw[0] = lengthAndFirst - (1 << 160);
+            }
         }
     }
 

package/contracts/libraries/AddressSet.sol

@@ -39,9 +39,11 @@ library AddressSet {
             return false;
         }
         if (index < s.items.length()) {
-            address lastItem = s.items.at(s.items.length() - 1);
-            s.items.set(index - 1, lastItem);
-            s.lookup[lastItem] = index;
+            unchecked {
+                address lastItem = s.items.at(s.items.length() - 1);
+                s.items.set(index - 1, lastItem);
+                s.lookup[lastItem] = index;
+            }
         }
         s.items.pop();
         delete s.lookup[item];

package/contracts/libraries/RevertReasonForwarder.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.0;
+pragma abicoder v1;
+
+library RevertReasonForwarder {
+    function reRevert() internal pure {
+        // bubble up revert reason from latest external call
+        assembly {  // solhint-disable-line no-inline-assembly
+            returndatacopy(0, 0, returndatasize())
+            revert(0, returndatasize())
+        }
+    }
+}

package/contracts/libraries/RevertReasonParser.sol

@@ -16,6 +16,8 @@ library RevertReasonParser {
     using StringUtil for uint256;
     using StringUtil for bytes;
 
+    error InvalidRevertReason();
+
     bytes4 constant private _ERROR_SELECTOR = bytes4(keccak256("Error(string)"));
     bytes4 constant private _PANIC_SELECTOR = bytes4(keccak256("Panic(uint256)"));
 
@@ -42,8 +44,8 @@ library RevertReasonParser {
                 because of that we can't check for equality and instead check
                 that string length + extra 68 bytes is less than overall data length
             */
-            require(data.length >= 68 + bytes(reason).length, "Invalid revert reason");
-            return string(abi.encodePacked(prefix, "Error(", reason, ")"));
+            if (data.length < 68 + bytes(reason).length) revert InvalidRevertReason();
+            return string.concat(prefix, "Error(", reason, ")");
         }
         // 36 = 4-byte selector + 32 bytes integer
         else if (selector == _PANIC_SELECTOR && data.length == 36) {
@@ -53,8 +55,8 @@ library RevertReasonParser {
                 // 36 = 32 bytes data length + 4-byte selector
                 code := mload(add(data, 36))
             }
-            return string(abi.encodePacked(prefix, "Panic(", code.toHex(), ")"));
+            return string.concat(prefix, "Panic(", code.toHex(), ")");
         }
-        return string(abi.encodePacked(prefix, "Unknown(", data.toHex(), ")"));
+        return string.concat(prefix, "Unknown(", data.toHex(), ")");
     }
 }

package/contracts/libraries/UniERC20.sol

@@ -6,13 +6,19 @@ 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));
 
@@ -41,9 +47,9 @@ library UniERC20 {
     function uniTransferFrom(IERC20 token, address payable from, address to, uint256 amount) internal {
         if (amount > 0) {
             if (isETH(token)) {
-                require(msg.value >= amount, "UniERC20: not enough value");
-                require(from == msg.sender, "from is not msg.sender");
-                require(to == address(this), "to is not this");
+                if (msg.value < amount) revert NotEnoughValue();
+                if (from != msg.sender) revert FromIsNotSender();
+                if (to != address(this)) revert ToIsNotThis();
                 if (msg.value > amount) {
                     // Return remainder if exist
                     from.transfer(msg.value.sub(amount));
@@ -63,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));
@@ -91,7 +97,7 @@ library UniERC20 {
         if (success && data.length >= 96) {
             (uint256 offset, uint256 len) = abi.decode(data, (uint256, uint256));
             if (offset == 0x20 && len > 0 && len <= 256) {
-                return string(abi.decode(data, (bytes)));
+                return abi.decode(data, (string));
             }
         }
 
@@ -103,8 +109,10 @@ library UniERC20 {
 
             if (len > 0) {
                 bytes memory result = new bytes(len);
-                for (uint i = 0; i < len; i++) {
-                    result[i] = data[i];
+                unchecked {
+                    for (uint i = 0; i < len; i++) {
+                        result[i] = data[i];
+                    }
                 }
                 return string(result);
             }
@@ -117,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/dist/src/index.js

@@ -2,9 +2,9 @@
 // created from 'create-ts-index'
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-(0, tslib_1.__exportStar)(require("./asserts"), exports);
-(0, tslib_1.__exportStar)(require("./permit"), exports);
-(0, tslib_1.__exportStar)(require("./prelude"), exports);
-(0, tslib_1.__exportStar)(require("./profileEVM"), exports);
-(0, tslib_1.__exportStar)(require("./utils"), exports);
+tslib_1.__exportStar(require("./asserts"), exports);
+tslib_1.__exportStar(require("./permit"), exports);
+tslib_1.__exportStar(require("./prelude"), exports);
+tslib_1.__exportStar(require("./profileEVM"), exports);
+tslib_1.__exportStar(require("./utils"), exports);
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,iCAAiC;;;AAEjC,yDAA0B;AAC1B,wDAAyB;AACzB,yDAA0B;AAC1B,4DAA6B;AAC7B,uDAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,iCAAiC;;;AAEjC,oDAA0B;AAC1B,mDAAyB;AACzB,oDAA0B;AAC1B,uDAA6B;AAC7B,kDAAwB"}

package/dist/src/prelude.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.should = exports.config = exports.expect = exports.assert = exports.AssertionError = exports.Assertion = exports.ether = exports.time = exports.toBN = exports.constants = void 0;
 const tslib_1 = require("tslib");
-const chai_1 = (0, tslib_1.__importStar)(require("chai"));
+const chai_1 = tslib_1.__importStar(require("chai"));
 Object.defineProperty(exports, "Assertion", { enumerable: true, get: function () { return chai_1.Assertion; } });
 Object.defineProperty(exports, "AssertionError", { enumerable: true, get: function () { return chai_1.AssertionError; } });
 Object.defineProperty(exports, "assert", { enumerable: true, get: function () { return chai_1.assert; } });
@@ -10,7 +10,7 @@ Object.defineProperty(exports, "expect", { enumerable: true, get: function () {
 Object.defineProperty(exports, "config", { enumerable: true, get: function () { return chai_1.config; } });
 Object.defineProperty(exports, "should", { enumerable: true, get: function () { return chai_1.should; } });
 require("chai-bn");
-const chai_as_promised_1 = (0, tslib_1.__importDefault)(require("chai-as-promised"));
+const chai_as_promised_1 = tslib_1.__importDefault(require("chai-as-promised"));
 const web3_utils_1 = require("web3-utils");
 Object.defineProperty(exports, "toBN", { enumerable: true, get: function () { return web3_utils_1.toBN; } });
 chai_1.default.use(chai_as_promised_1.default);

package/dist/src/prelude.js.map

@@ -1 +1 @@
-{"version":3,"file":"prelude.js","sourceRoot":"","sources":["../../src/prelude.ts"],"names":[],"mappings":";;;;AAAA,0DAAuF;AAqCnF,0FArCW,gBAAS,OAqCX;AACT,+FAtCsB,qBAAc,OAsCtB;AACd,uFAvCsC,aAAM,OAuCtC;AACN,uFAxC8C,aAAM,OAwC9C;AACN,uFAzCsD,aAAM,OAyCtD;AACN,uFA1C8D,aAAM,OA0C9D;AAzCV,mBAAiB;AACjB,qFAA8C;AAC9C,2CAAyC;AAiBrC,qFAjBK,iBAAI,OAiBL;AAfR,cAAI,CAAC,GAAG,CAAC,0BAAc,CAAC,CAAC;AACzB,8DAA8D;AAC9D,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;AAEpD,QAAA,SAAS,GAAG;IACrB,YAAY,EAAE,4CAA4C;IAC1D,WAAW,EAAE,4CAA4C;IACzD,YAAY,EAAE,oEAAoE;IAClF,WAAW,EAAE,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjE,UAAU,EAAE,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChE,UAAU,EAAE,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC3D,CAAC;AAaE,QAAA,IAAI,GAAS,QAAQ,CAAC;AAEnC,SAAgB,KAAK,CAAE,CAAS;IAC5B,OAAO,IAAA,iBAAI,EAAC,IAAA,kBAAK,EAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AACnC,CAAC;AAFD,sBAEC"}
+{"version":3,"file":"prelude.js","sourceRoot":"","sources":["../../src/prelude.ts"],"names":[],"mappings":";;;;AAAA,qDAAuF;AAqCnF,0FArCW,gBAAS,OAqCX;AACT,+FAtCsB,qBAAc,OAsCtB;AACd,uFAvCsC,aAAM,OAuCtC;AACN,uFAxC8C,aAAM,OAwC9C;AACN,uFAzCsD,aAAM,OAyCtD;AACN,uFA1C8D,aAAM,OA0C9D;AAzCV,mBAAiB;AACjB,gFAA8C;AAC9C,2CAAyC;AAiBrC,qFAjBK,iBAAI,OAiBL;AAfR,cAAI,CAAC,GAAG,CAAC,0BAAc,CAAC,CAAC;AACzB,8DAA8D;AAC9D,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;AAEpD,QAAA,SAAS,GAAG;IACrB,YAAY,EAAE,4CAA4C;IAC1D,WAAW,EAAE,4CAA4C;IACzD,YAAY,EAAE,oEAAoE;IAClF,WAAW,EAAE,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjE,UAAU,EAAE,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChE,UAAU,EAAE,IAAA,iBAAI,EAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAA,iBAAI,EAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC3D,CAAC;AAaE,QAAA,IAAI,GAAS,QAAQ,CAAC;AAEnC,SAAgB,KAAK,CAAE,CAAS;IAC5B,OAAO,IAAA,iBAAI,EAAC,IAAA,kBAAK,EAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AACnC,CAAC;AAFD,sBAEC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1inch/solidity-utils",
-  "version": "2.0.11",
+  "version": "2.0.14",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -20,7 +20,8 @@
     "lint:ts:fix": "eslint . --fix --ext .ts",
     "lint:sol": "solhint --max-warnings 0 \"contracts/**/*.sol\"",
     "lint:sol:fix": "solhint --max-warnings 0 \"contracts/**/*.sol\" --fix",
-    "test": "hardhat test",
+    "test": "hardhat test --parallel",
+    "test:ci": "hardhat test",
     "typecheck": "tsc --noEmit --skipLibCheck",
     "typechain": "hardhat typechain"
   },
@@ -33,44 +34,44 @@
     "chai-as-promised": "7.1.1",
     "chai-bn": "0.3.1",
     "ethereumjs-util": "7.1.4",
-    "web3-utils": "1.7.0"
+    "web3-utils": "1.7.1"
   },
   "devDependencies": {
-    "@nomiclabs/hardhat-etherscan": "3.0.1",
-    "@nomiclabs/hardhat-truffle5": "2.0.4",
+    "@nomiclabs/hardhat-truffle5": "2.0.5",
     "@nomiclabs/hardhat-web3": "2.0.0",
-    "@typechain/hardhat": "4.0.0",
+    "@typechain/hardhat": "6.0.0",
     "@typechain/truffle-v5": "7.0.0",
     "@types/chai": "4.3.0",
     "@types/chai-as-promised": "7.1.5",
     "@types/mocha": "9.1.0",
-    "@types/node": "17.0.18",
-    "@typescript-eslint/eslint-plugin": "5.12.0",
-    "@typescript-eslint/parser": "5.12.0",
+    "@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",
-    "eslint": "8.9.0",
+    "eslint": "8.12.0",
     "eslint-config-standard": "16.0.3",
-    "eslint-plugin-import": "2.25.4",
+    "eslint-plugin-import": "2.26.0",
     "eslint-plugin-node": "11.1.0",
     "eslint-plugin-promise": "6.0.0",
     "eslint-plugin-standard": "5.0.0",
     "eslint-plugin-typescript": "0.14.0",
-    "hardhat": "2.8.4",
-    "hardhat-deploy": "0.10.5",
+    "hardhat": "2.9.3",
     "hardhat-gas-reporter": "1.0.8",
     "rimraf": "3.0.2",
     "shx": "0.3.4",
-    "solc": "0.8.11",
     "solhint": "3.3.7",
     "solidity-coverage": "0.7.20",
-    "ts-node": "10.5.0",
+    "ts-node": "10.7.0",
     "typechain": "7.0.0",
-    "typescript": "4.5.5"
+    "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;
+}