sol2uml 2.1.5 → 2.1.8

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)

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.js

@@ -29,8 +29,8 @@ const addStorageValues = async (url, contractAddress, storage, blockTag) => {
     const valueVariables = storage.variables.filter((s) => !s.noValue);
     const slots = valueVariables.map((s) => s.fromSlot);
     const values = await (0, slotValues_1.getStorageValues)(url, contractAddress, slots, blockTag);
-    valueVariables.forEach((storage, i) => {
-        storage.value = values[i];
+    valueVariables.forEach((valueVariable, i) => {
+        valueVariable.value = values[i];
     });
 };
 exports.addStorageValues = addStorageValues;
@@ -41,14 +41,15 @@ const convertClasses2Storages = (contractName, umlClasses, contractFilename) =>
             return name === contractName;
         }
         return (name === contractName &&
-            (relativePath == contractFilename ||
-                path_1.default.basename(relativePath) === contractFilename));
+            (relativePath == path_1.default.normalize(contractFilename) ||
+                path_1.default.basename(relativePath) ===
+                    path_1.default.normalize(contractFilename)));
     });
     if (!umlClass) {
         const contractFilenameError = contractFilename
             ? ` in filename "${contractFilename}"`
             : '';
-        throw Error(`Failed to find contract with name "${contractName}"${contractFilenameError}`);
+        throw Error(`Failed to find contract with name "${contractName}"${contractFilenameError}.\nIs the \`-c --contract <name>\` option correct?`);
     }
     debug(`Found contract "${contractName}" in ${umlClass.absolutePath}`);
     const storages = [];
@@ -176,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,
@@ -204,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)
@@ -109,6 +110,10 @@ WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A k
             ...command.parent._optionValues,
             ...options,
         };
+        // If not an address and the contractName option has not been specified
+        if (!(0, regEx_1.isAddress)(fileFolderAddress) && !combinedOptions.contract) {
+            throw Error(`Must use the \`-c, --contract <name>\` option to specify the contract to draw the storage diagram for when sourcing from local files.\nThis option is not needed when sourcing from a blockchain explorer with a contract address.`);
+        }
         let { umlClasses, contractName } = await (0, parserGeneral_1.parserUmlClasses)(fileFolderAddress, combinedOptions);
         contractName = combinedOptions.contract || contractName;
         const storages = (0, converterClasses2Storage_1.convertClasses2Storages)(contractName, umlClasses, combinedOptions.contractFile);

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.5",
+  "version": "2.1.8",
   "description": "Solidity contract visualisation tool.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",