hardhat 3.1.2 → 3.1.4

package/src/internal/builtin-plugins/coverage/hook-handlers/solidity.ts

@@ -3,14 +3,19 @@ import type { CoverageMetadata } from "../types.js";
 
 import path from "node:path";
 
-import { addStatementCoverageInstrumentation } from "@nomicfoundation/edr";
+import {
+  addStatementCoverageInstrumentation,
+  latestSupportedSolidityVersion,
+} from "@nomicfoundation/edr";
 import {
   assertHardhatInvariant,
   HardhatError,
 } from "@nomicfoundation/hardhat-errors";
 import { ensureError } from "@nomicfoundation/hardhat-utils/error";
 import { readUtf8File } from "@nomicfoundation/hardhat-utils/fs";
+import { findClosestPackageRoot } from "@nomicfoundation/hardhat-utils/package";
 import debug from "debug";
+import { satisfies } from "semver";
 
 import { CoverageManagerImplementation } from "../coverage-manager.js";
 
@@ -35,6 +40,13 @@ export default async (): Promise<Partial<SolidityHooks>> => ({
 
     if (context.globalOptions.coverage && !isTestSource) {
       try {
+        const latestSupportedVersion = latestSupportedSolidityVersion();
+        if (!satisfies(solcVersion, `<=${latestSupportedVersion}`)) {
+          console.log(
+            `Solidity version ${solcVersion} is not yet supported for coverage instrumentation. Hardhat will try the latest supported version ${latestSupportedVersion} instead.`,
+          );
+          solcVersion = latestSupportedVersion;
+        }
         const { source, metadata } = addStatementCoverageInstrumentation(
           fileContent,
           sourceName,
@@ -63,13 +75,11 @@ export default async (): Promise<Partial<SolidityHooks>> => ({
                 fsPath,
               );
               const tag = Buffer.from(m.tag).toString("hex");
-              const startLine = lineNumbers[m.startUtf16];
-              const endLine = lineNumbers[m.endUtf16 - 1];
               coverageMetadata.push({
                 relativePath,
                 tag,
-                startLine,
-                endLine,
+                startUtf16: m.startUtf16,
+                endUtf16: m.endUtf16,
               });
               break;
             default:
@@ -124,9 +134,10 @@ export default async (): Promise<Partial<SolidityHooks>> => ({
       // NOTE: We add the coverage.sol straight into sources here. The alternative
       // would be to do it during the resolution phase. However, we decided this
       // is a simpler solution, at least for now.
-      const content = await readUtf8File(
-        path.join(import.meta.dirname, "../../../../../../coverage.sol"),
-      );
+      const packageRoot = await findClosestPackageRoot(import.meta.url);
+      const coverageSolPath = path.join(packageRoot, "coverage.sol");
+
+      const content = await readUtf8File(coverageSolPath);
       solcInput.sources[COVERAGE_LIBRARY_PATH] = { content };
     }
 

package/src/internal/builtin-plugins/coverage/process-coverage.ts

@@ -0,0 +1,442 @@
+import type {
+  CoverageMetadata,
+  ReportCoverageStatement,
+  Statement,
+} from "./types.js";
+
+import chalk from "chalk";
+
+// Use constants for the Uint8Array to improve memory usage (1 byte vs 8 bytes per item)
+const STATUS_NOT_EXECUTED = 0; // equivalent to false
+const STATUS_EXECUTED = 1; // equivalent to true
+const STATUS_IGNORED = 2; // equivalent to null
+
+/**
+ * Processes the raw EDR coverage information for a file and returns the executed and
+ * non-executed statements and lines.
+ *
+ * @param fileContent The original file content being analyzed
+ * @param metadata Coverage metadata received from EDR for this file
+ * @param hitTags The coverage tags recorded as executed during the test run
+ * for this specific file.
+ *
+ * @returns An object containing:
+ * - statements: the executed and not-executed statements
+ * - lines: the executed and not-executed line numbers
+ */
+export function getProcessedCoverageInfo(
+  fileContent: string,
+  metadata: CoverageMetadata,
+  hitTags: Set<string>,
+): {
+  lines: {
+    executed: Map<number, string>;
+    unexecuted: Map<number, string>;
+  };
+} {
+  const statementsByExecution = partitionStatementsByExecution(
+    metadata,
+    hitTags,
+  );
+
+  const { start, end } = getCoverageBounds(
+    statementsByExecution,
+    fileContent.length,
+  );
+
+  const characterCoverage = buildCharacterCoverage(
+    fileContent,
+    start,
+    end,
+    statementsByExecution.unexecuted,
+  );
+
+  // printStatementsForDebugging(fileContent, statementsByExecution);
+  // printCharacterCoverageForDebugging(fileContent, characterCoverage);
+
+  return {
+    lines: partitionLinesByExecution(fileContent, characterCoverage),
+  };
+}
+
+function partitionStatementsByExecution(
+  metadata: CoverageMetadata,
+  hitTags: Set<string>,
+): {
+  executed: Statement[];
+  unexecuted: Statement[];
+} {
+  const executed: Statement[] = [];
+  const unexecuted: Statement[] = [];
+
+  for (const node of metadata) {
+    if (hitTags.has(node.tag)) {
+      executed.push(node);
+    } else {
+      unexecuted.push(node);
+    }
+  }
+
+  return {
+    executed,
+    unexecuted,
+  };
+}
+
+// Determine the minimum and maximum character indexes that define the range
+// where coverage should be calculated, excluding parts that the tests never
+// reach. This removes irrelevant sections from coverage analysis, such as the
+// beginning or end of each Solidity file.
+// Example:
+// // SPDX-License-Identifier: MIT
+// pragma solidity ^0.8.0;
+function getCoverageBounds(
+  statementsByExecution: {
+    executed: Statement[];
+    unexecuted: Statement[];
+  },
+  fileLength: number,
+): { start: number; end: number } {
+  let start = fileLength;
+  let end = 0;
+
+  const { executed, unexecuted } = statementsByExecution;
+
+  for (const s of [...executed, ...unexecuted]) {
+    if (s.startUtf16 < start) {
+      start = s.startUtf16;
+    }
+
+    if (s.endUtf16 > end) {
+      end = s.endUtf16;
+    }
+  }
+
+  return { start, end };
+}
+
+// Return an array with the same length as the file content. Each position in
+// the array corresponds to a character in the file. The value at each position
+// indicates whether that character was executed during tests (STATUS_EXECUTED),
+// not executed (STATUS_NOT_EXECUTED), or not relevant for coverage
+// (STATUS_IGNORED). STATUS_IGNORED is used to indicate characters that are not
+// executed during test, such as those found at the start or end of every Solidity file.
+// Example:
+// // SPDX-License-Identifier: MIT
+// pragma solidity ^0.8.0;
+function buildCharacterCoverage(
+  fileContent: string,
+  start: number,
+  end: number,
+  unexecutedStatements: Statement[],
+): Uint8Array {
+  // Use Uint8Array instead of Array<null | boolean> for memory efficiency.
+  // We initialize with STATUS_IGNORED (equivalent to filling with null)
+  const characterCoverage = new Uint8Array(fileContent.length).fill(
+    STATUS_IGNORED,
+  );
+
+  // Initially mark all characters that may be executed during the tests as
+  // STATUS_EXECUTED. They will be set to false later if they are not executed.
+  // The coverage statement received from EDR will provide this information.
+  // Setting everything to true first simplifies the logic for extracting
+  // coverage data. Starting with false and toggling only covered characters
+  // would make statement processing more complex.
+  for (let i = start; i < end; i++) {
+    if (charMustBeIgnored(fileContent[i])) {
+      continue;
+    }
+
+    characterCoverage[i] = STATUS_EXECUTED;
+  }
+
+  for (const statement of unexecutedStatements) {
+    for (let i = statement.startUtf16; i < statement.endUtf16; i++) {
+      if (characterCoverage[i] === STATUS_IGNORED) {
+        continue;
+      }
+
+      characterCoverage[i] = STATUS_NOT_EXECUTED;
+    }
+  }
+
+  markNonExecutablePatterns(fileContent, characterCoverage);
+
+  return characterCoverage;
+}
+
+// The following characters are not relevant for the code coverage, so they
+// must be ignored when marking characters as executed (true) or not executed (false)
+function charMustBeIgnored(char: string): boolean {
+  const code = char.charCodeAt(0);
+
+  return (
+    code === 32 || // Space
+    (code >= 9 && code <= 13) || // \t (9), \n (10), \v (11), \f (12), \r (13)
+    code === 123 || // {
+    code === 125 // }
+  );
+}
+
+// Mark different types of substrings as not relevant for code coverage (set them to STATUS_IGNORED).
+// For example, all "else" substrings or comments are not relevant for code coverage.
+function markNonExecutablePatterns(
+  fileContent: string,
+  characterCoverage: Uint8Array,
+) {
+  // Comments that start with //
+  markMatchingCharsWithIgnored(
+    fileContent,
+    characterCoverage,
+    /\/\/.*?(?=\n|$)/g,
+  );
+
+  // Comments wrapped between /* and */
+  markMatchingCharsWithIgnored(
+    fileContent,
+    characterCoverage,
+    /\/\*[\s\S]*?\*\//g,
+  );
+
+  // Lines containing `else`, since they do not represent executable code by themselves.
+  // Keep in mind that `else` is preceded by a closing brace and followed by an opening brace.
+  // This can span multiple lines.
+  markMatchingCharsWithIgnored(
+    fileContent,
+    characterCoverage,
+    /\}\s*\belse\b\s*\{/g,
+  );
+
+  // Lines containing the function signature. This can span multiple lines
+  markMatchingCharsWithIgnored(
+    fileContent,
+    characterCoverage,
+    /^\s*(function\s+[A-Za-z_$][A-Za-z0-9_$]*\s*\([\s\S]*?\)[^{]*?)(?=\s*\{)/gm,
+  );
+
+  // Lines containing the catch signature. This can span multiple lines.
+  markMatchingCharsWithIgnored(
+    fileContent,
+    characterCoverage,
+    /\bcatch\b(?:\s+[A-Za-z_][A-Za-z0-9_]*)?\s*(?:\([\s\S]*?\))?(?=\s*\{)/g,
+  );
+}
+
+function markMatchingCharsWithIgnored(
+  fileContent: string,
+  characterCoverage: Uint8Array,
+  regex: RegExp,
+) {
+  for (const match of fileContent.matchAll(regex)) {
+    for (let i = match.index; i < match.index + match[0].length; i++) {
+      characterCoverage[i] = STATUS_IGNORED;
+    }
+  }
+}
+
+// Generate non overlapping coverage statements. Every character between the start
+// and end indexes is guaranteed to be either executed or not executed.
+// Unlike the statements received from EDR, which may include nested sub
+// statements, these are processed and have no sub statements or overlapping statements.
+// Example:
+// [
+//   { start: 12, end: 20, executed: true  },
+//   { start: 15, end: 17, executed: true }
+// ]
+// ->
+// [
+//   { start: 12, end: 20, executed: true  }
+// ]
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars
+-- currently not used, but it will be used to create more detailed.
+It will be used to return statements from the function `getProcessedCoverageInfo` */
+function getProcessedExecutedStatements(characterCoverage: Uint8Array): {
+  executed: ReportCoverageStatement[];
+  unexecuted: ReportCoverageStatement[];
+} {
+  const executed = generateProcessedStatements(
+    characterCoverage,
+    STATUS_EXECUTED,
+  );
+  const unexecuted = generateProcessedStatements(
+    characterCoverage,
+    STATUS_NOT_EXECUTED,
+  );
+
+  return {
+    executed,
+    unexecuted,
+  };
+}
+
+// Based on the marked file, where each character is marked as either
+// executed (STATUS_EXECUTED) or not executed (STATUS_NOT_EXECUTED),
+// generate non-overlapping statements that indicate the start and
+// end indices, along with whether they were executed or not.
+function generateProcessedStatements(
+  characterCoverage: Uint8Array,
+  targetStatus: number,
+): ReportCoverageStatement[] {
+  const ranges: ReportCoverageStatement[] = [];
+  const fileLength = characterCoverage.length;
+
+  let start = -1;
+
+  for (let i = 0; i < fileLength; i++) {
+    if (characterCoverage[i] === targetStatus) {
+      if (start === -1) {
+        start = i; // begin new range
+      }
+    } else {
+      if (start !== -1) {
+        // Map back to boolean for the output object
+        ranges.push({
+          startUtf16: start,
+          endUtf16: i - 1,
+          executed: targetStatus === STATUS_EXECUTED,
+        });
+        start = -1;
+      }
+    }
+  }
+
+  // close last range if file ends inside a run
+  if (start !== -1) {
+    ranges.push({
+      startUtf16: start,
+      endUtf16: fileLength - 1,
+      executed: targetStatus === STATUS_EXECUTED,
+    });
+  }
+
+  return ranges;
+}
+
+// Return the executed and non executed lines based on the marked file.
+// Some lines are excluded from the execution count, for example, comments.
+function partitionLinesByExecution(
+  fileContent: string,
+  characterCoverage: Uint8Array,
+): {
+  executed: Map<number, string>;
+  unexecuted: Map<number, string>;
+} {
+  const executed: Map<number, string> = new Map();
+  const unexecuted: Map<number, string> = new Map();
+
+  let lineStart = 0;
+  let isLineIgnored = true;
+  let isLineExecutedOrIgnored = true;
+  let lineNumber = 1; // File lines start at 1
+
+  // Helper to process a line and push to correct map
+  const processLine = (endIndex: number) => {
+    // Only process if the line isn't entirely ignored
+    if (!isLineIgnored) {
+      const lineText = fileContent.slice(lineStart, endIndex);
+
+      if (isLineExecutedOrIgnored) {
+        executed.set(lineNumber, lineText);
+      } else {
+        unexecuted.set(lineNumber, lineText);
+      }
+    }
+
+    // Reset state for the next line
+    lineStart = endIndex + 1;
+    isLineIgnored = true;
+    isLineExecutedOrIgnored = true;
+    lineNumber++;
+  };
+
+  for (let i = 0; i < fileContent.length; i++) {
+    const char = fileContent[i];
+    const status = characterCoverage[i];
+
+    if (status !== STATUS_IGNORED) {
+      isLineIgnored = false;
+    }
+    if (status === STATUS_NOT_EXECUTED) {
+      isLineExecutedOrIgnored = false;
+    }
+
+    if (char === "\n") {
+      processLine(i);
+    }
+  }
+
+  // Handle the final line if the file doesn't end in a newline
+  if (lineStart < fileContent.length) {
+    processLine(fileContent.length);
+  }
+
+  return { executed, unexecuted };
+}
+
+// Enable this function while debugging to display the coverage for a file.
+// The file will be printed with green characters when they are executed,
+// red characters when they are not executed,
+// and gray characters when they are irrelevant for code coverage.
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars
+-- this function can be enabled for debugging purposes */
+function printStatementsForDebugging(
+  fileContent: string,
+  statementsByExecution: {
+    executed: Statement[];
+    unexecuted: Statement[];
+  },
+): void {
+  const relativePath =
+    statementsByExecution.executed.length > 0
+      ? statementsByExecution.executed[0].relativePath
+      : statementsByExecution.unexecuted[0].relativePath;
+
+  console.debug("Statements for file: " + relativePath);
+
+  console.debug("Executed statements:");
+  let counter = 0;
+  for (const statement of statementsByExecution.executed) {
+    console.debug(counter++ + " ---");
+
+    for (let i = statement.startUtf16; i < statement.endUtf16; i++) {
+      process.stdout.write(chalk.gray(fileContent[i]));
+    }
+
+    console.debug();
+  }
+
+  console.debug();
+
+  console.debug("Unexecuted statements:");
+  counter = 0;
+  for (const statement of statementsByExecution.unexecuted) {
+    console.debug(counter++ + " ---");
+
+    for (let i = statement.startUtf16; i < statement.endUtf16; i++) {
+      process.stdout.write(chalk.gray(fileContent[i]));
+    }
+
+    console.debug();
+  }
+}
+
+// Enable this function while debugging to display the coverage for a file.
+// The file will be printed with green characters when they are executed,
+// red characters when they are not executed,
+// and gray characters when they are irrelevant for code coverage.
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars
+-- this function can be enabled for debugging purposes */
+function printCharacterCoverageForDebugging(
+  fileContent: string,
+  characterCoverage: Uint8Array,
+): void {
+  for (let i = 0; i < characterCoverage.length; i++) {
+    if (characterCoverage[i] === STATUS_IGNORED) {
+      process.stdout.write(chalk.gray(fileContent[i]));
+    } else if (characterCoverage[i] === STATUS_EXECUTED) {
+      process.stdout.write(chalk.green(fileContent[i]));
+    } else {
+      process.stdout.write(chalk.red(fileContent[i]));
+    }
+  }
+}

package/src/internal/builtin-plugins/coverage/reports/html.ts

@@ -0,0 +1,56 @@
+import type { Report } from "../coverage-manager.js";
+import type { FileCoverageData } from "@nomicfoundation/hardhat-vendored/coverage/types";
+
+import path from "node:path";
+
+import { mkdir } from "@nomicfoundation/hardhat-utils/fs";
+import {
+  istanbulLibCoverage,
+  istanbulLibReport,
+  istanbulReports,
+} from "@nomicfoundation/hardhat-vendored/coverage";
+
+export async function generateHtmlReport(
+  report: Report,
+  htmlReportPath: string,
+): Promise<void> {
+  const baseDir = process.cwd();
+  const coverageMap = istanbulLibCoverage.createCoverageMap({});
+
+  await mkdir(htmlReportPath);
+
+  // Construct coverage data for each tested file,
+  // detailing whether each line was executed or not.
+  for (const [p, coverageInfo] of Object.entries(report)) {
+    const testedFilePath = path.join(baseDir, p);
+
+    const fc: FileCoverageData = {
+      path: testedFilePath,
+      statementMap: {},
+      fnMap: {}, // Cannot be derived from current report data
+      branchMap: {}, // Cannot be derived from current report data
+      s: {},
+      f: {}, // Cannot be derived from current report data
+      b: {},
+    };
+
+    for (const [line, count] of coverageInfo.lineExecutionCounts) {
+      fc.statementMap[line] = {
+        start: { line, column: 0 },
+        end: { line, column: 0 },
+      };
+
+      // TODO: currently EDR does not provide per-statement coverage counts
+      fc.s[line] = count > 0 ? 1 : 0; // mark as covered if hit at least once
+    }
+
+    coverageMap.addFileCoverage(fc);
+  }
+
+  const context = istanbulLibReport.createContext({
+    dir: htmlReportPath,
+    coverageMap,
+  });
+
+  istanbulReports.create("html", undefined).execute(context);
+}

package/src/internal/builtin-plugins/coverage/types.ts

@@ -1,9 +1,14 @@
-export type Tag = string;
+type Tag = string;
 export interface Statement {
   relativePath: string;
   tag: Tag;
-  startLine: number;
-  endLine: number;
+  startUtf16: number;
+  endUtf16: number;
+}
+export interface ReportCoverageStatement {
+  startUtf16: number;
+  endUtf16: number;
+  executed: boolean;
 }
 export type CoverageMetadata = Statement[];
 export type CoverageData = Tag[];

package/src/internal/builtin-plugins/network-manager/config-resolution.ts

@@ -85,7 +85,7 @@ export function resolveEdrNetwork(
       networkConfig.allowBlocksWithSameTimestamp ?? false,
     allowUnlimitedContractSize:
       networkConfig.allowUnlimitedContractSize ?? false,
-    blockGasLimit: BigInt(networkConfig.blockGasLimit ?? 30_000_000n),
+    blockGasLimit: BigInt(networkConfig.blockGasLimit ?? 60_000_000n),
     coinbase: resolveCoinbase(networkConfig.coinbase),
 
     forking: resolveForkingConfig(

package/src/internal/builtin-plugins/solidity/build-system/compiler/downloader.ts

@@ -40,7 +40,7 @@ const LINUX_ARM64_REPOSITORY_URL =
 
 export enum CompilerPlatform {
   LINUX = "linux-amd64",
-  LINUX_ARM64 = "linux-aarch64",
+  LINUX_ARM64 = "linux-arm64",
   WINDOWS = "windows-amd64",
   MACOS = "macosx-amd64",
   WASM = "wasm",
@@ -48,6 +48,7 @@ export enum CompilerPlatform {
 
 interface CompilerBuild {
   path: string;
+  url?: string;
   version: string;
   longVersion: string;
   sha256: string;
@@ -341,46 +342,59 @@ export class CompilerDownloaderImplementation implements CompilerDownloader {
       }
     }
 
-    return false;
+    // download the list in case the cached list contains older ARM64 Linux builds without URL
+    return list.builds
+      .map((b) => b.path.startsWith("solc-v") && b.url === undefined)
+      .reduce((a, b) => a || b, false);
   }
 
   async #downloadCompilerList(): Promise<void> {
     log(`Downloading compiler list for platform ${this.#platform}`);
-    let url: string;
-
-    if (this.#onLinuxArm()) {
-      url = `${LINUX_ARM64_REPOSITORY_URL}/list.json`;
-    } else {
-      url = `${COMPILER_REPOSITORY_URL}/${this.#platform}/list.json`;
-    }
     const downloadPath = this.#getCompilerListPath();
 
-    await this.#downloadFunction(url, downloadPath);
+    // download hte official solc compiler list (now that ARM64 Linus is supported)
+    await this.#downloadFunction(
+      `${COMPILER_REPOSITORY_URL}/${this.#platform}/list.json`,
+      downloadPath,
+    );
+
+    // for Linux ARM64, we need to merge the official list with our custom builds
+    if (this.#platform === CompilerPlatform.LINUX_ARM64) {
+      // cache the official list since the file will be overwritten below
+      const officialCompilerList: CompilerList =
+        await readJsonFile(downloadPath);
+
+      await this.#downloadFunction(
+        `${LINUX_ARM64_REPOSITORY_URL}/list.json`,
+        downloadPath,
+      );
 
-    // If using the arm64 binary mirror, the list.json file has different information than the solc official mirror, so we complete it
-    if (this.#onLinuxArm()) {
-      const compilerList: CompilerList = await readJsonFile(downloadPath);
-      for (const build of compilerList.builds) {
+      // add missing information and an explicit URL for download
+      const armLinuxcompilerList: CompilerList =
+        await readJsonFile(downloadPath);
+      for (const build of armLinuxcompilerList.builds) {
         build.path = `solc-v${build.version}`;
+        build.url = LINUX_ARM64_REPOSITORY_URL;
         build.longVersion = build.version;
       }
 
-      await writeJsonFile(downloadPath, compilerList);
-    }
-  }
+      // merge the official and custom lists
+      officialCompilerList.builds = officialCompilerList.builds.concat(
+        armLinuxcompilerList.builds,
+      );
+      officialCompilerList.releases = {
+        ...officialCompilerList.releases,
+        ...armLinuxcompilerList.releases,
+      };
 
-  #onLinuxArm() {
-    return this.#platform === CompilerPlatform.LINUX_ARM64;
+      await writeJsonFile(downloadPath, officialCompilerList);
+    }
   }
 
   async #downloadCompiler(build: CompilerBuild): Promise<string> {
-    let url: string;
-
-    if (this.#onLinuxArm()) {
-      url = `${LINUX_ARM64_REPOSITORY_URL}/${build.path}`;
-    } else {
-      url = `${COMPILER_REPOSITORY_URL}/${this.#platform}/${build.path}`;
-    }
+    // use the explicit URL if available or the default solc download URL if not
+    const defaultUrl = `${COMPILER_REPOSITORY_URL}/${this.#platform}`;
+    const url = `${build.url ?? defaultUrl}/${build.path}`;
 
     log(`Downloading compiler ${build.version} from ${url}`);