@1inch/solidity-utils 5.3.0 → 6.0.0

package/utils/README.md

@@ -1,198 +0,0 @@
-### UTILS
-
-#### Docify
-
-Generates documentation in markdown format from natspec docs
-
-##### Usage
-Add to `package.json` file solidity compiler version (add version you use), solidity-docgen 0.6 util and shortcut to run command
-
-`devDependencies` section
-
-```
-"solc": "0.8.23",
-"solidity-docgen": "0.6.0-beta.36",
-```
-
-`scripts` section
-```
-"docify": "yarn hardhat docgen; npx solidity-utils-docify"
-```
-
-You can set output directory with ENV variable:
-```
-"docify": "DOCGEN_OUTPUT_DIR=./docs npx solidity-utils-docify"
-```
-
-Then set appopriate settings for docgen in `hardhat.config.js` file
-
-```JavaScript
-require('solidity-docgen');
-
-// You can use 1inch templates built-in templates
-const { oneInchTemplates } = require('@1inch/solidity-utils/docgen');
-
-module.exports = {
-...
-    docgen: {
-        outputDir: 'docs', // Can be omitted, docs used by default
-        templates: oneInchTemplates(), // 1inch templates
-        pages: 'files', // Doc output format for 1inch templates
-        exclude: ['mocks', 'test'], // Directories to exclude from generation
-    }
-}
-
-```
-
-#### Dependencies list (imports-list)
-
-Lists all imports recursively for the given solidity contract file.
-
-##### Usage
-```
-npx imports-list -i <solidity file> [-a <alias list>]
-```
-
-Available parameters
-```
-Options:
-  -i, --input <input>     file to get dependencies for
-  -a, --alias [alias...]  projects alias list
-  -h, --help              display help for command
-```
-Aliases are used to provide source code for third-party projects.
-For example, your contract uses imports from your other project and import is defined as
-```
-import "@1inch/otherproject/contracts/dependency.sol";
-```
-and you've got source code for `@1inch/otherproject` locally. Then you provide local path for the project to rip dependencies from `dependency.sol` as well.
-If there are several dependencies they should be provided using space as separator.
-
-##### Example
-File imports
-```Solidity
-#rootFile.sol
-import '@1inch/otherproject/contracts/dependency.sol'
-
-#@1inch/otherproject/contracts/dependency.sol
-import 'helpers/helper.sol'
-```
-File and folder structure
-```
-rootFolder/
-
--- mainProject/
----- contracts/
------- rootFile.sol
-
--- dependencyProject/
----- helpers/
------- helper.sol
----- dependency.sol
-```
-Command
-```
-rootFolder/mainProject % npx imports-list -i './contracts/rootFile.sol' -a '@1inch/otherproject' '../dependencyProject'
-```
-Output
-```
-Project => root
-not set
-
-Project => @1inch/otherproject
-../otherproject/contracts/dependency.sol
-../otherproject/contracts/helpers/helper.sol
-```
-
-#### 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/utils/acquit-markdown.js

@@ -1,53 +0,0 @@
-'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/docify.utils.js

@@ -1,99 +0,0 @@
-#!/usr/bin/env node
-const BASE_DIR = 'docs';
-const OUTPUT_DIR = process.env.DOCGEN_OUTPUT_DIR || `${BASE_DIR}`;
-
-const fs = require('fs');
-const path = require('path');
-
-function getFileNameWithoutExtension (fileName) {
-    return fileName.substr(0, fileName.lastIndexOf('.'));
-}
-
-function getReadmes (targetPath) {
-    let result = [];
-    const readmePath = path.join(targetPath, 'README.md');
-    if (!fs.existsSync(readmePath)) {
-        const content = `# ${path.basename(targetPath)}\n`;
-        result.push({ path: readmePath, content });
-    }
-    const childDirs = fs.readdirSync(targetPath, { withFileTypes: true }).filter(item => item.isDirectory());
-    for (const dir of childDirs) {
-        result = result.concat(getReadmes(path.join(targetPath, dir.name)));
-    }
-    return result;
-}
-
-function generateReadmes (readmes) {
-    for (const readme of readmes) {
-        fs.writeFileSync(readme.path, readme.content);
-    }
-}
-
-function getSummary (targetPath) {
-    function getSummaryRoot (summaryTargetPath, indentation) {
-        function specialCaseRoot (item) {
-            if (item.indentation >= 0) {
-                return item;
-            }
-            return ({
-                name: 'Main Readme',
-                path: item.path,
-                indentation: 0,
-            });
-        }
-
-        const items = fs.readdirSync(summaryTargetPath, { withFileTypes: true });
-        let result = [specialCaseRoot({
-            name: path.basename(summaryTargetPath),
-            path: path.relative(targetPath, path.join(summaryTargetPath, 'README.md')).replaceAll('\\', '/'),
-            indentation: indentation - 1,
-        })];
-        for (const dir of items.filter(item => item.isDirectory())) {
-            result = result.concat(getSummaryRoot(path.join(summaryTargetPath, dir.name), indentation + 1));
-        }
-        result = result
-            .concat(items
-                .filter(item => !item.isDirectory() &&
-                    !item.name.endsWith('README.md') &&
-                    !item.name.endsWith('SUMMARY.md'))
-                .map(file => ({
-                    name: getFileNameWithoutExtension(file.name),
-                    path: path.relative(targetPath, path.join(summaryTargetPath, file.name)).replaceAll('\\', '/'),
-                    indentation,
-                })));
-        return result;
-    }
-
-    function generateContent (summaryTree) {
-        const lines = summaryTree.map(x => `${'\t'.repeat(x.indentation)}* [${x.name}](${x.path})`).join('\n');
-        return `# Table of contents\n\n${lines}`;
-    }
-
-    return generateContent(getSummaryRoot(targetPath, 0));
-}
-
-function generateSummary (targetPath, summary) {
-    fs.writeFileSync(path.join(targetPath, 'SUMMARY.md'), summary);
-}
-
-function generateGitbookFiles () {
-    if (fs.existsSync(path.join(BASE_DIR, 'README.md'))){
-        fs.copyFileSync(path.join(BASE_DIR, 'README.md'), path.join(OUTPUT_DIR, 'README.md'));
-    }
-
-    const readmesToGenerate = getReadmes(OUTPUT_DIR);
-    const summary = getSummary(OUTPUT_DIR);
-
-    generateReadmes(readmesToGenerate);
-    generateSummary(OUTPUT_DIR, summary);
-}
-
-function removeUnwantedDocs () {
-    const unwantedDirs = ['mocks', 'tests'];
-    for (const unwantedDir of unwantedDirs) {
-        fs.rmSync(path.join(OUTPUT_DIR, unwantedDir), { force: true, recursive: true });
-    }
-}
-
-generateGitbookFiles();
-removeUnwantedDocs();

package/utils/file-dependencies.js

@@ -1,203 +0,0 @@
-#!/usr/bin/env node
-
-const fs  = require('fs');
-const path = require('path');
-const commander = require('commander');
-const program = new commander.Command();
-
-program
-    .name("imports-list")
-    .usage("-i <root file> [options]")
-    .requiredOption("-i, --input <input>", "file to get dependencies for")
-    .option("-a, --alias [alias...]", "alias list")
-
-
-program.parse(process.argv);
-
-const options = program.opts();
-// process input parameter
-const rootPath = options.input;
-// process alias parameter
-const aliases = {};
-const alias_opt = options.alias;
-if (alias_opt !=  undefined && alias_opt.length > 0){
-    if (alias_opt.length % 2 == 0){
-        for(let i=0; i<alias_opt.length; i+=2){
-            aliases[alias_opt[i]] = alias_opt[i+1];
-        }
-    }
-    else{
-        let warning_notice = "\nWARNING:Skipping alias parameter, there are odd number of arguments.";
-        warning_notice += "\nAliases should be set in the form of pairs seperated by space.";
-        warning_notice += "\nUsage: -a alias1 path1 alias2 path2";
-        console.warn(warning_notice);
-    }
-}
-
-// Script body
-const regexp = /^import ({.+} from )?"(?<source>.+)";/gm;
-
-const rootString = path.relative(process.cwd(), rootPath);
-
-let rootNode = new Node(null, new NodeItem('root', rootPath, path.resolve(rootPath)));
-let rootImports = extractImports(rootNode);
-rootImports = flattenResults(rootImports);
-
-// Scripts
-
-function Node(parentItem, nodeItem){
-    this.parent = parentItem;
-    this.import = nodeItem;
-}
-
-function NodeItem(name, source, path){
-    this.name = name;       // @1inch/solidity-utils/contracts/EthReceiver.sol
-    this.source = source;   // ./contracts/EthReceiver.sol
-    this.path = path;       // /usrs/james/Desktop/1inch/solidity-utils/contracts/EthReceiver.sol
-}
-
-function extractFileImports(file){
-    let imports = [];
-
-    if (file == null)
-        return imports;
-
-    let content = fs.readFileSync(file);
-    let result = content.toString().matchAll(regexp);
-
-    for (const match of result) {
-        let source = match.groups['source'];
-        if (source != null){
-            imports.push(source);
-        }
-        else{
-            console.log('No source found for import: ', match);
-        }
-    }
-
-    return imports;
-}
-
-function getAliasNameIfExists(source){
-    for(let alias in aliases){
-        if(source.startsWith(alias)){
-            return alias;
-        }
-    }
-
-    return false;
-}
-
-function getAliasIfExists(source){
-    for(let alias in aliases){
-        if(source.startsWith(alias)){
-            source = source.replace(alias, aliases[alias]);
-            return source;
-        }
-    }
-
-    return false;
-}
-
-function isAlias(dependencyLink){
-    return dependencyLink.startsWith('@');
-}
-
-function resolveProject(parentProject, dependencyLink){
-    if (isAlias(dependencyLink)) {
-        let alias = getAliasNameIfExists(dependencyLink);
-        if (alias){
-            return alias;
-        }
-        else{
-            return null;
-        }
-    }
-    else{
-        return parentProject;
-    }
-}
-
-function resolvePath(parentNode, dependencyLink){
-    if (isAlias(dependencyLink)) {
-        let alias = getAliasIfExists(dependencyLink)
-        if( alias ){
-            return path.join(process.cwd(), alias);
-        }
-        else{
-            return null;
-        }
-    }
-    let source_dir = path.dirname(parentNode.path);
-    return path.join(source_dir, dependencyLink);
-}
-
-function resolveLinks(parentNode, dependencyLinks, nodes = []){
-    for (let dependencyLink of dependencyLinks){
-        let project = resolveProject(parentNode.name, dependencyLink);
-        let dependencyPath = resolvePath(parentNode, dependencyLink);
-        let node = new Node(parentNode, new NodeItem(project, dependencyLink, dependencyPath));
-        nodes.push(node);
-    }
-
-    return nodes;
-}
-
-function extractImports(node, dependencies = []){
-    let dependencyLinks = extractFileImports(node.import.path);
-    let nodesToImport = resolveLinks(node.import, dependencyLinks);
-    for (let nodeToImport of nodesToImport){
-        let found = dependencies.find(item => item.import.path == nodeToImport.import.path);
-
-        if (!found){
-            dependencies.push(nodeToImport);
-            extractImports(nodeToImport, dependencies);
-        }
-    }
-    return dependencies;
-}
-
-function aliasCompare( a, b ) {
-    if ( a.import.name < b.import.name ){
-        return 1;
-    }
-    if ( a.import.name > b.import.name ){
-        return -1;
-    }
-    if( a.import.path < b.import.path ){
-        return -1;
-    }
-    if (a.import.path > b.import.path ){
-        return 1;
-    }
-    if ( a.import.source < b.import.source ){
-        return -1;
-    }
-    if ( a.import.source > b.import.source ){
-        return 1;
-    }
-    return 0;
-}
-
-function flattenResults(dependencyNodes){
-    dependencyNodes.sort(aliasCompare);
-
-    let prevProject = null;
-    for(let dependencyNode of dependencyNodes){
-        if (dependencyNode.import.name != prevProject){
-            console.log('\nProject =>', dependencyNode.import.name);
-            prevProject = dependencyNode.import.name;
-        }
-
-        let relativePath = 'not set';
-        if (dependencyNode.import.path != null){
-            relativePath = path.relative(process.cwd(), dependencyNode.import.path);
-        }
-        else{
-            relativePath = dependencyNode.import.source;
-        }
-
-
-        console.log(relativePath);
-    }
-}

package/utils/solidity-docgen-helpers.js

@@ -1,31 +0,0 @@
-module.exports = {
-    removeNewlines (str) {
-        return str.replace(/\r?\n/g, ' ');
-    },
-    withoutFirstElement (arr) {
-        return arr.splice(1);
-    },
-    getRelativeDocPath (contractName, contractsDir, sources) {
-        function getRelativePath (contractPath) {
-            if (contractPath){
-                if (contractPath.startsWith(contractsDir)) {
-                    return contractPath.substr(contractsDir.length + 1).replace('.sol', '.md');
-                }
-                if (contractPath.startsWith('@openzeppelin')) {
-                    const regexMatch = contractPath.match(/@openzeppelin\/contracts\/(.+)\/([^/]+)\.sol/);
-                    return `https://docs.openzeppelin.com/contracts/3.x/api/${regexMatch[1]}#${regexMatch[2]}`;
-                }
-            }
-            return null;
-        }
-
-        const sourcesKeys = Object.keys(sources);
-        const contractPath = sourcesKeys.find(x => x.includes(contractName));
-
-        if (!contractPath){
-            console.log('WARNING: file ' + contractName + '.sol not found in source files.');
-        }
-        
-        return getRelativePath(contractPath);
-    },
-};

package/utils/test-docgen.js

@@ -1,117 +0,0 @@
-#!/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;
-}