sol2uml 2.1.4 → 2.1.7

package/README.md

@@ -77,9 +77,9 @@ Usage: sol2uml class <fileFolderAddress> [options]
 
 Generates UML diagrams from Solidity source code.
 
-If no file, folder or address is passes as the first argument, the working folder is used.
+If no file, folder or address is passed as the first argument, the working folder is used.
 When a folder is used, all *.sol files are found in that folder and all sub folders.
-A comma separated list of files and folders can also used. For example
+A comma separated list of files and folders can also be used. For example
     sol2uml contracts,node_modules/openzeppelin-solidity
 
 If an Ethereum address with a 0x prefix is passed, the verified source code from Etherscan will be used. For example
@@ -97,6 +97,7 @@ Options:
   -hv, --hideVariables             hide variables from contracts, interfaces, structs and enums (default: false)
   -hf, --hideFunctions             hide functions from contracts, interfaces and libraries (default: false)
   -hp, --hidePrivates              hide private and internal attributes and operators (default: false)
+  -hc, --hideConstants             hide file level constants (default: false)
   -he, --hideEnums                 hide enum types (default: false)
   -hs, --hideStructs               hide data structures (default: false)
   -hl, --hideLibraries             hide libraries (default: false)
@@ -119,12 +120,13 @@ 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.
-  -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
+  -c, --contract <name>           Contract name in the local Solidity files. Not needed when using an address as the first argument as the contract name can be derived from Etherscan.
+  -cf, --contractFile <filename>  Filename the contract is located in. This can include the relative path to the desired file.
+  -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.
+  -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
 ```
 
 ### Flatten usage

package/lib/converterAST2Classes.js

@@ -25,6 +25,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertAST2UmlClasses = void 0;
 const path = __importStar(require("path"));
+const path_1 = require("path");
 const umlClass_1 = require("./umlClass");
 const typeGuards_1 = require("./typeGuards");
 const debug = require('debug')('sol2uml');
@@ -35,7 +36,6 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
     if (node.type === 'SourceUnit') {
         node.children.forEach((childNode) => {
             if (childNode.type === 'ContractDefinition') {
-                debug(`Adding contract ${childNode.name}`);
                 let umlClass = new umlClass_1.UmlClass({
                     name: childNode.name,
                     absolutePath: filesystem
@@ -44,10 +44,11 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                     relativePath,
                 });
                 umlClass = parseContractDefinition(umlClass, childNode);
+                debug(`Added contract ${childNode.name}`);
                 umlClasses.push(umlClass);
             }
             else if (childNode.type === 'StructDefinition') {
-                debug(`Adding struct ${childNode.name}`);
+                debug(`Adding file level struct ${childNode.name}`);
                 let umlClass = new umlClass_1.UmlClass({
                     name: childNode.name,
                     stereotype: umlClass_1.ClassStereotype.Struct,
@@ -57,10 +58,11 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                     relativePath,
                 });
                 umlClass = parseStructDefinition(umlClass, childNode);
+                debug(`Added struct ${umlClass.name}`);
                 umlClasses.push(umlClass);
             }
             else if (childNode.type === 'EnumDefinition') {
-                debug(`Adding enum ${childNode.name}`);
+                debug(`Adding file level enum ${childNode.name}`);
                 let umlClass = new umlClass_1.UmlClass({
                     name: childNode.name,
                     stereotype: umlClass_1.ClassStereotype.Enum,
@@ -69,6 +71,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                         : relativePath,
                     relativePath,
                 });
+                debug(`Added enum ${umlClass.name}`);
                 umlClass = parseEnumDefinition(umlClass, childNode);
                 umlClasses.push(umlClass);
             }
@@ -80,7 +83,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                         const importPath = require.resolve(childNode.path, {
                             paths: [codeFolder],
                         });
-                        imports.push({
+                        const newImport = {
                             absolutePath: importPath,
                             classNames: childNode.symbolAliases
                                 ? childNode.symbolAliases.map((alias) => {
@@ -90,7 +93,9 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                                     };
                                 })
                                 : [],
-                        });
+                        };
+                        debug(`Added filesystem import ${newImport.absolutePath} with class names ${newImport.classNames}`);
+                        imports.push(newImport);
                     }
                     catch (err) {
                         debug(`Failed to resolve import ${childNode.path} from file ${relativePath}`);
@@ -98,10 +103,12 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                 }
                 else {
                     // this has come from Etherscan
-                    const importPath = childNode.path[0] === '@'
-                        ? childNode.path
-                        : path.join(codeFolder, childNode.path);
-                    imports.push({
+                    const importPath = childNode.path[0] === '.'
+                        ? // Use Linux paths, not Windows paths, to resolve Etherscan files
+                            path_1.posix.join(codeFolder.toString(), childNode.path)
+                        : childNode.path;
+                    debug(`codeFolder ${codeFolder} childNode.path ${childNode.path}`);
+                    const newImport = {
                         absolutePath: importPath,
                         classNames: childNode.symbolAliases
                             ? childNode.symbolAliases.map((alias) => {
@@ -111,8 +118,40 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                                 };
                             })
                             : [],
+                    };
+                    debug(`Added Etherscan import ${newImport.absolutePath} with class names: ${newImport.classNames}`);
+                    imports.push(newImport);
+                }
+            }
+            else if (childNode.type === 'FileLevelConstant') {
+                debug(`Adding file level constant ${childNode.name}`);
+                const [type, attributeType] = parseTypeName(childNode.typeName);
+                const umlClass = new umlClass_1.UmlClass({
+                    name: childNode.name,
+                    stereotype: umlClass_1.ClassStereotype.Constant,
+                    absolutePath: filesystem
+                        ? path.resolve(relativePath) // resolve the absolute path
+                        : relativePath,
+                    relativePath,
+                    attributes: [
+                        {
+                            name: childNode.name,
+                            type,
+                            attributeType,
+                        },
+                    ],
+                });
+                if (childNode?.initialValue?.type === 'NumberLiteral') {
+                    umlClass.constants.push({
+                        name: childNode.name,
+                        value: parseInt(childNode.initialValue.number),
                     });
                 }
+                // TODO handle expressions. eg N_COINS * 2
+                umlClasses.push(umlClass);
+            }
+            else if (childNode.type !== 'PragmaDirective') {
+                debug(`node type "${childNode.type}" not parsed in ${relativePath}`);
             }
         });
     }
@@ -337,13 +376,22 @@ function addAssociations(nodes, umlClass) {
                     ], umlClass);
                     // Array of user defined types
                 }
-                else if (node.typeName.type == 'ArrayTypeName' &&
-                    node.typeName.baseTypeName.type === 'UserDefinedTypeName') {
-                    const { umlClassName } = parseClassName(node.typeName.baseTypeName.namePath);
-                    umlClass.addAssociation({
-                        referenceType,
-                        targetUmlClassName: umlClassName,
-                    });
+                else if (node.typeName.type == 'ArrayTypeName') {
+                    if (node.typeName.baseTypeName.type ===
+                        'UserDefinedTypeName') {
+                        const { umlClassName } = parseClassName(node.typeName.baseTypeName.namePath);
+                        umlClass.addAssociation({
+                            referenceType,
+                            targetUmlClassName: umlClassName,
+                        });
+                    }
+                    else if (node.typeName.length?.type === 'Identifier') {
+                        const { umlClassName } = parseClassName(node.typeName.length.name);
+                        umlClass.addAssociation({
+                            referenceType,
+                            targetUmlClassName: umlClassName,
+                        });
+                    }
                 }
                 break;
             case 'UserDefinedTypeName':

package/lib/converterClass2Dot.d.ts

@@ -1,5 +1,6 @@
 import { UmlClass } from './umlClass';
 export interface ClassOptions {
+    hideConstants?: boolean;
     hideVariables?: boolean;
     hideFunctions?: boolean;
     hideStructs?: boolean;

package/lib/converterClass2Dot.js

@@ -14,7 +14,9 @@ const convertClass2Dot = (umlClass, options = {}) => {
             umlClass.stereotype === umlClass_1.ClassStereotype.Abstract) ||
         (options.hideStructs &&
             umlClass.stereotype === umlClass_1.ClassStereotype.Struct) ||
-        (options.hideEnums && umlClass.stereotype === umlClass_1.ClassStereotype.Enum)) {
+        (options.hideEnums && umlClass.stereotype === umlClass_1.ClassStereotype.Enum) ||
+        (options.hideConstants &&
+            umlClass.stereotype === umlClass_1.ClassStereotype.Constant)) {
         return '';
     }
     let dotString = `\n${umlClass.id} [label="{${dotClassTitle(umlClass, options)}`;
@@ -51,6 +53,9 @@ const dotClassTitle = (umlClass, options = {}) => {
         case umlClass_1.ClassStereotype.Enum:
             stereoName = 'Enum';
             break;
+        case umlClass_1.ClassStereotype.Constant:
+            stereoName = 'Constant';
+            break;
         default:
             // Contract or undefined stereotype will just return the UmlClass name
             return `${umlClass.name}${relativePath}`;
@@ -61,9 +66,10 @@ const dotAttributeVisibilities = (umlClass, options = {}) => {
     if (umlClass.attributes.length === 0)
         return '';
     let dotString = '| ';
-    // if a struct or enum then no visibility group
+    // if a struct, enum or constant then no visibility group
     if (umlClass.stereotype === umlClass_1.ClassStereotype.Struct ||
-        umlClass.stereotype === umlClass_1.ClassStereotype.Enum) {
+        umlClass.stereotype === umlClass_1.ClassStereotype.Enum ||
+        umlClass.stereotype === umlClass_1.ClassStereotype.Constant) {
         return dotString + dotAttributes(umlClass.attributes, undefined, false);
     }
     // For each visibility group

package/lib/converterClasses2Dot.js

@@ -90,7 +90,7 @@ function addAssociationsToDot(umlClasses, classOptions = {}) {
 exports.addAssociationsToDot = addAssociationsToDot;
 function addAssociationToDot(sourceUmlClass, targetUmlClass, association, classOptions = {}) {
     // do not include library or interface associations if hidden
-    // Or associations to Structs or Enums if they are hidden
+    // Or associations to Structs, Enums or Constants if they are hidden
     if ((classOptions.hideLibraries &&
         (sourceUmlClass.stereotype === umlClass_1.ClassStereotype.Library ||
             targetUmlClass.stereotype === umlClass_1.ClassStereotype.Library)) ||
@@ -103,7 +103,9 @@ function addAssociationToDot(sourceUmlClass, targetUmlClass, association, classO
         (classOptions.hideStructs &&
             targetUmlClass.stereotype === umlClass_1.ClassStereotype.Struct) ||
         (classOptions.hideEnums &&
-            targetUmlClass.stereotype === umlClass_1.ClassStereotype.Enum)) {
+            targetUmlClass.stereotype === umlClass_1.ClassStereotype.Enum) ||
+        (classOptions.hideConstants &&
+            targetUmlClass.stereotype === umlClass_1.ClassStereotype.Constant)) {
         return '';
     }
     let dotString = `\n${sourceUmlClass.id} -> ${targetUmlClass.id} [`;

package/lib/converterClasses2Storage.d.ts

@@ -36,7 +36,7 @@ export interface Storage {
  * @param storage is mutated with the storage values
  */
 export declare const addStorageValues: (url: string, contractAddress: string, storage: Storage, blockTag: string) => Promise<void>;
-export declare const convertClasses2Storages: (contractName: string, umlClasses: UmlClass[]) => Storage[];
+export declare const convertClasses2Storages: (contractName: string, umlClasses: UmlClass[], contractFilename?: string) => Storage[];
 export declare const parseReferenceStorage: (attribute: Attribute, umlClass: UmlClass, otherClasses: UmlClass[], storages: Storage[]) => Storage | undefined;
 export declare const calcStorageByteSize: (attribute: Attribute, umlClass: UmlClass, otherClasses: UmlClass[]) => {
     size: number;

package/lib/converterClasses2Storage.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findDimensionLength = exports.offsetStorageSlots = exports.calcSlotKey = exports.isElementary = exports.calcStorageByteSize = exports.parseReferenceStorage = exports.convertClasses2Storages = exports.addStorageValues = exports.StorageType = void 0;
 const umlClass_1 = require("./umlClass");
@@ -6,6 +9,8 @@ const associations_1 = require("./associations");
 const slotValues_1 = require("./slotValues");
 const utils_1 = require("ethers/lib/utils");
 const ethers_1 = require("ethers");
+const path_1 = __importDefault(require("path"));
+const debug = require('debug')('sol2uml');
 var StorageType;
 (function (StorageType) {
     StorageType["Contract"] = "Contract";
@@ -29,14 +34,24 @@ const addStorageValues = async (url, contractAddress, storage, blockTag) => {
     });
 };
 exports.addStorageValues = addStorageValues;
-const convertClasses2Storages = (contractName, umlClasses) => {
+const convertClasses2Storages = (contractName, umlClasses, contractFilename) => {
     // Find the base UML Class from the base contract name
-    const umlClass = umlClasses.find(({ name }) => {
-        return name === contractName;
+    const umlClass = umlClasses.find(({ name, relativePath }) => {
+        if (!contractFilename) {
+            return name === contractName;
+        }
+        return (name === contractName &&
+            (relativePath == path_1.default.normalize(contractFilename) ||
+                path_1.default.basename(relativePath) ===
+                    path_1.default.normalize(contractFilename)));
     });
     if (!umlClass) {
-        throw Error(`Failed to find contract with name "${contractName}"`);
+        const contractFilenameError = contractFilename
+            ? ` in filename "${contractFilename}"`
+            : '';
+        throw Error(`Failed to find contract with name "${contractName}"${contractFilenameError}`);
     }
+    debug(`Found contract "${contractName}" in ${umlClass.absolutePath}`);
     const storages = [];
     const variables = parseVariables(umlClass, umlClasses, [], storages, []);
     storages.unshift({
@@ -162,25 +177,29 @@ const parseReferenceStorage = (attribute, umlClass, otherClasses, storages) => {
             attributeType: baseAttributeType,
         };
         const { size: arrayItemSize } = (0, exports.calcStorageByteSize)(baseAttribute, umlClass, otherClasses);
-        const firstVariable = {
+        const arraySlotSize = arrayItemSize > 16
+            ? 32 * Math.ceil(arrayItemSize / 32)
+            : arrayItemSize;
+        const variables = [];
+        variables[0] = {
             id: variableId++,
             fromSlot: 0,
-            toSlot: Math.floor((arrayItemSize - 1) / 32),
+            toSlot: Math.floor((arraySlotSize - 1) / 32),
             byteSize: arrayItemSize,
             byteOffset: 0,
             type: baseType,
             dynamic,
             noValue: false,
         };
-        const variables = [firstVariable];
         if (arrayLength > 1) {
+            // For fixed length arrays. Dynamic arrays will have undefined arrayLength
             for (let i = 1; i < arrayLength; i++) {
                 variables.push({
                     id: variableId++,
-                    fromSlot: Math.floor((i * arrayItemSize) / 32),
-                    toSlot: Math.floor(((i + 1) * arrayItemSize - 1) / 32),
+                    fromSlot: Math.floor((i * arraySlotSize) / 32),
+                    toSlot: Math.floor(((i + 1) * arraySlotSize - 1) / 32),
                     byteSize: arrayItemSize,
-                    byteOffset: (i * arrayItemSize) % 32,
+                    byteOffset: (i * arraySlotSize) % 32,
                     type: baseType,
                     dynamic,
                     noValue: false,
@@ -190,7 +209,7 @@ const parseReferenceStorage = (attribute, umlClass, otherClasses, storages) => {
         // recursively add storage
         if (baseAttributeType !== umlClass_1.AttributeType.Elementary) {
             const referenceStorage = (0, exports.parseReferenceStorage)(baseAttribute, umlClass, otherClasses, storages);
-            firstVariable.referenceStorageId = referenceStorage?.id;
+            variables[0].referenceStorageId = referenceStorage?.id;
         }
         const newStorage = {
             id: storageId++,

package/lib/parserEtherscan.js

@@ -105,6 +105,7 @@ class EtherscanParser {
         const { files, contractName } = await this.getSourceCode(contractAddress);
         let umlClasses = [];
         for (const file of files) {
+            debug(`Parsing source file ${file.filename}`);
             const node = await this.parseSourceCode(file.code);
             const umlClass = (0, converterAST2Classes_1.convertAST2UmlClasses)(node, file.filename);
             umlClasses = umlClasses.concat(umlClass);

package/lib/sol2uml.js

@@ -46,9 +46,9 @@ program
 
 Generates UML diagrams from Solidity source code.
 
-If no file, folder or address is passes as the first argument, the working folder is used.
+If no file, folder or address is passed as the first argument, the working folder is used.
 When a folder is used, all *.sol files are found in that folder and all sub folders.
-A comma separated list of files and folders can also used. For example
+A comma separated list of files and folders can also be used. For example
     sol2uml contracts,node_modules/openzeppelin-solidity
 
 If an Ethereum address with a 0x prefix is passed, the verified source code from Etherscan will be used. For example
@@ -60,6 +60,7 @@ If an Ethereum address with a 0x prefix is passed, the verified source code from
     .option('-hv, --hideVariables', 'hide variables from contracts, interfaces, structs and enums', false)
     .option('-hf, --hideFunctions', 'hide functions from contracts, interfaces and libraries', false)
     .option('-hp, --hidePrivates', 'hide private and internal attributes and operators', false)
+    .option('-hc, --hideConstants', 'hide file level constants', false)
     .option('-he, --hideEnums', 'hide enum types', false)
     .option('-hs, --hideStructs', 'hide data structures', false)
     .option('-hl, --hideLibraries', 'hide libraries', false)
@@ -95,7 +96,8 @@ program
 
 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('-c, --contract <name>', 'Contract name in the local Solidity files. Not needed when using an address as the first argument as the contract name can be derived from Etherscan.')
+    .option('-cf, --contractFile <filename>', 'Filename the contract is located in. This can include the relative path to the desired file.')
     .option('-d, --data', 'Gets the values in the storage slots from an Ethereum node.', false)
     .option('-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.')
     .addOption(new commander_1.Option('-u, --url <url>', 'URL of the Ethereum node to get storage values if the `data` option is used.')
@@ -110,7 +112,7 @@ WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A k
         };
         let { umlClasses, contractName } = await (0, parserGeneral_1.parserUmlClasses)(fileFolderAddress, combinedOptions);
         contractName = combinedOptions.contract || contractName;
-        const storages = (0, converterClasses2Storage_1.convertClasses2Storages)(contractName, umlClasses);
+        const storages = (0, converterClasses2Storage_1.convertClasses2Storages)(contractName, umlClasses, combinedOptions.contractFile);
         if ((0, regEx_1.isAddress)(fileFolderAddress)) {
             // The first storage is the contract
             storages[0].address = fileFolderAddress;
@@ -125,7 +127,7 @@ WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A k
             }
             else {
                 if (!(0, regEx_1.isAddress)(fileFolderAddress)) {
-                    throw Error(`Can not get storage slot values if first param is not an address and the \`address\` option is not used.`);
+                    throw Error(`Can not get storage slot values if first param is not an address and the \`--storage\` option is not used.`);
                 }
                 storageAddress = fileFolderAddress;
             }

package/lib/umlClass.d.ts

@@ -12,7 +12,8 @@ export declare enum ClassStereotype {
     Abstract = 3,
     Contract = 4,
     Struct = 5,
-    Enum = 6
+    Enum = 6,
+    Constant = 7
 }
 export declare enum OperatorStereotype {
     None = 0,

package/lib/umlClass.js

@@ -18,6 +18,7 @@ var ClassStereotype;
     ClassStereotype[ClassStereotype["Contract"] = 4] = "Contract";
     ClassStereotype[ClassStereotype["Struct"] = 5] = "Struct";
     ClassStereotype[ClassStereotype["Enum"] = 6] = "Enum";
+    ClassStereotype[ClassStereotype["Constant"] = 7] = "Constant";
 })(ClassStereotype = exports.ClassStereotype || (exports.ClassStereotype = {}));
 var OperatorStereotype;
 (function (OperatorStereotype) {

package/package.json

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