@nomicfoundation/hardhat-utils 3.0.5 → 4.0.0

package/src/errors/synchronization.ts

@@ -0,0 +1,75 @@
+import { CustomError } from "../error.js";
+
+export class BaseMultiProcessMutexError extends CustomError {
+  constructor(message: string, cause?: Error) {
+    super(message, cause);
+  }
+}
+
+export class InvalidMultiProcessMutexPathError extends BaseMultiProcessMutexError {
+  constructor(mutexPath: string) {
+    super(`The path ${mutexPath} is not a valid absolute path.`);
+  }
+}
+
+export class MultiProcessMutexError extends BaseMultiProcessMutexError {
+  constructor(lockPath: string, cause: Error) {
+    super(`Unexpected error with lock at ${lockPath}: ${cause.message}`, cause);
+  }
+}
+
+export class MultiProcessMutexTimeoutError extends BaseMultiProcessMutexError {
+  constructor(lockPath: string, timeoutMs: number) {
+    super(
+      `Timed out waiting to acquire lock at ${lockPath} after ${timeoutMs}ms`,
+    );
+  }
+}
+
+export class StaleMultiProcessMutexError extends BaseMultiProcessMutexError {
+  constructor(lockPath: string, ownerUid: number | undefined, cause: Error) {
+    const uidInfo = ownerUid !== undefined ? ` (uid: ${ownerUid})` : "";
+    super(
+      `Lock at ${lockPath} appears stale but cannot be removed due to insufficient permissions${uidInfo}. Please remove it manually: ${lockPath}`,
+      cause,
+    );
+  }
+}
+
+export class IncompatibleMultiProcessMutexError extends BaseMultiProcessMutexError {
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class IncompatibleHostnameMultiProcessMutexError extends IncompatibleMultiProcessMutexError {
+  constructor(
+    lockPath: string,
+    foreignHostname: string,
+    currentHostname: string,
+  ) {
+    super(
+      `Lock at ${lockPath} was created by a different host (${foreignHostname}, current: ${currentHostname}). It cannot be verified or removed automatically. Please remove it manually: ${lockPath}`,
+    );
+  }
+}
+
+export class IncompatiblePlatformMultiProcessMutexError extends IncompatibleMultiProcessMutexError {
+  constructor(
+    lockPath: string,
+    foreignPlatform: string,
+    currentPlatform: string,
+  ) {
+    super(
+      `Lock at ${lockPath} was created on a different platform (${foreignPlatform}, current: ${currentPlatform}). It cannot be verified or removed automatically. Please remove it manually: ${lockPath}`,
+    );
+  }
+}
+
+export class IncompatibleUidMultiProcessMutexError extends IncompatibleMultiProcessMutexError {
+  constructor(lockPath: string, foreignUid: number, currentUid: number) {
+    super(
+      `Lock at ${lockPath} is owned by a different user (uid: ${foreignUid}, current: ${currentUid}). It cannot be removed automatically. Please remove it manually: ${lockPath}`,
+    );
+  }
+}

package/src/format.ts

@@ -9,114 +9,31 @@ import {
   renderSectionClose,
 } from "./internal/format.js";
 
-export type TableRow = string[];
-export interface TableDivider {
-  type: "divider";
-}
-export type TableItem = TableRow | TableDivider;
-
-export const divider: TableDivider = { type: "divider" };
-
-/**
- * Formats an array of rows and dividers into a table string.
- *
- * @param items An array of table rows (string arrays) and dividers.
- * Dividers are objects with type: "divider" and will be rendered as table dividers.
- * @returns The formatted table as a string, ready to be rendered.
- *
- * @example
- * ```ts
- * formatTable([
- *   ["Name", "Age"],
- *   divider,
- *   ["Alice", "30"],
- *   ["Bob", "25"],
- *   divider,
- *   ["Average", "27.5"]
- * ]);
- *
- * // =>
- * // | Name    | Age  |
- * // | ------- | ---- |
- * // | Alice   | 30   |
- * // | Bob     | 25   |
- * // | ------- | ---- |
- * // | Average | 27.5 |
- * ```
- */
-export function formatTable(items: TableItem[]): string {
-  const widths: number[] = [];
-  const dataRows: string[][] = [];
-
-  for (const item of items) {
-    if (Array.isArray(item)) {
-      dataRows.push([...item]);
-    }
-  }
-
-  // Calculate maximum width for each column
-  for (const row of dataRows) {
-    for (let i = 0; i < row.length; i++) {
-      while (i >= widths.length) {
-        widths.push(0);
-      }
-      widths[i] = Math.max(widths[i], getStringWidth(row[i]));
-    }
-  }
-
-  const dividerRow = widths.map((width) => "-".repeat(width));
-  const outputRows: string[][] = [];
-
-  for (const item of items) {
-    if (Array.isArray(item)) {
-      const row = [...item];
-      // Pad the row to match the number of columns
-      while (row.length < widths.length) {
-        row.push("");
-      }
-      outputRows.push(row);
-    } else {
-      outputRows.push([...dividerRow]);
-    }
-  }
-
-  outputRows.forEach((row) => {
-    for (let i = 0; i < row.length; i++) {
-      const displayWidth = getStringWidth(row[i]);
-      const actualLength = row[i].length;
-      // Adjust padding to account for difference between display width and actual length
-      row[i] = row[i].padEnd(widths[i] + actualLength - displayWidth);
-    }
-  });
-
-  return outputRows.map((row) => `| ${row.join(" | ")} |`).join("\n");
-}
-
-export interface TableTitleV2 {
+export interface TableTitle {
   type: "title";
   text: string;
 }
 
-export interface TableSectionHeaderV2 {
+export interface TableSectionHeader {
   type: "section-header";
   text: string;
 }
 
-export interface TableHeaderV2 {
+export interface TableHeader {
   type: "header";
   cells: string[];
 }
 
-export interface TableRowV2 {
+export interface TableRow {
   type: "row";
   cells: string[];
 }
 
-export type TableItemV2 =
-  | TableTitleV2
-  | TableSectionHeaderV2
-  | TableHeaderV2
-  | TableRowV2;
+export type TableItem =
+  | TableTitle
+  | TableSectionHeader
+  | TableHeader
+  | TableRow;
 
 /**
  * Formats an array of titles, section headers, headers, and rows into a table
@@ -135,7 +52,7 @@ export type TableItemV2 =
  *
  * @example
  * ```ts
- * formatTableV2([
+ * formatTable([
  *   { type: "title", text: "My Table" },
  *   { type: "section-header", text: "User Data" },
  *   { type: "header", cells: ["Name", "Age", "City"] },
@@ -168,7 +85,7 @@ export type TableItemV2 =
  * // ╚═══════╧═══════════╝
  * ```
  */
-export function formatTableV2(items: TableItemV2[]): string {
+export function formatTable(items: TableItem[]): string {
   if (items.length === 0) {
     return "";
   }

package/src/fs.ts

@@ -642,6 +642,15 @@ export async function exists(absolutePath: string): Promise<boolean> {
  * @throws FileSystemAccessError for any other error.
  */
 export async function copy(source: string, destination: string): Promise<void> {
+  // We must proactively check if the source is a directory.
+  // On modern Linux kernels (6.x+), the `copy_file_range` system call used by
+  // Node.js may return success (0 bytes copied) when the source is a directory
+  // instead of throwing EISDIR. Node.js interprets this 0-byte success as a
+  // completed operation, resulting in no error being thrown.
+  if (await isDirectory(source)) {
+    throw new IsDirectoryError(source, undefined);
+  }
+
   try {
     await fsPromises.copyFile(source, destination);
   } catch (e) {

package/src/global-dir.ts

@@ -1,6 +1,27 @@
 import { ensureDir } from "./fs.js";
 import { generatePaths, HARDHAT_PACKAGE_NAME } from "./internal/global-dir.js";
 
+// Internal override for testing purposes
+let _cacheDirOverride: string | undefined;
+
+/**
+ * Sets a mock cache directory for getCacheDir. This is intended for testing
+ * purposes only, to isolate tests from the real global cache.
+ *
+ * @param dir The directory path to use as the mock cache directory.
+ */
+export function setMockCacheDir(dir: string): void {
+  _cacheDirOverride = dir;
+}
+
+/**
+ * Resets the mock cache directory set by setMockCacheDir.
+ * Call this in test cleanup to restore normal behavior.
+ */
+export function resetMockCacheDir(): void {
+  _cacheDirOverride = undefined;
+}
+
 /**
  * Returns the configuration directory path for a given package (defaults to "hardhat").
  * Ensures that the directory exists before returning the path.
@@ -21,6 +42,10 @@ export async function getConfigDir(
  * Returns the cache directory path for a given package (defaults to "hardhat").
  * Ensures that the directory exists before returning the path.
  *
+ * For testing purposes, the cache directory can be overridden using
+ * setMockCacheDir(). This is intended to isolate tests from the real
+ * global cache.
+ *
  * @param packageName The name of the package for which to generate paths. Defaults to "hardhat" if no package name is provided.
  * @returns The path to the hardhat cache directory.
  * @throws FileSystemAccessError for any error.
@@ -28,6 +53,12 @@ export async function getConfigDir(
 export async function getCacheDir(
   packageName: string = HARDHAT_PACKAGE_NAME,
 ): Promise<string> {
+  // Allow override for testing purposes
+  if (_cacheDirOverride !== undefined) {
+    await ensureDir(_cacheDirOverride);
+    return _cacheDirOverride;
+  }
+
   const { cache } = await generatePaths(packageName);
   await ensureDir(cache);
   return cache;

package/src/internal/format.ts

@@ -1,4 +1,4 @@
-import type { TableItemV2 } from "../format.js";
+import type { TableItem } from "../format.js";
 
 /**
  * Calculate the display width of a string by removing ANSI escape codes.
@@ -17,7 +17,7 @@ export function getStringWidth(str: string): number {
  * Calculates the minimum width needed by each column in the table
  * to fit its content (accounting for ANSI color codes).
  */
-export function getColumnWidths(items: TableItemV2[]): number[] {
+export function getColumnWidths(items: TableItem[]): number[] {
   const columnWidths: number[] = [];
 
   for (const item of items) {
@@ -53,7 +53,7 @@ export function getContentWidth(columnWidths: number[]): number {
  * Each title/header is padded by 1 space on each side.
  * Accounts for ANSI color codes.
  */
-export function getHeadingWidth(items: TableItemV2[]): number {
+export function getHeadingWidth(items: TableItem[]): number {
   let headingWidth = 0;
   for (const item of items) {
     if (item.type === "section-header" || item.type === "title") {

package/src/internal/lang.ts

@@ -53,3 +53,39 @@ export function deepMergeImpl<T extends object, S extends object>(
 
   return result;
 }
+
+let cachedCustomEqual: ((a: unknown, b: unknown) => boolean) | undefined;
+
+/**
+ * Performs a custom deep equality check using `fast-equals` with specific overrides.
+ *
+ * @param x The first value to compare.
+ * @param y The second value to compare.
+ * @returns A promise that resolves to true if the values are deeply equal, false otherwise.
+ */
+export async function customFastEqual<T>(x: T, y: T): Promise<boolean> {
+  if (cachedCustomEqual !== undefined) {
+    return cachedCustomEqual(x, y);
+  }
+
+  const { createCustomEqual } = await import("fast-equals");
+
+  cachedCustomEqual = createCustomEqual({
+    createCustomConfig: (defaultConfig) => ({
+      areTypedArraysEqual: (a, b, state) => {
+        // Node.js uses an internal pool for small Buffers, so multiple Buffers can
+        // share the same underlying ArrayBuffer while having different byteOffsets.
+        // Structural equality checks (e.g. deep equality) consider offset and length
+        // and may fail even if the contents are identical.
+        // We use Buffer.equals() to compare content only.
+        if (Buffer.isBuffer(a) && Buffer.isBuffer(b)) {
+          return a.equals(b);
+        }
+
+        return defaultConfig.areTypedArraysEqual(a, b, state);
+      },
+    }),
+  });
+
+  return cachedCustomEqual(x, y);
+}

package/src/internal/request.ts

@@ -2,6 +2,7 @@ import type { DispatcherOptions, RequestOptions } from "../request.js";
 import type EventEmitter from "node:events";
 import type UndiciT from "undici";
 
+import crypto from "node:crypto";
 import path from "node:path";
 
 import { mkdir } from "../fs.js";
@@ -24,7 +25,7 @@ export async function generateTempFilePath(filePath: string): Promise<string> {
   return path.format({
     dir,
     ext,
-    name: `tmp-${name}`,
+    name: `tmp-${name}-${crypto.randomBytes(8).toString("hex")}`,
   });
 }
 

package/src/lang.ts

@@ -1,4 +1,8 @@
-import { deepMergeImpl, getDeepCloneFunction } from "./internal/lang.js";
+import {
+  customFastEqual,
+  deepMergeImpl,
+  getDeepCloneFunction,
+} from "./internal/lang.js";
 
 /**
  * Creates a deep clone of the provided value.
@@ -20,9 +24,7 @@ export async function deepClone<T>(value: T): Promise<T> {
  * @returns True if the values are deeply equal, false otherwise.
  */
 export async function deepEqual<T>(x: T, y: T): Promise<boolean> {
-  const { deepEqual: _deepEqual } = await import("fast-equals");
-
-  return _deepEqual(x, y);
+  return customFastEqual(x, y);
 }
 
 /**

package/src/request.ts

@@ -1,8 +1,9 @@
 import type EventEmitter from "node:events";
+import type { FileHandle } from "node:fs/promises";
 import type { ParsedUrlQueryInput } from "node:querystring";
 import type UndiciT from "undici";
 
-import fs from "node:fs";
+import { open } from "node:fs/promises";
 import querystring from "node:querystring";
 import stream from "node:stream/promises";
 
@@ -12,7 +13,7 @@ import {
   RequestError,
   DispatcherError,
 } from "./errors/request.js";
-import { move } from "./fs.js";
+import { move, remove } from "./fs.js";
 import {
   generateTempFilePath,
   getBaseDispatcherOptions,
@@ -217,11 +218,12 @@ export async function download(
   dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
 ): Promise<void> {
   let statusCode: number | undefined;
+  let tempFilePath: string | undefined;
 
   try {
     /* 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.
+    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(
@@ -236,13 +238,34 @@ export async function download(
       throw new Error(await body.text());
     }
 
-    const tempFilePath = await generateTempFilePath(destination);
-    const fileStream = fs.createWriteStream(tempFilePath);
-    await stream.pipeline(body, fileStream);
+    tempFilePath = await generateTempFilePath(destination);
+
+    let fileHandle: FileHandle | undefined;
+
+    try {
+      fileHandle = await open(tempFilePath, "w");
+
+      const fileStream = fileHandle.createWriteStream();
+
+      await stream.pipeline(body, fileStream);
+    } finally {
+      // NOTE: Historically, not closing the file handle caused issues on Windows,
+      // for example, when trying to move the file previously written to by this function
+      await fileHandle?.close();
+    }
+
     await move(tempFilePath, destination);
   } catch (e) {
     ensureError(e);
 
+    if (tempFilePath !== undefined) {
+      try {
+        await remove(tempFilePath);
+      } catch {
+        // Best-effort: file may not exist or may have already been moved
+      }
+    }
+
     handleError(e, url);
 
     throw new DownloadError(url, e);