hardhat 3.4.3 → 3.4.4

package/src/internal/cli/telemetry/error-classification/codebase-dependent-helpers.ts

@@ -0,0 +1,200 @@
+/**
+ * @file This file has a set of helpers that depend on the codebase. They
+ * inspect the stack frames to look for known folders, files, or function names.
+ *
+ * As such, they are somewhat fragile and need to be periodically reevaluated,
+ * especially after large refactors to Hardhat's core.
+ */
+
+import { type StackFrame, includesAny } from "./helpers.js";
+
+/**
+ * Returns true when this package is being executed from the Hardhat monorepo
+ * source tree instead of from an installed `node_modules/hardhat` package.
+ */
+export function isRunningInsideHardhatMonorepo(): boolean {
+  // If this file is in `/packages/hardhat/`, as opposed to
+  // `node_modules/hardhat/`, then we're running inside the monorepo.
+  return import.meta.url.includes("/packages/hardhat/");
+}
+
+// ---------------------------------------------------------------------------
+// Boundary frame predicates
+//
+// These identify the first-party frames that mark the boundary between
+// Hardhat-controlled code and the user/plugin code that ultimately ran. Both
+// the classifier (to assign a category) and the filter (to find the frame
+// above the boundary) need to agree on what those frames look like, so they
+// share a single definition here.
+// ---------------------------------------------------------------------------
+
+/**
+ * Matches the Hardhat frame that imports the user's config file.
+ */
+export function isConfigLoadingBoundaryFrame(frame: StackFrame): boolean {
+  return (
+    frame.location.includes("internal/config-loading.") &&
+    frame.functionName?.includes("importUserConfig") === true
+  );
+}
+
+/**
+ * Matches the builtin console task frame that evaluates user input.
+ */
+export function isConsoleEvaluationBoundaryFrame(frame: StackFrame): boolean {
+  return (
+    frame.location.includes("/internal/builtin-plugins/console/task-action.") &&
+    frame.functionName?.includes("consoleAction") === true
+  );
+}
+
+/**
+ * Matches the builtin run task frame that executes a user script.
+ */
+export function isScriptExecutionBoundaryFrame(frame: StackFrame): boolean {
+  return (
+    frame.location.includes("/internal/builtin-plugins/run/task-action.") &&
+    frame.functionName?.includes("runScriptWithHardhat") === true
+  );
+}
+
+/**
+ * Matches the node:test runner task frame that executes user tests.
+ */
+export function isNodeTestExecutionBoundaryFrame(frame: StackFrame): boolean {
+  return (
+    frame.location.includes("/hardhat-node-test-runner/src/task-action.") &&
+    frame.functionName?.includes("testWithHardhat") === true
+  );
+}
+
+/**
+ * Matches the Mocha runner task frame that executes user tests.
+ */
+export function isMochaTestExecutionBoundaryFrame(frame: StackFrame): boolean {
+  return (
+    frame.location.includes("/hardhat-mocha/src/task-action.") &&
+    frame.functionName?.includes("testWithHardhat") === true
+  );
+}
+
+/**
+ * Matches the resolved-task frame that calls into a task action.
+ */
+export function isTaskActionBoundaryFrame(frame: StackFrame): boolean {
+  return (
+    frame.location.includes("/internal/core/tasks/resolved-task.") &&
+    frame.functionName?.includes(".run") === true
+  );
+}
+
+/**
+ * Matches the hook-manager frame that calls into hook handlers.
+ */
+export function isHookHandlerBoundaryFrame(frame: StackFrame): boolean {
+  return (
+    frame.location.includes("/internal/core/hook-manager.") &&
+    includesAny(
+      frame.functionName,
+      ".runHandlerChain",
+      ".runSequentialHandlers",
+      ".runParallelHandlers",
+    )
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Execution frame finders
+//
+// These locate the stack frame that identifies who the actual task action or
+// hook handler is, relative to the boundary frame.
+// ---------------------------------------------------------------------------
+
+/**
+ * Finds the task action frame immediately above the resolved-task boundary.
+ */
+export function getTaskExecutionFrame(
+  frames: StackFrame[],
+): StackFrame | undefined {
+  const resolvedTaskRunIndex = frames.findIndex(isTaskActionBoundaryFrame);
+
+  if (resolvedTaskRunIndex === -1) {
+    return;
+  }
+
+  // The frames between `task.run` calls may include other resolved-task.ts
+  // helpers; we want the last frame that does not belong to that file.
+  return frames
+    .slice(0, resolvedTaskRunIndex)
+    .findLast(
+      (frame) =>
+        frame.location.includes("/internal/core/tasks/resolved-task.") ===
+        false,
+    );
+}
+
+/**
+ * Finds the hook handler frame immediately above the hook-manager boundary.
+ */
+export function getHookExecutionFrame(
+  frames: StackFrame[],
+): StackFrame | undefined {
+  const hookManagerIndex = frames.findIndex(isHookHandlerBoundaryFrame);
+
+  if (hookManagerIndex === -1) {
+    return;
+  }
+
+  // The frames between hook-manager calls may include other hook-manager
+  // helpers; we want the last frame that does not belong to that file.
+  return frames
+    .slice(0, hookManagerIndex)
+    .findLast(
+      (frame) =>
+        frame.location.includes("/internal/core/hook-manager.") === false,
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Frame origin / ownership helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true for stack locations owned by packages outside Hardhat.
+ */
+export function isThirdPartyFrame(location: string): boolean {
+  return (
+    location.includes("/node_modules/") &&
+    isFirstPartyPluginFrame(location) === false
+  );
+}
+
+/**
+ * Returns true for stack locations owned by Hardhat or first-party packages.
+ */
+export function isFirstPartyPluginFrame(location: string): boolean {
+  return includesAny(
+    location,
+    "/node_modules/hardhat/",
+    "/node_modules/@nomicfoundation/",
+  );
+}
+
+/**
+ * Returns true when the error stack appears to come from workspace
+ * initialization.
+ */
+export function isWorkspaceInitFilesystemFrame(error: Error): boolean {
+  return error.stack?.includes("/internal/cli/init") ?? false;
+}
+
+/**
+ * Returns true for stack frames owned by EDR provider or stack-trace code.
+ */
+export function isEdrFrame(frame: StackFrame): boolean {
+  return includesAny(
+    frame.location,
+    "/builtin-plugins/network-manager/edr/",
+    "/edr-provider.",
+  );
+}

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

@@ -0,0 +1,140 @@
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+
+import {
+  type UserCodeBoundaryCategory,
+  ErrorCategory,
+  USER_CODE_BOUNDARY_FRAME_MATCHERS,
+} from "./classifier.js";
+import { FrameOrigin, createErrorContext } from "./helpers.js";
+
+/**
+ * Decides if an error should be reported to Sentry or not, based on the
+ * category returned by `classifyError(error)`.
+ *
+ * This first version intentionally uses a permissive policy: it drops clear
+ * noise, reports categories that are likely to be Hardhat bugs, and only uses a
+ * simple stack-shape heuristic for errors coming from user/plugin execution.
+ *
+ * @param error The error.
+ * @param category The result of calling `classifyError(error)`.
+ * @returns `true` if the error should be reported.
+ */
+export function shouldBeReported(
+  error: Error,
+  category: ErrorCategory,
+): boolean {
+  switch (category) {
+    case ErrorCategory.CJS_TO_ESM_MIGRATION_ERROR:
+    case ErrorCategory.HH2_TO_HH3_MIGRATION_ERROR:
+    case ErrorCategory.TYPESCRIPT_SUPPORT_ERROR:
+    case ErrorCategory.DEVELOPMENT_TIME_ERROR:
+    case ErrorCategory.PROVIDER_INTERACTION_ERROR:
+    case ErrorCategory.NETWORK_INTERACTION_ERROR:
+    case ErrorCategory.RUNTIME_ENVIRONMENT_ERROR:
+      return false;
+    case ErrorCategory.HARDHAT_ERROR:
+    case ErrorCategory.TASK_ACTION_ERROR:
+    case ErrorCategory.EDR_ERROR:
+    case ErrorCategory.FILESYSTEM_INTERACTION_ERROR:
+    case ErrorCategory.UNEXPECTED_ERROR:
+      return shouldReportNonUserCodeBoundaryError(error);
+    case ErrorCategory.CONFIG_LOADING_ERROR:
+    case ErrorCategory.CONSOLE_EVALUATION_ERROR:
+    case ErrorCategory.SCRIPT_EXECUTION_ERROR:
+    case ErrorCategory.NODE_TEST_EXECUTION_ERROR:
+    case ErrorCategory.MOCHA_TEST_EXECUTION_ERROR:
+    case ErrorCategory.PLUGIN_TASK_ACTION_ERROR:
+    case ErrorCategory.USER_TASK_ACTION_ERROR:
+    case ErrorCategory.PLUGIN_HOOK_HANDLER_ERROR:
+      return shouldReportUserCodeBoundaryError(error, category);
+  }
+}
+
+/**
+ * Applies the HardhatError descriptor reporting policy for categories that
+ * don't need user-code boundary inspection.
+ */
+function shouldReportNonUserCodeBoundaryError(error: Error): boolean {
+  if (HardhatError.isHardhatError(error)) {
+    return error.descriptor.shouldBeReported ?? false;
+  }
+
+  return true;
+}
+
+/**
+ * Applies the HardhatError descriptor policy before using stack shape to decide
+ * whether a user-code-boundary category should be reported.
+ */
+function shouldReportUserCodeBoundaryError(
+  error: Error,
+  category: UserCodeBoundaryCategory,
+): boolean {
+  if (HardhatError.isHardhatError(error)) {
+    return error.descriptor.shouldBeReported ?? false;
+  }
+
+  return hasHardhatFrameBeforeBoundary(error, category);
+}
+
+/**
+ * User-code-boundary categories mean Hardhat called into user or plugin code.
+ * We don't want to report every plain user script/test/config/plugin failure,
+ * but we do want to report when the stack shows user/plugin code calling back
+ * into Hardhat and then Hardhat, or one of its dependencies, failing.
+ *
+ * To approximate that, this looks for a stack segment before the category's
+ * boundary frame with this shape, from the throw site down:
+ *
+ *   dependency frames, optional
+ *   Hardhat frame, at least one
+ *   external frames, optional
+ *   boundary frame
+ *
+ * In stack-array order, that means scanning from the throw site down to the
+ * boundary and looking for a first-party Hardhat frame. If a user project frame
+ * appears before that Hardhat frame, we treat the failure as user-owned and
+ * don't report it.
+ *
+ * If no boundary frame is found in the error chain, we report the error. The
+ * classifier has already assigned one of these boundary categories, so a
+ * missing boundary frame means the filter couldn't validate the expected stack
+ * shape. For this initial permissive filter, that should fail open to avoid
+ * underreporting due to async stacks, wrapping, or parser limitations.
+ *
+ * We may reconsider making the external frames required in the future, as this
+ * may be too much noise.
+ */
+function hasHardhatFrameBeforeBoundary(
+  error: Error,
+  category: UserCodeBoundaryCategory,
+): boolean {
+  const context = createErrorContext(error);
+  const boundaryMatcher = USER_CODE_BOUNDARY_FRAME_MATCHERS[category];
+  let boundaryFrameFound = false;
+
+  for (const candidate of context.errorChain) {
+    const frames = context.stackFramesByError.get(candidate) ?? [];
+    const boundaryIndex = frames.findIndex(boundaryMatcher);
+
+    if (boundaryIndex === -1) {
+      continue;
+    }
+
+    boundaryFrameFound = true;
+
+    for (let i = 0; i < boundaryIndex; i++) {
+      const frame = frames[i];
+
+      if (frame.origin === FrameOrigin.USER_PROJECT) {
+        return false;
+      }
+
+      if (frame.origin === FrameOrigin.FIRST_PARTY) {
+        return true;
+      }
+    }
+  }
+
+  return !boundaryFrameFound;
+}

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

@@ -0,0 +1,235 @@
+export enum FrameOrigin {
+  FIRST_PARTY = "FIRST_PARTY",
+  THIRD_PARTY = "THIRD_PARTY",
+  USER_PROJECT = "USER_PROJECT",
+  NODE_INTERNAL = "NODE_INTERNAL",
+  OTHER = "OTHER",
+}
+
+export interface StackFrame {
+  functionName?: string;
+  location: string;
+  origin: FrameOrigin;
+}
+
+/**
+ * The error context encapsulates the shared derived data used by classification
+ * and filtering.
+ */
+export interface ErrorContext {
+  error: Error;
+  errorChain: Error[];
+  lowercaseMessageByError: Map<Error, string>;
+  stackFramesByError: Map<Error, StackFrame[]>;
+  allStackFrames: StackFrame[];
+}
+
+/**
+ * Builds the shared derived data used by classification and filtering.
+ *
+ * This keeps stack parsing and cause-chain traversal consistent across
+ * matchers, and avoids recomputing them for every category heuristic.
+ */
+export function createErrorContext(error: Error): ErrorContext {
+  const errorChain = getErrorChain(error);
+  const stackFramesByError = new Map(
+    errorChain.map((candidate) => [candidate, parseStackFrames(candidate)]),
+  );
+
+  return {
+    error,
+    errorChain,
+    lowercaseMessageByError: new Map(
+      errorChain.map((candidate) => [
+        candidate,
+        candidate.message.toLowerCase(),
+      ]),
+    ),
+    stackFramesByError,
+    allStackFrames: errorChain.flatMap(
+      (candidate) => stackFramesByError.get(candidate) ?? [],
+    ),
+  };
+}
+
+/**
+ * This function should be used instead of instanceof because it is robust
+ * under the presence of multiple installations of the same package (e.g.
+ * multiple hardhat-utils versions).
+ *
+ * @param error The error
+ * @param errorClass The error class
+ * @returns true if the error has the same name as the error class
+ */
+export function hasErrorClassName(
+  error: Error,
+  errorClass: abstract new (...args: never[]) => Error,
+): boolean {
+  return error.name === errorClass.name;
+}
+
+/**
+ * Returns true when `value` contains any of the supplied substrings.
+ */
+export function includesAny(
+  value: string | undefined,
+  ...substrings: string[]
+): boolean {
+  return (
+    value !== undefined &&
+    substrings.some((substring) => value.includes(substring))
+  );
+}
+
+/**
+ * Returns a Node-style `code` string from an error or any Error cause.
+ *
+ * Traversal stops when a cause is not an Error, a cycle is detected, or
+ * `maxCauseDepth` is reached.
+ */
+export function getNodeErrorCode(
+  error: Error,
+  maxCauseDepth = 10,
+): string | undefined {
+  const seen = new Set<Error>();
+  let current: Error | undefined = error;
+  let depth = 0;
+
+  while (current !== undefined && depth < maxCauseDepth && !seen.has(current)) {
+    if ("code" in current && typeof current.code === "string") {
+      return current.code;
+    }
+
+    seen.add(current);
+    current = getCause(current);
+    depth++;
+  }
+}
+
+/**
+ * Returns the error and its nested causes in outer-to-inner order.
+ *
+ * Traversal stops when a cause is not an Error, a cycle is detected, or
+ * `maxCauseDepth` is reached.
+ */
+function getErrorChain(error: Error, maxCauseDepth = 10): Error[] {
+  const errors: Error[] = [];
+  const seen = new Set<Error>();
+
+  let current: Error | undefined = error;
+  while (
+    current !== undefined &&
+    errors.length < maxCauseDepth &&
+    seen.has(current) === false
+  ) {
+    errors.push(current);
+    seen.add(current);
+
+    if (current.cause !== undefined && !(current.cause instanceof Error)) {
+      break;
+    }
+
+    current = getCause(current);
+  }
+
+  return errors;
+}
+
+/**
+ * Parses V8-style stack lines into normalized stack frames.
+ *
+ * Unrecognized lines are ignored, and path separators are normalized to `/`
+ * before the frame origin is inferred.
+ */
+function parseStackFrames(error: Error): StackFrame[] {
+  if (error.stack === undefined) {
+    return [];
+  }
+
+  return error.stack
+    .split("\n")
+    .slice(1)
+    .map((line) => line.trim())
+    .map(parseStackFrameLine)
+    .filter((frame): frame is StackFrame => frame !== undefined);
+}
+
+/**
+ * Parses a single V8 stack frame line.
+ */
+function parseStackFrameLine(line: string): StackFrame | undefined {
+  const match =
+    line.match(/^at (?:(.+?) \()?(.+?):\d+:\d+\)?$/) ??
+    line.match(/^at (?:(.+?) \()?(.+?)\)?$/);
+
+  if (match === null || match[2] === undefined) {
+    return;
+  }
+
+  const functionName = match[1] === undefined ? undefined : match[1].trim();
+  const location = normalizeLocation(match[2]);
+
+  return {
+    functionName,
+    location,
+    origin: getFrameOrigin(location),
+  };
+}
+
+/**
+ * Returns the Error-valued cause of an error, ignoring non-Error causes.
+ */
+function getCause(error: Error): Error | undefined {
+  if ("cause" in error && error.cause instanceof Error) {
+    return error.cause;
+  }
+}
+
+/**
+ * Normalizes Windows paths and file URLs enough for substring-based matchers.
+ */
+function normalizeLocation(location: string): string {
+  return location.replaceAll("\\", "/");
+}
+
+/**
+ * Infers who owns a stack frame from its normalized location.
+ */
+function getFrameOrigin(location: string): FrameOrigin {
+  if (
+    startsWithAny(location, "node:", "internal/") ||
+    includesAny(location, "node:internal/")
+  ) {
+    return FrameOrigin.NODE_INTERNAL;
+  }
+
+  if (location.includes("/node_modules/")) {
+    if (
+      includesAny(
+        location,
+        "/node_modules/hardhat/",
+        "/node_modules/@nomicfoundation/",
+      )
+    ) {
+      return FrameOrigin.FIRST_PARTY;
+    }
+
+    return FrameOrigin.THIRD_PARTY;
+  }
+
+  if (
+    startsWithAny(location, "/", "file://", "[eval]") ||
+    /^[A-Za-z]:\//.test(location)
+  ) {
+    return FrameOrigin.USER_PROJECT;
+  }
+
+  return FrameOrigin.OTHER;
+}
+
+/**
+ * Returns true when `value` starts with any of the supplied prefixes.
+ */
+function startsWithAny(value: string, ...prefixes: string[]): boolean {
+  return prefixes.some((prefix) => value.startsWith(prefix));
+}

package/src/internal/cli/telemetry/error-reporter/reporter.ts

@@ -1,9 +1,16 @@
+import type * as ClassifierT from "../error-classification/classifier.js";
+import type * as FilterT from "../error-classification/filter.js";
 import type * as SentryReporterT from "../sentry/reporter.js";
 
 // Sentry's reporter loads a large number of modules, so we only load it if
 // needed.
 let sentryReporterModule: typeof SentryReporterT | undefined;
 
+// The classifier and filter modules are small, but they may import many
+// unrelated things top-level to do their job, so we also load them lazily.
+let classifierModule: typeof ClassifierT | undefined;
+let filterModule: typeof FilterT | undefined;
+
 // We cache the `setCliHardhatConfigPath` to avoid loading the reporter just
 // for this setting. We load it and set the config path if needed.
 let cliHardhatConfigPath: string | undefined;
@@ -29,6 +36,20 @@ export async function sendErrorTelemetry(
   error: Error,
   hint?: { unhandled?: boolean; mechanismType?: string },
 ): Promise<void> {
+  if (classifierModule === undefined) {
+    classifierModule = await import("../error-classification/classifier.js");
+  }
+
+  if (filterModule === undefined) {
+    filterModule = await import("../error-classification/filter.js");
+  }
+
+  const category = classifierModule.classifyError(error);
+
+  if (!filterModule.shouldBeReported(error, category)) {
+    return;
+  }
+
   if (sentryReporterModule === undefined) {
     sentryReporterModule = await import("../sentry/reporter.js");
   }