sol2uml 2.5.4 → 2.5.6

package/README.md

@@ -55,7 +55,9 @@ Options:
   -f, --outputFormat <value>                   output file format. (choices: "svg", "png", "dot", "all", default: "svg")
   -o, --outputFileName <value>                 output file name
   -i, --ignoreFilesOrFolders <filesOrFolders>  comma separated list of files or folders to ignore
-  -n, --network <network>                      Ethereum network (choices: "mainnet", "goerli", "sepolia", "polygon", "arbitrum", "avalanche", "bsc", "crono", "fantom", "moonbeam", "optimism", "gnosis", default: "mainnet", env: ETH_NETWORK)
+  -n, --network <network>                      Ethereum network which maps to a blockchain explorer (choices: "mainnet", "goerli", "sepolia", "polygon", "arbitrum", "avalanche", "bsc", "crono", "fantom", "moonbeam",
+                                               "optimism", "gnosis", "celo", default: "mainnet", env: ETH_NETWORK)
+  -e, --explorerUrl <url>                      Override network with custom blockchain explorer API URL. eg Polygon Mumbai testnet https://api-testnet.polygonscan.com/api (env: EXPLORER_URL)
   -k, --apiKey <key>                           Blockchain explorer API key. eg Etherscan, Arbiscan, Optimism, BscScan, CronoScan, FTMScan, PolygonScan or SnowTrace API key (env: SCAN_API_KEY)
   -bc, --backColor <color>                     Canvas background color. "none" will use a transparent canvas. (default: "white")
   -sc, --shapeColor <color>                    Basic drawing color for graphics, not text (default: "black")
@@ -192,6 +194,8 @@ Arguments:
 
 Options:
   -l, --lineBuffer <value>  Minimum number of lines before and after changes (default: "4")
+  --aFile <value>           Contract A source code filename without the .sol extension. (default: compares all source files)
+  --bFile <value>           Contract B source code filename without the .sol extension. (default: aFile if specified)
   -s, --saveFiles           Save the flattened contract code to the filesystem. The file names will be the contract address with a .sol extension. (default: false)
   -h, --help                display help for command
 ```
@@ -329,6 +333,25 @@ To access your local changes on your machine globally.
 
 `npm link`
 
+# Publish
+
+Commands to publish a new package version.
+
+```bash
+npm run prettier
+npm run clean
+npm run package-lock
+npm run build
+npm run permit
+# make tx2uml globally available for local testing
+npm link
+# check all the files are included in the npm package
+npm pack --dry-run
+npm publish
+```
+
+Then create a new release on GitHub https://github.com/naddison36/sol2uml/releases
+
 # About
 
 This is a rewrite of the Richard Ramos's [solidity-diagram-gen](https://github.com/richard-ramos/solidity-diagram-gen) tool which no longer works as it uses [solidity-parser](https://www.npmjs.com/package/solidity-parser/v/0.4.0) which cannot handle newer Solidity syntax like `constructor`.

package/lib/converterAST2Classes.js

@@ -102,7 +102,7 @@ function convertAST2UmlClasses(node, relativePath, remappings, filesystem = fals
                                 })
                                 : [],
                         };
-                        debug(`Added filesystem import ${newImport.absolutePath} with class names ${newImport.classNames}`);
+                        debug(`Added filesystem import ${newImport.absolutePath} with class names ${newImport.classNames.map((i) => i.className)}`);
                         imports.push(newImport);
                     }
                     catch (err) {

package/lib/filterClasses.js

@@ -87,7 +87,7 @@ function loadWeightedDirectedGraph(umlClasses) {
                 continue;
             }
             const isTarget = umlClasses.find((u) => u.id === targetUmlClass.id);
-            debug(`isTarget ${isTarget} Adding edge from ${sourceUmlClass.name} with id ${sourceUmlClass.id} to ${targetUmlClass.name} with id ${targetUmlClass.id} and type ${targetUmlClass.stereotype}`);
+            debug(`isTarget ${!!isTarget}: Adding edge from ${sourceUmlClass.name} with id ${sourceUmlClass.id} to ${targetUmlClass.name} with id ${targetUmlClass.id} and type ${targetUmlClass.stereotype}`);
             weightedDirectedGraph.addEdge(new js_graph_algorithms_1.Edge(sourceUmlClass.id, targetUmlClass.id, 1));
         }
     }

package/lib/parserEtherscan.d.ts

@@ -4,13 +4,13 @@ export interface Remapping {
     from: RegExp;
     to: string;
 }
-export declare const networks: readonly ["mainnet", "goerli", "sepolia", "polygon", "arbitrum", "avalanche", "bsc", "crono", "fantom", "moonbeam", "optimism", "gnosis"];
+export declare const networks: readonly ["mainnet", "goerli", "sepolia", "polygon", "arbitrum", "avalanche", "bsc", "crono", "fantom", "moonbeam", "optimism", "gnosis", "celo"];
 export type Network = (typeof networks)[number];
 export declare class EtherscanParser {
     protected apikey: string;
     network: Network;
     readonly url: string;
-    constructor(apikey?: string, network?: Network);
+    constructor(apikey?: string, network?: Network, url?: string);
     /**
      * Parses the verified source code files from Etherscan
      * @param contractAddress Ethereum contract address with a 0x prefix
@@ -26,7 +26,7 @@ export declare class EtherscanParser {
      * @param contractAddress Ethereum contract address with a 0x prefix
      * @return Promise string of Solidity code
      */
-    getSolidityCode(contractAddress: string): Promise<{
+    getSolidityCode(contractAddress: string, filename?: string): Promise<{
         solidityCode: string;
         contractName: string;
     }>;
@@ -39,8 +39,9 @@ export declare class EtherscanParser {
     /**
      * Calls Etherscan to get the verified source code for the specified contract address
      * @param contractAddress Ethereum contract address with a 0x prefix
+     * @oaram filename optional, case-sensitive name of the source file without the .sol
      */
-    getSourceCode(contractAddress: string): Promise<{
+    getSourceCode(contractAddress: string, filename?: string): Promise<{
         files: readonly {
             code: string;
             filename: string;

package/lib/parserEtherscan.js

@@ -9,6 +9,7 @@ const parser_1 = require("@solidity-parser/parser");
 const converterAST2Classes_1 = require("./converterAST2Classes");
 const filterClasses_1 = require("./filterClasses");
 const regEx_1 = require("./utils/regEx");
+const path_1 = __importDefault(require("path"));
 require('axios-debug-log');
 const debug = require('debug')('sol2uml');
 exports.networks = [
@@ -24,11 +25,16 @@ exports.networks = [
     'moonbeam',
     'optimism',
     'gnosis',
+    'celo',
 ];
 class EtherscanParser {
-    constructor(apikey = 'ZAD4UI2RCXCQTP38EXS3UY2MPHFU5H9KB1', network = 'mainnet') {
+    constructor(apikey = 'ZAD4UI2RCXCQTP38EXS3UY2MPHFU5H9KB1', network = 'mainnet', url) {
         this.apikey = apikey;
         this.network = network;
+        if (url) {
+            this.url = url;
+            return;
+        }
         if (!exports.networks.includes(network)) {
             throw new Error(`Invalid network "${network}". Must be one of ${exports.networks}`);
         }
@@ -71,6 +77,10 @@ class EtherscanParser {
             this.url = 'https://api.gnosisscan.io/api';
             this.apikey = '2RWGXIWK538EJ8XSP9DE2JUINSCG7UCSJB';
         }
+        else if (network === 'celo') {
+            this.url = 'https://api.celoscan.io/api';
+            this.apikey = 'JBV78T5KP15W7WKKKD6KC4J8RX2F4PK8AF';
+        }
         else {
             this.url = `https://api-${network}.etherscan.io/api`;
         }
@@ -100,8 +110,8 @@ class EtherscanParser {
      * @param contractAddress Ethereum contract address with a 0x prefix
      * @return Promise string of Solidity code
      */
-    async getSolidityCode(contractAddress) {
-        const { files, contractName, compilerVersion, remappings } = await this.getSourceCode(contractAddress);
+    async getSolidityCode(contractAddress, filename) {
+        const { files, contractName, compilerVersion, remappings } = await this.getSourceCode(contractAddress, filename);
         // Parse the UmlClasses from the Solidity code in each file
         let umlClasses = [];
         for (const file of files) {
@@ -164,8 +174,9 @@ class EtherscanParser {
     /**
      * Calls Etherscan to get the verified source code for the specified contract address
      * @param contractAddress Ethereum contract address with a 0x prefix
+     * @oaram filename optional, case-sensitive name of the source file without the .sol
      */
-    async getSourceCode(contractAddress) {
+    async getSourceCode(contractAddress, filename) {
         const description = `get verified source code for address ${contractAddress} from Etherscan API.`;
         try {
             debug(`About to get Solidity source code for ${contractAddress} from ${this.url}`);
@@ -226,8 +237,16 @@ class EtherscanParser {
                     filename: contractAddress,
                 };
             });
+            let files = results.flat(1);
+            const filenameWithExt = filename + '.sol';
+            if (filename) {
+                files = files.filter((r) => path_1.default.parse(r.filename).base == filenameWithExt);
+                if (!files?.length) {
+                    throw new Error(`Failed to find source file "${filename}" for contract ${contractAddress}`);
+                }
+            }
             return {
-                files: results.flat(1),
+                files,
                 contractName: response.data.result[0].ContractName,
                 compilerVersion: response.data.result[0].CompilerVersion,
                 remappings,

package/lib/parserGeneral.d.ts

@@ -3,6 +3,7 @@ import { UmlClass } from './umlClass';
 export interface ParserOptions {
     apiKey?: string;
     network?: Network;
+    explorerUrl?: string;
     subfolders?: string;
     ignoreFilesOrFolders?: string;
 }

package/lib/parserGeneral.js

@@ -17,7 +17,7 @@ const parserUmlClasses = async (fileFolderAddress, options) => {
     if ((0, regEx_1.isAddress)(fileFolderAddress)) {
         debug(`argument ${fileFolderAddress} is an Ethereum address so checking Etherscan for the verified source code`);
         const etherscanApiKey = options.apiKey || 'ZAD4UI2RCXCQTP38EXS3UY2MPHFU5H9KB1';
-        const etherscanParser = new parserEtherscan_1.EtherscanParser(etherscanApiKey, options.network);
+        const etherscanParser = new parserEtherscan_1.EtherscanParser(etherscanApiKey, options.network, options.explorerUrl);
         result = await etherscanParser.getUmlClasses(fileFolderAddress);
     }
     else {

package/lib/sol2uml.js

@@ -29,10 +29,11 @@ Can also flatten or compare verified source files on Etherscan-like explorers.`)
     .default('svg'))
     .option('-o, --outputFileName <value>', 'output file name')
     .option('-i, --ignoreFilesOrFolders <filesOrFolders>', 'comma separated list of files or folders to ignore')
-    .addOption(new commander_1.Option('-n, --network <network>', 'Ethereum network')
+    .addOption(new commander_1.Option('-n, --network <network>', 'Ethereum network which maps to a blockchain explorer')
     .choices(parserEtherscan_1.networks)
     .default('mainnet')
     .env('ETH_NETWORK'))
+    .addOption(new commander_1.Option('-e, --explorerUrl <url>', 'Override network with custom blockchain explorer API URL. eg Polygon Mumbai testnet https://api-testnet.polygonscan.com/api').env('EXPLORER_URL'))
     .addOption(new commander_1.Option('-k, --apiKey <key>', 'Blockchain explorer API key. eg Etherscan, Arbiscan, Optimism, BscScan, CronoScan, FTMScan, PolygonScan or SnowTrace API key').env('SCAN_API_KEY'))
     .option('-bc, --backColor <color>', 'Canvas background color. "none" will use a transparent canvas.', 'white')
     .option('-sc, --shapeColor <color>', 'Basic drawing color for graphics, not text', 'black')
@@ -202,7 +203,7 @@ In order for the merged code to compile, the following is done:
             ...command.parent._optionValues,
             ...options,
         };
-        const etherscanParser = new parserEtherscan_1.EtherscanParser(combinedOptions.apiKey, combinedOptions.network);
+        const etherscanParser = new parserEtherscan_1.EtherscanParser(combinedOptions.apiKey, combinedOptions.network, combinedOptions.explorerUrl);
         const { solidityCode, contractName } = await etherscanParser.getSolidityCode(contractAddress);
         // Write Solidity to the contract address
         const outputFilename = combinedOptions.outputFileName || contractName;
@@ -225,6 +226,8 @@ The line numbers are from contract B. There are no line numbers for the red sect
     .argument('<addressA>', 'Contract address in hexadecimal format with a 0x prefix of the first contract.')
     .argument('<addressB>', 'Contract address in hexadecimal format with a 0x prefix of the second contract.')
     .addOption(new commander_1.Option('-l, --lineBuffer <value>', 'Minimum number of lines before and after changes').default('4'))
+    .addOption(new commander_1.Option('-af --aFile <value>', 'Contract A source code filename without the .sol extension. (default: compares all source files)'))
+    .addOption(new commander_1.Option('-bf --bFile <value>', 'Contract B source code filename without the .sol extension. (default: aFile if specified)'))
     .option('-s, --saveFiles', 'Save the flattened contract code to the filesystem. The file names will be the contract address with a .sol extension.', false)
     .action(async (addressA, addressB, options, command) => {
     try {
@@ -237,10 +240,10 @@ The line numbers are from contract B. There are no line numbers for the red sect
         const lineBuffer = parseInt(options.lineBuffer);
         if (isNaN(lineBuffer))
             throw Error(`Invalid line buffer "${options.lineBuffer}". Must be a number`);
-        const etherscanParser = new parserEtherscan_1.EtherscanParser(combinedOptions.apiKey, combinedOptions.network);
+        const etherscanParser = new parserEtherscan_1.EtherscanParser(combinedOptions.apiKey, combinedOptions.network, combinedOptions.explorerUrl);
         // Get verified Solidity code from Etherscan and flatten
-        const { solidityCode: codeA, contractName: contractNameA } = await etherscanParser.getSolidityCode(addressA);
-        const { solidityCode: codeB, contractName: contractNameB } = await etherscanParser.getSolidityCode(addressB);
+        const { solidityCode: codeA, contractName: contractNameA } = await etherscanParser.getSolidityCode(addressA, combinedOptions.aFile);
+        const { solidityCode: codeB, contractName: contractNameB } = await etherscanParser.getSolidityCode(addressB, combinedOptions.bFile || combinedOptions.aFile);
         console.log(`Difference between`);
         console.log(`A. ${addressA} ${contractNameA} on ${combinedOptions.network}`);
         console.log(`B. ${addressB} ${contractNameB} on ${combinedOptions.network}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sol2uml",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "Solidity contract visualisation tool.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",