sol2uml 2.2.5 → 2.3.0

package/README.md

@@ -58,7 +58,7 @@ 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", "ropsten", "kovan", "rinkeby", "goerli", "sepolia", "polygon", "testnet.polygon", "arbitrum", "testnet.arbitrum", "avalanche", "testnet.avalanche", "bsc", "testnet.bsc", "crono", "fantom", "testnet.fantom", "moonbeam", "optimistic", "kovan-optimistic", default: "mainnet", env: ETH_NETWORK)
+  -n, --network <network>                      Ethereum network (choices: "mainnet", "ropsten", "kovan", "rinkeby", "goerli", "sepolia", "polygon", "testnet.polygon", "arbitrum", "testnet.arbitrum", "avalanche", "testnet.avalanche", "bsc", "testnet.bsc", "crono", "fantom", "testnet.fantom", "moonbeam", "optimistic", "kovan-optimistic", "gnosisscan", default: "mainnet", env: ETH_NETWORK)
   -k, --apiKey <key>                           Blockchain explorer API key. eg Etherscan, Arbiscan, BscScan, CronoScan, FTMScan, PolygonScan or SnowTrace API key (env: SCAN_API_KEY)
   -v, --verbose                                run with debugging statements (default: false)
   -h, --help                                   display help for command
@@ -106,6 +106,8 @@ Options:
   -hi, --hideInterfaces            hide interfaces (default: false)
   -ha, --hideAbstracts             hide abstract contracts (default: false)
   -hn, --hideFilename              hide relative path and file name (default: false)
+  -s, --squash                     squash inherited contracts to the base contract(s) (default: false)
+  -hsc, --hideSourceContract       hide the source contract when using squash (default: false)
   -h, --help                       display help for command
 ```
 

package/lib/converterClass2Dot.d.ts

@@ -12,5 +12,6 @@ export interface ClassOptions {
     hidePrivates?: boolean;
     hideAbstracts?: boolean;
     hideFilename?: boolean;
+    hideSourceContract?: boolean;
 }
 export declare const convertClass2Dot: (umlClass: UmlClass, options?: ClassOptions) => string;

package/lib/converterClass2Dot.js

@@ -71,7 +71,8 @@ const dotAttributeVisibilities = (umlClass, options) => {
     if (umlClass.stereotype === umlClass_1.ClassStereotype.Struct ||
         umlClass.stereotype === umlClass_1.ClassStereotype.Enum ||
         umlClass.stereotype === umlClass_1.ClassStereotype.Constant) {
-        return dotString + dotAttributes(umlClass.attributes, undefined, false);
+        return (dotString +
+            dotAttributes(umlClass.attributes, options, undefined, false));
     }
     // For each visibility group
     for (const vizGroup of ['Private', 'Internal', 'External', 'Public']) {
@@ -100,11 +101,11 @@ const dotAttributeVisibilities = (umlClass, options) => {
                 attributes.push(attribute);
             }
         }
-        dotString += dotAttributes(attributes, vizGroup);
+        dotString += dotAttributes(attributes, options, vizGroup);
     }
     return dotString;
 };
-const dotAttributes = (attributes, vizGroup, indent = true) => {
+const dotAttributes = (attributes, options, vizGroup, indent = true) => {
     if (!attributes || attributes.length === 0) {
         return '';
     }
@@ -112,7 +113,10 @@ const dotAttributes = (attributes, vizGroup, indent = true) => {
     let dotString = vizGroup ? vizGroup + ':\\l' : '';
     // for each attribute
     attributes.forEach((attribute) => {
-        dotString += `${indentString}${attribute.name}: ${attribute.type}\\l`;
+        const sourceContract = attribute.sourceContract && !options.hideSourceContract
+            ? ` \\<\\<${attribute.sourceContract}\\>\\>`
+            : '';
+        dotString += `${indentString}${attribute.name}: ${attribute.type}${sourceContract}\\l`;
     });
     return dotString;
 };
@@ -179,6 +183,8 @@ const dotOperators = (umlClass, vizGroup, operators, options) => {
         if (options.hideModifiers === false && operator.modifiers?.length > 0) {
             dotString += ` \\<\\<${operator.modifiers.join(', ')}\\>\\>`;
         }
+        if (operator.sourceContract && !options.hideSourceContract)
+            dotString += ` \\<\\<${operator.sourceContract}\\>\\>`;
         dotString += '\\l';
     }
     return dotString;

package/lib/filterClasses.d.ts

@@ -1,5 +1,7 @@
 import { WeightedDiGraph } from 'js-graph-algorithms';
 import { UmlClass } from './umlClass';
+import { ClassOptions } from './converterClass2Dot';
+export declare const filterHiddenClasses: (umlClasses: UmlClass[], options: ClassOptions) => UmlClass[];
 export declare const classesConnectedToBaseContracts: (umlClasses: UmlClass[], baseContractNames: string[], depth?: number) => UmlClass[];
 export declare const classesConnectedToBaseContract: (umlClasses: UmlClass[], baseContractName: string, weightedDirectedGraph: WeightedDiGraph, depth?: number) => {
     [contractName: string]: UmlClass;

package/lib/filterClasses.js

@@ -1,8 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.topologicalSortClasses = exports.classesConnectedToBaseContract = exports.classesConnectedToBaseContracts = void 0;
+exports.topologicalSortClasses = exports.classesConnectedToBaseContract = exports.classesConnectedToBaseContracts = exports.filterHiddenClasses = void 0;
 const js_graph_algorithms_1 = require("js-graph-algorithms");
+const umlClass_1 = require("./umlClass");
 const associations_1 = require("./associations");
+const filterHiddenClasses = (umlClasses, options) => {
+    return umlClasses.filter((u) => (u.stereotype === umlClass_1.ClassStereotype.Enum && !options.hideEnums) ||
+        (u.stereotype === umlClass_1.ClassStereotype.Struct && !options.hideStructs) ||
+        (u.stereotype === umlClass_1.ClassStereotype.Abstract &&
+            !options.hideAbstracts) ||
+        (u.stereotype === umlClass_1.ClassStereotype.Interface &&
+            !options.hideInterfaces) ||
+        (u.stereotype === umlClass_1.ClassStereotype.Constant &&
+            !options.hideConstants) ||
+        (u.stereotype === umlClass_1.ClassStereotype.Library &&
+            !options.hideLibraries) ||
+        u.stereotype === umlClass_1.ClassStereotype.None ||
+        u.stereotype === umlClass_1.ClassStereotype.Contract);
+};
+exports.filterHiddenClasses = filterHiddenClasses;
 const classesConnectedToBaseContracts = (umlClasses, baseContractNames, depth) => {
     let filteredUmlClasses = {};
     const weightedDirectedGraph = loadWeightedDirectedGraph(umlClasses);
@@ -35,7 +51,9 @@ const classesConnectedToBaseContract = (umlClasses, baseContractName, weightedDi
 };
 exports.classesConnectedToBaseContract = classesConnectedToBaseContract;
 function loadWeightedDirectedGraph(umlClasses) {
-    const weightedDirectedGraph = new js_graph_algorithms_1.WeightedDiGraph(umlClasses.length); // the number vertices in the graph
+    const weightedDirectedGraph = new js_graph_algorithms_1.WeightedDiGraph(
+    // the number vertices in the graph
+    umlClass_1.UmlClass.idCounter + 1);
     for (const sourceUmlClass of umlClasses) {
         for (const association of Object.values(sourceUmlClass.associations)) {
             // Find the first UML Class that matches the target class name
@@ -43,6 +61,8 @@ function loadWeightedDirectedGraph(umlClasses) {
             if (!targetUmlClass) {
                 continue;
             }
+            const isTarget = umlClasses.find((u) => u.id === targetUmlClass.id);
+            console.log(`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

@@ -1,6 +1,6 @@
 import { ASTNode } from '@solidity-parser/parser/dist/src/ast-types';
 import { UmlClass } from './umlClass';
-export declare const networks: readonly ["mainnet", "ropsten", "kovan", "rinkeby", "goerli", "sepolia", "polygon", "testnet.polygon", "arbitrum", "testnet.arbitrum", "avalanche", "testnet.avalanche", "bsc", "testnet.bsc", "crono", "fantom", "testnet.fantom", "moonbeam", "optimistic", "kovan-optimistic"];
+export declare const networks: readonly ["mainnet", "ropsten", "kovan", "rinkeby", "goerli", "sepolia", "polygon", "testnet.polygon", "arbitrum", "testnet.arbitrum", "avalanche", "testnet.avalanche", "bsc", "testnet.bsc", "crono", "fantom", "testnet.fantom", "moonbeam", "optimistic", "kovan-optimistic", "gnosisscan"];
 declare type Network = typeof networks[number];
 export declare class EtherscanParser {
     protected apikey: string;

package/lib/parserEtherscan.js

@@ -32,6 +32,7 @@ exports.networks = [
     'moonbeam',
     'optimistic',
     'kovan-optimistic',
+    'gnosisscan',
 ];
 class EtherscanParser {
     constructor(apikey = 'ZAD4UI2RCXCQTP38EXS3UY2MPHFU5H9KB1', network = 'mainnet') {
@@ -69,14 +70,15 @@ class EtherscanParser {
         }
         else if (network === 'bsc') {
             this.url = 'https://api.bscscan.com/api';
+            this.apikey = 'APYH49FXVY9UA3KTDI6F4WP3KPIC86NITN';
         }
         else if (network === 'testnet.bsc') {
             this.url = 'https://api-testnet.bscscan.com/api';
+            this.apikey = 'APYH49FXVY9UA3KTDI6F4WP3KPIC86NITN';
         }
         else if (network === 'crono') {
             this.url = 'https://api.cronoscan.com/api';
             this.apikey = '76A3RG5WHTPMMR66E9SFI2EIDT6MP976W2';
-            this.apikey = 'APYH49FXVY9UA3KTDI6F4WP3KPIC86NITN';
         }
         else if (network === 'fantom') {
             this.url = 'https://api.ftmscan.com/api';
@@ -94,6 +96,10 @@ class EtherscanParser {
             this.url = 'https://api-moonbeam.moonscan.io/api';
             this.apikey = '5EUFXW6TDC16VERF3D9SCWRRU6AEMTBHNJ';
         }
+        else if (network === 'gnosisscan') {
+            this.url = 'https://api.gnosisscan.io/api';
+            this.apikey = '2RWGXIWK538EJ8XSP9DE2JUINSCG7UCSJB';
+        }
         else {
             this.url = `https://api-${network}.etherscan.io/api`;
         }

package/lib/sol2uml.js

@@ -11,6 +11,7 @@ const converterStorage2Dot_1 = require("./converterStorage2Dot");
 const regEx_1 = require("./utils/regEx");
 const writerFiles_1 = require("./writerFiles");
 const path_1 = require("path");
+const squashClasses_1 = require("./squashClasses");
 const program = new commander_1.Command();
 const version = (0, path_1.basename)(__dirname) === 'lib'
     ? require('../package.json').version // used when run from compile js in /lib
@@ -37,7 +38,7 @@ The Solidity code can be pulled from verified source code on Blockchain explorer
     .choices(parserEtherscan_1.networks)
     .default('mainnet')
     .env('ETH_NETWORK'))
-    .addOption(new commander_1.Option('-k, --apiKey <key>', 'Blockchain explorer API key. eg Etherscan, Arbiscan, BscScan, CronoScan, FTMScan, PolygonScan or SnowTrace API key').env('SCAN_API_KEY'))
+    .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('-v, --verbose', 'run with debugging statements', false);
 program
     .command('class', { isDefault: true })
@@ -69,6 +70,8 @@ If an Ethereum address with a 0x prefix is passed, the verified source code from
     .option('-hi, --hideInterfaces', 'hide interfaces', false)
     .option('-ha, --hideAbstracts', 'hide abstract contracts', false)
     .option('-hn, --hideFilename', 'hide relative path and file name', false)
+    .option('-s, --squash', 'squash inherited contracts to the base contract(s)', false)
+    .option('-hsc, --hideSourceContract', 'hide the source contract when using squash', false)
     .action(async (fileFolderAddress, options, command) => {
     try {
         const combinedOptions = {
@@ -76,12 +79,23 @@ If an Ethereum address with a 0x prefix is passed, the verified source code from
             ...options,
         };
         let { umlClasses, contractName } = await (0, parserGeneral_1.parserUmlClasses)(fileFolderAddress, combinedOptions);
-        let filteredUmlClasses = umlClasses;
-        if (options.baseContractNames) {
-            const baseContractNames = options.baseContractNames.split(',');
-            filteredUmlClasses = (0, filterClasses_1.classesConnectedToBaseContracts)(umlClasses, baseContractNames, options.depth);
+        if (options.squash &&
+            // Must specify base contract(s) or parse from Etherscan to get contractName
+            !(options.baseContractNames || contractName)) {
+            throw Error('Must specify base contract(s) when using the squash option against local Solidity files.');
+        }
+        // Filter out any class stereotypes that are to be hidden
+        let filteredUmlClasses = (0, filterClasses_1.filterHiddenClasses)(umlClasses, options);
+        const baseContractNames = options.baseContractNames?.split(',');
+        if (baseContractNames) {
+            // Find all the classes connected to the base classes
+            filteredUmlClasses = (0, filterClasses_1.classesConnectedToBaseContracts)(filteredUmlClasses, baseContractNames, options.depth);
             contractName = baseContractNames[0];
         }
+        // squash contracts
+        if (options.squash) {
+            filteredUmlClasses = (0, squashClasses_1.squashUmlClasses)(filteredUmlClasses, baseContractNames || [contractName]);
+        }
         const dotString = (0, converterClasses2Dot_1.convertUmlClasses2Dot)(filteredUmlClasses, combinedOptions.clusterFolders, combinedOptions);
         await (0, writerFiles_1.writeOutputFiles)(dotString, fileFolderAddress, contractName || 'classDiagram', combinedOptions.outputFormat, combinedOptions.outputFileName);
         debug(`Finished generating UML`);

package/lib/squashClasses.d.ts

@@ -0,0 +1,2 @@
+import { UmlClass } from './umlClass';
+export declare const squashUmlClasses: (umlClasses: UmlClass[], squashContractNames: string[]) => UmlClass[];

package/lib/squashClasses.js

@@ -0,0 +1,143 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.squashUmlClasses = void 0;
+const umlClass_1 = require("./umlClass");
+const crypto = __importStar(require("crypto"));
+const debug = require('debug')('sol2uml');
+const squashUmlClasses = (umlClasses, squashContractNames) => {
+    let removedClassIds = [];
+    for (const squashContractName of squashContractNames) {
+        // Find the base UML Class to squash
+        let baseIndex = umlClasses.findIndex(({ name }) => {
+            return name === squashContractName;
+        });
+        if (baseIndex === undefined) {
+            throw Error(`Failed to find contract with name "${squashContractName}" to squash`);
+        }
+        const baseClass = umlClasses[baseIndex];
+        let squashedClass = new umlClass_1.UmlClass({
+            name: baseClass.name,
+            absolutePath: baseClass.absolutePath,
+            relativePath: baseClass.relativePath,
+        });
+        squashedClass.id = baseClass.id;
+        const result = recursiveSquash(squashedClass, [], baseClass, umlClasses, 1);
+        removedClassIds = removedClassIds.concat(result.removedClassIds);
+        // Remove overridden functions from squashed class
+        squashedClass.operators = reduceOperators(squashedClass.operators);
+        umlClasses[baseIndex] = squashedClass;
+    }
+    // filter the list of classes that will be rendered
+    return umlClasses.filter((u) => 
+    // remove any squashed inherited contracts
+    !removedClassIds.includes(u.id) ||
+        // Include all base contracts
+        squashContractNames.includes(u.name));
+};
+exports.squashUmlClasses = squashUmlClasses;
+const recursiveSquash = (squashedClass, inheritedContractNames, baseClass, umlClasses, startPosition) => {
+    let currentPosition = startPosition;
+    const removedClassIds = [];
+    // For each association from the baseClass
+    for (const [targetClassName, association] of Object.entries(baseClass.associations)) {
+        // if inheritance and (Abstract or Contract)
+        // Libraries and Interfaces will be copied
+        if (association.realization) {
+            // Find the target UML Class
+            const inheritedContract = umlClasses.find(({ name }) => {
+                return name === targetClassName;
+            });
+            if (!inheritedContract) {
+                debug(`Warning: failed to find inherited contract with name ${targetClassName}`);
+                continue;
+            }
+            // Is the associated class a contract or abstract contract?
+            if (inheritedContract?.stereotype === umlClass_1.ClassStereotype.Library) {
+                squashedClass.addAssociation(association);
+            }
+            else {
+                // has the contract already been added to the inheritance tree?
+                const alreadyInherited = inheritedContractNames.includes(inheritedContract.name);
+                // Do not add inherited contract if it has already been added to the inheritance tree
+                if (!alreadyInherited) {
+                    inheritedContractNames.push(inheritedContract.name);
+                    const squashResult = recursiveSquash(squashedClass, inheritedContractNames, inheritedContract, umlClasses, currentPosition++);
+                    // Add to list of removed class ids
+                    removedClassIds.push(...squashResult.removedClassIds, inheritedContract.id);
+                }
+            }
+        }
+        else {
+            // Copy association but will not duplicate it
+            squashedClass.addAssociation(association);
+        }
+    }
+    // Copy class properties from the baseClass to the squashedClass
+    baseClass.constants.forEach((c) => squashedClass.constants.push({ ...c, sourceContract: baseClass.name }));
+    baseClass.attributes.forEach((a) => squashedClass.attributes.push({ ...a, sourceContract: baseClass.name }));
+    baseClass.enums.forEach((e) => squashedClass.enums.push(e));
+    baseClass.structs.forEach((s) => squashedClass.structs.push(s));
+    baseClass.imports.forEach((i) => squashedClass.imports.push(i));
+    // copy the functions
+    baseClass.operators.forEach((f) => squashedClass.operators.push({
+        ...f,
+        hash: hash(f),
+        inheritancePosition: currentPosition,
+        sourceContract: baseClass.name,
+    }));
+    return {
+        currentPosition,
+        removedClassIds,
+    };
+};
+const hash = (operator) => {
+    const hash = crypto.createHash('sha256');
+    let data = operator.name ?? 'fallback';
+    operator.parameters?.forEach((p) => {
+        data += ',' + p.type;
+    });
+    operator.returnParameters?.forEach((p) => {
+        data += ',' + p.type;
+    });
+    return hash.update(data).digest('hex');
+};
+const reduceOperators = (operators) => {
+    const hashes = new Set(operators.map((o) => o.hash));
+    const operatorsWithNoHash = operators.filter((o) => !o.hash);
+    const newOperators = [];
+    for (const hash of hashes) {
+        const operator = operators
+            .filter((o) => o.hash === hash)
+            // sort operators by inheritance position. smaller to highest
+            .sort((o) => o.inheritancePosition)
+            // get last operator in the array
+            .slice(-1)[0];
+        newOperators.push(operator);
+    }
+    newOperators.push(...operatorsWithNoHash);
+    return newOperators;
+};
+//# sourceMappingURL=squashClasses.js.map

package/lib/umlClass.d.ts

@@ -44,6 +44,7 @@ export interface Attribute {
     type?: string;
     attributeType?: AttributeType;
     compiled?: boolean;
+    sourceContract?: string;
 }
 export interface Parameter {
     name?: string;
@@ -55,6 +56,9 @@ export interface Operator extends Attribute {
     returnParameters?: Parameter[];
     isPayable?: boolean;
     modifiers?: string[];
+    hash?: string;
+    inheritancePosition?: number;
+    sourceContract?: string;
 }
 export declare enum ReferenceType {
     Memory = 0,
@@ -63,12 +67,12 @@ export declare enum ReferenceType {
 export interface Association {
     referenceType: ReferenceType;
     targetUmlClassName: string;
-    targetUmlClassStereotype?: ClassStereotype;
     realization?: boolean;
 }
 export interface Constants {
     name: string;
     value: number;
+    sourceContract?: string;
 }
 export interface ClassProperties {
     name: string;

package/lib/umlClass.js

@@ -45,6 +45,7 @@ var ReferenceType;
 })(ReferenceType = exports.ReferenceType || (exports.ReferenceType = {}));
 class UmlClass {
     constructor(properties) {
+        this.imports = [];
         this.constants = [];
         this.attributes = [];
         this.operators = [];
@@ -83,9 +84,7 @@ class UmlClass {
      * Does not include any grand parent associations. That has to be done recursively.
      */
     getParentContracts() {
-        return Object.values(this.associations).filter((association) => association.realization &&
-            association.targetUmlClassStereotype !==
-                ClassStereotype.Interface);
+        return Object.values(this.associations).filter((association) => association.realization);
     }
 }
 exports.UmlClass = UmlClass;

package/package.json

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