hardhat 3.1.3 → 3.1.5

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/solidity/build-system/build-system.ts

@@ -1,5 +1,4 @@
 import type { CompileCache } from "./cache.js";
-import type { Compiler } from "./compiler/compiler.js";
 import type { DependencyGraphImplementation } from "./dependency-graph.js";
 import type { Artifact } from "../../../../types/artifacts.js";
 import type { SolcConfig, SolidityConfig } from "../../../../types/config.js";
@@ -17,12 +16,13 @@ import type {
   RunCompilationJobResult,
   BuildScope,
 } from "../../../../types/solidity/build-system.js";
-import type { CompilationJob } from "../../../../types/solidity/compilation-job.js";
 import type {
+  CompilationJob,
+  Compiler,
   CompilerOutput,
   CompilerOutputError,
-} from "../../../../types/solidity/compiler-io.js";
-import type { SolidityBuildInfo } from "../../../../types/solidity.js";
+  SolidityBuildInfo,
+} from "../../../../types/solidity.js";
 
 import os from "node:os";
 import path from "node:path";
@@ -633,9 +633,17 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
       "The long version of the compiler should match the long version of the compilation job",
     );
 
-    const output = await compiler.compile(
-      await runnableCompilationJob.getSolcInput(),
+    const input = await runnableCompilationJob.getSolcInput();
+
+    const output = await this.#hooks.runHandlerChain(
+      "solidity",
+      "invokeSolc",
+      [compiler, input, runnableCompilationJob.solcConfig],
+      async (_context, nextCompiler, nextSolcInput) => {
+        return nextCompiler.compile(nextSolcInput);
+      },
     );
+
     return { output, compiler };
   }
 

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

@@ -2,6 +2,7 @@ import type {
   CompilerInput,
   CompilerOutput,
 } from "../../../../../types/solidity/compiler-io.js";
+import type { Compiler } from "../../../../../types/solidity/compiler.js";
 
 import { spawn } from "node:child_process";
 import fsPromises from "node:fs/promises";
@@ -23,15 +24,6 @@ import {
 import { createNonClosingWriter } from "@nomicfoundation/hardhat-utils/stream";
 import * as semver from "semver";
 
-export interface Compiler {
-  readonly version: string;
-  readonly longVersion: string;
-  readonly compilerPath: string;
-  readonly isSolcJs: boolean;
-
-  compile(input: CompilerInput): Promise<CompilerOutput>;
-}
-
 /**
  * Spawns a compilation process and returns its output.
  *

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

@@ -1,4 +1,4 @@
-import type { Compiler } from "./compiler.js";
+import type { Compiler } from "../../../../../../src/types/solidity.js";
 
 import { execFile } from "node:child_process";
 import os from "node:os";

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

@@ -1,3 +1,5 @@
+import type { Compiler } from "../../../../../types/solidity.js";
+
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -11,7 +13,7 @@ import { exists, isBinaryFile } from "@nomicfoundation/hardhat-utils/fs";
 import { getCacheDir } from "@nomicfoundation/hardhat-utils/global-dir";
 import debug from "debug";
 
-import { NativeCompiler, SolcJsCompiler, type Compiler } from "./compiler.js";
+import { NativeCompiler, SolcJsCompiler } from "./compiler.js";
 import {
   CompilerDownloaderImplementation,
   CompilerPlatform,

package/src/internal/builtin-plugins/solidity/type-extensions.ts

@@ -1,5 +1,10 @@
+import type { SolcConfig } from "../../../types/config.js";
 import type { SolidityBuildSystem } from "../../../types/solidity/build-system.js";
-import type { CompilerInput } from "../../../types/solidity.js";
+import type {
+  Compiler,
+  CompilerInput,
+  CompilerOutput,
+} from "../../../types/solidity.js";
 
 import "../../../types/config.js";
 declare module "../../../types/config.js" {
@@ -123,7 +128,10 @@ declare module "../../../types/hooks.js" {
     ) => Promise<void>;
 
     /**
-     * Hook triggered within the compilation job when its' solc input is first constructed.
+     * Hook triggered to preprocess a Solidity file and manipulate its contents
+     * before it is passed along for compilation. Only files directly under
+     * the Hardhat project are preprocessed, Solidity files from npm
+     * dependencies are not included.
      *
      * @param context The hook context.
      * @param inputSourceName The input source name of the project file.
@@ -177,5 +185,34 @@ declare module "../../../types/hooks.js" {
         nextAbsolutePath: string,
       ) => Promise<string>,
     ) => Promise<string>;
+
+    /**
+     * Hook triggered to invoke a passed in Solc compiler on the
+     * Solc input generated for a given compilation job.
+     * This hook allows for manipulating the Solc input passed into the Solc
+     * compiler Hardhat has selected for the compilation job, and similarly to
+     * manipulate the Solc output.
+     *
+     * @param context The hook context.
+     * @param compile The Solc compiler selected by Hardhat for this compilation
+     * job.
+     * @param solcInput The solc input json constructed from the compilation
+     * job.
+     * @param solcConfig The configuration used to setup solc e.g. version.
+     * @param next A function to call the next handler for this hook, or the
+     * default implementation if no more handlers exist.
+     */
+    invokeSolc(
+      context: HookContext,
+      compiler: Compiler,
+      solcInput: CompilerInput,
+      solcConfig: SolcConfig,
+      next: (
+        nextContext: HookContext,
+        nextCompiler: Compiler,
+        nextSolcInput: CompilerInput,
+        nextSolcConfig: SolcConfig,
+      ) => Promise<CompilerOutput>,
+    ): Promise<CompilerOutput>;
   }
 }