hardhat 3.5.0 → 3.5.1

package/dist/src/internal/using-hardhat2-plugin-errors.js

@@ -10,21 +10,18 @@ export class UsingHardhat2PluginError extends CustomError {
         if (callerPath !== undefined) {
             message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.
 
-This file is part of a Hardhat 2 plugin calling an API that was removed in Hardhat 3: ${styleText("bold", callerPath)}
-
-Please read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.
-`;
+This file is part of a Hardhat 2 plugin calling an API that was removed in Hardhat 3: ${styleText("bold", callerPath)}`;
         }
         else {
-            message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.
-      
-Check the stack trace below to identify which plugin is causing this.
-
-Please read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.
-`;
+            message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.`;
         }
         super(message);
-        this.callerRelativePath = callerPath;
+        // Use a non-enumerable property so that `console.error(error)` does not
+        // print `{ callerRelativePath: '…' }` after the stack trace.
+        Object.defineProperty(this, "callerRelativePath", {
+            value: callerPath,
+            enumerable: false,
+        });
     }
 }
 /**

package/dist/src/internal/using-hardhat2-plugin-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"using-hardhat2-plugin-errors.js","sourceRoot":"","sources":["../../../src/internal/using-hardhat2-plugin-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAElE,MAAM,OAAO,wBAAyB,SAAQ,WAAW;IACvC,kBAAkB,CAAqB;IACvD;QACE,MAAM,UAAU,GAAG,qBAAqB,EAAE,CAAC;QAE3C,IAAI,OAAe,CAAC;QACpB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,GAAG;;wFAEwE,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC;;;CAGpH,CAAC;QACE,CAAC;aAAM,CAAC;YACN,OAAO,GAAG;;;;;CAKf,CAAC;QACE,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,kBAAkB,GAAG,UAAU,CAAC;IACvC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB,CAAC;IACrD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED;;;;;;;;WAQG;QACH,MAAM,sBAAsB,GAC1B,iDAAiD,CAAC;QAEpD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC9D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YAC7C,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAExB,4CAA4C;QAC5C,IAAI,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC;QAED,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C;kEAC8D;IAC9D,MAAM,IAAI,wBAAwB,EAAE,CAAC;AACvC,CAAC"}
+{"version":3,"file":"using-hardhat2-plugin-errors.js","sourceRoot":"","sources":["../../../src/internal/using-hardhat2-plugin-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAElE,MAAM,OAAO,wBAAyB,SAAQ,WAAW;IACvC,kBAAkB,CAAqB;IACvD;QACE,MAAM,UAAU,GAAG,qBAAqB,EAAE,CAAC;QAE3C,IAAI,OAAe,CAAC;QACpB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,GAAG;;wFAEwE,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC;QACpH,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,kEAAkE,CAAC;QAC/E,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,wEAAwE;QACxE,6DAA6D;QAC7D,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,oBAAoB,EAAE;YAChD,KAAK,EAAE,UAAU;YACjB,UAAU,EAAE,KAAK;SAClB,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB,CAAC;IACrD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED;;;;;;;;WAQG;QACH,MAAM,sBAAsB,GAC1B,iDAAiD,CAAC;QAEpD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC9D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YAC7C,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAExB,4CAA4C;QAC5C,IAAI,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC;QAED,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C;kEAC8D;IAC9D,MAAM,IAAI,wBAAwB,EAAE,CAAC;AACvC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hardhat",
-  "version": "3.5.0",
+  "version": "3.5.1",
   "description": "Hardhat is an extensible developer tool that helps smart contract developers increase productivity by reliably bringing together the tools they want.",
   "homepage": "https://hardhat.org",
   "repository": {

package/src/internal/builtin-plugins/solidity/build-system/build-system.ts

@@ -95,21 +95,6 @@ export function isSolcSolidityCompilerConfig(
   return config.type === undefined || config.type === "solc";
 }
 
-// Compiler warnings to suppress from build output.
-// Each rule specifies a warning message and the source file it applies to.
-// This allows suppressing known warnings from internal files (e.g., console.sol)
-// while still showing the same warning type from user code.
-export const SUPPRESSED_WARNINGS: Array<{
-  message: string;
-  sourceFile: string;
-}> = [
-  {
-    message:
-      "Natspec memory-safe-assembly special comment for inline assembly is deprecated and scheduled for removal. Use the memory-safe block annotation instead.",
-    sourceFile: path.normalize("hardhat/console.sol"),
-  },
-];
-
 interface CompilationResult {
   compilationJob: CompilationJob;
   compilerOutput: CompilerOutput;
@@ -123,6 +108,7 @@ export interface SolidityBuildSystemOptions {
   readonly artifactsPath: string;
   readonly cachePath: string;
   readonly solidityTestsPath: string;
+  readonly coverage: boolean;
 }
 
 /**
@@ -1417,6 +1403,7 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
       msg,
       this.#options.solidityTestsPath,
       this.#options.projectRoot,
+      this.#options.coverage,
     );
   }
 

package/src/internal/builtin-plugins/solidity/build-system/warning-suppression.ts

@@ -1,97 +1,119 @@
 import path from "node:path";
 
-// Compiler warnings to suppress from build output.
-// Supports two types of suppression rules:
-//
-// 1. scope: 'specific-file' - Suppress warnings from specific file paths
-//    - Use this to suppress known warnings from internal/library files (e.g., console.sol)
-//    - The same warning type will still be shown for user code
-//
-// 2. scope: 'test-files' - Suppress warnings from all test files
-//    - Test files are identified as:
-//      * Files ending in .t.sol (e.g., Counter.t.sol)
-//      * Files inside test/contracts/ directory
-//        (e.g., test/contracts/Example.sol)
-//    - Use this for warnings that are acceptable in test code but not in production code
-//      (e.g., missing SPDX license identifiers or pragma statements)
-export const SUPPRESSED_WARNINGS: Array<
-  | {
-      message: string;
-      scope: "specific-file";
-      filePath: string;
-    }
-  | {
-      message: string;
-      scope: "test-files";
-    }
-> = [
+import { COVERAGE_LIBRARY_FILE_NAME } from "@nomicfoundation/edr";
+
+export const NATSPEC_MEMORY_SAFE_ASSEMBLY_WARNING =
+  "Natspec memory-safe-assembly special comment for inline assembly is deprecated and scheduled for removal. Use the memory-safe block annotation instead.";
+export const SPDX_WARNING = "SPDX license identifier not provided";
+export const PRAGMA_WARNING =
+  "Source file does not specify required compiler version";
+const CONTRACT_SIZE_WARNING = "Contract code size is";
+
+// Suppression rules are grouped by scope. Each array has its own match logic
+// in `shouldSuppressWarning` function; add new entries to the array that fits, or add
+// a new array + block for a new scope.
+
+// Warnings tied to a specific internal file (e.g. console.sol). Suppressed
+// only when the warning points at that file.
+const SPECIFIC_FILE_RULES: ReadonlyArray<{
+  message: string;
+  filePath: string;
+}> = [
   {
-    message:
-      "Natspec memory-safe-assembly special comment for inline assembly is deprecated and scheduled for removal. Use the memory-safe block annotation instead.",
-    scope: "specific-file",
+    message: NATSPEC_MEMORY_SAFE_ASSEMBLY_WARNING,
     // Normalize to handle different OS path separators
     filePath: path.normalize("hardhat/console.sol"),
   },
+];
+
+// Warnings acceptable in test files. Suppressed when the warning points at a
+// file ending in `.t.sol` or inside the configured Solidity test directory.
+const TEST_FILE_WARNING_MESSAGES: readonly string[] = [
+  SPDX_WARNING,
+  PRAGMA_WARNING,
+];
+
+// Warnings suppressed only when running with `--coverage`. An entry with no
+// `filePath` matches the message anywhere (e.g. contract-size warnings that
+// fire on user files as a side effect of instrumentation); an entry with a
+// `filePath` only matches when the diagnostic also points at that file
+// (e.g. the injected coverage library file, which users can't edit).
+const COVERAGE_MODE_RULES: ReadonlyArray<{
+  message: string;
+  filePath?: string;
+}> = [
+  { message: CONTRACT_SIZE_WARNING },
   {
-    message: "SPDX license identifier not provided",
-    scope: "test-files",
-  },
-  {
-    message: "Source file does not specify required compiler version",
-    scope: "test-files",
+    message: NATSPEC_MEMORY_SAFE_ASSEMBLY_WARNING,
+    filePath: COVERAGE_LIBRARY_FILE_NAME,
   },
 ];
 
 /**
- * Determines if a compiler warning should be suppressed based on the suppression rules.
+ * Determines if a compiler warning should be suppressed.
  *
  * @param errorMessage - The formatted error message from the compiler
  * @param absoluteSolidityTestsPath - Absolute path to the Solidity test directory
  * @param absoluteProjectRoot - Absolute path to the project root
+ * @param coverage - Whether the build is running with `--coverage` enabled
  * @returns true if the warning should be suppressed, false otherwise
  */
 export function shouldSuppressWarning(
   errorMessage: string,
   absoluteSolidityTestsPath: string,
   absoluteProjectRoot: string,
+  coverage: boolean,
 ): boolean {
-  // Compute relative path from project root to test directory.
-  // Example:
-  // absoluteSolidityTestsPath: /workspaces/hardhat-4/packages/example-project/test/contracts
-  // absoluteProjectRoot:       /workspaces/hardhat-4/packages/example-project
-  // relativeTestPath:          test/contracts/ - note the addition of the `/`
-  // to avoid partial matches, e.g.: test/contractsUtils/
-  const relativeTestPath = path.join(
-    path.relative(absoluteProjectRoot, absoluteSolidityTestsPath),
-    "/",
-  );
-
-  return SUPPRESSED_WARNINGS.some((rule) => {
-    if (!errorMessage.includes(rule.message)) {
-      return false;
-    }
+  // Warnings suppressed only when running with `--coverage`.
+  if (
+    coverage &&
+    COVERAGE_MODE_RULES.some(
+      (rule) =>
+        errorMessage.includes(rule.message) &&
+        (rule.filePath === undefined || errorMessage.includes(rule.filePath)),
+    )
+  ) {
+    return true;
+  }
 
-    if (rule.scope === "specific-file") {
-      return errorMessage.includes(rule.filePath);
-    }
+  // Warnings tied to a specific internal file (e.g. console.sol).
+  if (
+    SPECIFIC_FILE_RULES.some(
+      (rule) =>
+        errorMessage.includes(rule.message) &&
+        errorMessage.includes(rule.filePath),
+    )
+  ) {
+    return true;
+  }
 
-    // Check if the message contains a path to a test file
+  // Warnings allowed in test files.
+  if (TEST_FILE_WARNING_MESSAGES.some((m) => errorMessage.includes(m))) {
     // Test files are identified by:
     // - Ending in .t.sol (e.g., Counter.t.sol)
     // - Being inside the configured Solidity test directory
-
     if (/\.t\.sol(:|$|\s)/.test(errorMessage)) {
       return true;
     }
 
-    // Extract file path from error message
+    // Compute relative path from project root to test directory.
+    // Example:
+    // absoluteSolidityTestsPath: /workspaces/hardhat-4/packages/example-project/test/contracts
+    // absoluteProjectRoot:       /workspaces/hardhat-4/packages/example-project
+    // relativeTestPath:          test/contracts/ - note the addition of the `/`
+    // to avoid partial matches, e.g.: test/contractsUtils/
+    const relativeTestPath = path.join(
+      path.relative(absoluteProjectRoot, absoluteSolidityTestsPath),
+      "/",
+    );
+
+    // Extract file path from error message.
     // Format: "Warning: message\n  --> path/to/file.sol:line:column:"
     const pathMatches = errorMessage.match(/-->\s+([^\s:]+\.sol)/);
-
     if (pathMatches !== null) {
       return pathMatches[1].includes(relativeTestPath);
     }
+  }
 
-    return false;
-  });
+  return false;
 }

package/src/internal/builtin-plugins/solidity/hook-handlers/hre.ts

@@ -152,7 +152,7 @@ class LazySolidityBuildSystem implements SolidityBuildSystem {
 
 export default async (): Promise<Partial<HardhatRuntimeEnvironmentHooks>> => {
   return {
-    created: async (_context, hre) => {
+    created: async (context, hre) => {
       hre.solidity = new LazySolidityBuildSystem(hre.hooks, {
         solidityConfig: hre.config.solidity,
         projectRoot: hre.config.paths.root,
@@ -160,6 +160,7 @@ export default async (): Promise<Partial<HardhatRuntimeEnvironmentHooks>> => {
         artifactsPath: hre.config.paths.artifacts,
         cachePath: hre.config.paths.cache,
         solidityTestsPath: hre.config.paths.tests.solidity,
+        coverage: context.globalOptions.coverage,
       });
     },
   };

package/src/internal/cli/error-handler.ts

@@ -1,3 +1,5 @@
+import type * as ClassifierT from "./telemetry/error-classification/classifier.js";
+
 import { styleText } from "node:util";
 
 import {
@@ -6,19 +8,24 @@ import {
 } from "@nomicfoundation/hardhat-errors";
 
 import { HARDHAT_NAME, HARDHAT_WEBSITE_URL } from "../constants.js";
-import { UsingHardhat2PluginError } from "../using-hardhat2-plugin-errors.js";
+
+// The classifier may import many unrelated things top-level to do its job, so
+// we load it lazily.
+let classifierModule: typeof ClassifierT | undefined;
 
 /**
  * The different categories of errors that can be handled by hardhat cli.
  * Each category has a different way of being formatted and displayed.
  * To add new categories, add a new entry to this enum and update the
- *  {@link getErrorWithCategory} and {@link getErrorMessages} functions
- * accordingly.
+ *  {@link getErrorWithCategory} function and the switch inside
+ * {@link printErrorMessages} accordingly.
  */
 enum ErrorCategory {
   HARDHAT = "HARDHAT",
   PLUGIN = "PLUGIN",
   COMMUNITY_PLUGIN = "COMMUNITY_PLUGIN",
+  HH2_TO_HH3_MIGRATION = "HH2_TO_HH3_MIGRATION",
+  CJS_TO_ESM_MIGRATION = "CJS_TO_ESM_MIGRATION",
   OTHER = "OTHER",
 }
 
@@ -35,55 +42,91 @@ type ErrorWithCategory =
       category: ErrorCategory.COMMUNITY_PLUGIN;
       categorizedError: HardhatPluginError;
     }
+  | {
+      category: ErrorCategory.HH2_TO_HH3_MIGRATION;
+      categorizedError: Error;
+    }
+  | {
+      category: ErrorCategory.CJS_TO_ESM_MIGRATION;
+      categorizedError: Error;
+    }
   | {
       category: ErrorCategory.OTHER;
       categorizedError: unknown;
     };
 
-/**
- * The different messages that can be displayed for each category of errors.
- *  - `formattedErrorMessage`: the main error message that is always displayed.
- *  - `showMoreInfoMessage`: an optional message that can be displayed to
- * provide more information about the error. It is only displayed when stack
- * traces are hidden.
- *  - `postErrorStackTraceMessage` an optional message that can be displayed
- * after the stack trace. It is only displayed when stack traces are shown.
- */
-interface ErrorMessages {
-  formattedErrorMessage: string;
-  showMoreInfoMessage?: string;
-  postErrorStackTraceMessage?: string;
-}
-
 /**
  * Formats and logs error messages based on the category the error belongs to.
  *
+ * For each category, we produce up to three pieces:
+ *  - `formattedErrorMessage`: the main error message that is always displayed.
+ *  - `showMoreInfoMessage`: an optional message that points the user at more
+ *    info. It is only displayed when the stack trace is hidden.
+ *  - `postErrorStackTraceMessage`: an optional message that is displayed after
+ *    the stack trace.
+ *
  * @param error the error to handle. Supported categories are defined in
  * {@link ErrorCategory}.
  * @param shouldShowStackTraces whether to show stack traces or not. If true,
  * the stack trace is always shown. If false, the stack trace is only shown for
- * errors of category {@link ErrorCategory.OTHER}.
+ * errors of category {@link ErrorCategory.OTHER},
+ * {@link ErrorCategory.HH2_TO_HH3_MIGRATION}, and
+ * {@link ErrorCategory.CJS_TO_ESM_MIGRATION}.
  * @param print the function used to print the error message, defaults to
  * `console.error`. Useful for testing to capture error messages.
  */
-export function printErrorMessages(
+export async function printErrorMessages(
   error: Error,
   shouldShowStackTraces: boolean = false,
   print: (message: string | Error) => void = console.error,
-): void {
-  if (error instanceof UsingHardhat2PluginError) {
-    printUsingHardhat2Error(error, print);
-    return;
+): Promise<void> {
+  const { category, categorizedError } = await getErrorWithCategory(error);
+
+  let formattedErrorMessage: string;
+  let showMoreInfoMessage: string | undefined;
+  let postErrorStackTraceMessage: string | undefined;
+
+  switch (category) {
+    case ErrorCategory.HARDHAT:
+      formattedErrorMessage = `${styleText(["red", "bold"], `Error ${categorizedError.errorCode}:`)} ${categorizedError.formattedMessage}`;
+      showMoreInfoMessage = `For more info go to ${HARDHAT_WEBSITE_URL}${categorizedError.errorCode} or run ${HARDHAT_NAME} with --show-stack-traces`;
+      break;
+    case ErrorCategory.PLUGIN:
+      formattedErrorMessage = `${styleText(["red", "bold"], `Error ${categorizedError.errorCode} in plugin ${categorizedError.pluginId}:`)} ${categorizedError.formattedMessage}`;
+      showMoreInfoMessage = `For more info go to ${HARDHAT_WEBSITE_URL}${categorizedError.errorCode} or run ${HARDHAT_NAME} with --show-stack-traces`;
+      break;
+    case ErrorCategory.COMMUNITY_PLUGIN:
+      formattedErrorMessage = `${styleText(["red", "bold"], `Error in community plugin ${categorizedError.pluginId}:`)} ${categorizedError.message}`;
+      showMoreInfoMessage = `For more info run ${HARDHAT_NAME} with --show-stack-traces`;
+      break;
+    case ErrorCategory.HH2_TO_HH3_MIGRATION:
+      formattedErrorMessage = styleText(
+        ["red", "bold"],
+        `Hardhat 3 migration error:`,
+      );
+      postErrorStackTraceMessage = `It looks like you are migrating from Hardhat 2 to Hardhat 3. The following error often shows up during this kind of migration.\nPlease read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.`;
+      break;
+    case ErrorCategory.CJS_TO_ESM_MIGRATION:
+      formattedErrorMessage = styleText(
+        ["red", "bold"],
+        `Hardhat 3 migration error:`,
+      );
+      postErrorStackTraceMessage = `It looks like you are migrating from CommonJS to ESM. The following error often shows up during this kind of migration.\nPlease read https://hardhat.org/migrate-to-esm to learn how to migrate your project to ESM.`;
+      break;
+    case ErrorCategory.OTHER:
+      formattedErrorMessage = styleText(
+        ["red", "bold"],
+        `An unexpected error occurred:`,
+      );
+      postErrorStackTraceMessage = `If you think this is a bug in Hardhat, please report it here: ${HARDHAT_WEBSITE_URL}report-bug`;
+      break;
   }
 
   const showStackTraces =
     shouldShowStackTraces ||
-    getErrorWithCategory(error).category === ErrorCategory.OTHER;
-  const {
-    formattedErrorMessage,
-    showMoreInfoMessage,
-    postErrorStackTraceMessage,
-  } = getErrorMessages(error);
+    category === ErrorCategory.OTHER ||
+    category === ErrorCategory.HH2_TO_HH3_MIGRATION ||
+    category === ErrorCategory.CJS_TO_ESM_MIGRATION;
 
   print(formattedErrorMessage);
 
@@ -100,7 +143,7 @@ export function printErrorMessages(
   }
 }
 
-function getErrorWithCategory(error: Error): ErrorWithCategory {
+async function getErrorWithCategory(error: Error): Promise<ErrorWithCategory> {
   if (HardhatError.isHardhatError(error)) {
     if (error.pluginId === undefined) {
       return {
@@ -122,49 +165,37 @@ function getErrorWithCategory(error: Error): ErrorWithCategory {
     };
   }
 
+  if (classifierModule === undefined) {
+    classifierModule = await import(
+      "./telemetry/error-classification/classifier.js"
+    );
+  }
+
+  // Pass `ignoreDevelopmentTimeFilter=true` so the migration footer also shows
+  // when hardhat is run from inside its own monorepo — the dev-time filter is
+  // a telemetry concern (don't report to Sentry), unrelated to display routing.
+  const classifierCategory = classifierModule.classifyError(error, true);
+  if (
+    classifierCategory ===
+    classifierModule.ErrorCategory.HH2_TO_HH3_MIGRATION_ERROR
+  ) {
+    return {
+      category: ErrorCategory.HH2_TO_HH3_MIGRATION,
+      categorizedError: error,
+    };
+  }
+  if (
+    classifierCategory ===
+    classifierModule.ErrorCategory.CJS_TO_ESM_MIGRATION_ERROR
+  ) {
+    return {
+      category: ErrorCategory.CJS_TO_ESM_MIGRATION,
+      categorizedError: error,
+    };
+  }
+
   return {
     category: ErrorCategory.OTHER,
     categorizedError: error,
   };
 }
-
-function getErrorMessages(error: Error): ErrorMessages {
-  const { category, categorizedError } = getErrorWithCategory(error);
-  switch (category) {
-    case ErrorCategory.HARDHAT:
-      return {
-        formattedErrorMessage: `${styleText(["red", "bold"], `Error ${categorizedError.errorCode}:`)} ${categorizedError.formattedMessage}`,
-        showMoreInfoMessage: `For more info go to ${HARDHAT_WEBSITE_URL}${categorizedError.errorCode} or run ${HARDHAT_NAME} with --show-stack-traces`,
-      };
-    case ErrorCategory.PLUGIN:
-      return {
-        formattedErrorMessage: `${styleText(["red", "bold"], `Error ${categorizedError.errorCode} in plugin ${categorizedError.pluginId}:`)} ${categorizedError.formattedMessage}`,
-        showMoreInfoMessage: `For more info go to ${HARDHAT_WEBSITE_URL}${categorizedError.errorCode} or run ${HARDHAT_NAME} with --show-stack-traces`,
-      };
-    case ErrorCategory.COMMUNITY_PLUGIN:
-      return {
-        formattedErrorMessage: `${styleText(["red", "bold"], `Error in community plugin ${categorizedError.pluginId}:`)} ${categorizedError.message}`,
-        showMoreInfoMessage: `For more info run ${HARDHAT_NAME} with --show-stack-traces`,
-      };
-    case ErrorCategory.OTHER:
-      return {
-        formattedErrorMessage: styleText(
-          ["red", "bold"],
-          `An unexpected error occurred:`,
-        ),
-        postErrorStackTraceMessage: `If you think this is a bug in Hardhat, please report it here: ${HARDHAT_WEBSITE_URL}report-bug`,
-      };
-  }
-}
-function printUsingHardhat2Error(
-  error: UsingHardhat2PluginError,
-  print: (message: string | Error) => void = console.error,
-): void {
-  print(styleText(["red", "bold"], `Hardhat 3 installation error:`));
-  print("");
-  if (error.callerRelativePath !== undefined) {
-    print(error.message);
-  } else {
-    print(error.stack);
-  }
-}

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

@@ -35,6 +35,7 @@ import { sendErrorTelemetry } from "../telemetry/error-reporter/reporter.js";
 import {
   getDevDependenciesInstallationCommand,
   getPackageManager,
+  getVersion,
   installsPeerDependenciesByDefault,
 } from "./package-manager.js";
 import {
@@ -694,6 +695,8 @@ export async function installProjectDependencies({
   );
 
   const packageManager = getPackageManager();
+  const packageManagerVersion = await getVersion(workspace, packageManager);
+  const packageManagerMajorVersion = packageManagerVersion?.[0];
 
   // Find the template dev dependencies that are not already installed
   const templateDependencies = template.packageJson.devDependencies ?? {};
@@ -730,6 +733,7 @@ export async function installProjectDependencies({
     const command = getDevDependenciesInstallationCommand(
       packageManager,
       dependenciesToInstall,
+      packageManagerMajorVersion,
     );
     const commandString = command.join(" ");
 
@@ -788,6 +792,7 @@ export async function installProjectDependencies({
     const command = getDevDependenciesInstallationCommand(
       packageManager,
       dependenciesToUpdate,
+      packageManagerMajorVersion,
     );
     const commandString = command.join(" ");
 

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

@@ -104,11 +104,16 @@ export function getPackageManager(): PackageManager {
  *
  * @param packageManager The package manager to use.
  * @param dependencies The dependencies to install.
+ * @param packageManagerMajorVersion The major version of the package manager,
+ * if known. Used to opt into version-specific flags (e.g. pnpm 11's
+ * `--allow-build=esbuild`, required because `tsx` ships `esbuild` whose
+ * postinstall script is otherwise blocked).
  * @returns The installation command.
  */
 export function getDevDependenciesInstallationCommand(
   packageManager: PackageManager,
   dependencies: string[],
+  packageManagerMajorVersion?: number,
 ): string[] {
   const packageManagerToCommand: Record<PackageManager, string[]> = {
     npm: ["npm", "install", "--save-dev"],
@@ -118,6 +123,18 @@ export function getDevDependenciesInstallationCommand(
     bun: ["bun", "add", "--dev"],
   };
   const command = packageManagerToCommand[packageManager];
+
+  // NOTE: adding an unnecessary flag doesn't result in an error
+  // nor warning, so we don't check if hardhat or tsx are being
+  // installed.
+  if (
+    packageManager === "pnpm" &&
+    packageManagerMajorVersion !== undefined &&
+    packageManagerMajorVersion >= 11
+  ) {
+    command.push("--allow-build=esbuild");
+  }
+
   // We quote all the dependency identifiers so that they can be run on a shell
   // without semver symbols interfering with the command
   command.push(
@@ -205,7 +222,7 @@ export async function installsPeerDependenciesByDefault(
   }
 }
 
-async function getVersion(
+export async function getVersion(
   workspace: string,
   packageManager: PackageManager,
   version?: string,

package/src/internal/cli/main.ts

@@ -318,7 +318,7 @@ export async function main(
     }
   } catch (error) {
     ensureError(error);
-    printErrorMessages(error, builtinGlobalOptions?.showStackTraces);
+    await printErrorMessages(error, builtinGlobalOptions?.showStackTraces);
 
     try {
       await sendErrorTelemetry(error);

package/src/internal/cli/telemetry/error-classification/classifier.ts

@@ -70,7 +70,8 @@ import {
  * @param error The error to classify.
  * @param ignoreDevelopmentTimeFilter If true, the classifier will ignore the
  * development-time filter, which is used to exclude errors that happen during
- * development of Hardhat itself. This is only meant to be used for testing.
+ * development of Hardhat itself. Set this from display-side callers (where the
+ * dev-time skip is irrelevant) and from tests.
  * @returns The error category.
  */
 export function classifyError(

package/src/internal/using-hardhat2-plugin-errors.ts

@@ -13,21 +13,18 @@ export class UsingHardhat2PluginError extends CustomError {
     if (callerPath !== undefined) {
       message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.
 
-This file is part of a Hardhat 2 plugin calling an API that was removed in Hardhat 3: ${styleText("bold", callerPath)}
-
-Please read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.
-`;
+This file is part of a Hardhat 2 plugin calling an API that was removed in Hardhat 3: ${styleText("bold", callerPath)}`;
     } else {
-      message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.
-      
-Check the stack trace below to identify which plugin is causing this.
-
-Please read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.
-`;
+      message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.`;
     }
 
     super(message);
-    this.callerRelativePath = callerPath;
+    // Use a non-enumerable property so that `console.error(error)` does not
+    // print `{ callerRelativePath: '…' }` after the stack trace.
+    Object.defineProperty(this, "callerRelativePath", {
+      value: callerPath,
+      enumerable: false,
+    });
   }
 }