@nomicfoundation/hardhat-utils 4.0.5 → 4.1.1

package/src/fs.ts

@@ -1,4 +1,5 @@
-import type { JsonTypes, ParsedElementInfo } from "@streamparser/json-node";
+import type * as StreamParserJson from "@streamparser/json-node";
+import type * as JsonStreamStringify from "json-stream-stringify";
 import type { FileHandle } from "node:fs/promises";
 
 import fsPromises from "node:fs/promises";
@@ -6,9 +7,6 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
 
-import { JSONParser } from "@streamparser/json-node";
-import { JsonStreamStringify } from "json-stream-stringify";
-
 import { ensureError, ensureNodeErrnoExceptionError } from "./error.js";
 import {
   FileNotFoundError,
@@ -21,10 +19,265 @@ import {
   DirectoryNotEmptyError,
 } from "./errors/fs.js";
 import {
-  isDirectoryDirentAware,
-  readdirWithFileTypesOrEmpty,
+  collectAllDirectoriesMatching,
+  collectAllFilesMatching,
 } from "./internal/fs.js";
 
+// We don't load @streamparser/json-node on startup because it's only
+// used by readJsonFileAsStream for very large JSON files.
+let streamParserJson: typeof StreamParserJson | undefined;
+
+// We don't load json-stream-stringify on startup because it's only
+// used by writeJsonFileAsStream for very large JSON objects.
+let jsonStreamStringify: typeof JsonStreamStringify | undefined;
+
+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.
@@ -63,33 +316,10 @@ export async function getAllFilesMatching(
   matches?: (absolutePathToFile: string) => Promise<boolean> | boolean,
   directoryFilter?: (absolutePathToDir: string) => Promise<boolean> | boolean,
 ): Promise<string[]> {
-  const dirContent = await readdirWithFileTypesOrEmpty(dirFrom);
-
-  const results = await Promise.all(
-    dirContent.map(async (dirent) => {
-      const absolutePathToFile = path.join(dirFrom, dirent.name);
-      if (await isDirectoryDirentAware(absolutePathToFile, dirent)) {
-        if (
-          directoryFilter === undefined ||
-          (await directoryFilter(absolutePathToFile))
-        ) {
-          return await getAllFilesMatching(
-            absolutePathToFile,
-            matches,
-            directoryFilter,
-          );
-        }
+  const results: string[] = [];
+  await collectAllFilesMatching(dirFrom, results, matches, directoryFilter);
 
-        return [];
-      } else if (matches === undefined || (await matches(absolutePathToFile))) {
-        return absolutePathToFile;
-      } else {
-        return [];
-      }
-    }),
-  );
-
-  return results.flat();
+  return results;
 }
 
 /**
@@ -111,24 +341,10 @@ export async function getAllDirectoriesMatching(
   dirFrom: string,
   matches?: (absolutePathToDir: string) => Promise<boolean> | boolean,
 ): Promise<string[]> {
-  const dirContent = await readdirWithFileTypesOrEmpty(dirFrom);
-
-  const results = await Promise.all(
-    dirContent.map(async (dirent) => {
-      const absolutePathToFile = path.join(dirFrom, dirent.name);
-      if (!(await isDirectoryDirentAware(absolutePathToFile, dirent))) {
-        return [];
-      }
-
-      if (matches === undefined || (await matches(absolutePathToFile))) {
-        return absolutePathToFile;
-      }
+  const results: string[] = [];
+  await collectAllDirectoriesMatching(dirFrom, results, matches);
 
-      return await getAllDirectoriesMatching(absolutePathToFile, matches);
-    }),
-  );
-
-  return results.flat();
+  return results;
 }
 
 /**
@@ -141,34 +357,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);
 }
 
 /**
@@ -233,9 +428,13 @@ export async function readJsonFileAsStream<T>(
 
     const fileReadStream = fileHandle.createReadStream();
 
+    if (streamParserJson === undefined) {
+      streamParserJson = await import("@streamparser/json-node");
+    }
+
     // NOTE: We set a separator to disable self-closing to be able to use the parser
     // in the stream.pipeline context; see https://github.com/juanjoDiaz/streamparser-json/issues/47
-    const jsonParser = new JSONParser({
+    const jsonParser = new streamParserJson.JSONParser({
       separator: "",
     });
 
@@ -243,9 +442,12 @@ export async function readJsonFileAsStream<T>(
       fileReadStream,
       jsonParser,
       async (
-        elements: AsyncIterable<ParsedElementInfo.ParsedElementInfo>,
+        elements: AsyncIterable<StreamParserJson.ParsedElementInfo.ParsedElementInfo>,
       ): Promise<any | undefined> => {
-        let value: JsonTypes.JsonPrimitive | JsonTypes.JsonStruct | undefined;
+        let value:
+          | StreamParserJson.JsonTypes.JsonPrimitive
+          | StreamParserJson.JsonTypes.JsonStruct
+          | undefined;
         for await (const element of elements) {
           value = element.value;
         }
@@ -334,7 +536,11 @@ export async function writeJsonFileAsStream<T>(
   try {
     fileHandle = await fsPromises.open(absolutePathToFile, "w");
 
-    const jsonStream = new JsonStreamStringify(object);
+    if (jsonStreamStringify === undefined) {
+      jsonStreamStringify = await import("json-stream-stringify");
+    }
+
+    const jsonStream = new jsonStreamStringify.JsonStreamStringify(object);
     const fileWriteStream = fileHandle.createWriteStream();
 
     await pipeline(jsonStream, fileWriteStream);

package/src/internal/bytecode.ts

@@ -29,6 +29,17 @@ export interface LibraryAddresses {
   [contractName: string]: PrefixedHexString;
 }
 
+export interface BytecodeReplacement {
+  start: number;
+  length: number;
+  value: string;
+}
+
+interface LibraryLinksIndex {
+  byName: Map<string, LibraryLink[]>;
+  byFqn: Map<string, LibraryLink>;
+}
+
 /**
  * Check that the provided library addresses are valid Ethereum addresses.
  * If any of them are not, an InvalidLibraryAddressError is thrown.
@@ -61,13 +72,15 @@ export function checkAmbiguousOrUnnecessaryLinks(
 ): void {
   const ambiguousLibraries: Record<string, LibraryLink[]> = {};
   const unnecessaryLibraries: string[] = [];
+  const neededLibrariesIndex = indexLibraryLinks(neededLibraries);
 
   for (const providedLibraryName of Object.keys(providedLibraries)) {
-    const matchingLibraries = neededLibraries.filter(
-      ({ libraryName, libraryFqn }) =>
-        libraryName === providedLibraryName ||
-        libraryFqn === providedLibraryName,
-    );
+    const matchingLibraryByFqn =
+      neededLibrariesIndex.byFqn.get(providedLibraryName);
+    const matchingLibraries =
+      matchingLibraryByFqn !== undefined
+        ? [matchingLibraryByFqn]
+        : neededLibrariesIndex.byName.get(providedLibraryName) ?? [];
 
     if (matchingLibraries.length > 1) {
       ambiguousLibraries[providedLibraryName] = matchingLibraries;
@@ -85,6 +98,24 @@ export function checkAmbiguousOrUnnecessaryLinks(
   }
 }
 
+function indexLibraryLinks(neededLibraries: LibraryLink[]): LibraryLinksIndex {
+  const byName = new Map<string, LibraryLink[]>();
+  const byFqn = new Map<string, LibraryLink>();
+
+  for (const neededLibrary of neededLibraries) {
+    byFqn.set(neededLibrary.libraryFqn, neededLibrary);
+
+    const sameNameLibraries = byName.get(neededLibrary.libraryName);
+    if (sameNameLibraries === undefined) {
+      byName.set(neededLibrary.libraryName, [neededLibrary]);
+    } else {
+      sameNameLibraries.push(neededLibrary);
+    }
+  }
+
+  return { byName, byFqn };
+}
+
 /**
  * Check that each library is only provided once, either by its name or its
  * fully qualified name. If a library is provided more than once, an
@@ -127,3 +158,31 @@ export function checkMissingLibraryAddresses(
 
   throw new MissingLibrariesError(missingLibraries);
 }
+
+/**
+ * Apply a set of replacements to a bytecode string, returning the resulting
+ * bytecode. Each replacement overwrites `length` characters starting at
+ * `start` with `value`. Replacements must not overlap.
+ */
+export function applyBytecodeReplacements(
+  bytecode: string,
+  replacements: BytecodeReplacement[],
+): string {
+  if (replacements.length === 0) {
+    return bytecode;
+  }
+
+  replacements.sort((a, b) => a.start - b.start);
+
+  const parts: string[] = [];
+  let position = 0;
+
+  for (const { start, length, value } of replacements) {
+    parts.push(bytecode.slice(position, start), value);
+    position = start + length;
+  }
+
+  parts.push(bytecode.slice(position));
+
+  return parts.join("");
+}

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;
+}