@nomicfoundation/hardhat-utils 3.0.3 → 3.0.5

package/src/internal/format.ts

@@ -0,0 +1,260 @@
+import type { TableItemV2 } from "../format.js";
+
+/**
+ * Calculate the display width of a string by removing ANSI escape codes.
+ *
+ * NOTE: This implementation only removes basic ANSI color/style codes and may
+ * not handle all escape sequences (e.g., cursor movement, complex control
+ * sequences).
+ */
+export function getStringWidth(str: string): number {
+  // Remove ANSI escape codes if present
+  const stripped = str.replace(/\u001b\[[0-9;]*m/g, "");
+  return stripped.length;
+}
+
+/**
+ * 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[] {
+  const columnWidths: number[] = [];
+
+  for (const item of items) {
+    if (item.type === "row" || item.type === "header") {
+      item.cells.forEach((cell, i) => {
+        columnWidths[i] = Math.max(columnWidths[i] ?? 0, getStringWidth(cell));
+      });
+    }
+  }
+
+  return columnWidths;
+}
+
+/**
+ * Calculates the inner width needed to fit the rows and headers
+ * (excludes borders, which are added during rendering).
+ *
+ * Each column is padded by 1 space on each side, and columns are
+ * separated by " │ " (3 spaces).
+ */
+export function getContentWidth(columnWidths: number[]): number {
+  return (
+    columnWidths.reduce((sum, w) => sum + w, 0) +
+    (columnWidths.length - 1) * 3 +
+    2
+  );
+}
+
+/**
+ * Calculates the inner width needed to fit titles and section headers
+ * (excludes borders, which are added during rendering).
+ *
+ * Each title/header is padded by 1 space on each side.
+ * Accounts for ANSI color codes.
+ */
+export function getHeadingWidth(items: TableItemV2[]): number {
+  let headingWidth = 0;
+  for (const item of items) {
+    if (item.type === "section-header" || item.type === "title") {
+      headingWidth = Math.max(headingWidth, getStringWidth(item.text) + 2);
+    }
+  }
+  return headingWidth;
+}
+
+/**
+ * Calculates the width needed for unused columns when a row/header has fewer
+ * cells than the total column count (e.g., if table has 6 columns but row
+ * only has 2 cells, calculates space for the remaining 4 columns).
+ */
+export function getUnusedColumnsWidth(
+  columnWidths: number[],
+  previousCellCount: number,
+): number {
+  const remainingWidths = columnWidths.slice(previousCellCount);
+  return remainingWidths.reduce((sum, w) => sum + w + 3, 0) - 3;
+}
+
+/**
+ * Renders a horizontal rule segment by repeating a character for each column
+ * with padding, joined by a separator (e.g., "─────┼─────┼─────").
+ */
+export function renderRuleSegment(
+  columnWidths: number[],
+  char: string,
+  joiner: string,
+): string {
+  return columnWidths.map((w) => char.repeat(w + 2)).join(joiner);
+}
+
+/**
+ * Renders a complete horizontal rule with left and right borders
+ * (e.g., "╟─────┼─────┼─────╢").
+ */
+export function renderHorizontalRule(
+  leftBorder: string,
+  columnWidths: number[],
+  char: string,
+  joiner: string,
+  rightBorder: string,
+): string {
+  return (
+    leftBorder + renderRuleSegment(columnWidths, char, joiner) + rightBorder
+  );
+}
+
+/**
+ * Renders a content line containing cells from either a header or row.
+ *
+ * Handles two cases:
+ * - Full width: When all columns are used, cells are separated by " │ " and
+ *   line ends with " ║" (e.g., "║ cell1 │ cell2 │ cell3 ║")
+ * - Short line: When fewer columns are used, active cells are followed by
+ *   " │ " and empty space, ending with "║" (e.g., "║ cell1 │ cell2 │       ║")
+ *
+ * Accounts for ANSI color codes when padding cells.
+ */
+export function renderContentLine(
+  cells: string[],
+  columnWidths: number[],
+  currentCellCount: number,
+): string {
+  if (currentCellCount === columnWidths.length) {
+    return (
+      "║ " +
+      cells
+        .map((cell, j) => {
+          const displayWidth = getStringWidth(cell);
+          const actualLength = cell.length;
+          // Adjust padding to account for ANSI escape codes
+          return cell.padEnd(columnWidths[j] + actualLength - displayWidth);
+        })
+        .join(" │ ") +
+      " ║"
+    );
+  } else {
+    const usedWidths = columnWidths.slice(0, currentCellCount);
+    const remainingWidth = getUnusedColumnsWidth(
+      columnWidths,
+      currentCellCount,
+    );
+    return (
+      "║ " +
+      cells
+        .map((cell, j) => {
+          const displayWidth = getStringWidth(cell);
+          const actualLength = cell.length;
+          // Adjust padding to account for ANSI escape codes
+          return cell.padEnd(usedWidths[j] + actualLength - displayWidth);
+        })
+        .join(" │ ") +
+      " │ " +
+      " ".repeat(remainingWidth + 1) +
+      "║"
+    );
+  }
+}
+
+/**
+ * Renders the horizontal rule that appears above a header row.
+ *
+ * Handles three cases:
+ * - Transition rule: When going from more columns to fewer, shows ┴ marks
+ *   where columns collapse (e.g., "╟───┼───┼───┴───┴───╢")
+ * - Full width: When header uses all columns (e.g., "╟───┬───┬───╢" or "╟───┼───┼───╢")
+ * - Short header: When header uses fewer columns than max (e.g., "╟───┬─────────╢")
+ *
+ * The innerJoiner determines the separator character: ┬ after section-header, ┼ otherwise.
+ */
+export function renderHeaderOpen(
+  columnWidths: number[],
+  currentCellCount: number,
+  innerJoiner: string,
+  needsTransition: boolean,
+): string {
+  if (needsTransition) {
+    const usedWidths = columnWidths.slice(0, currentCellCount);
+    const collapsingWidths = columnWidths.slice(currentCellCount);
+    return (
+      "╟" +
+      renderRuleSegment(usedWidths, "─", "┼") +
+      "┼" +
+      renderRuleSegment(collapsingWidths, "─", "┴") +
+      "╢"
+    );
+  } else if (currentCellCount === columnWidths.length) {
+    return renderHorizontalRule("╟", columnWidths, "─", innerJoiner, "╢");
+  } else {
+    const usedWidths = columnWidths.slice(0, currentCellCount);
+    const remainingWidth = getUnusedColumnsWidth(
+      columnWidths,
+      currentCellCount,
+    );
+    return (
+      "╟" +
+      renderRuleSegment(usedWidths, "─", innerJoiner) +
+      innerJoiner +
+      "─".repeat(remainingWidth + 2) +
+      "╢"
+    );
+  }
+}
+
+/**
+ * Renders the horizontal rule that appears above a row.
+ *
+ * Handles two cases:
+ * - Full width: When row uses all columns, renders with ┼ joiners and
+ *   ends with ╢ (e.g., "╟───┼───┼───╢")
+ * - Short row: When row uses fewer columns, renders active columns with
+ *   ┼ joiners, ends with ┤, then fills remaining space and ends with ║
+ *   (e.g., "╟───┼───┤         ║")
+ */
+export function renderRowSeparator(
+  columnWidths: number[],
+  currentCellCount: number,
+): string {
+  if (currentCellCount === columnWidths.length) {
+    return renderHorizontalRule("╟", columnWidths, "─", "┼", "╢");
+  } else {
+    // Short row - ends with ┤ instead of ╢
+    const usedWidths = columnWidths.slice(0, currentCellCount);
+    const remainingWidth = getUnusedColumnsWidth(
+      columnWidths,
+      currentCellCount,
+    );
+    return (
+      "╟" +
+      renderRuleSegment(usedWidths, "─", "┼") +
+      "┤" +
+      " ".repeat(remainingWidth + 2) +
+      "║"
+    );
+  }
+}
+
+/**
+ * Renders the section's bottom border, placing ╧ marks under column
+ * separators where the last row/header had cells (e.g., if the last row
+ * looked like "║ a │ b │       ║", the bottom border would be
+ *             "╚═══╧═══╧═══════╝").
+ */
+export function renderSectionClose(
+  columnWidths: number[],
+  previousCellCount: number,
+): string {
+  if (previousCellCount === columnWidths.length) {
+    return renderHorizontalRule("╚", columnWidths, "═", "╧", "╝");
+  } else {
+    const usedWidths = columnWidths.slice(0, previousCellCount);
+    const unusedWidth = getUnusedColumnsWidth(columnWidths, previousCellCount);
+    return (
+      "╚" +
+      renderRuleSegment(usedWidths, "═", "╧") +
+      "╧" +
+      renderRuleSegment([unusedWidth], "═", "") +
+      "╝"
+    );
+  }
+}

package/src/internal/lang.ts

@@ -13,36 +13,41 @@ export async function getDeepCloneFunction(): Promise<<T>(input: T) => T> {
   return clone;
 }
 
-export function deepMergeImpl<T extends object, U extends object>(
+export function deepMergeImpl<T extends object, S extends object>(
   target: T,
-  source: U,
-): T & U {
+  source: S,
+  shouldOverwriteUndefined: boolean,
+): T & S {
   /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-  -- The result is expected to include properties from both target and source,
-  but initially only target is spread in, so a cast is needed. */
-  const result = { ...target } as T & U;
+  -- Result will include properties from both T and S, but starts with only T */
+  const result = { ...target } as T & S;
 
-  /*  eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-  -- TypeScript cannot infer the correct union of string and symbol keys, but all keys come from U */
+  /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  -- All keys come from S, TypeScript can't infer the union of string and symbol keys */
   const keys = [
     ...Object.keys(source),
     ...Object.getOwnPropertySymbols(source),
-  ] as Array<keyof U>;
+  ] as Array<keyof S>;
 
   for (const key of keys) {
     if (
       isObject(source[key]) &&
-      // Only merge recursively objects that are not class instances
+      // Only merge plain objects, not class instances
       Object.getPrototypeOf(source[key]) === Object.prototype
     ) {
       /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      -- The call signature expects the second argument to be of type U; the type is correct, but TypeScript can't infer it here. */
-      result[key] = deepMergeImpl(result[key] ?? {}, source[key] as U) as (T &
-        U)[Extract<keyof U, string>];
-    } else {
+      -- result[key] will have the correct type after assignment but TS can't infer it */
+      result[key] = deepMergeImpl(
+        result[key] ?? {},
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        -- source[key] is known to be from S but TS can't infer it */
+        source[key] as S,
+        shouldOverwriteUndefined,
+      ) as (T & S)[Extract<keyof S, string>];
+    } else if (shouldOverwriteUndefined || source[key] !== undefined) {
       /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      --  Cast required because TypeScript can't guarantee that a dynamic key from `U` exists in `T & U` or has the correct value type. */
-      result[key] = source[key] as (T & U)[Extract<keyof U, string>];
+      -- result[key] will have the correct type after assignment but TS can't infer it */
+      result[key] = source[key] as (T & S)[Extract<keyof S, string>];
     }
   }
 

package/src/internal/panic-errors.ts

@@ -0,0 +1,23 @@
+export 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/lang.ts

@@ -30,24 +30,33 @@ export async function deepEqual<T>(x: T, y: T): Promise<boolean> {
  *
  * @remarks
  * - Arrays or `undefined` values are not valid inputs.
- * - Functions: If a function exists in both the target and source, the source function overwrites the target.
- * - Symbol properties: Symbol-keyed properties are merged just like string keys.
- * - Class instances: Class instances are not merged recursively. If a class instance exists in the source, it will replace the one in the target.
+ * - Functions: If a function exists in both the target and source, the source
+ * function overwrites the target.
+ * - Symbol properties: Symbol-keyed properties are merged just like string
+ * keys.
+ * - Class instances: Class instances are not merged recursively. If a class
+ * instance exists in the source, it will replace the one in the target.
  *
  * @param target The target object to merge into.
  * @param source The source object to merge from.
+ * @param shouldOverwriteUndefined If true, properties with `undefined` values
+ * in the source will overwrite those in the target. Default is true.
  * @returns A new object containing the deeply merged properties.
  *
  * @example
  * deepMerge({ a: { b: 1 } }, { a: { c: 2 } }) // => { a: { b: 1, c: 2 } }
  *
- * deepMerge({ a: { fn: () => "from target" } }, { a: { fn: () => "from source" } }) // => { a: { fn: () => "from source" } }
+ * deepMerge(
+ *   { a: { fn: () => "from target" } },
+ *   { a: { fn: () => "from source" } }
+ * ) // => { a: { fn: () => "from source" } }
  */
 export function deepMerge<T extends object, U extends object>(
   target: T,
   source: U,
+  shouldOverwriteUndefined: boolean = true,
 ): T & U {
-  return deepMergeImpl(target, source);
+  return deepMergeImpl(target, source, shouldOverwriteUndefined);
 }
 
 /**

package/src/panic-errors.ts

@@ -1,5 +1,19 @@
 import { numberToHexString } from "./hex.js";
+import { panicErrorCodeToReason } from "./internal/panic-errors.js";
 
+/**
+ * Converts a Solidity panic error code into a human-readable revert message.
+ *
+ * Solidity defines a set of standardized panic codes (0x01, 0x11, etc.)
+ * that represent specific runtime errors (e.g. arithmetic overflow).
+ * This function looks up the corresponding reason string and formats it
+ * into a message similar to what clients like Hardhat or ethers.js display.
+ *
+ * @param errorCode The panic error code returned by the EVM as a bigint.
+ * @returns A formatted message string:
+ * - `"reverted with panic code <hex> (<reason>)"` if the code is recognized.
+ * - `"reverted with unknown panic code <hex>"` if the code is not recognized.
+ */
 export function panicErrorCodeToMessage(errorCode: bigint): string {
   const reason = panicErrorCodeToReason(errorCode);
 
@@ -9,27 +23,3 @@ export function panicErrorCodeToMessage(errorCode: bigint): string {
 
   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";
-  }
-}