sol2uml 2.1.1 → 2.1.2

package/README.md

@@ -44,12 +44,11 @@ npm ls sol2uml -g
 ## Command Line Interface (CLI)
 
 ```
-$ sol2uml --help
 Usage: sol2uml [subcommand] <options>
 The three subcommands:
 * class:    Generates a UML class diagram from Solidity source code. default
 * storage:  Generates a diagram of a contract's storage slots.
-* flatten:  Pulls verified source files from a Blockchain explorer into one, flat, local Solidity file.
+* flatten:  Merges verified source files from a Blockchain explorer into one local file.
 
 The Solidity code can be pulled from verified source code on Blockchain explorers like Etherscan or from local Solidity files.
 
@@ -73,7 +72,6 @@ Commands:
 ### Class usage
 
 ```
-$sol2uml class --help
 Usage: sol2uml class <fileFolderAddress> [options]
 
 Generates UML diagrams from Solidity source code.
@@ -110,20 +108,19 @@ Options:
 ### Storage usage
 
 ```
-Usage: sol2uml storage [options] <fileFolderAddress>
-
-Visually display a contract's storage slots.
+Usage: sol2uml storage <fileFolderAddress> [options]
 
 WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A known example is fixed-sized arrays declared with an expression will fail to be sized.
 
+Visually display a contract's storage slots.
+
 Arguments:
   fileFolderAddress        file name, base folder or contract address
 
 Options:
   -c, --contract <name>    Contract name in local Solidity files. Not needed when using an address as the first argument as the contract name can be derived from Etherscan.
   -d, --data               Gets the values in the storage slots from an Ethereum node. (default: false)
-  -s, --storage <address>  The address of the contract with the storage values. This will be different from the contract with the code if a proxy contract is used. This is not needed if `fileFolderAddress` is an address and
-                           the contract is not proxied.
+  -s, --storage <address>  The address of the contract with the storage values. This will be different from the contract with the code if a proxy contract is used. This is not needed if `fileFolderAddress` is an address and the contract is not proxied.
   -u, --url <url>          URL of the Ethereum node to get storage values if the `data` option is used. (default: "http://localhost:8545", env: NODE_URL)
   -bn, --block <number>    Block number to get the contract storage values from. (default: "latest")
   -h, --help               display help for command
@@ -132,17 +129,20 @@ Options:
 ### Flatten usage
 
 ```
-$sol2uml flatten --help
-Usage: sol2uml flatten [options] <contractAddress>
+Usage: sol2uml flatten <contractAddress> [options]
+
+In order for the merged code to compile, the following is done:
+1. File imports are commented out.
+2. "SPDX-License-Identifier" is renamed to "SPDX--License-Identifier".
+3. Contract dependencies are analysed so the files are merged in an order that will compile.
 
-get all verified source code for a contract from the Blockchain explorer into one local file
+Merges verified source files for a contract from a Blockchain explorer into one local file.
 
 Arguments:
-  contractAddress  Contract address
+  contractAddress  Contract address in hexadecimal format with a 0x prefix.
 
 Options:
   -h, --help       display help for command
-
 ```
 
 ## UML Class diagram examples

package/lib/converterClasses2Storage.js

@@ -162,11 +162,10 @@ const parseReferenceStorage = (attribute, umlClass, otherClasses, storages) => {
             attributeType: baseAttributeType,
         };
         const { size: arrayItemSize } = (0, exports.calcStorageByteSize)(baseAttribute, umlClass, otherClasses);
-        const slotSize = arrayItemSize > 16 ? 32 : arrayItemSize;
         const firstVariable = {
             id: variableId++,
             fromSlot: 0,
-            toSlot: Math.floor((slotSize - 1) / 32),
+            toSlot: Math.floor((arrayItemSize - 1) / 32),
             byteSize: arrayItemSize,
             byteOffset: 0,
             type: baseType,
@@ -178,10 +177,10 @@ const parseReferenceStorage = (attribute, umlClass, otherClasses, storages) => {
             for (let i = 1; i < arrayLength; i++) {
                 variables.push({
                     id: variableId++,
-                    fromSlot: Math.floor((i * slotSize) / 32),
-                    toSlot: Math.floor(((i + 1) * slotSize - 1) / 32),
+                    fromSlot: Math.floor((i * arrayItemSize) / 32),
+                    toSlot: Math.floor(((i + 1) * arrayItemSize - 1) / 32),
                     byteSize: arrayItemSize,
-                    byteOffset: (i * slotSize) % 32,
+                    byteOffset: (i * arrayItemSize) % 32,
                     type: baseType,
                     dynamic,
                     noValue: false,

package/lib/filterClasses.d.ts

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

package/lib/filterClasses.js

@@ -1,21 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.classesConnectedToBaseContract = exports.classesConnectedToBaseContracts = void 0;
+exports.topologicalSortClasses = exports.classesConnectedToBaseContract = exports.classesConnectedToBaseContracts = void 0;
 const js_graph_algorithms_1 = require("js-graph-algorithms");
 const associations_1 = require("./associations");
 const classesConnectedToBaseContracts = (umlClasses, baseContractNames, depth) => {
     let filteredUmlClasses = {};
-    const graph = loadGraph(umlClasses);
+    const weightedDirectedGraph = loadWeightedDirectedGraph(umlClasses);
     for (const baseContractName of baseContractNames) {
         filteredUmlClasses = {
             ...filteredUmlClasses,
-            ...(0, exports.classesConnectedToBaseContract)(umlClasses, baseContractName, graph, depth),
+            ...(0, exports.classesConnectedToBaseContract)(umlClasses, baseContractName, weightedDirectedGraph, depth),
         };
     }
     return Object.values(filteredUmlClasses);
 };
 exports.classesConnectedToBaseContracts = classesConnectedToBaseContracts;
-const classesConnectedToBaseContract = (umlClasses, baseContractName, graph, depth = 1000) => {
+const classesConnectedToBaseContract = (umlClasses, baseContractName, weightedDirectedGraph, depth = 1000) => {
     // Find the base UML Class from the base contract name
     const baseUmlClass = umlClasses.find(({ name }) => {
         return name === baseContractName;
@@ -23,7 +23,7 @@ const classesConnectedToBaseContract = (umlClasses, baseContractName, graph, dep
     if (!baseUmlClass) {
         throw Error(`Failed to find base contract with name "${baseContractName}"`);
     }
-    const dfs = new js_graph_algorithms_1.Dijkstra(graph, baseUmlClass.id);
+    const dfs = new js_graph_algorithms_1.Dijkstra(weightedDirectedGraph, baseUmlClass.id);
     // Get all the UML Classes that are connected to the base contract
     const filteredUmlClasses = {};
     for (const umlClass of umlClasses) {
@@ -34,8 +34,8 @@ const classesConnectedToBaseContract = (umlClasses, baseContractName, graph, dep
     return filteredUmlClasses;
 };
 exports.classesConnectedToBaseContract = classesConnectedToBaseContract;
-function loadGraph(umlClasses) {
-    const graph = new js_graph_algorithms_1.WeightedDiGraph(umlClasses.length); // 6 is the number vertices in the graph
+function loadWeightedDirectedGraph(umlClasses) {
+    const weightedDirectedGraph = new js_graph_algorithms_1.WeightedDiGraph(umlClasses.length); // the number vertices in the graph
     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,9 +43,34 @@ function loadGraph(umlClasses) {
             if (!targetUmlClass) {
                 continue;
             }
-            graph.addEdge(new js_graph_algorithms_1.Edge(sourceUmlClass.id, targetUmlClass.id, 1));
+            weightedDirectedGraph.addEdge(new js_graph_algorithms_1.Edge(sourceUmlClass.id, targetUmlClass.id, 1));
         }
     }
-    return graph;
+    return weightedDirectedGraph;
 }
+const topologicalSortClasses = (umlClasses) => {
+    const directedAcyclicGraph = loadDirectedAcyclicGraph(umlClasses);
+    const topologicalSort = new js_graph_algorithms_1.TopologicalSort(directedAcyclicGraph);
+    // Topological sort the class ids
+    const sortedUmlClassIds = topologicalSort.order().reverse();
+    const sortedUmlClasses = sortedUmlClassIds.map((umlClassId) => 
+    // Lookup the UmlClass for each class id
+    umlClasses.find((umlClass) => umlClass.id === umlClassId));
+    return sortedUmlClasses;
+};
+exports.topologicalSortClasses = topologicalSortClasses;
+const loadDirectedAcyclicGraph = (umlClasses) => {
+    const directedAcyclicGraph = new js_graph_algorithms_1.DiGraph(umlClasses.length); // the number vertices in the graph
+    for (const sourceUmlClass of umlClasses) {
+        for (const association of Object.values(sourceUmlClass.associations)) {
+            // Find the first UML Class that matches the target class name
+            const targetUmlClass = (0, associations_1.findAssociatedClass)(association, sourceUmlClass, umlClasses);
+            if (!targetUmlClass) {
+                continue;
+            }
+            directedAcyclicGraph.addEdge(sourceUmlClass.id, targetUmlClass.id);
+        }
+    }
+    return directedAcyclicGraph;
+};
 //# sourceMappingURL=filterClasses.js.map

package/lib/parserEtherscan.js

@@ -7,6 +7,7 @@ exports.EtherscanParser = void 0;
 const axios_1 = __importDefault(require("axios"));
 const parser_1 = require("@solidity-parser/parser");
 const converterAST2Classes_1 = require("./converterAST2Classes");
+const filterClasses_1 = require("./filterClasses");
 const networks = [
     'mainnet',
     'ropsten',
@@ -69,8 +70,31 @@ class EtherscanParser {
      */
     async getSolidityCode(contractAddress) {
         const { files, contractName } = await this.getSourceCode(contractAddress);
+        // Parse the UmlClasses from the Solidity code in each file
+        let umlClasses = [];
+        for (const file of files) {
+            const node = await this.parseSourceCode(file.code);
+            const umlClass = (0, converterAST2Classes_1.convertAST2UmlClasses)(node, file.filename);
+            umlClasses = umlClasses.concat(umlClass);
+        }
+        // Sort the classes so dependent code is first
+        const topologicalSortedClasses = (0, filterClasses_1.topologicalSortClasses)(umlClasses);
+        // Get a list of filenames the classes are in
+        const sortedFilenames = topologicalSortedClasses.map((umlClass) => umlClass.relativePath);
+        // Remove duplicate filenames from the list
+        const dependentFilenames = [...new Set(sortedFilenames)];
+        // find any files that didn't have dependencies found
+        const nonDependentFiles = files.filter((f) => !dependentFilenames.includes(f.filename));
+        const nonDependentFilenames = nonDependentFiles.map((f) => f.filename);
         let solidityCode = '';
-        files.forEach((file) => {
+        // output non dependent code before the dependent files just in case sol2uml missed some dependencies
+        const filenames = [...nonDependentFilenames, ...dependentFilenames];
+        // For each filename
+        filenames.forEach((filename) => {
+            // Lookup the file that contains the Solidity code
+            const file = files.find((f) => f.filename === filename);
+            if (!file)
+                throw Error(`Failed to find file with filename "${filename}"`);
             // comment out any import statements
             // match whitespace before import
             // and characters after import up to ;

package/lib/sol2uml.js

@@ -15,10 +15,11 @@ const debugControl = require('debug');
 const debug = require('debug')('sol2uml');
 program
     .usage(`[subcommand] <options>
-The three subcommands:
-* class:    Generates a UML class diagram from Solidity source code. default
+
+sol2uml comes with three subcommands:
+* class:    Generates a UML class diagram from Solidity source code. (default)
 * storage:  Generates a diagram of a contract's storage slots.
-* flatten:  Pulls verified source files from a Blockchain explorer into one, flat, local Solidity file.
+* flatten:  Merges verified source files from a Blockchain explorer into one local file.
 
 The Solidity code can be pulled from verified source code on Blockchain explorers like Etherscan or from local Solidity files.`)
     .addOption(new commander_1.Option('-sf, --subfolders <value>', 'number of subfolders that will be recursively searched for Solidity files.').default('-1', 'all'))
@@ -93,7 +94,10 @@ If an Ethereum address with a 0x prefix is passed, the verified source code from
 });
 program
     .command('storage')
-    .description("Visually display a contract's storage slots.\n\nWARNING: sol2uml does not use the Solidity compiler so may differ with solc. A known example is fixed-sized arrays declared with an expression will fail to be sized.")
+    .description("Visually display a contract's storage slots.")
+    .usage(`<fileFolderAddress> [options]
+
+WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A known example is fixed-sized arrays declared with an expression will fail to be sized.`)
     .argument('<fileFolderAddress>', 'file name, base folder or contract address')
     .option('-c, --contract <name>', 'Contract name in local Solidity files. Not needed when using an address as the first argument as the contract name can be derived from Etherscan.')
     .option('-d, --data', 'Gets the values in the storage slots from an Ethereum node.', false)
@@ -143,8 +147,14 @@ program
 });
 program
     .command('flatten')
-    .description('get all verified source code for a contract from the Blockchain explorer into one local file')
-    .argument('<contractAddress>', 'Contract address')
+    .description('Merges verified source files for a contract from a Blockchain explorer into one local file.')
+    .usage(`<contractAddress> [options]
+
+In order for the merged code to compile, the following is done:
+1. File imports are commented out.
+2. "SPDX-License-Identifier" is renamed to "SPDX--License-Identifier".
+3. Contract dependencies are analysed so the files are merged in an order that will compile.`)
+    .argument('<contractAddress>', 'Contract address in hexadecimal format with a 0x prefix.')
     .action(async (contractAddress, options, command) => {
     try {
         debug(`About to flatten ${contractAddress}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sol2uml",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Unified Modeling Language (UML) class diagram generator for Solidity contracts",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",