added basic debug logging

Author: zoeyTM

pnpm-lock.yaml

@@ -55,8 +55,9 @@
   "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/debug": "^4.1.4",
     "@types/node": "^20.14.9",
     "@types/semver": "^7.5.8",
     "@typescript-eslint/eslint-plugin": "^7.7.1",
@@ -79,6 +80,7 @@
     "@ignored/hardhat-vnext-errors": "workspace:^3.0.0-next.2",
     "@ignored/hardhat-vnext-utils": "workspace:^3.0.0-next.2",
     "chalk": "^5.3.0",
+    "debug": "^4.1.1",
     "env-paths": "^2.2.0",
     "semver": "^7.6.2"
   }

v-next/core/package.json

@@ -0,0 +1,36 @@
+import debugLib from "debug";
+
+/**
+ * A simple decorator that adds debug logging for when a method is entered and exited.
+ *
+ * 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: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/core/src/internal/debug.ts

@@ -17,6 +17,8 @@ import {
   assertHardhatInvariant,
 } from "@ignored/hardhat-vnext-errors";
 
+import { withDebugLogs } from "./debug.js";
+
 export class HookManagerImplementation implements HookManager {
   readonly #pluginsInReverseOrder: HardhatPlugin[];
 
@@ -99,6 +101,7 @@ export class HookManagerImplementation implements HookManager {
     );
   }
 
+  @withDebugLogs("HookManager:runHandlerChain")
   public async runHandlerChain<
     HookCategoryNameT extends keyof HardhatHooks,
     HookNameT extends keyof HardhatHooks[HookCategoryNameT],
@@ -137,6 +140,7 @@ export class HookManagerImplementation implements HookManager {
     return next(...handlerParams);
   }
 
+  @withDebugLogs("HookManager:runSequentialHandlers")
   public async runSequentialHandlers<
     HookCategoryNameT extends keyof HardhatHooks,
     HookNameT extends keyof HardhatHooks[HookCategoryNameT],
@@ -170,6 +174,7 @@ export class HookManagerImplementation implements HookManager {
     return result;
   }
 
+  @withDebugLogs("HookManager:runParallelHandlers")
   public async runParallelHandlers<
     HookCategoryNameT extends keyof HardhatHooks,
     HookNameT extends keyof HardhatHooks[HookCategoryNameT],

v-next/core/src/internal/hook-manager.ts

@@ -17,6 +17,7 @@ import type { UserInterruptionManager } from "../types/user-interruptions.js";
 import { HardhatError } from "@ignored/hardhat-vnext-errors";
 
 import { ResolvedConfigurationVariableImplementation } from "./configuration-variables.js";
+import { withDebugLogs } from "./debug.js";
 import {
   buildGlobalOptionDefinitions,
   resolveGlobalOptions,
@@ -29,6 +30,7 @@ import { UserInterruptionManagerImplementation } from "./user-interruptions.js";
 export class HardhatRuntimeEnvironmentImplementation
   implements HardhatRuntimeEnvironment
 {
+  @withDebugLogs("HardhatRuntimeEnvironment:create")
   public static async create(
     inputUserConfig: HardhatUserConfig,
     userProvidedGlobalOptions: Partial<GlobalOptions>,

v-next/core/src/internal/hre.ts

@@ -18,6 +18,7 @@ import {
 } from "@ignored/hardhat-vnext-errors";
 import { ensureError } from "@ignored/hardhat-vnext-utils/error";
 
+import { withDebugLogs } from "../debug.js";
 import { detectPluginNpmDependencyProblems } from "../plugins/detect-plugin-npm-dependency-problems.js";
 
 import { formatTaskId } from "./utils.js";
@@ -26,6 +27,7 @@ import { validateTaskArgumentValue } from "./validations.js";
 export class ResolvedTask implements Task {
   readonly #hre: HardhatRuntimeEnvironment;
 
+  @withDebugLogs("ResolvedTask:createEmptyTask")
   public static createEmptyTask(
     hre: HardhatRuntimeEnvironment,
     id: string[],
@@ -44,6 +46,7 @@ export class ResolvedTask implements Task {
     );
   }
 
+  @withDebugLogs("ResolvedTask:createNewTask")
   public static createNewTask(
     hre: HardhatRuntimeEnvironment,
     id: string[],
@@ -92,6 +95,7 @@ export class ResolvedTask implements Task {
    * @throws HardhatError if the task is empty, a required argument is missing,
    * a argument has an invalid type, or the file actions can't be resolved.
    */
+  @withDebugLogs("ResolvedTask:run")
   public async run(taskArguments: TaskArguments): Promise<any> {
     if (this.isEmpty) {
       throw new HardhatError(HardhatError.ERRORS.TASK_DEFINITIONS.EMPTY_TASK, {

v-next/core/src/internal/tasks/resolved-task.ts

@@ -15,6 +15,7 @@ import {
 } from "@ignored/hardhat-vnext-errors";
 
 import { TaskDefinitionType } from "../../types/tasks.js";
+import { withDebugLogs } from "../debug.js";
 
 import { ResolvedTask } from "./resolved-task.js";
 import { formatTaskId, getActorFragment } from "./utils.js";
@@ -62,6 +63,7 @@ export class TaskManagerImplementation implements TaskManager {
     return this.#rootTasks;
   }
 
+  @withDebugLogs("TaskManager:getTask")
   public getTask(taskId: string | string[]): Task {
     taskId = Array.isArray(taskId) ? taskId : [taskId];
     if (taskId.length === 0) {
@@ -99,6 +101,7 @@ export class TaskManagerImplementation implements TaskManager {
     return task;
   }
 
+  @withDebugLogs("TaskManager:insertTask")
   #insertTask(taskId: string[], task: Task, pluginId?: string) {
     if (taskId.length === 0) {
       throw new HardhatError(

v-next/core/src/internal/tasks/task-manager.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

@@ -26,6 +26,7 @@ import {
 } from "@ignored/hardhat-vnext-errors";
 import { isCi } from "@ignored/hardhat-vnext-utils/ci";
 import { kebabToCamelCase } from "@ignored/hardhat-vnext-utils/string";
+import debug from "debug";
 
 import { resolveHardhatConfigPath } from "../../config.js";
 import { createHardhatRuntimeEnvironment } from "../../hre.js";
@@ -45,18 +46,26 @@ 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 with arguments:", cliArguments);
+
   try {
     const usedCliArguments: boolean[] = new Array(cliArguments.length).fill(
       false,
     );
 
+    log("Parsing builtin global options");
+
     builtinGlobalOptions = await parseBuiltinGlobalOptions(
       cliArguments,
       usedCliArguments,
     );
 
+    log("Parsed builtin global options:", builtinGlobalOptions);
+
     if (builtinGlobalOptions.version) {
       return await printVersionMessage(print);
     }
@@ -65,15 +74,27 @@ export async function main(
       return await initHardhat();
     }
 
+    log("Checking telemetry consent");
+
     // TODO: the consent will be enabled in the other PRs related to telemetry
     const _telemetryConsent = await getTelemetryConsent();
 
+    log("Telemetry consent:", _telemetryConsent);
+
     if (builtinGlobalOptions.configPath === undefined) {
+      log("Config path not provided, attempting to resolve it");
+
       builtinGlobalOptions.configPath = await resolveHardhatConfigPath();
+
+      log("Resolved config path:", builtinGlobalOptions.configPath);
     }
 
+    log("Importing user config");
+
     const userConfig = await importUserConfig(builtinGlobalOptions.configPath);
 
+    log("User config imported:", userConfig);
+
     const configPlugins = Array.isArray(userConfig.plugins)
       ? userConfig.plugins
       : [];
@@ -83,6 +104,8 @@ export async function main(
       builtinGlobalOptions.configPath,
     );
 
+    log("Resolved plugins:", resolvedPlugins);
+
     const pluginGlobalOptionDefinitions =
       buildGlobalOptionDefinitions(resolvedPlugins);
     const globalOptionDefinitions = new Map([
@@ -95,6 +118,10 @@ export async function main(
       usedCliArguments,
     );
 
+    log("User provided global options:", userProvidedGlobalOptions);
+
+    log("Creating Hardhat Runtime Environment");
+
     const hre = await createHardhatRuntimeEnvironment(
       userConfig,
       { ...builtinGlobalOptions, ...userProvidedGlobalOptions },
@@ -106,6 +133,8 @@ export async function main(
 
     const taskOrId = parseTask(cliArguments, usedCliArguments, hre);
 
+    log("Parsed task:", taskOrId);
+
     if (Array.isArray(taskOrId)) {
       if (taskOrId.length === 0) {
         const globalHelp = await getGlobalHelpString(
@@ -138,6 +167,8 @@ export async function main(
       task,
     );
 
+    log(`Running task "${task.id.join(" ")}" with arguments:`, taskArguments);
+
     await task.run(taskArguments);
   } catch (error) {
     printErrorMessages(error, builtinGlobalOptions?.showStackTraces);