Include disableFetchExternal flag to avoid debugging with fetching external sources (#255)

* feat: add `disableFetchExternal` debugger flag

* docs: improve description and comments

* refactor: remove unnecessary casts

* refactor: remove unnecessary constants & module

* refactor: refine `const`s scope

* refactor: refine more `const`s scope

* refactor: continue to merge def and usages

* docs: improve note formatting

* refactor: refine function scope

* refactor: remove unused `export`

* refactor: simplify tests

Author: acuarica

package.json

@@ -567,7 +567,11 @@
         "runtime": "node",
         "configurationAttributes": {
           "launch": {
-            "required": [],
+            "required": [
+              "txHash",
+              "workingDirectory",
+              "providerUrl"
+            ],
             "properties": {
               "stopOnEntry": {
                 "type": "boolean",
@@ -581,23 +585,28 @@
               },
               "txHash": {
                 "type": "string",
-                "description": "Transaction hash to debug",
+                "description": "The transaction hash to debug.",
                 "default": "0x"
               },
               "files": {
                 "type": "string[]",
-                "description": "Array of file paths of solidity files to debug",
+                "description": "Array of file paths of solidity files to debug.",
                 "default": []
               },
               "workingDirectory": {
                 "type": "string",
-                "description": "Directory of truffle project",
+                "description": "Directory of the Truffle project where to find the Truffle config file.",
                 "default": "${workspaceFolder}"
               },
               "providerUrl": {
                 "type": "string",
-                "description": "URL of provider",
+                "description": "Provider's URL of the Ethereum network to connect to.",
                 "default": "http://127.0.0.1:8545"
+              },
+              "disableFetchExternal": {
+                "type": "boolean",
+                "description": "When set, do not try to fetch external contract sources when debugging a forked network instance. When the network is not being forked, this flag is ignored.",
+                "default": false
               }
             }
           }
@@ -611,7 +620,8 @@
             "txHash": "0x",
             "files": [],
             "workingDirectory": "${workspaceFolder}",
-            "providerUrl": "http://127.0.0.1:8545"
+            "providerUrl": "http://127.0.0.1:8545",
+            "disableFetchExternal": false
           }
         ],
         "configurationSnippets": [
@@ -625,8 +635,9 @@
               "stopOnEntry": false,
               "txHash": "0x",
               "files": [],
-              "workingDirectory": "^\"\\${workspaceFolder}/",
-              "providerUrl": "http://127.0.0.1:8545"
+              "workingDirectory": "^\"\\${workspaceFolder}\"",
+              "providerUrl": "http://127.0.0.1:8545",
+              "disableFetchExternal": false
             }
           }
         ],

src/commands/DebuggerCommands.ts

@@ -6,12 +6,12 @@ import {debug, DebugConfiguration, QuickPickItem, Uri, QuickPickItemKind, worksp
 
 import {DEBUG_TYPE} from '@/debugAdapter/constants/debugAdapter';
 import {DebugNetwork} from '@/debugAdapter/debugNetwork';
-import {shortenHash} from '@/debugAdapter/functions';
 import {TransactionProvider} from '@/debugAdapter/transaction/transactionProvider';
 import {Web3Wrapper} from '@/debugAdapter/web3Wrapper';
 import {getTruffleWorkspace, getPathByPlatform} from '@/helpers/workspace';
 import {showInputBox, showQuickPick} from '@/helpers/userInteraction';
 import {Telemetry} from '@/TelemetryClient';
+import {DebuggerTypes} from '@/debugAdapter/models/debuggerTypes';
 
 const TX_REGEX = /^(?:0x)?[0-9a-fA-F]{64}$/;
 
@@ -68,7 +68,7 @@ export namespace DebuggerCommands {
       txHash = txHashSelection.detail || txHashSelection.label;
     }
 
-    await startDebugging(txHash, workingDirectory, providerUrl);
+    await startDebugging({txHash, workingDirectory, providerUrl, disableFetchExternal: false});
   }
 }
 
@@ -85,30 +85,23 @@ async function getQuickPickItems(txProvider: TransactionProvider) {
 }
 
 /**
- * This functions is responsible for starting the solidity debugger with the given parameters.
- *
- * @param txHash A transaction hash.
- * @param workingDirectory The working directory of the project.
- * @param providerUrl The network provider url.
- * @param fetchExternal Indicates if the debugger should fetch external contracts.
+ * Responsible for starting the Solidity debugger with the given arguments.
+ * 
+   @param args The `DebugArgs` to initialize the `DebugSession`.
  */
-export async function startDebugging(
-  txHash: string,
-  workingDirectory: string,
-  providerUrl: string,
-  fetchExternal?: boolean
-): Promise<void> {
-  const workspaceFolder = workspace.getWorkspaceFolder(Uri.parse(workingDirectory));
-  const config: DebugConfiguration = {
-    files: [],
+export async function startDebugging(args: DebuggerTypes.DebugArgs): Promise<void> {
+  const workspaceFolder =
+    args.workingDirectory === undefined ? undefined : workspace.getWorkspaceFolder(Uri.parse(args.workingDirectory));
+  const config: DebugConfiguration & DebuggerTypes.ILaunchRequestArguments = {
+    type: DEBUG_TYPE,
     name: 'Debug Transactions',
-    providerUrl,
     request: 'launch',
-    txHash,
-    type: DEBUG_TYPE,
-    workingDirectory,
+
+    // TODO: are these `timeout` and `files` properties used?
     timeout: 30000,
-    fetchExternal,
+    files: [],
+
+    ...args,
   };
 
   debug.startDebugging(workspaceFolder, config).then(() => {
@@ -121,3 +114,22 @@ function generateDescription(contractName?: string, methodName?: string) {
   const contractNameWithoutExt = path.basename(contractName || '', '.json');
   return `${contractNameWithoutExt}.${methodName}()`;
 }
+
+/**
+ * Shorten the checksummed version of the input `hash` to have `0x + chars ... chars` characters.
+ * It assumes that `hash` starts with the prefix `0x`.
+ *
+ * > **NOTE**. _This is only `export`ed to be used in tests._
+ *
+ * @param hash the hash to shorten.
+ * @param chars the desired length to append both at the start and at the end.
+ * @returns the shortened `hash`.
+ */
+export function shortenHash(hash: string, chars = 4): string {
+  try {
+    const parsed = hash;
+    return `${parsed.substring(0, chars + 2)}...${parsed.substring(parsed.length - chars)}`;
+  } catch (error) {
+    throw Error(`Invalid 'address' parameter '${hash}'.`);
+  }
+}

src/debugAdapter/constants/contractJson.ts

@@ -3,15 +3,14 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import {CONTRACT_JSON_ENCODING} from '../constants/contractJson';
 import {IContractJsonModel} from '../models/IContractJsonModel';
 
 export class ContractJsonsProvider {
   private contractBuildDirectory: string;
   private contractJsonEncoding: string;
   private _cachedContractJsons: {[fileName: string]: IContractJsonModel} | undefined;
 
-  constructor(contractBuildDirectory: string, contractJsonEncoding = CONTRACT_JSON_ENCODING) {
+  constructor(contractBuildDirectory: string, contractJsonEncoding = 'utf-8') {
     this.contractBuildDirectory = contractBuildDirectory;
     this.contractJsonEncoding = contractJsonEncoding;
   }

src/debugAdapter/constants/transaction.ts

@@ -3,7 +3,6 @@
 
 import path from 'path';
 import {IConfiguration, INetwork, INetworkOption} from '@/helpers/ConfigurationReader';
-import {TRUFFLE_CONFIG_NAME} from './constants/truffleConfig';
 import {TreeManager} from '@/services/tree/TreeManager';
 import {ItemType} from '@/Models/ItemType';
 import {Constants} from '@/Constants';
@@ -14,6 +13,11 @@ import {LocalProject} from '@/Models/TreeItems/LocalProject';
 import {LocalNetworkNode} from '@/Models/TreeItems';
 import {ConfigurationReader} from '../helpers/debugConfigurationReader';
 
+/**
+ * TODO: We should removed this hardcoded name since there might be multiple Truffle config files in the same workspace.
+ */
+const TRUFFLE_CONFIG_NAME = 'truffle-config.js';
+
 export class DebugNetwork {
   public workingDirectory: string;
   private _basedConfig: ConfigurationReader.TruffleConfig | undefined;

src/debugAdapter/constants/truffleConfig.ts

@@ -101,18 +101,33 @@ export class SolidityDebugSession extends LoggingDebugSession {
     args: DebuggerTypes.ILaunchRequestArguments
   ): Promise<void> {
     await this.sendErrorIfFailed(response, async () => {
+      validateRequiredArg(args.txHash, `txHash`);
+      validateRequiredArg(args.workingDirectory, `workingDirectory`);
+      validateRequiredArg(args.providerUrl, `providerUrl`);
+
+      if (args.disableFetchExternal === undefined) {
+        args.disableFetchExternal = false;
+      }
+
       // make sure to 'Stop' the buffered logging if 'trace' is not set
       // logger.setup enable logs in client
       logger.setup(args.noDebug ? Logger.LogLevel.Verbose : Logger.LogLevel.Stop, false);
 
       // start the program in the runtime
-      await this._runtime.attach(args.txHash, args.workingDirectory, args.providerUrl);
+      // This cast is only necessary because TypeScript does not narrow types in properties
+      await this._runtime.attach(<Required<DebuggerTypes.DebugArgs>>args);
       await this._runtime.processInitialBreakPoints();
 
       // Events order is important
       this.sendEvent(new DebuggerTypes.LaunchedEvent());
       this.sendEvent(new StoppedEvent(EVENT_REASONS.breakpoint, MAIN_THREAD.id));
     });
+
+    function validateRequiredArg(arg: string | undefined, name: string) {
+      if (!arg) {
+        throw new Error(`\`${name}\` must be specified to initiate the Truffle Debugger`);
+      }
+    }
   }
 
   protected async disconnectRequest(