@nomicfoundation/hardhat-utils 4.0.5 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomicfoundation/hardhat-utils",
-  "version": "4.0.5",
+  "version": "4.1.0",
   "description": "Utilities for Hardhat and its plugins",
   "homepage": "https://github.com/NomicFoundation/hardhat/tree/main/packages/hardhat-utils",
   "repository": {
@@ -23,6 +23,7 @@
     "./env": "./dist/src/env.js",
     "./error": "./dist/src/error.js",
     "./eth": "./dist/src/eth.js",
+    "./fast-semver": "./dist/src/fast-semver.js",
     "./format": "./dist/src/format.js",
     "./fs": "./dist/src/fs.js",
     "./global-dir": "./dist/src/global-dir.js",
@@ -53,9 +54,8 @@
     "README.md"
   ],
   "devDependencies": {
-    "@nomicfoundation/hardhat-node-test-reporter": "^3.0.5",
+    "@nomicfoundation/hardhat-node-test-reporter": "^3.0.6",
     "@types/bn.js": "^5.1.5",
-    "@types/debug": "^4.1.7",
     "@types/node": "^22.0.0",
     "c8": "^9.1.0",
     "eslint": "9.25.1",
@@ -67,7 +67,6 @@
   },
   "dependencies": {
     "@streamparser/json-node": "^0.0.22",
-    "debug": "^4.3.2",
     "env-paths": "^2.2.0",
     "ethereum-cryptography": "^2.2.1",
     "fast-equals": "^5.4.0",

package/src/debug.ts

@@ -1,38 +1,83 @@
-import debugLib from "debug";
+import { formatWithOptions } from "node:util";
+
+import { NOOP, isEnabled, selectColor, useColors } from "./internal/debug.js";
+
+/**
+ * A logger function returned by {@link createDebug}.
+ * The `enabled` property is `true` when the logger will produce output.
+ */
+export interface DebugLogger {
+  (format: unknown, ...args: unknown[]): void;
+  readonly enabled: boolean;
+}
 
 /**
- * A simple decorator that adds debug logging for when a method is entered and exited.
+ * Creates a namespaced logger controlled by the `DEBUG` env var.
  *
- * This decorator is meant to be used for debugging purposes only. It should not be committed in runtime code.
+ * If `namespace` matches `DEBUG`, the logger writes to `process.stderr`;
+ * otherwise, it is a no-op. Additionally, `logger.enabled` is `true` when
+ * the namespace matches `DEBUG`, allowing you to conditionally run expensive
+ * diagnostics.
  *
- * Example usage:
+ * `DEBUG` should be a comma- or whitespace-separated list of patterns.
+ * `*` is a wildcard and a leading `-` negates a pattern (e.g.
+ * `hardhat:*,-hardhat:noisy`).
  *
- * ```
- * class MyClass {
- *   @withDebugLogs("MyClass:exampleClassMethod")
- *   public function exampleClassMethod(...)
+ * Messages are formatted using `node:util.format`, allowing you to use format
+ * specifiers like `%O`, `%o`, `%s`, `%d`, `%j`. Extra arguments without a
+ * matching specifier are inspected automatically.
+ *
+ * Output is colorized per namespace when `stderr` is a TTY. Set
+ * `DEBUG_COLORS=no` or `false` to disable colors.
+ *
+ * @example
+ * ```ts
+ * const log = createDebug("hardhat:utils:foo");
+ * log("Starting up");
+ * log("Received %O", payload);
+ * log("Saved data", id, filePath);
+ *
+ * if (log.enabled) {
+ *   // expensive diagnostics that should only run while debugging
  * }
  * ```
+ *
+ * ```sh
+ * DEBUG="hardhat:*,-hardhat:noisy" DEBUG_COLORS=no pnpm hardhat run script.js
+ * ```
+ *
+ * @param namespace Namespace used for filtering and as the log prefix.
+ * @returns Logger function, or a shared no-op if disabled.
  */
-export function withDebugLogs<This, Args extends any[], Return>(
-  tag: string = "",
-) {
-  return function actualDecorator(
-    originalMethod: (this: This, ...args: Args) => Return,
-    _context: ClassMethodDecoratorContext<
-      This,
-      (this: This, ...args: Args) => Return
-    >,
-  ): (this: This, ...args: Args) => Return {
-    const log = debugLib(`hardhat:dev:core${tag === "" ? "" : `:${tag}`}`);
-
-    function replacementMethod(this: This, ...args: Args): Return {
-      log(`Entering method with args:`, args);
-      const result = originalMethod.call(this, ...args);
-      log(`Exiting method.`);
-      return result;
-    }
-
-    return replacementMethod;
+export function createDebug(namespace: string): DebugLogger {
+  if (!isEnabled(namespace, process.env.DEBUG ?? "")) {
+    return NOOP;
+  }
+
+  const colors = useColors();
+  const color = colors ? selectColor(namespace) : undefined;
+  const prefix =
+    color !== undefined
+      ? `\x1b[38;5;${color};1m  ${namespace}\x1b[0m`
+      : `  ${namespace}`;
+  const suffixOpen = color !== undefined ? `\x1b[38;5;${color}m` : "";
+  const suffixClose = color !== undefined ? `\x1b[0m` : "";
+  let prev = 0;
+
+  const logger = (format: unknown, ...args: unknown[]): void => {
+    const now = Date.now();
+    const diff = prev === 0 ? 0 : now - prev;
+    prev = now;
+
+    const body =
+      args.length === 0 && typeof format === "string"
+        ? format
+        : formatWithOptions({ colors }, format, ...args);
+
+    process.stderr.write(
+      `${prefix} ${body} ${suffixOpen}+${diff}ms${suffixClose}\n`,
+    );
   };
+
+  return Object.assign(logger, { enabled: true });
 }

package/src/fast-semver.ts

@@ -0,0 +1,95 @@
+/**
+ * A small, fast subset of semver: strict `MAJOR.MINOR.PATCH` parsing and
+ * triple-wise comparison helpers.
+ *
+ * This module exists because the full `semver` package is slow to load and is
+ * overkill for the many call sites in Hardhat that compare against hard-coded
+ * `x.y.z` literals. For range grammar (caret/tilde, disjunctions, prerelease
+ * subset, etc.) keep using `semver`.
+ */
+
+export type SemverVersion = [major: number, minor: number, patch: number];
+
+const VERSION_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z.-]+)?$/;
+
+/**
+ * Parses a strict `MAJOR.MINOR.PATCH` version string into a `SemverVersion`
+ * tuple.
+ *
+ * An optional `+build` suffix is accepted and stripped silently. A
+ * `-prerelease` suffix is rejected.
+ *
+ * @param version The version string to parse.
+ * @returns The parsed `SemverVersion`, or `undefined` if the input does not
+ * match the strict `\d+\.\d+\.\d+` shape.
+ */
+export function parseVersion(version: string): SemverVersion | undefined {
+  const match = VERSION_REGEX.exec(version);
+  if (match === null) {
+    return undefined;
+  }
+
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/**
+ * `Array#sort`-style comparator for `SemverVersion` tuples: returns a negative
+ * number, zero, or a positive number depending on whether `a` is lower than,
+ * equal to, or greater than `b`.
+ */
+export function compare(a: SemverVersion, b: SemverVersion): number {
+  if (a[0] !== b[0]) {
+    return a[0] - b[0];
+  }
+  if (a[1] !== b[1]) {
+    return a[1] - b[1];
+  }
+  return a[2] - b[2];
+}
+
+/**
+ * Returns `true` if `a` and `b` represent the same `MAJOR.MINOR.PATCH`.
+ */
+export function equals(a: SemverVersion, b: SemverVersion): boolean {
+  return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+}
+
+/**
+ * Returns `true` if `compared` is strictly lower than `comparator`.
+ */
+export function lowerThan(
+  compared: SemverVersion,
+  comparator: SemverVersion,
+): boolean {
+  return compare(compared, comparator) < 0;
+}
+
+/**
+ * Returns `true` if `compared` is lower than or equal to `comparator`.
+ */
+export function lowerThanOrEqual(
+  compared: SemverVersion,
+  comparator: SemverVersion,
+): boolean {
+  return compare(compared, comparator) <= 0;
+}
+
+/**
+ * Returns `true` if `compared` is strictly greater than `comparator`.
+ */
+export function greaterThan(
+  compared: SemverVersion,
+  comparator: SemverVersion,
+): boolean {
+  return compare(compared, comparator) > 0;
+}
+
+/**
+ * Returns `true` if `compared` is greater than or equal to `comparator`.
+ */
+export function greaterThanOrEqual(
+  compared: SemverVersion,
+  comparator: SemverVersion,
+): boolean {
+  return compare(compared, comparator) >= 0;
+}

package/src/fs.ts

@@ -25,6 +25,253 @@ import {
   readdirWithFileTypesOrEmpty,
 } from "./internal/fs.js";
 
+const AMBIGUOUS_CASING_DIR_ENTRY = Symbol("ambiguous");
+
+type CaseFoldedEntry = string | typeof AMBIGUOUS_CASING_DIR_ENTRY;
+
+/**
+ * The entries in a directory, which stores their exact name, and also a
+ * case-folded mapping to support case-insensitive lookups.
+ */
+interface DirEntries {
+  /**
+   * The exact names present in the directory, as returned by `readdir`.
+   */
+  readonly exactNames: Set<string>;
+
+  /**
+   * Case-folded key -> the actual on-disk spelling, or
+   * AMBIGUOUS_CASING_DIR_ENTRY when multiple entries in the directory fold to
+   * the same key.
+   */
+  readonly caseFoldedNames: Map<string, CaseFoldedEntry>;
+}
+
+/**
+ * Resolves paths to their true (on-disk) casing, caching directory listings
+ * and resolutions so repeated lookups against the same directories don't re-hit
+ * the filesystem.
+ *
+ * Intended to be used in hot paths where the same `from` directories are seen
+ * over and over.
+ *
+ * Does not resolve symbolic links.
+ *
+ * This class caches successful resolutions internally, and may do some
+ * duplicate work when multiple concurrent lookups for the same path are made
+ * before the first one finishes. It does not cache failed resolutions as
+ * negative result entries, but it does cache directory listings, so filesystem
+ * changes may not be observed until `clear()` is called. After `clear()`,
+ * previously cached directory and resolution data is discarded. If profiling
+ * shows that this work duplication is a problem, we can either cache in-flight
+ * operations, or add a mutex.
+ */
+export class TrueCasePathResolver {
+  /**
+   * A cache of DirEntries for the directories we've seen, keyed by their
+   * normalized absolute path as read. For example, if the same physical
+   * directory is read as `/a/foo` and `/a/Foo`, each path gets its own entry.
+   */
+  readonly #dirCache = new Map<string, DirEntries>();
+
+  /**
+   * A cache of successful resolutions, grouped by their `from` trusted starting
+   * directory.
+   *
+   * The outer key is the normalized absolute `from` path, and the inner key is
+   * the normalized `relativePath`.
+   *
+   * This keeps paths like `/a/B` + `foo.ts` distinct from `/a` + `B/foo.ts`,
+   * even if they point to the same location.
+   */
+  readonly #resultCache = new Map<string, Map<string, string>>();
+
+  /**
+   * Determines the true-case path of a given relative path from a specified
+   * directory, without resolving symbolic links.
+   *
+   * Note that the casing of the `from` path is not checked against the
+   * filesystem, and is trusted as-is. This avoids unnecessary directory
+   * listings for every ancestor of `from`, which can result in permission
+   * errors for directories that are otherwise accessible.
+   *
+   * @param from The absolute path of the directory to start the search from.
+   * @param relativePath The relative path to get the true case of.
+   * @returns The true case of the relative path. Returns an empty string if
+   * relativePath points to from.
+   * @throws FileNotFoundError if the starting directory or the relative path
+   *  doesn't exist or is ambiguous.
+   * @throws NotADirectoryError if the starting directory, or an intermediate
+   *  segment, is not a directory.
+   * @throws FileSystemAccessError for any other error.
+   */
+  public async getFileTrueCase(
+    from: string,
+    relativePath: string,
+  ): Promise<string> {
+    const absoluteFrom = path.resolve(from);
+
+    if (path.normalize(relativePath) === ".") {
+      // There's no casing to resolve, but we still read `from` so that callers
+      // get the documented FileNotFoundError / NotADirectoryError if it
+      // doesn't exist or isn't a directory.
+      await this.#getDirEntries(absoluteFrom);
+      return "";
+    }
+
+    const resolved = await this.#resolveFrom(absoluteFrom, relativePath);
+    const resolvedRelativePath = path.relative(absoluteFrom, resolved);
+
+    if (
+      resolvedRelativePath === ".." ||
+      resolvedRelativePath.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(resolvedRelativePath)
+    ) {
+      throw new FileNotFoundError(path.resolve(absoluteFrom, relativePath));
+    }
+
+    return resolvedRelativePath;
+  }
+
+  /**
+   * Clears all cached directory listings and resolutions.
+   */
+  public clear(): void {
+    this.#dirCache.clear();
+    this.#resultCache.clear();
+  }
+
+  async #resolveFrom(from: string, relativePath: string): Promise<string> {
+    const fromCacheKey = this.#getResultFromCacheKey(from);
+    const relativePathCacheKey =
+      this.#getResultRelativePathCacheKey(relativePath);
+
+    const cached = this.#resultCache
+      .get(fromCacheKey)
+      ?.get(relativePathCacheKey);
+
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const resolved = await this.#doResolveFrom(from, relativePath);
+
+    let resultsFromCache = this.#resultCache.get(fromCacheKey);
+    if (resultsFromCache === undefined) {
+      resultsFromCache = new Map<string, string>();
+      this.#resultCache.set(fromCacheKey, resultsFromCache);
+    }
+
+    resultsFromCache.set(relativePathCacheKey, resolved);
+
+    return resolved;
+  }
+
+  async #doResolveFrom(from: string, relativePath: string): Promise<string> {
+    let currentPath = from;
+
+    const segments = path
+      .normalize(relativePath)
+      .split(path.sep)
+      .filter((s) => s.length > 0 || s === ".");
+
+    for (const requestedName of segments) {
+      if (requestedName === "..") {
+        currentPath = path.join(currentPath, requestedName);
+        continue;
+      }
+
+      const entries = await this.#getDirEntries(currentPath);
+      const actualName = this.#lookupChild(entries, requestedName);
+
+      if (actualName === undefined) {
+        throw new FileNotFoundError(path.resolve(from, relativePath));
+      }
+
+      currentPath = path.join(currentPath, actualName);
+    }
+
+    return currentPath;
+  }
+
+  async #getDirEntries(dirPath: string): Promise<DirEntries> {
+    const cacheKey = this.#getDirCacheKey(dirPath);
+    const cached = this.#dirCache.get(cacheKey);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const entries = await this.#readDirEntries(dirPath);
+    this.#dirCache.set(cacheKey, entries);
+
+    return entries;
+  }
+
+  async #readDirEntries(dirPath: string): Promise<DirEntries> {
+    const names = await readdir(dirPath);
+
+    const exactNames = new Set<string>();
+    const caseFoldedNames = new Map<string, CaseFoldedEntry>();
+
+    for (const name of names) {
+      exactNames.add(name);
+
+      const folded = this.#caseFold(name);
+      const previous = caseFoldedNames.get(folded);
+      if (previous === undefined) {
+        caseFoldedNames.set(folded, name);
+      } else if (previous !== name) {
+        caseFoldedNames.set(folded, AMBIGUOUS_CASING_DIR_ENTRY);
+      }
+    }
+
+    return { exactNames, caseFoldedNames };
+  }
+
+  #lookupChild(entries: DirEntries, requestedName: string): string | undefined {
+    if (entries.exactNames.has(requestedName)) {
+      return requestedName;
+    }
+
+    const candidate = entries.caseFoldedNames.get(
+      this.#caseFold(requestedName),
+    );
+
+    if (candidate === undefined || candidate === AMBIGUOUS_CASING_DIR_ENTRY) {
+      return undefined;
+    }
+
+    return candidate;
+  }
+
+  #getResultFromCacheKey(from: string): string {
+    return path.normalize(from);
+  }
+
+  #getResultRelativePathCacheKey(relativePath: string): string {
+    return path.normalize(relativePath);
+  }
+
+  #getDirCacheKey(dirPath: string): string {
+    return path.normalize(dirPath);
+  }
+
+  /**
+   * Returns a case-folded version of the given name, which can be thought of as
+   * a "normalized uppercase" form. This is used to implement case-insensitive
+   * comparisons.
+   *
+   * This is not an exact match with what every filesystem would do, but a good
+   * enough approximation for our purposes.
+   *
+   * @param name The name to fold.
+   * @returns The case-folded version of the name.
+   */
+  #caseFold(name: string): string {
+    return name.normalize("NFC").toUpperCase();
+  }
+}
+
 /**
  * Determines the canonical pathname for a given path, resolving any symbolic
  * links, and returns it.
@@ -141,34 +388,13 @@ export async function getAllDirectoriesMatching(
  * @throws FileNotFoundError if the starting directory or the relative path doesn't exist.
  * @throws NotADirectoryError if the starting directory is not a directory.
  * @throws FileSystemAccessError for any other error.
+ * @deprecated Use {@link TrueCasePathResolver} instead.
  */
 export async function getFileTrueCase(
   from: string,
   relativePath: string,
 ): Promise<string> {
-  const dirEntries = await readdirOrEmpty(from);
-
-  const segments = relativePath.split(path.sep);
-  const nextDir = segments[0];
-  const nextDirLowerCase = nextDir.toLowerCase();
-
-  for (const dirEntry of dirEntries) {
-    if (dirEntry.toLowerCase() === nextDirLowerCase) {
-      if (segments.length === 1) {
-        return dirEntry;
-      }
-
-      return path.join(
-        dirEntry,
-        await getFileTrueCase(
-          path.join(from, dirEntry),
-          path.relative(nextDir, relativePath),
-        ),
-      );
-    }
-  }
-
-  throw new FileNotFoundError(path.join(from, relativePath));
+  return await new TrueCasePathResolver().getFileTrueCase(from, relativePath);
 }
 
 /**

package/src/internal/debug.ts

@@ -0,0 +1,119 @@
+import type { DebugLogger } from "../debug.js";
+
+export const NOOP: DebugLogger = Object.assign(
+  (_format: unknown, ..._args: unknown[]): void => {},
+  { enabled: false },
+);
+
+interface ParsedPatterns {
+  include: RegExp[];
+  exclude: RegExp[];
+}
+
+let cached: { env: string; parsed: ParsedPatterns } | undefined;
+
+/**
+ * Parses a `DEBUG`-style pattern string into include/exclude regex lists.
+ * Patterns prefixed with `-` go into `exclude`; everything else into `include`.
+ *
+ * Results are memoized against the last-seen `env` string, since
+ * `process.env.DEBUG` is effectively constant within a process and
+ * `createDebug` is called many times at startup.
+ */
+export function parsePatterns(env: string): ParsedPatterns {
+  if (cached !== undefined && cached.env === env) {
+    return cached.parsed;
+  }
+
+  const include: RegExp[] = [];
+  const exclude: RegExp[] = [];
+
+  for (const raw of env.split(/[\s,]+/)) {
+    if (raw === "") {
+      continue;
+    }
+    if (raw.startsWith("-")) {
+      exclude.push(namespaceToRegExp(raw.slice(1)));
+    } else {
+      include.push(namespaceToRegExp(raw));
+    }
+  }
+
+  const parsed: ParsedPatterns = { include, exclude };
+  cached = { env, parsed };
+  return parsed;
+}
+
+/**
+ * Converts a `DEBUG`-style namespace pattern into an anchored regex.
+ * Regex metacharacters are escaped to match literally, and `*` is translated
+ * into `.*?` so it behaves as a glob wildcard.
+ */
+function namespaceToRegExp(namespace: string): RegExp {
+  const escaped = namespace
+    .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*?");
+
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Checks whether a namespace is enabled under the given `DEBUG` pattern string.
+ */
+export function isEnabled(namespace: string, env: string): boolean {
+  if (env === "") {
+    return false;
+  }
+
+  const { include, exclude } = parsePatterns(env);
+
+  return (
+    !exclude.some((p) => p.test(namespace)) &&
+    include.some((p) => p.test(namespace))
+  );
+}
+
+// `debug@4`'s 76-colour 256-palette with the red and red-orange families
+// stripped, so red stays reserved for error output.
+export const COLORS: readonly number[] = [
+  20, 21, 26, 27, 32, 33, 38, 39, 40, 41, 42, 43, 44, 45, 56, 57, 62, 63, 68,
+  69, 74, 75, 76, 77, 78, 79, 80, 81, 92, 93, 98, 99, 112, 113, 128, 129, 134,
+  135, 148, 149, 178, 179, 184, 185, 201, 214, 215, 220, 221,
+];
+
+/**
+ * Picks an ANSI 256-colour code for a namespace, deterministic from its
+ * characters.
+ *
+ * Uses a 32-bit FNV-1a hash followed by an xorshift finalizer. The finalizer
+ * improves bit avalanche so the low bits used by `% COLORS.length`
+ * distribute Hardhat's namespaces more evenly across the palette.
+ */
+export function selectColor(namespace: string): number {
+  let hash = 0x811c9dc5;
+
+  for (let i = 0; i < namespace.length; i++) {
+    // eslint-disable-next-line no-bitwise -- FNV-1a hash
+    hash ^= namespace.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+
+  // xorshift finalizer for better avalanche on the low bits
+  /* eslint-disable no-bitwise -- xorshift finalizer */
+  hash ^= hash >>> 16;
+  hash = Math.imul(hash, 0x85ebca6b);
+  hash ^= hash >>> 13;
+  /* eslint-enable no-bitwise */
+
+  return COLORS[Math.abs(hash) % COLORS.length];
+}
+
+/**
+ * Reports whether ANSI colours should be used, honouring `DEBUG_COLORS` and TTY.
+ */
+export function useColors(): boolean {
+  const isDisabled =
+    process.env.DEBUG_COLORS === "no" || process.env.DEBUG_COLORS === "false";
+
+  return !isDisabled && process.stderr.isTTY === true;
+}

package/src/subprocess.ts

@@ -6,6 +6,8 @@ import {
 } from "./errors/subprocess.js";
 import { exists, isDirectory } from "./fs.js";
 
+export { SubprocessFileNotFoundError, SubprocessPathIsDirectoryError };
+
 /**
  * Spawns a detached subprocess to execute a given file with optional arguments.
  *