sol2uml 2.1.6 → 2.1.9

package/README.md

@@ -97,6 +97,9 @@ 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)
+  -hm, --hideModifiers             hide modifier functions from contracts (default: false)
+  -ht, --hideEvents                hide events from contracts, interfaces and libraries (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/associations.d.ts

@@ -1,2 +1,2 @@
 import { Association, UmlClass } from './umlClass';
-export declare const findAssociatedClass: (association: Association, sourceUmlClass: UmlClass, umlClasses: UmlClass[]) => UmlClass | undefined;
+export declare const findAssociatedClass: (association: Association, sourceUmlClass: UmlClass, umlClasses: UmlClass[], searchedAbsolutePaths?: string[]) => UmlClass | undefined;

package/lib/associations.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.findAssociatedClass = void 0;
 const umlClass_1 = require("./umlClass");
 // Find the UML class linked to the association
-const findAssociatedClass = (association, sourceUmlClass, umlClasses) => {
+const findAssociatedClass = (association, sourceUmlClass, umlClasses, searchedAbsolutePaths = []) => {
     let umlClass = umlClasses.find((targetUmlClass) => {
         // is the source class link via the association to the target class?
         if (isAssociated(association, sourceUmlClass, targetUmlClass))
@@ -28,7 +28,9 @@ const findAssociatedClass = (association, sourceUmlClass, umlClasses) => {
     if (umlClass)
         return umlClass;
     // Could not find a link so now need to recursively look at imports of imports
-    return findImplicitImport(association, sourceUmlClass, umlClasses);
+    // add to already recursively processed files to avoid getting stuck in circular imports
+    searchedAbsolutePaths.push(sourceUmlClass.absolutePath);
+    return findImplicitImport(association, sourceUmlClass, umlClasses, searchedAbsolutePaths);
 };
 exports.findAssociatedClass = findAssociatedClass;
 // Tests if source class can be linked to the target class via an association
@@ -54,7 +56,7 @@ const isAssociated = (association, sourceUmlClass, targetUmlClass) => {
                     importedClass.alias &&
                     importedClass.className === targetUmlClass.name))));
 };
-const findImplicitImport = (association, sourceUmlClass, umlClasses) => {
+const findImplicitImport = (association, sourceUmlClass, umlClasses, searchedRelativePaths) => {
     // Get all implicit imports. That is, imports that do not explicitly import contracts or interfaces.
     const implicitImports = sourceUmlClass.imports.filter((i) => i.classNames.length === 0);
     // For each implicit import
@@ -65,8 +67,13 @@ const findImplicitImport = (association, sourceUmlClass, umlClasses) => {
             // Could not find a class in the import file so just move onto the next loop
             continue;
         }
+        // Avoid circular imports
+        if (searchedRelativePaths.includes(newSourceUmlClass.absolutePath)) {
+            // Have already recursively looked for imports of imports in this file
+            continue;
+        }
         // TODO need to handle imports that use aliases as the association will not be found
-        const umlClass = (0, exports.findAssociatedClass)(association, newSourceUmlClass, umlClasses);
+        const umlClass = (0, exports.findAssociatedClass)(association, newSourceUmlClass, umlClasses, searchedRelativePaths);
         if (umlClass)
             return umlClass;
     }

package/lib/converterAST2Classes.js

@@ -48,7 +48,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                 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,
@@ -62,7 +62,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                 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,
@@ -123,7 +123,36 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                     imports.push(newImport);
                 }
             }
-            // TODO add file level constants
+            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}`);
+            }
         });
     }
     else {
@@ -347,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,7 +1,10 @@
 import { UmlClass } from './umlClass';
 export interface ClassOptions {
+    hideConstants?: boolean;
     hideVariables?: boolean;
     hideFunctions?: boolean;
+    hideModifiers?: boolean;
+    hideEvents?: boolean;
     hideStructs?: boolean;
     hideEnums?: boolean;
     hideLibraries?: 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,19 +53,23 @@ 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}`;
     }
     return `\\<\\<${stereoName}\\>\\>\\n${umlClass.name}${relativePath}`;
 };
-const dotAttributeVisibilities = (umlClass, options = {}) => {
+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
@@ -109,7 +115,7 @@ const dotAttributes = (attributes, vizGroup, indent = true) => {
     });
     return dotString;
 };
-const dotOperatorVisibilities = (umlClass, options = {}) => {
+const dotOperatorVisibilities = (umlClass, options) => {
     if (umlClass.operators.length === 0)
         return '';
     let dotString = '| ';
@@ -140,11 +146,11 @@ const dotOperatorVisibilities = (umlClass, options = {}) => {
                 operators.push(operator);
             }
         }
-        dotString += dotOperators(umlClass, vizGroup, operators);
+        dotString += dotOperators(umlClass, vizGroup, operators, options);
     }
     return dotString;
 };
-const dotOperators = (umlClass, vizGroup, operators) => {
+const dotOperators = (umlClass, vizGroup, operators, options) => {
     // Skip if there are no operators
     if (!operators || operators.length === 0) {
         return '';
@@ -154,7 +160,12 @@ const dotOperators = (umlClass, vizGroup, operators) => {
     const operatorsSortedByStereotype = operators.sort((a, b) => {
         return b.stereotype - a.stereotype;
     });
-    for (const operator of operatorsSortedByStereotype) {
+    // Filter out any modifiers or events if options are flagged to hide them
+    let operatorsFiltered = operatorsSortedByStereotype.filter((o) => !((options.hideModifiers === true &&
+        o.stereotype === umlClass_1.OperatorStereotype.Modifier) ||
+        (options.hideEvents === true &&
+            o.stereotype === umlClass_1.OperatorStereotype.Event)));
+    for (const operator of operatorsFiltered) {
         dotString += '\\ \\ \\ \\ ';
         if (operator.stereotype > 0) {
             dotString += dotOperatorStereotype(umlClass, operator.stereotype);

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;
@@ -49,7 +49,7 @@ const convertClasses2Storages = (contractName, umlClasses, contractFilename) =>
         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 = [];
@@ -177,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,
@@ -205,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/parserFiles.js

@@ -48,7 +48,12 @@ function getSolidityFilesFromFolderOrFile(folderOrFilePath, ignoreFilesOrFolders
                     preserveSymlinks: true,
                 })
                     .on('data', (file) => {
-                    if ((0, path_1.extname)(file.path) === '.sol')
+                    if (
+                    // If file has sol extension
+                    (0, path_1.extname)(file.path) === '.sol' &&
+                        // and file and not a folder
+                        // Note Foundry's forge outputs folders with the same name as the source file
+                        file.stats.isFile())
                         files.push(file.path);
                 })
                     .on('end', () => {

package/lib/sol2uml.js

@@ -60,6 +60,9 @@ 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('-hm, --hideModifiers', 'hide modifier functions from contracts', false)
+    .option('-ht, --hideEvents', 'hide events from contracts, interfaces and libraries', 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 +112,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.6",
+  "version": "2.1.9",
   "description": "Solidity contract visualisation tool.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",