Merge pull request #5541 from NomicFoundation/debug-logs

Basic debug logging

Author: zoeyTM

pnpm-lock.yaml

@@ -55,8 +55,8 @@
   "devDependencies": {
     "@eslint-community/eslint-plugin-eslint-comments": "^4.3.0",
     "@ignored/hardhat-vnext-node-test-reporter": "workspace:^3.0.0-next.2",
-    "@nomicfoundation/hardhat-test-utils": "workspace:^",
     "@microsoft/api-extractor": "^7.43.4",
+    "@nomicfoundation/hardhat-test-utils": "workspace:^",
     "@types/node": "^20.14.9",
     "@types/semver": "^7.5.8",
     "@typescript-eslint/eslint-plugin": "^7.7.1",

v-next/core/package.json

@@ -18,6 +18,7 @@
     "./common-errors": "./dist/src/common-errors.js",
     "./crypto": "./dist/src/crypto.js",
     "./date": "./dist/src/date.js",
+    "./debug": "./dist/src/debug.js",
     "./error": "./dist/src/error.js",
     "./eth": "./dist/src/eth.js",
     "./fs": "./dist/src/fs.js",
@@ -57,6 +58,7 @@
     "@eslint-community/eslint-plugin-eslint-comments": "^4.3.0",
     "@ignored/hardhat-vnext-node-test-reporter": "workspace:^3.0.0-next.2",
     "@types/bn.js": "^5.1.5",
+    "@types/debug": "^4.1.4",
     "@types/keccak": "^3.0.4",
     "@types/node": "^20.14.9",
     "@typescript-eslint/eslint-plugin": "^7.7.1",
@@ -74,6 +76,7 @@
     "typescript-eslint": "7.7.1"
   },
   "dependencies": {
+    "debug": "^4.1.1",
     "fast-equals": "^5.0.1",
     "keccak": "^3.0.4",
     "rfdc": "^1.3.1",

v-next/hardhat-utils/package.json

@@ -0,0 +1,38 @@
+import debugLib from "debug";
+
+/**
+ * A simple decorator that adds debug logging for when a method is entered and exited.
+ *
+ * This decorator is meant to be used for debugging purposes only. It should not be committed in runtime code.
+ *
+ * Example usage:
+ *
+ * ```
+ * class MyClass {
+ *   @withDebugLogs("MyClass:exampleClassMethod")
+ *   public function exampleClassMethod(...)
+ * }
+ * ```
+ */
+export function withDebugLogs<This, Args extends any[], Return>(
+  tag: string = "",
+) {
+  return function actualDecorator(
+    originalMethod: (this: This, ...args: Args) => Return,
+    _context: ClassMethodDecoratorContext<
+      This,
+      (this: This, ...args: Args) => Return
+    >,
+  ): (this: This, ...args: Args) => Return {
+    const log = debugLib(`hardhat:dev:core${tag === "" ? "" : `:${tag}`}`);
+
+    function replacementMethod(this: This, ...args: Args): Return {
+      log(`Entering method with args:`, args);
+      const result = originalMethod.call(this, ...args);
+      log(`Exiting method.`);
+      return result;
+    }
+
+    return replacementMethod;
+  };
+}

v-next/hardhat-utils/src/debug.ts

@@ -58,6 +58,7 @@
     "@eslint-community/eslint-plugin-eslint-comments": "^4.3.0",
     "@ignored/hardhat-vnext-node-test-reporter": "workspace:^3.0.0-next.2",
     "@nomicfoundation/hardhat-test-utils": "workspace:^",
+    "@types/debug": "^4.1.4",
     "@types/node": "^20.14.9",
     "@typescript-eslint/eslint-plugin": "^7.7.1",
     "@typescript-eslint/parser": "^7.7.1",
@@ -78,6 +79,7 @@
     "@ignored/hardhat-vnext-utils": "workspace:^3.0.0-next.2",
     "@ignored/hardhat-vnext-zod-utils": "workspace:^3.0.0-next.2",
     "chalk": "^5.3.0",
+    "debug": "^4.1.1",
     "enquirer": "^2.3.0",
     "tsx": "^4.11.0",
     "zod": "^3.23.8"

v-next/hardhat/package.json

@@ -28,6 +28,7 @@ import {
 import { isCi } from "@ignored/hardhat-vnext-utils/ci";
 import { getRealPath } from "@ignored/hardhat-vnext-utils/fs";
 import { kebabToCamelCase } from "@ignored/hardhat-vnext-utils/string";
+import debug from "debug";
 
 import { resolveHardhatConfigPath } from "../../config.js";
 import { createHardhatRuntimeEnvironment } from "../../hre.js";
@@ -47,8 +48,12 @@ export async function main(
   cliArguments: string[],
   print: (message: string) => void = console.log,
 ): Promise<void> {
+  const log = debug("hardhat:core:cli:main");
+
   let builtinGlobalOptions;
 
+  log("Hardhat CLI started");
+
   try {
     const usedCliArguments: boolean[] = new Array(cliArguments.length).fill(
       false,
@@ -59,6 +64,8 @@ export async function main(
       usedCliArguments,
     );
 
+    log("Parsed builtin global options");
+
     if (builtinGlobalOptions.version) {
       return await printVersionMessage(print);
     }
@@ -69,8 +76,12 @@ export async function main(
 
     await ensureTelemetryConsent();
 
+    log("Retrieved telemetry consent");
+
     if (builtinGlobalOptions.configPath === undefined) {
       builtinGlobalOptions.configPath = await resolveHardhatConfigPath();
+
+      log("Resolved config path");
     }
 
     const projectRoot = await resolveProjectRoot(
@@ -79,12 +90,16 @@ export async function main(
 
     const userConfig = await importUserConfig(builtinGlobalOptions.configPath);
 
+    log("User config imported");
+
     const configPlugins = Array.isArray(userConfig.plugins)
       ? userConfig.plugins
       : [];
     const plugins = [...builtinPlugins, ...configPlugins];
     const resolvedPlugins = await resolvePluginList(projectRoot, plugins);
 
+    log("Resolved plugins");
+
     const pluginGlobalOptionDefinitions =
       buildGlobalOptionDefinitions(resolvedPlugins);
     const globalOptionDefinitions = new Map([
@@ -97,6 +112,8 @@ export async function main(
       usedCliArguments,
     );
 
+    log("Creating Hardhat Runtime Environment");
+
     const hre = await createHardhatRuntimeEnvironment(
       userConfig,
       { ...builtinGlobalOptions, ...userProvidedGlobalOptions },
@@ -141,6 +158,8 @@ export async function main(
       task,
     );
 
+    log(`Running task "${task.id.join(" ")}"`);
+
     await task.run(taskArguments);
   } catch (error) {
     printErrorMessages(error, builtinGlobalOptions?.showStackTraces);