hardhat 3.4.1 → 3.4.2

package/src/internal/cli/init/init.ts

@@ -12,7 +12,6 @@ import {
   copy,
   ensureDir,
   exists,
-  getAllFilesMatching,
   isDirectory,
   mkdir,
   readJsonFile,
@@ -435,17 +434,36 @@ export async function copyProjectFiles(
   template: Template,
   force?: boolean,
 ): Promise<void> {
-  // Find all the files in the workspace that would have been overwritten by the template files
-  const matchingRelativeWorkspacePaths = await getAllFilesMatching(
-    workspace,
-    (file) => {
-      const relativeWorkspacePath = path.relative(workspace, file);
-      const relativeTemplatePath = relativeWorkspaceToTemplatePath(
-        relativeWorkspacePath,
-      );
-      return template.files.includes(relativeTemplatePath);
-    },
-  ).then((files) => files.map((f) => path.relative(workspace, f)));
+  // Find all the paths in the template that clash with an existing one in the
+  // workspace
+  const matchingRelativeWorkspacePaths = (
+    await Promise.all(
+      template.files.map(async (relativeTemplatePath) => {
+        const relativeWorkspacePath =
+          relativeTemplateToWorkspacePath(relativeTemplatePath);
+
+        const absoluteWorkspacePath = path.join(
+          workspace,
+          relativeWorkspacePath,
+        );
+
+        if (!(await exists(absoluteWorkspacePath))) {
+          return undefined;
+        }
+
+        // We ignore directories in this clash detection
+        if (await isDirectory(absoluteWorkspacePath)) {
+          return undefined;
+        }
+
+        return relativeWorkspacePath;
+      }),
+    )
+  ).filter((relativeWorkspacePath) => relativeWorkspacePath !== undefined);
+
+  const matchingRelativeWorkspacePathsSet = new Set(
+    matchingRelativeWorkspacePaths,
+  );
 
   // Ask the user for permission to overwrite existing files if needed
   if (matchingRelativeWorkspacePaths.length !== 0) {
@@ -461,7 +479,7 @@ export async function copyProjectFiles(
 
     if (
       force === false &&
-      matchingRelativeWorkspacePaths.includes(relativeWorkspacePath)
+      matchingRelativeWorkspacePathsSet.has(relativeWorkspacePath)
     ) {
       continue;
     }

package/src/internal/cli/init/template.ts

@@ -5,7 +5,7 @@ import {
   exists,
   getAllFilesMatching,
   isDirectory,
-  readdir,
+  readdirOrEmpty,
   readJsonFile,
 } from "@nomicfoundation/hardhat-utils/fs";
 import {
@@ -40,11 +40,7 @@ export async function getTemplates(
   const packageRoot = await findClosestPackageRoot(import.meta.url);
   const pathToTemplates = path.join(packageRoot, "templates", templatesDir);
 
-  if (!(await exists(pathToTemplates))) {
-    return [];
-  }
-
-  const pathsToTemplates = await readdir(pathToTemplates);
+  const pathsToTemplates = await readdirOrEmpty(pathToTemplates);
   pathsToTemplates.sort();
 
   const templates = await Promise.all(
@@ -65,27 +61,26 @@ export async function getTemplates(
 
       const packageJson: PackageJson =
         await readJsonFile<PackageJson>(pathToPackageJson);
-      const files = await getAllFilesMatching(pathToTemplate, (f) => {
-        // Ignore the package.json file because it is handled separately
-        if (f === pathToPackageJson) {
-          return false;
-        }
-        // .gitignore files are expected to be called gitignore in the templates
-        // because npm ignores .gitignore files during npm pack (see https://github.com/npm/npm/issues/3763)
-        if (path.basename(f) === ".gitignore") {
-          return false;
-        }
-        // We should ignore all the files according to the .gitignore rules
-        // However, for simplicity, we just ignore the node_modules folder
-        // If we needed to implement a more complex ignore logic, we could
-        // use recently introduced glob from node:fs/promises
-        if (
-          path.relative(pathToTemplate, f).split(path.sep)[0] === "node_modules"
-        ) {
-          return false;
-        }
-        return true;
-      }).then((fs) => fs.map((f) => path.relative(pathToTemplate, f)));
+
+      const matchingFiles = await getAllFilesMatching(
+        pathToTemplate,
+        (f) => {
+          // Ignore the package.json file because it is handled separately
+          if (f === pathToPackageJson) {
+            return false;
+          }
+
+          // .gitignore files are expected to be called gitignore in the templates
+          // because npm ignores .gitignore files during npm pack (see https://github.com/npm/npm/issues/3763)
+          if (path.basename(f) === ".gitignore") {
+            return false;
+          }
+          return true;
+        },
+        (dir) => path.basename(dir) !== "node_modules",
+      );
+
+      const files = matchingFiles.map((f) => path.relative(pathToTemplate, f));
 
       return {
         name,

package/src/internal/cli/node-version.ts

@@ -2,9 +2,13 @@
 // is always run during the initialization of the CLI.
 //
 // NOTE: This file shouldn't import any non-builtin dependency, as it's imported
-// before enabling source maps support. TODO: Change chalk to util.styleText
+// before enabling source maps support.
+//
+// EXCEPTION: we share `getRuntimeInfo` with the rest of the codebase instead
+// of duplicating it. The helper has no transitive dependencies, so the risk of
+// an unreadable stack trace from its import graph is negligible.
 
-import chalk from "chalk";
+import { getRuntimeInfo } from "@nomicfoundation/hardhat-utils/runtime";
 
 export const MIN_SUPPORTED_NODE_VERSION: number[] = [22, 10, 0];
 
@@ -15,10 +19,6 @@ export function isNodeVersionSupported(): boolean {
     const minor = parseInt(minorStr, 10);
     const patch = parseInt(patchStr, 10);
 
-    if (major % 2 === 1) {
-      return false;
-    }
-
     if (major < MIN_SUPPORTED_NODE_VERSION[0]) {
       return false;
     } else if (major > MIN_SUPPORTED_NODE_VERSION[0]) {
@@ -42,12 +42,20 @@ export function isNodeVersionSupported(): boolean {
   return true;
 }
 
-export function printNodeJsVersionWarningIfNecessary(): void {
+export function exitIfNodeVersionNotSupported(): void {
+  // Only enforce the Node.js version when we're actually running on Node.js.
+  // Bun and Deno emulate `process.versions.node`, so checking it there would
+  // incorrectly reject users on those runtimes.
+  if (getRuntimeInfo()?.runtime !== "node") {
+    return;
+  }
+
   if (!isNodeVersionSupported()) {
-    console.log(
-      chalk.bold(`\n${chalk.yellow("WARNING:")} You are using Node.js ${process.versions.node} which is not supported by Hardhat.
-Please upgrade to ${MIN_SUPPORTED_NODE_VERSION.join(".")} or a later LTS version (even major version number)\n`),
+    console.error(
+      `\nERROR: You are using Node.js ${process.versions.node} which is not supported by Hardhat.\n` +
+        `Please upgrade to Node.js ${MIN_SUPPORTED_NODE_VERSION.join(".")} or later.\n`,
     );
-    return;
+
+    process.exit(1);
   }
 }

package/src/internal/core/hook-manager.ts

@@ -23,35 +23,94 @@ export class HookManagerImplementation implements HookManager {
 
   readonly #projectRoot: string;
 
-  readonly #pluginsInReverseOrder: HardhatPlugin[];
-
   /**
+   * The context passed to hook handlers, except to the `config` ones, to break
+   * a circular dependency between the config and the hook handler.
+   *
    * Initially `undefined` to be able to run the config hooks during
    * initialization.
    */
   #context: HookContext | undefined;
 
   /**
-   * The initialized handler categories for each plugin.
+   * Plugins that provide hook handlers for each category, in reverse order.
+   *
+   * Precomputed from the plugin list at construction.
+   */
+  readonly #pluginsByHookCategory: Map<keyof HardhatHooks, HardhatPlugin[]> =
+    new Map();
+
+  /**
+   * Cached resolved category objects per hook category in reverse plugin
+   * order.
+   *
+   * Only written by #getStaticHookHandlerCategories, which uses a mutex to
+   * ensure that every Hook Category Factory is run once per HookManager
+   * instance.
    */
-  readonly #staticHookHandlerCategories: Map<
-    string,
-    Map<keyof HardhatHooks, Partial<HardhatHooks[keyof HardhatHooks]>>
+  readonly #resolvedStaticCategories: Map<
+    keyof HardhatHooks,
+    Array<Partial<HardhatHooks[keyof HardhatHooks]>>
   > = new Map();
 
   /**
    * A map of the dynamically registered handler categories.
    *
    * Each array is a list of categories, in reverse order of registration.
+   *
+   * Written by registerHandlers and unregisterHandlers.
    */
   readonly #dynamicHookHandlerCategories: Map<
     keyof HardhatHooks,
     Array<Partial<HardhatHooks[keyof HardhatHooks]>>
   > = new Map();
 
+  /**
+   * Cached combined (dynamic + static) handlers per (category, hook name) in
+   * chained running order.
+   *
+   * Only written by #getHandlersInChainedRunningOrder, and invalidated
+   * per-category on dynamic handlers register/unregister.
+   */
+  readonly #chainedHandlers: Map<keyof HardhatHooks, Map<string, any[]>> =
+    new Map();
+
+  /**
+   * Cached combined handlers per (category, hook name) in sequential running
+   * order (reverse of chained).
+   *
+   * Only written by #getHandlersInSequentialRunningOrder, and invalidated
+   * per-category on dynamic handlers register/unregister.
+   */
+  readonly #sequentialHandlers: Map<keyof HardhatHooks, Map<string, any[]>> =
+    new Map();
+
   constructor(projectRoot: string, plugins: HardhatPlugin[]) {
     this.#projectRoot = projectRoot;
-    this.#pluginsInReverseOrder = plugins.toReversed();
+
+    for (const plugin of plugins.toReversed()) {
+      if (plugin.hookHandlers === undefined) {
+        continue;
+      }
+
+      for (const hookCategoryName of Object.keys(plugin.hookHandlers) as Array<
+        keyof HardhatHooks
+      >) {
+        if (plugin.hookHandlers[hookCategoryName] === undefined) {
+          continue;
+        }
+
+        let pluginsForCategory =
+          this.#pluginsByHookCategory.get(hookCategoryName);
+
+        if (pluginsForCategory === undefined) {
+          pluginsForCategory = [];
+          this.#pluginsByHookCategory.set(hookCategoryName, pluginsForCategory);
+        }
+
+        pluginsForCategory.push(plugin);
+      }
+    }
   }
 
   public setContext(context: HookContext): void {
@@ -69,6 +128,8 @@ export class HookManagerImplementation implements HookManager {
     }
 
     categories.unshift(hookHandlerCategory);
+
+    this.#invalidateResolvedHandlersCache(hookCategoryName);
   }
 
   public unregisterHandlers<HookCategoryNameT extends keyof HardhatHooks>(
@@ -84,6 +145,8 @@ export class HookManagerImplementation implements HookManager {
       hookCategoryName,
       categories.filter((c) => c !== hookHandlerCategory),
     );
+
+    this.#invalidateResolvedHandlersCache(hookCategoryName);
   }
 
   public async runHandlerChain<
@@ -96,10 +159,23 @@ export class HookManagerImplementation implements HookManager {
     params: InitialChainedHookParams<HookCategoryNameT, HookT>,
     defaultImplementation: LastParameter<HookT>,
   ): Promise<Awaited<Return<HardhatHooks[HookCategoryNameT][HookNameT]>>> {
-    const handlers = await this.#getHandlersInChainedRunningOrder(
-      hookCategoryName,
-      hookName,
-    );
+    // Synchronous fast path for already cached handlers. This duplicates
+    // the check inside #getHandlersInChainedRunningOrder on purpose:
+    // calling that async method introduces a microtask tick even on a
+    // cache hit, whereas a direct Map lookup stays on the current tick.
+    // That tick matters here because runHandlerChain is on every hook's
+    // hot path, and this path pairs with the empty-handlers shortcut
+    // below to dispatch straight to defaultImplementation with no awaits.
+    const cachedHandlers = this.#chainedHandlers
+      .get(hookCategoryName)
+      ?.get(hookName as string);
+
+    const handlers =
+      cachedHandlers ??
+      (await this.#getHandlersInChainedRunningOrder(
+        hookCategoryName,
+        hookName,
+      ));
 
     let handlerParams: Parameters<typeof defaultImplementation>;
     if (hookCategoryName !== "config") {
@@ -113,6 +189,13 @@ export class HookManagerImplementation implements HookManager {
       handlerParams = params as any;
     }
 
+    // Fast path for the common case of no registered handlers: skip building
+    // handlerParams and the `next` closure, and call the default implementation
+    // directly.
+    if (handlers.length === 0) {
+      return (await defaultImplementation(...handlerParams)) as any;
+    }
+
     const numberOfHandlers = handlers.length;
     let index = 0;
     const next = async (...nextParams: typeof handlerParams) => {
@@ -220,14 +303,48 @@ export class HookManagerImplementation implements HookManager {
     hookCategoryName: HookCategoryNameT,
     hookName: HookNameT,
   ): Promise<Array<HardhatHooks[HookCategoryNameT][HookNameT]>> {
-    const pluginHooks = await this.#getPluginHooks(hookCategoryName, hookName);
+    let handlersByName = this.#chainedHandlers.get(hookCategoryName);
+    if (handlersByName === undefined) {
+      handlersByName = new Map();
+      this.#chainedHandlers.set(hookCategoryName, handlersByName);
+    }
 
-    const dynamicHooks = await this.#getDynamicHooks(
+    const cached = handlersByName.get(hookName as string);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const staticCategories =
+      await this.#getStaticHookHandlerCategories(hookCategoryName);
+
+    // IMPORTANT NOTE: Accessing the dynamic hook handlers MUST happen
+    // after awaiting the static ones. See
+    // #invalidateResolvedHandlersCache for more info.
+    const dynamicCategories = this.#dynamicHookHandlerCategories.get(
       hookCategoryName,
-      hookName,
-    );
+    ) as Array<Partial<HardhatHooks[HookCategoryNameT]>> | undefined;
+
+    const handlers: Array<HardhatHooks[HookCategoryNameT][HookNameT]> = [];
 
-    return [...dynamicHooks, ...pluginHooks];
+    if (dynamicCategories !== undefined) {
+      for (const category of dynamicCategories) {
+        const handler = category[hookName];
+        if (handler !== undefined) {
+          handlers.push(handler as HardhatHooks[HookCategoryNameT][HookNameT]);
+        }
+      }
+    }
+
+    for (const category of staticCategories) {
+      const handler = category[hookName];
+      if (handler !== undefined) {
+        handlers.push(handler as HardhatHooks[HookCategoryNameT][HookNameT]);
+      }
+    }
+
+    handlersByName.set(hookName as string, handlers);
+
+    return handlers;
   }
 
   async #getHandlersInSequentialRunningOrder<
@@ -237,111 +354,158 @@ export class HookManagerImplementation implements HookManager {
     hookCategoryName: HookCategoryNameT,
     hookName: HookNameT,
   ): Promise<Array<HardhatHooks[HookCategoryNameT][HookNameT]>> {
-    const handlersInChainedOrder = await this.#getHandlersInChainedRunningOrder(
+    let handlersByName = this.#sequentialHandlers.get(hookCategoryName);
+    if (handlersByName === undefined) {
+      handlersByName = new Map();
+      this.#sequentialHandlers.set(hookCategoryName, handlersByName);
+    }
+
+    const cached = handlersByName.get(hookName as string);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const chained = await this.#getHandlersInChainedRunningOrder(
       hookCategoryName,
       hookName,
     );
 
-    return handlersInChainedOrder.reverse();
+    const sequential = chained.toReversed();
+
+    handlersByName.set(hookName as string, sequential);
+
+    return sequential;
   }
 
-  async #getDynamicHooks<
+  async #getStaticHookHandlerCategories<
     HookCategoryNameT extends keyof HardhatHooks,
-    HookNameT extends keyof HardhatHooks[HookCategoryNameT],
   >(
     hookCategoryName: HookCategoryNameT,
-    hookName: HookNameT,
-  ): Promise<Array<HardhatHooks[HookCategoryNameT][HookNameT]>> {
-    const categories = this.#dynamicHookHandlerCategories.get(
-      hookCategoryName,
-    ) as Array<Partial<HardhatHooks[HookCategoryNameT]>> | undefined;
+  ): Promise<Array<Partial<HardhatHooks[HookCategoryNameT]>>> {
+    const cached = this.#resolvedStaticCategories.get(hookCategoryName) as
+      | Array<Partial<HardhatHooks[HookCategoryNameT]>>
+      | undefined;
 
-    if (categories === undefined) {
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const plugins = this.#pluginsByHookCategory.get(hookCategoryName);
+
+    // We don't need to get the mutex to resolve this case, as it will always
+    // be an empty array, and won't execute any factory.
+    if (plugins === undefined) {
+      this.#resolvedStaticCategories.set(hookCategoryName, []);
       return [];
     }
 
-    return categories.flatMap((hookCategory) => {
-      return (hookCategory[hookName] ?? []) as Array<
-        HardhatHooks[HookCategoryNameT][HookNameT]
-      >;
+    return await this.#mutex.exclusiveRun(async () => {
+      // Re-check under the mutex in case another caller just populated it.
+      const recheck = this.#resolvedStaticCategories.get(hookCategoryName) as
+        | Array<Partial<HardhatHooks[HookCategoryNameT]>>
+        | undefined;
+
+      if (recheck !== undefined) {
+        return recheck;
+      }
+
+      const resolved = await Promise.all(
+        plugins.map(
+          async (plugin) =>
+            await this.#getPluginStaticHookCategory(plugin, hookCategoryName),
+        ),
+      );
+
+      this.#resolvedStaticCategories.set(hookCategoryName, resolved);
+
+      return resolved;
     });
   }
 
-  async #getPluginHooks<
+  /**
+   * Returns the hook category object for a plugin that has the hook category
+   * defined.
+   *
+   * @param plugin A plugin that MUST have the given hook category defined.
+   * @param hookCategoryName The name of the hook category.
+   * @returns The hook category object.
+   */
+  async #getPluginStaticHookCategory<
     HookCategoryNameT extends keyof HardhatHooks,
-    HookNameT extends keyof HardhatHooks[HookCategoryNameT],
   >(
+    plugin: HardhatPlugin,
     hookCategoryName: HookCategoryNameT,
-    hookName: HookNameT,
-  ): Promise<Array<HardhatHooks[HookCategoryNameT][HookNameT]>> {
-    const categories: Array<
-      Partial<HardhatHooks[HookCategoryNameT]> | undefined
-    > = await this.#mutex.exclusiveRun(async () => {
-      return await Promise.all(
-        this.#pluginsInReverseOrder.map(async (plugin) => {
-          const existingCategory = this.#staticHookHandlerCategories
-            .get(plugin.id)
-            ?.get(hookCategoryName);
-
-          if (existingCategory !== undefined) {
-            return existingCategory as Partial<HardhatHooks[HookCategoryNameT]>;
-          }
-
-          const hookHandlerCategoryFactory =
-            plugin.hookHandlers?.[hookCategoryName];
-
-          if (hookHandlerCategoryFactory === undefined) {
-            return;
-          }
-
-          let factory;
-          try {
-            factory = (await hookHandlerCategoryFactory()).default;
-          } catch (error) {
-            ensureError(error);
-
-            await detectPluginNpmDependencyProblems(
-              this.#projectRoot,
-              plugin,
-              error,
-            );
-
-            throw error;
-          }
-
-          assertHardhatInvariant(
-            typeof factory === "function",
-            `Plugin ${plugin.id} doesn't export a hook factory for category ${hookCategoryName}`,
-          );
-
-          const hookCategory = await factory();
-
-          assertHardhatInvariant(
-            hookCategory !== null && typeof hookCategory === "object",
-            `Plugin ${plugin.id} doesn't export a valid factory for category ${hookCategoryName}, it didn't return an object`,
-          );
-
-          if (!this.#staticHookHandlerCategories.has(plugin.id)) {
-            this.#staticHookHandlerCategories.set(plugin.id, new Map());
-          }
-
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Defined right above
-          this.#staticHookHandlerCategories
-            .get(plugin.id)!
-            .set(hookCategoryName, hookCategory);
-
-          return hookCategory;
-        }),
-      );
-    });
+  ): Promise<Partial<HardhatHooks[HookCategoryNameT]>> {
+    const hookHandlerCategoryFactory = plugin.hookHandlers?.[hookCategoryName];
 
-    return categories.flatMap((category) => {
-      const handler = category?.[hookName];
-      if (handler === undefined) {
-        return [];
-      }
+    assertHardhatInvariant(
+      hookHandlerCategoryFactory !== undefined,
+      "#pluginsByHookCategory only contains plugins with this hook category",
+    );
 
-      return handler as HardhatHooks[HookCategoryNameT][HookNameT];
-    });
+    let factory;
+    try {
+      factory = (await hookHandlerCategoryFactory()).default;
+    } catch (error) {
+      ensureError(error);
+
+      await detectPluginNpmDependencyProblems(this.#projectRoot, plugin, error);
+
+      throw error;
+    }
+
+    assertHardhatInvariant(
+      typeof factory === "function",
+      `Plugin ${plugin.id} doesn't export a hook factory for category ${hookCategoryName}`,
+    );
+
+    const hookCategory = await factory();
+
+    assertHardhatInvariant(
+      hookCategory !== null && typeof hookCategory === "object",
+      `Plugin ${plugin.id} doesn't export a valid factory for category ${hookCategoryName}, it didn't return an object`,
+    );
+
+    return hookCategory;
+  }
+
+  #invalidateResolvedHandlersCache<
+    HookCategoryNameT extends keyof HardhatHooks,
+  >(hookCategoryName: HookCategoryNameT) {
+    // Invalidation deletes the outer entry rather than clearing the inner
+    // map. This matters under concurrency.
+    //
+    // A reader of #getHandlersInChainedRunningOrder (or its sequential
+    // sibling) captures a reference to the inner map before awaiting the
+    // static categories, and writes its computed array back after the
+    // await. If invalidation runs during that await, deleting the outer
+    // entry leaves the reader's inner map orphaned: its write lands in a
+    // map no longer reachable from #chainedHandlers/#sequentialHandlers,
+    // so it cannot poison the shared cache. The next reader sees
+    // `undefined`, installs a fresh inner map, and rebuilds from the
+    // current dynamic state.
+    //
+    // Two distinct properties make this safe, guaranteed by two different
+    // things:
+    //
+    //   1. The in-flight reader's own return value is correct. This is
+    //      because #getHandlersInChainedRunningOrder reads
+    //      #dynamicHookHandlerCategories *after* awaiting the static
+    //      categories. Any invalidation that happened during the await is
+    //      visible to the reader when it resumes, so the array it builds
+    //      reflects the current dynamic state.
+    //
+    //   2. The shared cache never holds a stale array. This is guaranteed
+    //      by the orphaning-by-delete described above: a reader that
+    //      started before the invalidation can only write into an
+    //      unreachable inner map.
+    //
+    // Property 1 depends on the ordering of the dynamic handlers read relative
+    // to the await. If that read ever moved *before* the await, a reader
+    // could build a stale array and return it to its caller — the cache
+    // would still be protected by property 2, but the reader's caller
+    // would see the stale result.
+    this.#chainedHandlers.delete(hookCategoryName);
+    this.#sequentialHandlers.delete(hookCategoryName);
   }
 }

package/src/internal/core/hre.ts

@@ -40,9 +40,9 @@ import {
   resolveGlobalOptions,
 } from "./global-options.js";
 import { HookManagerImplementation } from "./hook-manager.js";
+import { LazyUserInterruptionManager } from "./lazy-user-interruptions.js";
 import { resolvePluginList } from "./plugins/resolve-plugin-list.js";
 import { TaskManagerImplementation } from "./tasks/task-manager.js";
-import { UserInterruptionManagerImplementation } from "./user-interruptions.js";
 
 export class HardhatRuntimeEnvironmentImplementation
   implements HardhatRuntimeEnvironment
@@ -134,7 +134,7 @@ export class HardhatRuntimeEnvironmentImplementation
 
     // Set the HookContext in the hook manager so that non-config hooks can
     // use it
-    const interruptions = new UserInterruptionManagerImplementation(hooks);
+    const interruptions = new LazyUserInterruptionManager(hooks);
 
     const hre = new HardhatRuntimeEnvironmentImplementation(
       extendedUserConfig,