sol2uml 2.3.0 → 2.4.0

package/README.md

@@ -49,6 +49,7 @@ 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:  Merges verified source files from a Blockchain explorer into one local file.
+* diff:     Compares the flattened Solidity code from a Blockchain explorer for two contracts.
 
 The Solidity code can be pulled from verified source code on Blockchain explorers like Etherscan or from local Solidity files.
 
@@ -73,7 +74,7 @@ Commands:
 ### Class usage
 
 ```
-Usage: sol2uml class <fileFolderAddress> [options]
+Usage: sol2uml class [options] <fileFolderAddress>
 
 Generates UML diagrams from Solidity source code.
 
@@ -114,7 +115,7 @@ Options:
 ### Storage usage
 
 ```
-Usage: sol2uml storage <fileFolderAddress> [options]
+Usage: sol2uml storage [options] <fileFolderAddress>
 
 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.
 
@@ -136,7 +137,7 @@ Options:
 ### Flatten usage
 
 ```
-Usage: sol2uml flatten <contractAddress> [options]
+Usage: sol2uml flatten <contractAddress>
 
 In order for the merged code to compile, the following is done:
 1. pragma solidity is set using the compiler of the verified contract.
@@ -154,6 +155,28 @@ Options:
   -h, --help       display help for command
 ```
 
+### Diff usage
+
+```
+Usage: sol2uml diff [options] <addressA> <addressB>
+
+The results show the comparision of contract A to B.
+The green sections are additions to contract B that are not in contract A.
+The red sections are removals from contract A that are not in contract B.
+The line numbers are from contract B. There are no line numbers for the red sections as they are not in contract B.
+
+Compare verified Solidity code differences between two contracts.
+
+Arguments:
+  addressA                  Contract address in hexadecimal format with a 0x prefix.
+  addressB                  Contract address in hexadecimal format with a 0x prefix.
+
+Options:
+  -l, --lineBuffer <value>  Minimum number a lines before and after changes (default: "4")
+  -s, --saveFiles           Save the flattened contract code to the filesystem. The file names will be the contract address with a .sol extension. (default: false)
+  -h, --help                display help for command
+```
+
 ## UML Class diagram examples
 
 To generate a diagram of all contracts under the contracts folder and its sub folders

package/lib/converterAST2Classes.d.ts

@@ -1,3 +1,10 @@
 import { ASTNode } from '@solidity-parser/parser/dist/src/ast-types';
 import { UmlClass } from './umlClass';
+/**
+ * Convert solidity parser output of type `ASTNode` to UML classes of type `UMLClass`
+ * @param node output of Solidity parser of type `ASTNode`
+ * @param relativePath relative path from the working directory to the Solidity source file
+ * @param filesystem flag if Solidity source code was parsed from the filesystem or Etherscan
+ * @return umlClasses array of UML class definitions of type `UmlClass`
+ */
 export declare function convertAST2UmlClasses(node: ASTNode, relativePath: string, filesystem?: boolean): UmlClass[];

package/lib/converterAST2Classes.js

@@ -29,7 +29,14 @@ const path_1 = require("path");
 const umlClass_1 = require("./umlClass");
 const typeGuards_1 = require("./typeGuards");
 const debug = require('debug')('sol2uml');
-let umlClasses = [];
+let umlClasses;
+/**
+ * Convert solidity parser output of type `ASTNode` to UML classes of type `UMLClass`
+ * @param node output of Solidity parser of type `ASTNode`
+ * @param relativePath relative path from the working directory to the Solidity source file
+ * @param filesystem flag if Solidity source code was parsed from the filesystem or Etherscan
+ * @return umlClasses array of UML class definitions of type `UmlClass`
+ */
 function convertAST2UmlClasses(node, relativePath, filesystem = false) {
     const imports = [];
     umlClasses = [];
@@ -43,7 +50,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                         : relativePath,
                     relativePath,
                 });
-                umlClass = parseContractDefinition(umlClass, childNode);
+                parseContractDefinition(childNode, umlClass);
                 debug(`Added contract ${childNode.name}`);
                 umlClasses.push(umlClass);
             }
@@ -57,7 +64,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                         : relativePath,
                     relativePath,
                 });
-                umlClass = parseStructDefinition(umlClass, childNode);
+                parseStructDefinition(childNode, umlClass);
                 debug(`Added struct ${umlClass.name}`);
                 umlClasses.push(umlClass);
             }
@@ -72,7 +79,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                     relativePath,
                 });
                 debug(`Added enum ${umlClass.name}`);
-                umlClass = parseEnumDefinition(umlClass, childNode);
+                parseEnumDefinition(childNode, umlClass);
                 umlClasses.push(umlClass);
             }
             else if (childNode.type === 'ImportDirective') {
@@ -178,7 +185,12 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
     return umlClasses;
 }
 exports.convertAST2UmlClasses = convertAST2UmlClasses;
-function parseStructDefinition(umlClass, node) {
+/**
+ * Parse struct definition for UML attributes and associations.
+ * @param node defined in ASTNode as `StructDefinition`
+ * @param umlClass that has struct attributes and associations added. This parameter is mutated.
+ */
+function parseStructDefinition(node, umlClass) {
     node.members.forEach((member) => {
         const [type, attributeType] = parseTypeName(member.typeName);
         umlClass.attributes.push({
@@ -188,10 +200,14 @@ function parseStructDefinition(umlClass, node) {
         });
     });
     // Recursively parse struct members for associations
-    umlClass = addAssociations(node.members, umlClass);
-    return umlClass;
+    addAssociations(node.members, umlClass);
 }
-function parseEnumDefinition(umlClass, node) {
+/**
+ * Parse enum definition for UML attributes and associations.
+ * @param node defined in ASTNode as `EnumDefinition`
+ * @param umlClass that has enum attributes and associations added. This parameter is mutated.
+ */
+function parseEnumDefinition(node, umlClass) {
     let index = 0;
     node.members.forEach((member) => {
         umlClass.attributes.push({
@@ -200,10 +216,14 @@ function parseEnumDefinition(umlClass, node) {
         });
     });
     // Recursively parse struct members for associations
-    umlClass = addAssociations(node.members, umlClass);
-    return umlClass;
+    addAssociations(node.members, umlClass);
 }
-function parseContractDefinition(umlClass, node) {
+/**
+ * Parse contract definition for UML attributes, operations and associations.
+ * @param node defined in ASTNode as `ContractDefinition`
+ * @param umlClass that has attributes, operations and associations added. This parameter is mutated.
+ */
+function parseContractDefinition(node, umlClass) {
     umlClass.stereotype = parseContractKind(node.kind);
     // For each base contract
     node.baseContracts.forEach((baseClass) => {
@@ -239,7 +259,7 @@ function parseContractDefinition(umlClass, node) {
                 }
             });
             // Recursively parse variables for associations
-            umlClass = addAssociations(subNode.variables, umlClass);
+            addAssociations(subNode.variables, umlClass);
         }
         else if ((0, typeGuards_1.isUsingForDeclaration)(subNode)) {
             // Add association to library contract
@@ -262,7 +282,7 @@ function parseContractDefinition(umlClass, node) {
                     name: '',
                     stereotype: umlClass_1.OperatorStereotype.Fallback,
                     parameters: parseParameters(subNode.parameters),
-                    isPayable: parsePayable(subNode.stateMutability),
+                    stateMutability: subNode.stateMutability,
                 });
             }
             else {
@@ -283,9 +303,9 @@ function parseContractDefinition(umlClass, node) {
                 });
             }
             // Recursively parse function parameters for associations
-            umlClass = addAssociations(subNode.parameters, umlClass);
+            addAssociations(subNode.parameters, umlClass);
             if (subNode.returnParameters) {
-                umlClass = addAssociations(subNode.returnParameters, umlClass);
+                addAssociations(subNode.returnParameters, umlClass);
             }
             // If no body to the function, it must be either an Interface or Abstract
             if (subNode.body === null) {
@@ -296,7 +316,7 @@ function parseContractDefinition(umlClass, node) {
             }
             else {
                 // Recursively parse function statements for associations
-                umlClass = addAssociations(subNode.body.statements, umlClass);
+                addAssociations(subNode.body.statements, umlClass);
             }
         }
         else if ((0, typeGuards_1.isModifierDefinition)(subNode)) {
@@ -307,7 +327,7 @@ function parseContractDefinition(umlClass, node) {
             });
             if (subNode.body && subNode.body.statements) {
                 // Recursively parse modifier statements for associations
-                umlClass = addAssociations(subNode.body.statements, umlClass);
+                addAssociations(subNode.body.statements, umlClass);
             }
         }
         else if ((0, typeGuards_1.isEventDefinition)(subNode)) {
@@ -317,7 +337,7 @@ function parseContractDefinition(umlClass, node) {
                 parameters: parseParameters(subNode.parameters),
             });
             // Recursively parse event parameters for associations
-            umlClass = addAssociations(subNode.parameters, umlClass);
+            addAssociations(subNode.parameters, umlClass);
         }
         else if ((0, typeGuards_1.isStructDefinition)(subNode)) {
             const structClass = new umlClass_1.UmlClass({
@@ -326,7 +346,7 @@ function parseContractDefinition(umlClass, node) {
                 relativePath: umlClass.relativePath,
                 stereotype: umlClass_1.ClassStereotype.Struct,
             });
-            parseStructDefinition(structClass, subNode);
+            parseStructDefinition(subNode, structClass);
             umlClasses.push(structClass);
             // list as contract level struct
             umlClass.structs.push(structClass.id);
@@ -338,19 +358,22 @@ function parseContractDefinition(umlClass, node) {
                 relativePath: umlClass.relativePath,
                 stereotype: umlClass_1.ClassStereotype.Enum,
             });
-            parseEnumDefinition(enumClass, subNode);
+            parseEnumDefinition(subNode, enumClass);
             umlClasses.push(enumClass);
             // list as contract level enum
             umlClass.enums.push(enumClass.id);
         }
     });
-    return umlClass;
 }
-// Recursively parse AST nodes for associations
+/**
+ * Recursively parse a list of ASTNodes for UML associations
+ * @param nodes array of parser output of type ASTNode
+ * @param umlClass that has associations added of type `Association`. This parameter is mutated.
+ */
 function addAssociations(nodes, umlClass) {
     if (!nodes || !Array.isArray(nodes)) {
         debug('Warning - can not recursively parse AST nodes for associations. Invalid nodes array');
-        return umlClass;
+        return;
     }
     for (const node of nodes) {
         // Some variables can be null. eg var (lad,,,) = tub.cups(cup);
@@ -382,8 +405,8 @@ function addAssociations(nodes, umlClass) {
                     }
                 }
                 else if (node.typeName.type === 'Mapping') {
-                    umlClass = addAssociations([node.typeName.keyType], umlClass);
-                    umlClass = addAssociations([
+                    addAssociations([node.typeName.keyType], umlClass);
+                    addAssociations([
                         {
                             ...node.typeName.valueType,
                             isStateVar: node.isStateVar,
@@ -416,89 +439,101 @@ function addAssociations(nodes, umlClass) {
                 });
                 break;
             case 'Block':
-                umlClass = addAssociations(node.statements, umlClass);
+                addAssociations(node.statements, umlClass);
                 break;
             case 'StateVariableDeclaration':
             case 'VariableDeclarationStatement':
-                umlClass = addAssociations(node.variables, umlClass);
-                umlClass = parseExpression(node.initialValue, umlClass);
+                addAssociations(node.variables, umlClass);
+                parseExpression(node.initialValue, umlClass);
+                break;
+            case 'EmitStatement':
+                addAssociations(node.eventCall.arguments, umlClass);
+                parseExpression(node.eventCall.expression, umlClass);
+                break;
+            case 'FunctionCall':
+                addAssociations(node.arguments, umlClass);
+                parseExpression(node.expression, umlClass);
                 break;
             case 'ForStatement':
                 if ('statements' in node.body) {
-                    umlClass = addAssociations(node.body.statements, umlClass);
+                    addAssociations(node.body.statements, umlClass);
                 }
-                umlClass = parseExpression(node.conditionExpression, umlClass);
-                umlClass = parseExpression(node.loopExpression.expression, umlClass);
+                parseExpression(node.conditionExpression, umlClass);
+                parseExpression(node.loopExpression.expression, umlClass);
                 break;
             case 'WhileStatement':
                 if ('statements' in node.body) {
-                    umlClass = addAssociations(node.body.statements, umlClass);
+                    addAssociations(node.body.statements, umlClass);
                 }
                 break;
             case 'DoWhileStatement':
                 if ('statements' in node.body) {
-                    umlClass = addAssociations(node.body.statements, umlClass);
+                    addAssociations(node.body.statements, umlClass);
                 }
-                umlClass = parseExpression(node.condition, umlClass);
+                parseExpression(node.condition, umlClass);
                 break;
             case 'ReturnStatement':
             case 'ExpressionStatement':
-                umlClass = parseExpression(node.expression, umlClass);
+                parseExpression(node.expression, umlClass);
                 break;
             case 'IfStatement':
                 if (node.trueBody) {
                     if ('statements' in node.trueBody) {
-                        umlClass = addAssociations(node.trueBody.statements, umlClass);
+                        addAssociations(node.trueBody.statements, umlClass);
                     }
                     if ('expression' in node.trueBody) {
-                        umlClass = parseExpression(node.trueBody.expression, umlClass);
+                        parseExpression(node.trueBody.expression, umlClass);
                     }
                 }
                 if (node.falseBody) {
                     if ('statements' in node.falseBody) {
-                        umlClass = addAssociations(node.falseBody.statements, umlClass);
+                        addAssociations(node.falseBody.statements, umlClass);
                     }
                     if ('expression' in node.falseBody) {
-                        umlClass = parseExpression(node.falseBody.expression, umlClass);
+                        parseExpression(node.falseBody.expression, umlClass);
                     }
                 }
-                umlClass = parseExpression(node.condition, umlClass);
+                parseExpression(node.condition, umlClass);
                 break;
             default:
                 break;
         }
     }
-    return umlClass;
 }
+/**
+ * Recursively parse an expression to add UML associations to other contracts, constants, enums or structs.
+ * @param expression defined in ASTNode as `Expression`
+ * @param umlClass that has associations added of type `Association`. This parameter is mutated.
+ */
 function parseExpression(expression, umlClass) {
     if (!expression || !expression.type) {
-        return umlClass;
+        return;
     }
     if (expression.type === 'BinaryOperation') {
-        umlClass = parseExpression(expression.left, umlClass);
-        umlClass = parseExpression(expression.right, umlClass);
+        parseExpression(expression.left, umlClass);
+        parseExpression(expression.right, umlClass);
     }
     else if (expression.type === 'FunctionCall') {
-        umlClass = parseExpression(expression.expression, umlClass);
+        parseExpression(expression.expression, umlClass);
         expression.arguments.forEach((arg) => {
-            umlClass = parseExpression(arg, umlClass);
+            parseExpression(arg, umlClass);
         });
     }
     else if (expression.type === 'IndexAccess') {
-        umlClass = parseExpression(expression.base, umlClass);
-        umlClass = parseExpression(expression.index, umlClass);
+        parseExpression(expression.base, umlClass);
+        parseExpression(expression.index, umlClass);
     }
     else if (expression.type === 'TupleExpression') {
         expression.components.forEach((component) => {
-            umlClass = parseExpression(component, umlClass);
+            parseExpression(component, umlClass);
         });
     }
     else if (expression.type === 'MemberAccess') {
-        umlClass = parseExpression(expression.expression, umlClass);
+        parseExpression(expression.expression, umlClass);
     }
     else if (expression.type === 'Conditional') {
-        umlClass = addAssociations([expression.trueExpression], umlClass);
-        umlClass = addAssociations([expression.falseExpression], umlClass);
+        addAssociations([expression.trueExpression], umlClass);
+        addAssociations([expression.falseExpression], umlClass);
     }
     else if (expression.type === 'Identifier') {
         umlClass.addAssociation({
@@ -507,14 +542,19 @@ function parseExpression(expression, umlClass) {
         });
     }
     else if (expression.type === 'NewExpression') {
-        umlClass = addAssociations([expression.typeName], umlClass);
+        addAssociations([expression.typeName], umlClass);
     }
     else if (expression.type === 'UnaryOperation' &&
         expression.subExpression) {
-        umlClass = parseExpression(expression.subExpression, umlClass);
+        parseExpression(expression.subExpression, umlClass);
     }
-    return umlClass;
 }
+/**
+ * Convert user defined type to class name and struct or enum.
+ * eg `Set.Data` has class `Set` and struct or enum of `Data`
+ * @param rawClassName can be `TypeName` properties `namePath`, `length.name` or `baseTypeName.namePath` as defined in the ASTNode
+ * @return object with `umlClassName` and `structOrEnum` of type string
+ */
 function parseClassName(rawClassName) {
     if (!rawClassName ||
         typeof rawClassName !== 'string' ||
@@ -531,6 +571,11 @@ function parseClassName(rawClassName) {
         structOrEnum: splitUmlClassName[1],
     };
 }
+/**
+ * Converts the contract visibility to attribute or operator visibility of type `Visibility`
+ * @param params defined in ASTNode as VariableDeclaration.visibility, FunctionDefinition.visibility or FunctionTypeName.visibility
+ * @return visibility `Visibility` enum used by the `visibility` property on UML `Attribute` or `Operator`
+ */
 function parseVisibility(visibility) {
     switch (visibility) {
         case 'default':
@@ -547,6 +592,12 @@ function parseVisibility(visibility) {
             throw Error(`Invalid visibility ${visibility}. Was not public, external, internal or private`);
     }
 }
+/**
+ * Recursively converts contract variables to UMLClass attribute types.
+ * Types can be standard Solidity types, arrays, mappings or user defined types like structs and enums.
+ * @param typeName defined in ASTNode as `TypeName`
+ * @return attributeTypes array of type string and `AttributeType`
+ */
 function parseTypeName(typeName) {
     switch (typeName.type) {
         case 'ElementaryTypeName':
@@ -582,6 +633,11 @@ function parseTypeName(typeName) {
             throw Error(`Invalid typeName ${typeName}`);
     }
 }
+/**
+ * Converts the contract params to `Operator` properties `parameters` or `returnParameters`
+ * @param params defined in ASTNode as `VariableDeclaration`
+ * @return parameters or `returnParameters` of the `Operator` of type `Parameter`
+ */
 function parseParameters(params) {
     if (!params || !params) {
         return [];
@@ -596,6 +652,11 @@ function parseParameters(params) {
     }
     return parameters;
 }
+/**
+ * Converts the contract `kind` to `UMLClass` stereotype
+ * @param kind defined in ASTNode as ContractDefinition.kind
+ * @return stereotype of the `UMLClass` with type `ClassStereotype
+ */
 function parseContractKind(kind) {
     switch (kind) {
         case 'contract':
@@ -610,7 +671,4 @@ function parseContractKind(kind) {
             throw Error(`Invalid kind ${kind}`);
     }
 }
-function parsePayable(stateMutability) {
-    return stateMutability === 'payable';
-}
 //# sourceMappingURL=converterAST2Classes.js.map

package/lib/converterClasses2Dot.d.ts

@@ -1,4 +1,12 @@
 import { ClassOptions } from './converterClass2Dot';
 import { UmlClass } from './umlClass';
+/**
+ * Converts UML classes to Graphviz's DOT format.
+ * The DOT grammar defines Graphviz nodes, edges, graphs, subgraphs, and clusters http://www.graphviz.org/doc/info/lang.html
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param clusterFolders flag if UML classes are to be clustered into folders their source code was in
+ * @param classOptions command line options for the `class` command
+ * @return dotString Graphviz's DOT format for defining nodes, edges and clusters.
+ */
 export declare function convertUmlClasses2Dot(umlClasses: UmlClass[], clusterFolders?: boolean, classOptions?: ClassOptions): string;
 export declare function addAssociationsToDot(umlClasses: UmlClass[], classOptions?: ClassOptions): string;

package/lib/converterClasses2Dot.js

@@ -6,6 +6,14 @@ const converterClass2Dot_1 = require("./converterClass2Dot");
 const umlClass_1 = require("./umlClass");
 const associations_1 = require("./associations");
 const debug = require('debug')('sol2uml');
+/**
+ * Converts UML classes to Graphviz's DOT format.
+ * The DOT grammar defines Graphviz nodes, edges, graphs, subgraphs, and clusters http://www.graphviz.org/doc/info/lang.html
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param clusterFolders flag if UML classes are to be clustered into folders their source code was in
+ * @param classOptions command line options for the `class` command
+ * @return dotString Graphviz's DOT format for defining nodes, edges and clusters.
+ */
 function convertUmlClasses2Dot(umlClasses, clusterFolders = false, classOptions = {}) {
     let dotString = `
 digraph UmlClassDiagram {

package/lib/diff.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compares code using Google's diff_match_patch and displays the results in the console.
+ * @param codeA
+ * @param codeB
+ * @param lineBuff the number of lines to display before and after each change.
+ */
+export declare const diffCode: (codeA: string, codeB: string, lineBuff: number) => void;

package/lib/diff.js

@@ -0,0 +1,188 @@
+"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.diffCode = void 0;
+const diff_match_patch_1 = __importStar(require("diff-match-patch"));
+const clc = require('cli-color');
+const SkippedLinesMarker = `\n---`;
+/**
+ * Compares code using Google's diff_match_patch and displays the results in the console.
+ * @param codeA
+ * @param codeB
+ * @param lineBuff the number of lines to display before and after each change.
+ */
+const diffCode = (codeA, codeB, lineBuff) => {
+    // @ts-ignore
+    const dmp = new diff_match_patch_1.default();
+    const diff = dmp.diff_main(codeA, codeB);
+    dmp.diff_cleanupSemantic(diff);
+    const linesB = countLines(codeB) + 1;
+    diff_pretty(diff, linesB, lineBuff);
+};
+exports.diffCode = diffCode;
+/**
+ * Convert a diff array into human readable for the console
+ * @param {!Array.<!diff_match_patch.Diff>} diffs Array of diff tuples.
+ * @param lines number of a lines in the second contract B
+ * @param lineBuff number of a lines to output before and after the change
+ */
+const diff_pretty = (diffs, lines, lineBuff = 2) => {
+    const linePad = lines.toString().length;
+    let output = '';
+    let diffIndex = 0;
+    let lineCount = 1;
+    const firstLineNumber = '1'.padStart(linePad) + ' ';
+    for (const diff of diffs) {
+        diffIndex++;
+        const initialLineNumber = diffIndex <= 1 ? firstLineNumber : '';
+        const op = diff[0]; // Operation (insert, delete, equal)
+        const text = diff[1]; // Text of change.
+        switch (op) {
+            case diff_match_patch_1.DIFF_INSERT:
+                // If first diff then we need to add the first line number
+                const linesInserted = addLineNumbers(text, lineCount, linePad);
+                output += initialLineNumber + clc.green(linesInserted);
+                lineCount += countLines(text);
+                break;
+            case diff_match_patch_1.DIFF_DELETE:
+                // zero start line means blank line numbers are used
+                const linesDeleted = addLineNumbers(text, 0, linePad);
+                output += initialLineNumber + clc.red(linesDeleted);
+                break;
+            case diff_match_patch_1.DIFF_EQUAL:
+                const eolPositions = findEOLPositions(text);
+                // If no changes yet
+                if (diffIndex <= 1) {
+                    output += lastLines(text, eolPositions, lineBuff, linePad);
+                }
+                // if no more changes
+                else if (diffIndex === diffs.length) {
+                    output += firstLines(text, eolPositions, lineBuff, lineCount, linePad);
+                }
+                else {
+                    // else the first n lines and last n lines
+                    output += firstAndLastLines(text, eolPositions, lineBuff, lineCount, linePad);
+                }
+                lineCount += eolPositions.length;
+                break;
+        }
+    }
+    output += '\n';
+    console.log(output);
+};
+/**
+ * Used when there is no more changes left
+ */
+const firstLines = (text, eolPositions, lineBuff, lineStart, linePad) => {
+    const lines = text.slice(0, eolPositions[lineBuff]);
+    return addLineNumbers(lines, lineStart, linePad);
+};
+/**
+ * Used before the first change
+ */
+const lastLines = (text, eolPositions, lineBuff, linePad) => {
+    const eolFrom = eolPositions.length - (lineBuff + 1);
+    let lines = text;
+    let lineCount = 1;
+    if (eolFrom >= 0) {
+        lines = eolFrom >= 0 ? text.slice(eolPositions[eolFrom] + 1) : text;
+        lineCount = eolFrom + 2;
+    }
+    const firstLineNumber = lineCount.toString().padStart(linePad) + ' ';
+    return firstLineNumber + addLineNumbers(lines, lineCount, linePad);
+};
+/**
+ * Used between changes to show the lines after the last change and before the next change.
+ * @param text
+ * @param eolPositions
+ * @param lineBuff
+ * @param lineStart
+ * @param linePad
+ */
+const firstAndLastLines = (text, eolPositions, lineBuff, lineStart, linePad) => {
+    if (eolPositions.length <= 2 * lineBuff) {
+        return addLineNumbers(text, lineStart, linePad);
+    }
+    const endFirstLines = eolPositions[lineBuff];
+    const eolFrom = eolPositions.length - (lineBuff + 1);
+    const startLastLines = eolPositions[eolFrom];
+    if (startLastLines <= endFirstLines) {
+        return addLineNumbers(text, lineStart, linePad);
+    }
+    // Lines after the previous change
+    let lines = text.slice(0, endFirstLines);
+    let output = addLineNumbers(lines, lineStart, linePad);
+    output += SkippedLinesMarker;
+    // Lines before the next change
+    lines = text.slice(startLastLines);
+    const lineCount = lineStart + eolFrom;
+    output += addLineNumbers(lines, lineCount, linePad);
+    return output;
+};
+/**
+ * Gets the positions of the end of lines in the string
+ * @param text
+ */
+const findEOLPositions = (text) => {
+    const eolPositions = [];
+    text.split('').forEach((c, i) => {
+        if (c === '\n') {
+            eolPositions.push(i);
+        }
+    });
+    return eolPositions;
+};
+/**
+ * Counts the number of carriage returns in a string
+ * @param text
+ */
+const countLines = (text) => (text.match(/\n/g) || '').length;
+/**
+ * Adds left padded line numbers to each line.
+ * @param text with the lines of code
+ * @param lineStart the line number of the first line in the text. If zero, then no lines numbers are added.
+ * @param linePad the width of the largest number which may not be in the text
+ */
+const addLineNumbers = (text, lineStart, linePad) => {
+    let lineCount = lineStart;
+    let textWithLineNumbers = '';
+    text.split('').forEach((c, i) => {
+        if (c === '\n') {
+            if (lineStart > 0) {
+                textWithLineNumbers += `\n${(++lineCount)
+                    .toString()
+                    .padStart(linePad)} `;
+            }
+            else {
+                textWithLineNumbers += `\n${' '.repeat(linePad)} `;
+            }
+        }
+        else {
+            textWithLineNumbers += c;
+        }
+    });
+    return textWithLineNumbers;
+};
+//# sourceMappingURL=diff.js.map

package/lib/filterClasses.d.ts

@@ -1,8 +1,31 @@
 import { WeightedDiGraph } from 'js-graph-algorithms';
 import { UmlClass } from './umlClass';
 import { ClassOptions } from './converterClass2Dot';
+/**
+ * Filter out any UML Class types that are to be hidden.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param options sol2uml class options
+ * @return umlClasses filtered list of UML classes of type `UMLClass`
+ */
 export declare const filterHiddenClasses: (umlClasses: UmlClass[], options: ClassOptions) => UmlClass[];
+/**
+ * Finds all the UML classes that have an association with a list of base contract names.
+ * The associated classes can be contracts, abstract contracts, interfaces, libraries, enums, structs or constants.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param baseContractNames array of base contract names
+ * @param depth limit the number of associations from the base contract.
+ * @return filteredUmlClasses list of UML classes of type `UMLClass`
+ */
 export declare const classesConnectedToBaseContracts: (umlClasses: UmlClass[], baseContractNames: string[], depth?: number) => UmlClass[];
+/**
+ * Finds all the UML classes that have an association with a base contract name.
+ * The associated classes can be contracts, abstract contracts, interfaces, libraries, enums, structs or constants.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param baseContractName base contract name
+ * @param weightedDirectedGraph graph of type WeightedDiGraph from the `js-graph-algorithms` package
+ * @param depth limit the number of associations from the base contract.
+ * @return filteredUmlClasses list of UML classes of type `UMLClass`
+ */
 export declare const classesConnectedToBaseContract: (umlClasses: UmlClass[], baseContractName: string, weightedDirectedGraph: WeightedDiGraph, depth?: number) => {
     [contractName: string]: UmlClass;
 };

package/lib/filterClasses.js

@@ -4,6 +4,12 @@ exports.topologicalSortClasses = exports.classesConnectedToBaseContract = export
 const js_graph_algorithms_1 = require("js-graph-algorithms");
 const umlClass_1 = require("./umlClass");
 const associations_1 = require("./associations");
+/**
+ * Filter out any UML Class types that are to be hidden.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param options sol2uml class options
+ * @return umlClasses filtered list of UML classes of type `UMLClass`
+ */
 const filterHiddenClasses = (umlClasses, options) => {
     return umlClasses.filter((u) => (u.stereotype === umlClass_1.ClassStereotype.Enum && !options.hideEnums) ||
         (u.stereotype === umlClass_1.ClassStereotype.Struct && !options.hideStructs) ||
@@ -19,6 +25,14 @@ const filterHiddenClasses = (umlClasses, options) => {
         u.stereotype === umlClass_1.ClassStereotype.Contract);
 };
 exports.filterHiddenClasses = filterHiddenClasses;
+/**
+ * Finds all the UML classes that have an association with a list of base contract names.
+ * The associated classes can be contracts, abstract contracts, interfaces, libraries, enums, structs or constants.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param baseContractNames array of base contract names
+ * @param depth limit the number of associations from the base contract.
+ * @return filteredUmlClasses list of UML classes of type `UMLClass`
+ */
 const classesConnectedToBaseContracts = (umlClasses, baseContractNames, depth) => {
     let filteredUmlClasses = {};
     const weightedDirectedGraph = loadWeightedDirectedGraph(umlClasses);
@@ -31,6 +45,15 @@ const classesConnectedToBaseContracts = (umlClasses, baseContractNames, depth) =
     return Object.values(filteredUmlClasses);
 };
 exports.classesConnectedToBaseContracts = classesConnectedToBaseContracts;
+/**
+ * Finds all the UML classes that have an association with a base contract name.
+ * The associated classes can be contracts, abstract contracts, interfaces, libraries, enums, structs or constants.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param baseContractName base contract name
+ * @param weightedDirectedGraph graph of type WeightedDiGraph from the `js-graph-algorithms` package
+ * @param depth limit the number of associations from the base contract.
+ * @return filteredUmlClasses list of UML classes of type `UMLClass`
+ */
 const classesConnectedToBaseContract = (umlClasses, baseContractName, weightedDirectedGraph, depth = 1000) => {
     // Find the base UML Class from the base contract name
     const baseUmlClass = umlClasses.find(({ name }) => {
@@ -76,11 +99,12 @@ const topologicalSortClasses = (umlClasses) => {
     const sortedUmlClasses = sortedUmlClassIds.map((umlClassId) => 
     // Lookup the UmlClass for each class id
     umlClasses.find((umlClass) => umlClass.id === umlClassId));
-    return sortedUmlClasses;
+    // Filter out any unfound classes. This happens when diff sources the second contract.
+    return sortedUmlClasses.filter((umlClass) => umlClass !== undefined);
 };
 exports.topologicalSortClasses = topologicalSortClasses;
 const loadDirectedAcyclicGraph = (umlClasses) => {
-    const directedAcyclicGraph = new js_graph_algorithms_1.DiGraph(umlClasses.length); // the number vertices in the graph
+    const directedAcyclicGraph = new js_graph_algorithms_1.DiGraph(umlClass_1.UmlClass.idCounter); // 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

package/lib/parserEtherscan.d.ts

@@ -1,7 +1,7 @@
 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", "gnosisscan"];
-declare type Network = typeof networks[number];
+export type Network = typeof networks[number];
 export declare class EtherscanParser {
     protected apikey: string;
     network: Network;
@@ -45,4 +45,3 @@ export declare class EtherscanParser {
         compilerVersion: string;
     }>;
 }
-export {};

package/lib/parserEtherscan.js

@@ -147,7 +147,9 @@ class EtherscanParser {
         // 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);
-        debug(`Failed to find dependencies to files: ${nonDependentFilenames}`);
+        if (nonDependentFilenames.length) {
+            debug(`Failed to find dependencies to files: ${nonDependentFilenames}`);
+        }
         const solidityVersion = (0, regEx_1.parseSolidityVersion)(compilerVersion);
         let solidityCode = `pragma solidity =${solidityVersion};\n`;
         // output non dependent code before the dependent files just in case sol2uml missed some dependencies

package/lib/parserGeneral.d.ts

@@ -1,5 +1,17 @@
+import { Network } from './parserEtherscan';
 import { UmlClass } from './umlClass';
-export declare const parserUmlClasses: (fileFolderAddress: string, options: any) => Promise<{
+export interface ParserOptions {
+    apiKey?: string;
+    network?: Network;
+    subfolders?: string;
+    ignoreFilesOrFolders?: string;
+}
+/**
+ * Parses Solidity source code from a local filesystem or verified code on Etherscan
+ * @param fileFolderAddress filename, folder name or contract address
+ * @param options of type `ParserOptions`
+ */
+export declare const parserUmlClasses: (fileFolderAddress: string, options: ParserOptions) => Promise<{
     umlClasses: UmlClass[];
     contractName?: string;
 }>;

package/lib/parserGeneral.js

@@ -5,6 +5,11 @@ const parserEtherscan_1 = require("./parserEtherscan");
 const parserFiles_1 = require("./parserFiles");
 const regEx_1 = require("./utils/regEx");
 const debug = require('debug')('sol2uml');
+/**
+ * Parses Solidity source code from a local filesystem or verified code on Etherscan
+ * @param fileFolderAddress filename, folder name or contract address
+ * @param options of type `ParserOptions`
+ */
 const parserUmlClasses = async (fileFolderAddress, options) => {
     let result = {
         umlClasses: [],

package/lib/sol2uml.js

@@ -12,6 +12,8 @@ const regEx_1 = require("./utils/regEx");
 const writerFiles_1 = require("./writerFiles");
 const path_1 = require("path");
 const squashClasses_1 = require("./squashClasses");
+const diff_1 = require("./diff");
+const clc = require('cli-color');
 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
@@ -25,7 +27,8 @@ program
 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:  Merges verified source files from a Blockchain explorer into one local file.
+* flatten:  Merges verified Solidity files from a Blockchain explorer into one local file.
+* diff:     Compares the flattened Solidity code from a Blockchain explorer for two contracts.
 
 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'))
@@ -43,7 +46,7 @@ The Solidity code can be pulled from verified source code on Blockchain explorer
 program
     .command('class', { isDefault: true })
     .description('Generates a UML class diagram from Solidity source code.')
-    .usage(`<fileFolderAddress> [options]
+    .usage(`sol2uml [options] <fileFolderAddress>
 
 Generates UML diagrams from Solidity source code.
 
@@ -78,6 +81,7 @@ If an Ethereum address with a 0x prefix is passed, the verified source code from
             ...command.parent._optionValues,
             ...options,
         };
+        // Parse Solidity code from local file system or verified source code on Etherscan.
         let { umlClasses, contractName } = await (0, parserGeneral_1.parserUmlClasses)(fileFolderAddress, combinedOptions);
         if (options.squash &&
             // Must specify base contract(s) or parse from Etherscan to get contractName
@@ -96,7 +100,9 @@ If an Ethereum address with a 0x prefix is passed, the verified source code from
         if (options.squash) {
             filteredUmlClasses = (0, squashClasses_1.squashUmlClasses)(filteredUmlClasses, baseContractNames || [contractName]);
         }
+        // Convert UML classes to Graphviz dot format.
         const dotString = (0, converterClasses2Dot_1.convertUmlClasses2Dot)(filteredUmlClasses, combinedOptions.clusterFolders, combinedOptions);
+        // Convert Graphviz dot format to file formats. eg svg or png
         await (0, writerFiles_1.writeOutputFiles)(dotString, fileFolderAddress, contractName || 'classDiagram', combinedOptions.outputFormat, combinedOptions.outputFileName);
         debug(`Finished generating UML`);
     }
@@ -108,7 +114,7 @@ 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.")
-    .usage(`<fileFolderAddress> [options]
+    .usage(`[options] <fileFolderAddress>
 
 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')
@@ -167,7 +173,7 @@ WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A k
 program
     .command('flatten')
     .description('Merges verified source files for a contract from a Blockchain explorer into one local file.')
-    .usage(`<contractAddress> [options]
+    .usage(`<contractAddress>
 
 In order for the merged code to compile, the following is done:
 1. pragma solidity is set using the compiler of the verified contract.
@@ -194,6 +200,48 @@ In order for the merged code to compile, the following is done:
         process.exit(2);
     }
 });
+program
+    .command('diff')
+    .description('Compare verified Solidity code differences between two contracts.')
+    .usage(`[options] <addressA> <addressB>
+
+The results show the comparision of contract A to B.
+The ${clc.green('green')} sections are additions to contract B that are not in contract A.
+The ${clc.red('red')} sections are removals from contract A that are not in contract B.
+The line numbers are from contract B. There are no line numbers for the red sections as they are not in contract B.`)
+    .argument('<addressA>', 'Contract address in hexadecimal format with a 0x prefix.')
+    .argument('<addressB>', 'Contract address in hexadecimal format with a 0x prefix.')
+    .addOption(new commander_1.Option('-l, --lineBuffer <value>', 'Minimum number a lines before and after changes').default('4'))
+    .option('-s, --saveFiles', 'Save the flattened contract code to the filesystem. The file names will be the contract address with a .sol extension.', false)
+    .action(async (addressA, addressB, options, command) => {
+    try {
+        debug(`About to diff ${addressA} and ${addressB}`);
+        const combinedOptions = {
+            ...command.parent._optionValues,
+            ...options,
+        };
+        // Diff solidity code
+        const lineBuffer = parseInt(options.lineBuffer);
+        if (isNaN(lineBuffer))
+            throw Error(`Invalid line buffer "${options.lineBuffer}". Must be a number`);
+        const etherscanParser = new parserEtherscan_1.EtherscanParser(combinedOptions.apiKey, combinedOptions.network);
+        // Get verified Solidity code from Etherscan and flatten
+        const { solidityCode: codeA, contractName: contractNameA } = await etherscanParser.getSolidityCode(addressA);
+        const { solidityCode: codeB, contractName: contractNameB } = await etherscanParser.getSolidityCode(addressB);
+        console.log(`Difference between`);
+        console.log(`A. ${addressA} ${contractNameA} on ${combinedOptions.network}`);
+        console.log(`B. ${addressB} ${contractNameB} on ${combinedOptions.network}\n`);
+        (0, diff_1.diffCode)(codeA, codeB, lineBuffer);
+        if (options.saveFiles) {
+            await (0, writerFiles_1.writeSolidity)(codeA, addressA);
+            await (0, writerFiles_1.writeSolidity)(codeB, addressB);
+        }
+    }
+    catch (err) {
+        console.error(err);
+        process.exit(2);
+    }
+});
 program.on('option:verbose', () => {
     debugControl.enable('sol2uml,axios');
     debug('verbose on');

package/lib/squashClasses.d.ts

@@ -1,2 +1,8 @@
 import { UmlClass } from './umlClass';
-export declare const squashUmlClasses: (umlClasses: UmlClass[], squashContractNames: string[]) => UmlClass[];
+/**
+ * Flattens the inheritance hierarchy for each base contract.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param baseContractNames array of contract names to be rendered in squashed format.
+ * @return squashUmlClasses array of UML classes of type `UMLClass`
+ */
+export declare const squashUmlClasses: (umlClasses: UmlClass[], baseContractNames: string[]) => UmlClass[];

package/lib/squashClasses.js

@@ -27,15 +27,21 @@ exports.squashUmlClasses = void 0;
 const umlClass_1 = require("./umlClass");
 const crypto = __importStar(require("crypto"));
 const debug = require('debug')('sol2uml');
-const squashUmlClasses = (umlClasses, squashContractNames) => {
+/**
+ * Flattens the inheritance hierarchy for each base contract.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param baseContractNames array of contract names to be rendered in squashed format.
+ * @return squashUmlClasses array of UML classes of type `UMLClass`
+ */
+const squashUmlClasses = (umlClasses, baseContractNames) => {
     let removedClassIds = [];
-    for (const squashContractName of squashContractNames) {
+    for (const baseContractName of baseContractNames) {
         // Find the base UML Class to squash
         let baseIndex = umlClasses.findIndex(({ name }) => {
-            return name === squashContractName;
+            return name === baseContractName;
         });
         if (baseIndex === undefined) {
-            throw Error(`Failed to find contract with name "${squashContractName}" to squash`);
+            throw Error(`Failed to find contract with name "${baseContractName}" to squash`);
         }
         const baseClass = umlClasses[baseIndex];
         let squashedClass = new umlClass_1.UmlClass({
@@ -55,7 +61,7 @@ const squashUmlClasses = (umlClasses, squashContractNames) => {
     // remove any squashed inherited contracts
     !removedClassIds.includes(u.id) ||
         // Include all base contracts
-        squashContractNames.includes(u.name));
+        baseContractNames.includes(u.name));
 };
 exports.squashUmlClasses = squashUmlClasses;
 const recursiveSquash = (squashedClass, inheritedContractNames, baseClass, umlClasses, startPosition) => {

package/lib/umlClass.d.ts

@@ -54,7 +54,7 @@ export interface Operator extends Attribute {
     stereotype?: OperatorStereotype;
     parameters?: Parameter[];
     returnParameters?: Parameter[];
-    isPayable?: boolean;
+    stateMutability?: string;
     modifiers?: string[];
     hash?: string;
     inheritancePosition?: number;

package/lib/utils/diff.js

@@ -0,0 +1 @@
+//# sourceMappingURL=diff.js.map

package/lib/writerFiles.d.ts

@@ -1,4 +1,4 @@
-export declare type OutputFormats = 'svg' | 'png' | 'dot' | 'all';
+export type OutputFormats = 'svg' | 'png' | 'dot' | 'all';
 export declare const writeOutputFiles: (dot: string, fileFolderAddress: string, contractName: string, outputFormat?: OutputFormats, outputFilename?: string) => Promise<void>;
 export declare function convertDot2Svg(dot: string): any;
 export declare function writeSolidity(code: string, filename?: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sol2uml",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Solidity contract visualisation tool.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -20,25 +20,28 @@
   "license": "MIT",
   "dependencies": {
     "@aduh95/viz.js": "^3.7.0",
-    "@solidity-parser/parser": "^0.14.3",
-    "axios": "^0.27.2",
-    "axios-debug-log": "^0.8.4",
+    "@solidity-parser/parser": "^0.14.5",
+    "axios": "^1.2.1",
+    "axios-debug-log": "^1.0.0",
+    "cli-color": "^2.0.3",
     "commander": "^9.4.1",
     "convert-svg-to-png": "^0.6.4",
     "debug": "^4.3.4",
-    "ethers": "^5.7.1",
+    "diff-match-patch": "^1.0.5",
+    "ethers": "^5.7.2",
     "js-graph-algorithms": "^1.0.18",
     "klaw": "^4.0.1"
   },
   "devDependencies": {
-    "@openzeppelin/contracts": "4.7.3",
-    "@types/jest": "^29.1.1",
+    "@openzeppelin/contracts": "4.8.0",
+    "@types/diff-match-patch": "^1.0.32",
+    "@types/jest": "^29.2.4",
     "@types/klaw": "^3.0.3",
-    "jest": "^29.1.2",
-    "prettier": "^2.7.1",
+    "jest": "^29.3.1",
+    "prettier": "^2.8.1",
     "ts-jest": "^29.0.3",
     "ts-node": "^10.9.1",
-    "typescript": "^4.8.4"
+    "typescript": "^4.9.4"
   },
   "files": [
     "lib/*.js",