@nomicfoundation/hardhat-utils 3.0.0-next.9 → 3.0.1

package/src/fs.ts

@@ -56,8 +56,8 @@ export async function getRealPath(absolutePath: string): Promise<string> {
  */
 export async function getAllFilesMatching(
   dirFrom: string,
-  matches?: (absolutePathToFile: string) => boolean,
-  directoryFilter?: (absolutePathToDir: string) => boolean,
+  matches?: (absolutePathToFile: string) => Promise<boolean> | boolean,
+  directoryFilter?: (absolutePathToDir: string) => Promise<boolean> | boolean,
 ): Promise<string[]> {
   const dirContent = await readdirOrEmpty(dirFrom);
 
@@ -67,7 +67,7 @@ export async function getAllFilesMatching(
       if (await isDirectory(absolutePathToFile)) {
         if (
           directoryFilter === undefined ||
-          directoryFilter(absolutePathToFile)
+          (await directoryFilter(absolutePathToFile))
         ) {
           return getAllFilesMatching(
             absolutePathToFile,
@@ -77,7 +77,7 @@ export async function getAllFilesMatching(
         }
 
         return [];
-      } else if (matches === undefined || matches(absolutePathToFile)) {
+      } else if (matches === undefined || (await matches(absolutePathToFile))) {
         return absolutePathToFile;
       } else {
         return [];
@@ -93,7 +93,7 @@ export async function getAllFilesMatching(
  * satisfy the specified condition, returning their absolute paths. Once a
  * directory is found, its subdirectories are not searched.
  *
- * Note: dirFrom is never returned, nor `matches` is called on it.
+ * Note: dirFrom is never returned, nor is `matches` called on it.
  *
  * @param dirFrom The absolute path of the directory to start the search from.
  * @param matches A function to filter directories (not files).
@@ -105,7 +105,7 @@ export async function getAllFilesMatching(
  */
 export async function getAllDirectoriesMatching(
   dirFrom: string,
-  matches?: (absolutePathToDir: string) => boolean,
+  matches?: (absolutePathToDir: string) => Promise<boolean> | boolean,
 ): Promise<string[]> {
   const dirContent = await readdirOrEmpty(dirFrom);
 
@@ -116,7 +116,7 @@ export async function getAllDirectoriesMatching(
         return [];
       }
 
-      if (matches === undefined || matches(absolutePathToFile)) {
+      if (matches === undefined || (await matches(absolutePathToFile))) {
         return absolutePathToFile;
       }
 
@@ -540,7 +540,9 @@ export const ensureDir: typeof mkdir = mkdir;
  */
 export async function mkdtemp(prefix: string): Promise<string> {
   try {
-    return await fsPromises.mkdtemp(path.join(tmpdir(), prefix));
+    return await getRealPath(
+      await fsPromises.mkdtemp(path.join(tmpdir(), prefix)),
+    );
   } catch (e) {
     ensureNodeErrnoExceptionError(e);
     throw new FileSystemAccessError(e.message, e);
@@ -832,6 +834,39 @@ export async function findUp(
   }
 }
 
+/**
+ * This function uses some heuristics to check if a file is binary by reading the first bytesToCheck bytes from the file.
+ */
+export async function isBinaryFile(
+  filePath: string,
+  bytesToCheck = 8000,
+): Promise<boolean> {
+  const fd = await fsPromises.open(filePath, "r");
+
+  const buffer = Buffer.alloc(bytesToCheck);
+  const { bytesRead } = await fd.read(buffer, 0, bytesToCheck, 0);
+  await fd.close();
+
+  let nonPrintable = 0;
+  for (let i = 0; i < bytesRead; i++) {
+    const byte = buffer[i];
+
+    // Allow common text ranges: tab, newline, carriage return, and printable ASCII
+    if (
+      byte === 9 || // tab
+      byte === 10 || // newline
+      byte === 13 || // carriage return
+      (byte >= 32 && byte <= 126)
+    ) {
+      continue;
+    }
+    nonPrintable++;
+  }
+
+  // Heuristic: if more than ~30% of bytes are non-printable, assume binary
+  return nonPrintable / bytesRead > 0.3;
+}
+
 export {
   FileNotFoundError,
   FileSystemAccessError,

package/src/internal/bytecode.ts

@@ -12,7 +12,7 @@ import { isAddress } from "../eth.js";
 export interface Artifact {
   bytecode: string;
   linkReferences: {
-    [sourceName: string]: {
+    [inputSourceName: string]: {
       [libraryName: string]: Array<{ start: number; length: number }>;
     };
   };

package/src/lang.ts

@@ -71,3 +71,39 @@ export function isObject(
 export async function sleep(seconds: number): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
 }
+
+/**
+ * Binds all methods of an object to the object itself, so that they can be
+ * assigned to an independent variable and still work.
+ *
+ * @param obj The object, which can be an instance of a class.
+ */
+export function bindAllMethods<ObjectT extends object>(obj: ObjectT): void {
+  const prototype = Object.getPrototypeOf(obj);
+  const prototypeKeys =
+    prototype !== null ? Object.getOwnPropertyNames(prototype) : [];
+
+  const keys = [...prototypeKeys, ...Object.getOwnPropertyNames(obj)];
+
+  /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
+    typescript can't express this in a safe way, so we use any here */
+  const objAsAny = obj as any;
+
+  // Exclude methods that should not be rebound (constructor, Object.prototype methods, etc.)
+  const EXCLUDED_METHODS = [
+    "constructor",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "toLocaleString",
+    "toString",
+    "valueOf",
+  ];
+
+  for (const key of keys) {
+    const val = objAsAny[key];
+    if (typeof val === "function" && !EXCLUDED_METHODS.includes(key)) {
+      objAsAny[key] = val.bind(obj);
+    }
+  }
+}

package/src/package.ts

@@ -10,6 +10,31 @@ import { exists, findUp, getRealPath, readJsonFile } from "./fs.js";
 import { getFilePath } from "./internal/package.js";
 import { ensureTrailingSlash } from "./string.js";
 
+/* Adapted from `resolve.exports`. License: https://github.com/lukeed/resolve.exports/blob/master/license */
+
+export type PackageExports =
+  | PackageExportPath
+  | {
+      [path: PackageExportsEntry]: PackageExportsValue;
+      [condition: string]: PackageExportsValue;
+    };
+
+/** Allows "." and "./{name}" */
+export type PackageExportsEntry = `.${string}`;
+
+/** Internal path */
+export type PackageExportPath = `./${string}`;
+
+export type PackageExportsValue =
+  | PackageExportPath
+  | null
+  | {
+      [condition: string]: PackageExportsValue;
+    }
+  | PackageExportsValue[];
+
+/* End of `resolve.exports` adaptation */
+
 /**
  * The structure of a `package.json` file. This is a subset of the actual
  * `package.json` file, if you need to access other fields you add them here.
@@ -22,6 +47,7 @@ export interface PackageJson {
   engines?: {
     node?: string;
   };
+  exports?: PackageExports;
   dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
   peerDependencies?: Record<string, string>;

package/src/panic-errors.ts

@@ -0,0 +1,35 @@
+import { numberToHexString } from "./hex.js";
+
+export function panicErrorCodeToMessage(errorCode: bigint): string {
+  const reason = panicErrorCodeToReason(errorCode);
+
+  if (reason !== undefined) {
+    return `reverted with panic code ${numberToHexString(errorCode)} (${reason})`;
+  }
+
+  return `reverted with unknown panic code ${numberToHexString(errorCode)}`;
+}
+
+function panicErrorCodeToReason(errorCode: bigint): string | undefined {
+  // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- we are only covering some of the integer range
+  switch (errorCode) {
+    case 0x1n:
+      return "Assertion error";
+    case 0x11n:
+      return "Arithmetic operation overflowed outside of an unchecked block";
+    case 0x12n:
+      return "Division or modulo division by zero";
+    case 0x21n:
+      return "Tried to convert a value into an enum, but the value was too big or negative";
+    case 0x22n:
+      return "Incorrectly encoded storage byte array";
+    case 0x31n:
+      return ".pop() was called on an empty array";
+    case 0x32n:
+      return "Array accessed at an out-of-bounds or negative index";
+    case 0x41n:
+      return "Too much memory was allocated, or an array was created that is too large";
+    case 0x51n:
+      return "Called a zero-initialized variable of internal function type";
+  }
+}

package/src/path.ts

@@ -22,7 +22,7 @@ export function resolveFromRoot(root: string, target: string): string {
  * Tries to return a shorter version of the path if its inside the given folder.
  *
  * This is useful for displaying paths in the terminal, as they can be shorter
- * when they are insidde the current working directory. For example, if the
+ * when they are inside the current working directory. For example, if the
  * current working directory is `/home/user/project`, and the path is
  * `/home/user/project/contracts/File.sol`, the shorter path is
  * `contracts/File.sol`.
@@ -31,11 +31,21 @@ export function resolveFromRoot(root: string, target: string): string {
  * @param folder The absolute path to the folder.
  * @returns The shorter path, if possible, or the original path.
  */
-export function shortenPath(
-  absolutePath: string,
-  folder: string = process.cwd(),
-): string {
-  const relativePath = path.relative(folder, absolutePath);
+export function shortenPath(absolutePath: string): string {
+  const cwd = process.cwd();
+  let relativePath = path.relative(cwd, absolutePath);
+
+  if (relativePath === "..") {
+    return ".." + path.sep;
+  }
+
+  if (
+    !relativePath.startsWith(".." + path.sep) &&
+    !relativePath.startsWith("." + path.sep) &&
+    !path.isAbsolute(relativePath)
+  ) {
+    relativePath = "." + path.sep + relativePath;
+  }
 
   if (relativePath.length < absolutePath.length) {
     return relativePath;

package/src/request.ts

@@ -62,13 +62,22 @@ export interface RequestOptions {
   abortSignal?: AbortSignal | EventEmitter;
 }
 
+export interface HttpResponse {
+  statusCode: number;
+  body: {
+    json(): Promise<any>;
+    text(): Promise<string>;
+  };
+}
+
 /**
  * Performs a HTTP request.
  *
  * @param url The url to make the request to.
  * @param requestOptions The options to configure the request. See {@link RequestOptions}.
  * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
- * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @returns An object containing the status code and the response body. The body can be accessed as JSON or text.
+ * `body` can not be consumed twice. For example, calling `text()` after `json()` throws `TypeError`.
  * @throws ConnectionRefusedError If the connection is refused by the server.
  * @throws RequestTimeoutError If the request times out.
  * @throws RequestError If the request fails for any other reason.
@@ -77,7 +86,7 @@ export async function getRequest(
   url: string,
   requestOptions: RequestOptions = {},
   dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
-): Promise<UndiciT.Dispatcher.ResponseData> {
+): Promise<HttpResponse> {
   const { request } = await import("undici");
 
   try {
@@ -106,7 +115,8 @@ export async function getRequest(
  * @param body The body of the request, represented as an object.
  * @param requestOptions The options to configure the request. See {@link RequestOptions}.
  * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
- * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @returns An object containing the status code and the response body. The body can be accessed as JSON or text.
+ * `body` can not be consumed twice. For example, calling `text()` after `json()` throws `TypeError`.
  * @throws ConnectionRefusedError If the connection is refused by the server.
  * @throws RequestTimeoutError If the request times out.
  * @throws RequestError If the request fails for any other reason.
@@ -116,7 +126,7 @@ export async function postJsonRequest(
   body: unknown,
   requestOptions: RequestOptions = {},
   dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
-): Promise<UndiciT.Dispatcher.ResponseData> {
+): Promise<HttpResponse> {
   const { request } = await import("undici");
 
   try {
@@ -150,7 +160,8 @@ export async function postJsonRequest(
  * @param body The body of the request, represented as an object.
  * @param requestOptions The options to configure the request. See {@link RequestOptions}.
  * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
- * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @returns An object containing the status code and the response body. The body can be accessed as JSON or text.
+ * `body` can not be consumed twice. For example, calling `text()` after `json()` throws `TypeError`.
  * @throws ConnectionRefusedError If the connection is refused by the server.
  * @throws RequestTimeoutError If the request times out.
  * @throws RequestError If the request fails for any other reason.
@@ -160,7 +171,7 @@ export async function postFormRequest(
   body: unknown,
   requestOptions: RequestOptions = {},
   dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
-): Promise<UndiciT.Dispatcher.ResponseData> {
+): Promise<HttpResponse> {
   const { request } = await import("undici");
 
   try {
@@ -208,11 +219,16 @@ export async function download(
   let statusCode: number | undefined;
 
   try {
-    const response = await getRequest(
+    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    -- We need the full Dispatcher.ResponseData here for stream.pipeline,
+    but HttpResponse doesn’t expose the raw ReadableStream.
+    TODO: wrap undici's request so we can keep the public API
+    strictly typed without falling back to Undici types. */
+    const response = (await getRequest(
       url,
       requestOptions,
       dispatcherOrDispatcherOptions,
-    );
+    )) as UndiciT.Dispatcher.ResponseData;
     const { body } = response;
     statusCode = response.statusCode;
 
@@ -331,6 +347,37 @@ export function isValidUrl(url: string): boolean {
   }
 }
 
+/**
+ * Returns the proxy URL from environment variables based on the target URL.
+ * For HTTPS URLs, checks `https_proxy` then `HTTPS_PROXY`.
+ * For HTTP URLs, checks `http_proxy` then `HTTP_PROXY`.
+ * Falls back to the other protocol's proxy if none found.
+ *
+ * @param url The target URL to determine proxy for.
+ * @returns The proxy URL, or `undefined` if none are set.
+ */
+export function getProxyUrl(url: string): string | undefined {
+  const { protocol } = new URL(url);
+
+  if (protocol === "https:") {
+    return (
+      process.env.https_proxy ??
+      process.env.HTTPS_PROXY ??
+      process.env.http_proxy ??
+      process.env.HTTP_PROXY
+    );
+  } else if (protocol === "http:") {
+    return (
+      process.env.http_proxy ??
+      process.env.HTTP_PROXY ??
+      process.env.https_proxy ??
+      process.env.HTTPS_PROXY
+    );
+  }
+
+  return undefined;
+}
+
 export {
   ConnectionRefusedError,
   DispatcherError,

package/src/stream.ts

@@ -1,7 +1,7 @@
 import { Writable } from "node:stream";
 
 /**
- * Creates a Tansform that writes everything to actualWritable, without closing it
+ * Creates a Transform that writes everything to actualWritable, without closing it
  * when finished.
  *
  * This is useful to pipe things to stdout, without closing it, while being

package/src/subprocess.ts

@@ -33,7 +33,7 @@ export async function spawnDetachedSubProcess(
   const subprocessArgs = [absolutePathToSubProcessFile, ...args];
 
   if (absolutePathToSubProcessFile.endsWith(".ts")) {
-    subprocessArgs.unshift("--import", "tsx/esm");
+    subprocessArgs.unshift("--import", import.meta.resolve("tsx/esm"));
   }
 
   const subprocess = spawn(process.execPath, subprocessArgs, {

package/src/synchronization.ts

@@ -15,6 +15,7 @@ import debug from "debug";
 
 import { ensureNodeErrnoExceptionError } from "./error.js";
 import { FileSystemAccessError } from "./errors/fs.js";
+import { readUtf8File } from "./fs.js";
 import { sleep } from "./lang.js";
 
 const log = debug("hardhat:util:multi-process-mutex");
@@ -48,6 +49,13 @@ export class MultiProcessMutex {
         log(
           `Current mutex file is too old, removing it at path '${this.#mutexFilePath}'`,
         );
+
+        this.#deleteMutexFile();
+      } else if (await this.#isMutexProcessOwnerDead()) {
+        log(
+          `The process owning the mutex file no longer exists. Removing mutex file at '${this.#mutexFilePath}'.`,
+        );
+
         this.#deleteMutexFile();
       } else {
         // wait
@@ -59,7 +67,10 @@ export class MultiProcessMutex {
   async #tryToAcquireMutex() {
     try {
       // Create a file only if it does not exist
-      fs.writeFileSync(this.#mutexFilePath, "", { flag: "wx+" });
+      fs.writeFileSync(this.#mutexFilePath, process.pid.toString(), {
+        flag: "wx+",
+      });
+
       return true;
     } catch (e) {
       ensureNodeErrnoExceptionError(e);
@@ -80,6 +91,8 @@ export class MultiProcessMutex {
       return await f();
     } finally {
       // Release the mutex
+      // Note: if a process dies, its `finally` block never executes, and the process hangs indefinitely since no response is received.
+      // To handle this, we use the function `isMutexProcessOwnerDead`.
       log(`Mutex released at path '${this.#mutexFilePath}'`);
       this.#deleteMutexFile();
       log(`Mutex released at path '${this.#mutexFilePath}'`);
@@ -123,4 +136,80 @@ export class MultiProcessMutex {
       throw new FileSystemAccessError(e.message, e);
     }
   }
+
+  async #isMutexProcessOwnerDead(): Promise<boolean> {
+    let mutexPid: string;
+
+    try {
+      // If the file doesn't exist, it means the owning process deleted it
+      mutexPid = await readUtf8File(this.#mutexFilePath);
+    } catch (_e) {
+      return false;
+    }
+
+    try {
+      process.kill(parseInt(mutexPid, 10), 0);
+    } catch (e) {
+      ensureNodeErrnoExceptionError(e);
+
+      if (e.code === "ESRCH") {
+        // The process owning the mutex no longer exists
+        return true;
+      }
+    }
+
+    return false;
+  }
+}
+
+/**
+ * A class that implements an asynchronous mutex (mutual exclusion) lock.
+ *
+ * The mutex ensures that only one asynchronous operation can be executed at a time,
+ * providing exclusive access to a shared resource.
+ */
+export class AsyncMutex {
+  #acquired = false;
+  readonly #queue: Array<() => void> = [];
+
+  /**
+   * Acquires the mutex, running the provided function exclusively,
+   * and releasing it afterwards.
+   *
+   * @param f The function to run.
+   * @returns The result of the function.
+   */
+  public async exclusiveRun<ReturnT>(
+    f: () => ReturnT,
+  ): Promise<Awaited<ReturnT>> {
+    const release = await this.#acquire();
+
+    try {
+      return await f();
+    } finally {
+      await release();
+    }
+  }
+
+  /**
+   * Acquires the mutex, returning a function that releases it.
+   */
+  async #acquire(): Promise<() => Promise<void>> {
+    if (!this.#acquired) {
+      this.#acquired = true;
+      return async () => {
+        this.#acquired = false;
+        const next = this.#queue.shift();
+        if (next !== undefined) {
+          next();
+        }
+      };
+    }
+
+    return new Promise<() => Promise<void>>((resolve) => {
+      this.#queue.push(() => {
+        resolve(this.#acquire());
+      });
+    });
+  }
 }