@nomicfoundation/hardhat-utils 4.0.4 → 4.1.0

package/src/fs.ts

@@ -20,6 +20,257 @@ import {
   IsDirectoryError,
   DirectoryNotEmptyError,
 } from "./errors/fs.js";
+import {
+  isDirectoryDirentAware,
+  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
@@ -59,12 +310,12 @@ export async function getAllFilesMatching(
   matches?: (absolutePathToFile: string) => Promise<boolean> | boolean,
   directoryFilter?: (absolutePathToDir: string) => Promise<boolean> | boolean,
 ): Promise<string[]> {
-  const dirContent = await readdirOrEmpty(dirFrom);
+  const dirContent = await readdirWithFileTypesOrEmpty(dirFrom);
 
   const results = await Promise.all(
-    dirContent.map(async (file) => {
-      const absolutePathToFile = path.join(dirFrom, file);
-      if (await isDirectory(absolutePathToFile)) {
+    dirContent.map(async (dirent) => {
+      const absolutePathToFile = path.join(dirFrom, dirent.name);
+      if (await isDirectoryDirentAware(absolutePathToFile, dirent)) {
         if (
           directoryFilter === undefined ||
           (await directoryFilter(absolutePathToFile))
@@ -107,12 +358,12 @@ export async function getAllDirectoriesMatching(
   dirFrom: string,
   matches?: (absolutePathToDir: string) => Promise<boolean> | boolean,
 ): Promise<string[]> {
-  const dirContent = await readdirOrEmpty(dirFrom);
+  const dirContent = await readdirWithFileTypesOrEmpty(dirFrom);
 
   const results = await Promise.all(
-    dirContent.map(async (file) => {
-      const absolutePathToFile = path.join(dirFrom, file);
-      if (!(await isDirectory(absolutePathToFile))) {
+    dirContent.map(async (dirent) => {
+      const absolutePathToFile = path.join(dirFrom, dirent.name);
+      if (!(await isDirectoryDirentAware(absolutePathToFile, dirent))) {
         return [];
       }
 
@@ -137,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);
 }
 
 /**
@@ -494,17 +724,24 @@ export async function readdir(absolutePathToDir: string): Promise<string[]> {
 }
 
 /**
- * Wrapper around `readdir` that returns an empty array if the directory doesn't exist.
+ * Reads a directory and returns its content as an array of strings, returning
+ * an empty array if the directory doesn't exist.
  *
- * @see readdir
+ * @param absolutePathToDir The path to the directory.
+ * @returns An array of strings with the names of the files and directories in the directory, and an empty array if the directory doesn't exist.
+ * @throws NotADirectoryError if the path is not a directory.
+ * @throws FileSystemAccessError for any other error.
  */
-async function readdirOrEmpty(dirFrom: string): Promise<string[]> {
+export async function readdirOrEmpty(
+  absolutePathToDir: string,
+): Promise<string[]> {
   try {
-    return await readdir(dirFrom);
+    return await readdir(absolutePathToDir);
   } catch (error) {
     if (error instanceof FileNotFoundError) {
       return [];
     }
+
     throw error;
   }
 }

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/internal/fs.ts

@@ -0,0 +1,57 @@
+import type { Dirent } from "node:fs";
+
+import fsPromises from "node:fs/promises";
+
+import { ensureNodeErrnoExceptionError } from "../error.js";
+import { FileSystemAccessError, NotADirectoryError } from "../errors/fs.js";
+import { isDirectory } from "../fs.js";
+
+/**
+ * Like `readdirOrEmpty`, but returns `Dirent` entries to know if an entry is a
+ * directory or not without an extra `lstat` syscall.
+ */
+export async function readdirWithFileTypesOrEmpty(
+  dirFrom: string,
+): Promise<Dirent[]> {
+  try {
+    return await fsPromises.readdir(dirFrom, { withFileTypes: true });
+  } catch (e) {
+    ensureNodeErrnoExceptionError(e);
+
+    if (e.code === "ENOENT") {
+      return [];
+    }
+
+    if (e.code === "ENOTDIR") {
+      throw new NotADirectoryError(dirFrom, e);
+    }
+
+    throw new FileSystemAccessError(e.message, e);
+  }
+}
+
+/**
+ * Determines if a dirent refers to a directory, falling back to `lstat` only
+ * when the dirent type is unknown.
+ */
+export async function isDirectoryDirentAware(
+  absolutePath: string,
+  dirent: Dirent,
+): Promise<boolean> {
+  if (dirent.isDirectory()) {
+    return true;
+  }
+
+  if (
+    dirent.isFile() ||
+    dirent.isSymbolicLink() ||
+    dirent.isBlockDevice() ||
+    dirent.isCharacterDevice() ||
+    dirent.isFIFO() ||
+    dirent.isSocket()
+  ) {
+    return false;
+  }
+
+  return await isDirectory(absolutePath);
+}

package/src/runtime.ts

@@ -0,0 +1,45 @@
+export interface RuntimeInfo {
+  runtime: "bun" | "deno" | "node";
+  version: string;
+}
+
+declare const globalThis: {
+  Deno?: { version?: { deno?: string } };
+};
+
+/**
+ * Detects the JavaScript runtime environment (Node.js, Deno, Bun, or unknown)
+ * and its version.
+ *
+ * @returns An object containing the runtime type and version, or `undefined`
+ * if the runtime cannot be detected.
+ */
+export function getRuntimeInfo(): RuntimeInfo | undefined {
+  // Deno
+  const deno = globalThis.Deno;
+  if (typeof deno === "object" && deno?.version?.deno !== undefined) {
+    return {
+      runtime: "deno",
+      version: deno.version.deno,
+    };
+  }
+
+  // Bun: this should be checked before Node.js since Bun also defines
+  // `process.versions.node`
+  if (typeof process !== "undefined" && process.versions?.bun !== undefined) {
+    return {
+      runtime: "bun",
+      version: process.versions.bun,
+    };
+  }
+
+  // Node
+  if (typeof process !== "undefined" && process.versions?.node !== undefined) {
+    return {
+      runtime: "node",
+      version: process.versions.node,
+    };
+  }
+
+  return undefined;
+}

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.
  *