sol2uml 2.3.1 → 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/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.js

@@ -99,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.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/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.
 
@@ -111,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')
@@ -170,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.
@@ -197,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/utils/diff.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sol2uml",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Solidity contract visualisation tool.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -23,15 +23,18 @@
     "@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",
+    "diff-match-patch": "^1.0.5",
     "ethers": "^5.7.2",
     "js-graph-algorithms": "^1.0.18",
     "klaw": "^4.0.1"
   },
   "devDependencies": {
     "@openzeppelin/contracts": "4.8.0",
+    "@types/diff-match-patch": "^1.0.32",
     "@types/jest": "^29.2.4",
     "@types/klaw": "^3.0.3",
     "jest": "^29.3.1",