@nomicfoundation/hardhat-utils 3.0.2 → 3.0.4

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/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/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";
-  }
-}

package/src/spinner.ts

@@ -0,0 +1,130 @@
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export const FRAME_INTERVAL_MS = 80;
+
+export interface ISpinner {
+  readonly isEnabled: boolean;
+  start(): void;
+  stop(): void;
+}
+
+/**
+ * Optional settings when creating a spinner.
+ */
+export interface SpinnerOptions {
+  /**
+   * Text shown next to the spinner.
+   */
+  text?: string;
+
+  /**
+   * Stream used to write frames.
+   */
+  stream?: NodeJS.WriteStream;
+
+  /**
+   * Whether the spinner is enabled.
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Spinner that writes frames to a stream.
+ */
+class Spinner implements ISpinner {
+  public readonly isEnabled: boolean;
+  readonly #text: string;
+  #interval: NodeJS.Timeout | null = null;
+  readonly #stream: NodeJS.WriteStream;
+
+  constructor(options: Required<SpinnerOptions>) {
+    this.isEnabled = options.enabled;
+    this.#stream = options.stream;
+    this.#text = options.text;
+  }
+  /**
+   * Begin rendering frames when enabled.
+   */
+  public start(): void {
+    if (!this.isEnabled) {
+      return;
+    }
+
+    this.#stopAnimation();
+    let frameIndex = 0;
+
+    this.#interval = setInterval(() => {
+      this.#render(FRAMES[frameIndex]);
+      frameIndex = (frameIndex + 1) % FRAMES.length;
+    }, FRAME_INTERVAL_MS);
+  }
+
+  /**
+   * Stop the spinner without printing a final line.
+   */
+  public stop(): void {
+    this.#stopAnimation();
+  }
+
+  #clearLine(): void {
+    this.#stream.clearLine(0);
+    this.#stream.cursorTo(0);
+  }
+
+  #render(frame: string): void {
+    if (!this.isEnabled) {
+      return;
+    }
+    this.#clearLine();
+    this.#stream.write(`${frame} ${this.#text}`);
+  }
+
+  #stopAnimation(): void {
+    if (this.#interval === null) {
+      return;
+    }
+
+    clearInterval(this.#interval);
+    this.#interval = null;
+
+    if (this.isEnabled) {
+      this.#clearLine();
+    }
+  }
+}
+
+/**
+ * Create a spinner instance.
+ *
+ * @example
+ * ```typescript
+ * const spinner = createSpinner({ text: "Compiling…" });
+ * spinner.start();
+ *
+ * try {
+ *   await compileContracts();
+ *   spinner.stop();
+ *   console.log("Compiled 12 contracts");
+ * } catch (error) {
+ *   spinner.stop();
+ *   console.error("Compilation failed");
+ * }
+ * ```
+ *
+ * @param options  Optional spinner configuration.
+ * @returns {Spinner} A spinner instance.
+ */
+export function createSpinner(options: SpinnerOptions = {}): ISpinner {
+  const stream = options.stream ?? process.stdout;
+
+  const enabled =
+    stream.isTTY === true &&
+    process.env.TERM !== "dumb" &&
+    (options.enabled ?? true);
+
+  const text = options.text ?? "";
+  return new Spinner({
+    enabled,
+    stream,
+    text,
+  });
+}